- Add language identifier to markdown code block in docs - Increase Undo/Redo button touch targets from 32px to 44px 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
7.3 KiB
Mobile UX Best Practices
This document outlines the mobile-first UX principles and implementation patterns used in this project to ensure a great experience across all screen sizes.
Core Principles
1. Mobile-First Responsive Design
Design for the smallest screen first, then progressively enhance for larger screens.
/* Base styles for mobile */
.element {
width: 100%;
padding: 12px;
}
/* Enhance for larger screens */
@media (min-width: 640px) {
.element {
width: 280px;
padding: 16px;
}
}
2. No Horizontal Overflow
The most critical mobile UX issue is horizontal scrolling. Always ensure content fits within the viewport width.
Testing for overflow:
async function hasNoHorizontalOverflow(page: Page): Promise<boolean> {
return await page.evaluate(() => {
const docWidth = document.documentElement.scrollWidth;
const viewportWidth = window.innerWidth;
return docWidth <= viewportWidth + 2; // Small tolerance for rounding
});
}
Common causes of horizontal overflow:
- Fixed widths (e.g.,
width: 340px) - Horizontal flex layouts without wrapping
- Images without
max-width: 100% - Tables without horizontal scroll containers
3. Touch Target Sizing
Interactive elements must be easily tappable. Follow these minimum sizes:
| Platform | Minimum Size | Recommended |
|---|---|---|
| Apple iOS | 44x44px | 48x48px |
| Material Design | 48x48px | 48x48px |
| Web (general) | 32x32px | 44x44px |
Implementation:
<Button className="min-h-[44px] px-3">
<Icon className="w-4 h-4" />
<span className="hidden sm:inline">Label</span>
</Button>
4. Progressive Disclosure
Show less content on mobile, with clear paths to access more:
-
Icon-only buttons on mobile, labels on desktop:
<Icon className="w-4 h-4 sm:mr-2" /> <span className="hidden sm:inline">Action Label</span> -
Collapsed navigation on mobile
-
Truncated text with expansion options
Layout Patterns
Responsive Grid
Use responsive grid columns that stack on mobile:
// Bad - always 2 columns
<div className="grid grid-cols-2 gap-4">
// Good - stack on mobile, 2 columns on larger screens
<div className="grid grid-cols-1 sm:grid-cols-2 gap-3 sm:gap-4">
Flexible Containers
Avoid fixed widths. Use percentage-based or responsive widths:
/* Bad */
.sidebar {
width: 340px;
}
/* Good */
.sidebar {
width: 100%;
}
@media (min-width: 768px) {
.sidebar {
width: 340px;
}
}
Flex Wrap for Toolbars
Allow toolbar items to wrap on smaller screens:
<div className="flex flex-wrap gap-2 items-center">
{/* Items will wrap naturally */}
</div>
Typography
Readable Font Sizes
Minimum font sizes for readability without zooming:
| Element | Minimum Size | Recommended |
|---|---|---|
| Body text | 14px | 16px |
| Labels | 12px | 14px |
| Small text/badges | 11px | 12px |
Responsive Headings
<h1 className="text-base sm:text-xl font-bold truncate">
Title Text
</h1>
Form Design
Input Fields on Mobile
- Stack form fields vertically on mobile
- Use full-width inputs for easier tapping
- Ensure proper input type for mobile keyboard optimization
<input
type="email" // Shows email keyboard
inputMode="numeric" // Shows number pad
className="w-full min-h-[44px]"
/>
Labels and Placeholders
- Labels should be visible (not just placeholders)
- Adequate spacing between label and input
- Clear validation feedback
Testing Strategy
Automated Testing with Playwright
Test across multiple viewport sizes representing real devices:
const MOBILE_VIEWPORTS = {
'iPhone SE': { width: 375, height: 667 },
'iPhone 14': { width: 390, height: 844 },
'Pixel 7': { width: 412, height: 915 },
'iPad Mini': { width: 768, height: 1024 },
};
for (const [name, viewport] of Object.entries(MOBILE_VIEWPORTS)) {
test(`page works on ${name}`, async ({ page }) => {
await page.setViewportSize(viewport);
await page.goto('/');
// Test for horizontal overflow
const hasOverflow = await page.evaluate(() =>
document.documentElement.scrollWidth > window.innerWidth + 2
);
expect(hasOverflow).toBe(false);
});
}
Visual Regression Testing
Capture screenshots at different viewports to catch visual regressions:
await expect(page).toHaveScreenshot(`homepage-${deviceName}.png`, {
fullPage: true,
maxDiffPixelRatio: 0.1,
});
Touch Target Validation
const buttons = page.locator('button, a, [role="button"]');
for (const button of await buttons.all()) {
const box = await button.boundingBox();
if (box) {
expect(box.width).toBeGreaterThanOrEqual(32);
expect(box.height).toBeGreaterThanOrEqual(32);
}
}
Framework-Specific Guidelines
Tailwind CSS (Next.js Frontend)
Use responsive prefixes consistently:
sm: 640px - Small tablets and up
md: 768px - Tablets and up
lg: 1024px - Laptops and up
xl: 1280px - Desktops and up
Common patterns:
// Stack on mobile, side-by-side on larger
className="flex flex-col sm:flex-row"
// Hide on mobile, show on larger
className="hidden sm:block"
// Reduce padding on mobile
className="p-3 sm:p-4"
// Smaller font on mobile
className="text-xs sm:text-sm"
Material UI (Lyrics Review UI)
Use the useMediaQuery hook:
const theme = useTheme();
const isMobile = useMediaQuery(theme.breakpoints.down('md'));
return (
<Box sx={{
flexDirection: isMobile ? 'column' : 'row',
width: isMobile ? '100%' : '280px',
}}>
Vanilla CSS (Instrumental Review)
Use CSS media queries:
.element {
width: 100%;
}
@media (min-width: 768px) {
.element {
width: 340px;
}
}
Checklist for New Features
Before merging any UI changes, verify:
- No horizontal overflow on any mobile viewport (320px - 480px)
- All interactive elements are at least 44x44px
- Text is readable without zooming (minimum 11px)
- Form inputs stack vertically on mobile
- Navigation is accessible on mobile
- Images scale properly with
max-width: 100% - Modals/dialogs fit within mobile viewport
- Buttons show icons-only on very small screens
- Playwright mobile tests pass
Common Fixes
Fix: Horizontal Overflow
- Check for fixed widths - Replace with responsive values
- Add flex-wrap - Allow content to wrap
- Add overflow-x: hidden - On containers (use sparingly)
- Check images - Add
max-width: 100%
Fix: Touch Target Too Small
- Add minimum height -
min-h-[44px] - Add padding -
p-3orpx-4 py-3 - Use icon-only on mobile - Hide text labels
Fix: Text Too Small
- Use responsive font sizes -
text-xs sm:text-sm - Set minimum body font size - At least 14px
- Increase line height - For better readability