| name | responsive-design |
| description | Mobile-first strategy, breakpoints, fluid layouts, content choreography, and cross-device optimization with CSS Grid, Flexbox, and modern responsive techniques. |
Responsive Design
Start with the smallest viewport and the most important content. Enhance progressively. If it doesn't work at 320px, it has no place at 1920px.
Scope
Use this skill when you:
- Design a layout for different viewports and devices
- Define or review breakpoints
- Implement mobile-first CSS strategies
- Implement responsive images and media
- Need to ensure touch optimization
- Set up responsive typography
Principles
1. Mobile First, Content First
Start with the smallest viewport and the most important content. Enhance progressively for larger screens.
2. Content Determines Breakpoints
Set breakpoints where the design breaks — not at device widths. "Start with the small screen first, then expand until it looks like shit. Time for a breakpoint!" (Stephen Hay).
3. Flexibility Over Perfection
Websites don't need to be pixel-perfect. They need to look good and be usable on every device.
4. Four Building Blocks
Responsive design consists of flexible layout, media queries, flexible media, and flexible typography.
5. Content Choreography
Content adapts not only in size but in arrangement, prioritization, and presentation to match the viewport.
6. Progressive Enhancement
Build a solid foundation for all devices and enhance progressively for more capable systems.
Rules
DO: Use a Fluid Grid
- USE percentage-based widths instead of fixed pixel values.
- USE CSS Grid for two-dimensional layouts, Flexbox for one-dimensional layouts.
- SET a max-width for the overall container (e.g., 1200-1440px).
- PREFER a 12-column grid system as the starting point.
DO: Implement Mobile-First in CSS
- WRITE base CSS for the smallest viewport.
- EXTEND with
min-width media queries for larger screens.
- AVOID
max-width media queries as the primary strategy (that is desktop-first).
DO: Implement Responsive Images
- USE
srcset with at least 3 image sizes (400px, 800px, 1200px).
- USE the
picture element for art direction.
- SET
width and height attributes to prevent CLS.
- IMPLEMENT
loading="lazy" for images below the fold.
- COMPRESS in WebP or AVIF.
DO: Set Breakpoints Thoughtfully
- DEFINE breakpoints based on content, not specific devices.
- Orientation: 320-480px (smartphone), 768px (tablet), 1024px (desktop), 1440px+ (widescreen).
- TEST between breakpoints to ensure the layout remains stable.
- SET a maximum of 4-5 main breakpoints.
DO: Ensure Touch Optimization
- SIZE touch targets to a minimum of 44x44px.
- MAINTAIN at least 8px spacing between tappable elements.
- REPLACE hover interactions with tap/click alternatives on touch devices.
- AVOID drag-and-drop as the sole interaction method.
DO: Use Responsive Typography
- USE relative units (rem, em,
clamp()).
- IMPLEMENT fluid typography with
clamp() for seamless scaling.
- ADAPT line length to the viewport (optimal: 45-75 characters per line).
DON'T: Simply Hide Content on Mobile
- DO NOT hide content via
display:none solely for mobile.
- ADAPT the presentation instead: shorter text, different arrangement, more compact components.
DON'T: Force Horizontal Scrolling
- ENSURE that no element is wider than the viewport.
- TEST at 320px width as the minimum.
- USE
overflow-x: hidden only as a last resort.
DON'T: Use Hamburger Menu on Desktop
- DISPLAY the main navigation visibly on large screens.
- RESERVE the hamburger icon for viewports where the navigation does not fit horizontally.
Patterns
Responsive Layout (Fluid Grid)
12-column grid with percentage-based widths. CSS Grid for page structure, Flexbox for component layout. Breakpoints at 768px and 1024px as a minimum. For details and code examples, see references/fluid-grid.md.
Content Choreography
Define the content order per viewport for each page. Mobile shows the most important content first. Desktop uses column layouts for secondary content alongside primary content.
Card Layout
For equivalent content units (blog posts, products, team members). Cards in a flexible grid that automatically reflows from 3+ columns to 1 column. Each card has an identical structure (image, title, excerpt, CTA).
Sticky Header with Scroll Behavior
For pages with significant scroll depth: hide the header on scroll down, reveal it on scroll up. On mobile: compact version (logo + hamburger). On desktop: full navigation.
Responsive Navigation
Full horizontal navigation on desktop. Hamburger icon with slide-in or fullscreen overlay on mobile. Breakpoint where the navigation wraps.
Anti-Patterns
Device Targeting Instead of Content Breakpoints
Breakpoints set to exact device widths (375px for iPhone, 768px for iPad). The device landscape is too fragmented. Solution: Set breakpoints where the layout breaks.
Retrofitting Responsive Design onto a Desktop Layout
A desktop design is retrofitted with media queries after the fact. Leads to hidden content and compromised solutions. Solution: Think responsive and mobile-first from the start.
Fixed Pixel Layouts
Column widths and spacing in fixed pixel values. Layout breaks at unexpected viewports. Solution: Percentage-based widths, rem/em, clamp().
Missing Viewport Meta Tag
No <meta name="viewport" content="width=device-width, initial-scale=1">. Mobile browsers render at desktop width. Solution: Include the viewport meta tag in every HTML document.
Checklist
Layout
Breakpoints
Images and Media
Typography
Navigation and Touch
Performance and Testing
Cross-References
usability -- Usability requirements that must be met responsivelynavigation-design -- Responsive navigation in detailimages-media -- Image optimization and responsive image strategiesweb-typography -- Responsive typography rulesaccessibility -- Touch optimization and mobile accessibility
