Setting the file. One moment.
Subchapter 3.1
reference/adapt.mdMarkdown11 KBView on GitHub
Additional context needed: target platforms/devices and usage contexts.
Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
Web only (mobile web included). Native platforms (ios / android / adaptive) route to adapt.native.md instead; if the project is native, switch to it now.
Understand what needs adaptation and why:
Identify the source context:
Understand target context:
Identify adaptation challenges:
CRITICAL: Adaptation is rethinking the experience for the new context, not scaling pixels.
Create context-appropriate strategy:
Layout Strategy:
Interaction Strategy:
Content Strategy:
Navigation Strategy:
Layout Strategy:
Interaction Strategy:
Layout Strategy:
Interaction Strategy:
Content Strategy:
Layout Strategy:
Content Strategy:
Layout Strategy:
Interaction Strategy:
Apply changes systematically:
Choose appropriate breakpoints:
clamp(): Fluid sizing between min and maxdisplay: none sparingly (still downloads)srcset, picture element)IMPORTANT: Test on real devices. Device emulation in DevTools is helpful but not perfect.
NEVER:
Test thoroughly across contexts:
Custom controls (sliders, drag surfaces, scrollable control strips): a before/after slider can pass every width check above and still refuse to drag on iOS, so exercise each one in scope in the same batched round as the checks above:
When the adaptation feels native to each context, hand off to /impeccable polish for the final pass.
The sections below were previously responsive-design.md and live inline now so the adapt flow has its deep responsive reference in one place.
Start with base styles for mobile, use min-width queries to layer complexity. Desktop-first (max-width) means mobile loads unnecessary styles first.
Don’t chase device sizes; let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use clamp() for fluid values without breakpoints.
Screen size doesn’t tell you input method. A laptop with touchscreen, a tablet with keyboard. Use pointer and hover queries:
/* Fine pointer (mouse, trackpad) */
@media (pointer: fine) {
.button { padding: 8px 16px; }
}
/* Coarse pointer (touch, stylus) */
@media (pointer: coarse) {
.button { padding: 12px 20px; } /* Larger touch target */
}
/* Device supports hover */
@media (hover: hover) {
.card:hover { transform: translateY(-2px); }
}
/* Device doesn't support hover (touch) */
@media (hover: none) {
.card { /* No hover state - use active instead */ }
}Critical: Don’t rely on hover for functionality. Touch users can’t hover.
Modern phones have notches, rounded corners, and home indicators. Use env():
body {
padding-top: env(safe-area-inset-top);
padding-bottom: env(safe-area-inset-bottom);
padding-left: env(safe-area-inset-left);
padding-right: env(safe-area-inset-right);
}
/* With fallback */
.footer {
padding-bottom: max(1rem, env(safe-area-inset-bottom));
}Enable viewport-fit in your meta tag:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"><img
src="hero-800.jpg"
srcset="
hero-400.jpg 400w,
hero-800.jpg 800w,
hero-1200.jpg 1200w
"
sizes="(max-width: 768px) 100vw, 50vw"
alt="Hero image"
>How it works:
srcset lists available images with their actual widths (w descriptors)sizes tells the browser how wide the image will displayWhen you need different crops/compositions (not just resolutions):
<picture>
<source media="(min-width: 768px)" srcset="wide.jpg">
<source media="(max-width: 767px)" srcset="tall.jpg">
<img src="fallback.jpg" alt="...">
</picture>Navigation: Three stages: hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. Tables: Transform to cards on mobile using display: block and data-label attributes. Progressive disclosure: Use <details>/<summary> for content that can collapse on mobile.
DevTools device emulation is useful for layout but misses:
Test on at least: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you’ll never see on simulators.
Avoid: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.