Responsive And Adaptive Layout

Responsive And Adaptive Layout

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com.

Use When

• Building or restyling any browser-rendered artifact that must survive multiple widths: a website, landing page, web/app UI screen, dashboard, marketing email, or embeddable widget.
• Deciding breakpoints — how many, where, and whether they belong to the viewport or to a component's container.
• A component must adapt to wherever it is placed (a card in a 1-up hero vs the same card in a 4-up sidebar grid), not merely to the global window width — i.e. you need container queries.
• Deciding whether a value should be fixed, fluid, or intrinsic: column counts, gutters, type size, image sizing, and how they interpolate between sizes via clamp().
• An Apple-platform UI or web surface must survive iPhone resizability, iPad multitasking, Mac-designed-for-iPhone windows, iPhone Mirroring, Safari/WebKit viewport behavior, or intermediate window widths that are not named device breakpoints.
• A layout was designed desktop-first and "responsiveness" is being bolted on by stacking everything into one centred column on small screens — the slop tell this skill exists to remove.

Do Not Use When

• The page-level grid, spacing unit, focal point, and hierarchy are not yet decided — set those first in 03-layout-grid-and-composition/layout-grid-and-spacing, then make them respond here.
• The decision is purely which typeface (01-typography-and-fonts/font-selection-and-pairing) or purely which colours (02-color-brand-and-visual-identity). Set those, then size them here.
• The artifact is a fixed-canvas document or slide (DOCX/PPTX/PDF) with no fluid viewport — use layout-grid-and-spacing for page/slide grids; this skill targets resizable surfaces.
• The work is RTL mirroring or translation-expansion tolerance — that is internationalization-and-rtl-design (combine with it; logical properties below support both).
• Performance is the primary deliverable (budgets, CWV as a gate) — that is performance-as-ux-and-core-web-vitals. This skill respects those budgets; it does not own them.

Required Inputs

• The target surfaces and their realistic width range (smallest phone to largest desktop/ultrawide the design must survive — not an assumed 320–1440 default).
• The content inventory and per-block importance from layout-grid-and-spacing (you re-compose hierarchy at each size; you cannot do that without knowing what should dominate).
• The chosen type scale and spacing unit from doctrine/references/type-scale-and-spacing.md (fluid type interpolates between scale steps; it does not invent new ones).
• Which components are context-portable (placed in more than one container width) — these are the container-query candidates, not viewport candidates.
• The performance budget from doctrine/references/web-performance-budgets-2026.md (CLS ≤ 0.1 in particular constrains how images and fluid blocks may resize).

Workflow

1. Start mobile-first, and design — don't reflow. Author the smallest realistic width first and let layout add structure as space appears (min-width media/container queries only). This is not just a CSS convention: it forces you to decide what the focal point and hierarchy are when space is scarcest, which is the honest test of a composition. Per layout-grid-and-spacing §8, each width is re-composed, never collapsed into one stacked column of identical cards — that collapse is the single most common responsive slop tell.

2. Prefer intrinsic, content-driven layout over breakpoints. Most "responsiveness" should need no breakpoint at all. Let CSS Grid and Flexbox respond to content and available space: grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)) reflows a card field from 1 to N columns with zero media queries and never produces a too-narrow column. Reach for an explicit breakpoint only where the design itself must change (a sidebar appears, a nav becomes a bar, the focal point moves) — not merely because the screen got wider. See references/container-queries-and-intrinsic.md.

3. Make portable components respond to their CONTAINER, not the viewport. A card, media object, or stat block that appears in several different column widths must adapt to where it is placed. Viewport media queries cannot do this — the same card is "wide" in a hero and "narrow" in a 4-up grid at the same viewport width. Use container queries: set container-type: inline-size on the wrapper and switch the component's internal layout with @container (min-width: …). This is the core modern capability of this skill — define the breakpoint where the component breaks, intrinsically, regardless of page context. Patterns in references/container-queries-and-intrinsic.md.

4. Choose breakpoints from the CONTENT, not from device names. Do not target "iPhone" or "iPad" widths. Resize until the layout breaks — a line gets too long (>~70–75ch), a column too narrow to hold its content, a focal point lost — and put a breakpoint there. Keep the set small (typically 2–4). Express widths in em/rem so breakpoints respect the user's font size. Full rationale and a starter scale in references/breakpoint-strategy.md.

5. Make size fluid with clamp() instead of stepping at breakpoints. Type, spacing, and measure should interpolate smoothly between a floor and a ceiling so the page bends rather than snapping. Fluid type: font-size: clamp(<min>, <preferred-with-vw>, <max>), where the floor and ceiling are real steps from doctrine/references/type-scale-and-spacing.md (clamp interpolates between the scale; it does not replace it). Always set a rem floor and ceiling so text stays readable on tiny screens and never balloons on ultrawide, and so the user can still zoom (a pure-vw size defeats zoom — a WCAG 1.4.4 failure). Recipe in references/breakpoint-strategy.md.

6. Size images and media to prevent layout shift. Every image/video/embed gets an intrinsic width/height or aspect-ratio so the box is reserved before load — this is what keeps CLS ≤ 0.1 per doctrine/references/web-performance-budgets-2026.md. Serve responsive sources (srcset/sizes, AVIF→WebP→fallback) and lazy-load below the fold. A fluid image is max-width: 100%; height: auto inside an aspect-ratio box. Never resize a block in a way that reflows content already on screen.

7. Use logical properties and modern fit functions. Author with inline-size, margin-inline, padding-block, inset-inline instead of physical width/left/right so the layout survives RTL and vertical writing modes for free (pairs with internationalization-and-rtl-design). Constrain measure with width: min(100% - 2rem, 70ch) and centre content columns with margin-inline: auto; cap line length at ~66ch for body text regardless of viewport.

8. Re-decide the focal point and asymmetry at every size — apply progressive enhancement, not graceful degradation. Carry the authored composition from layout-grid-and-spacing (focal point, intentional asymmetry, uneven whitespace) into each size. The mobile view is not a lesser version of desktop: decide what leads on a phone, then enrich as width allows (a margin column appears, an image bleeds off one edge). Mobile must still have a focal point and tension — not a flat single-column stack.

9. Respect user and device preferences as first-class adaptivity. Honour prefers-reduced-motion (no large fluid motion for those users), prefers-color-scheme, and coarse-vs-fine pointers (@media (pointer: coarse) → ≥24px / ideally ≥44px touch targets per doctrine/references/wcag-2.2-criteria.md target-size). Adaptivity is about the person and context, not only the pixel width.

10. Run the responsive anti-slop checklist (below). If any item fails, fix before shipping.

11. For Apple surfaces, test resizable windows, not just device presets. On iOS/iPadOS/macOS and Safari/WebKit, resize through intermediate widths; verify Liquid Glass chrome, safe areas, toolbars, keyboards, popovers, pointer states, and home-screen PWA display modes do not clip, overlap, or hide primary actions.

The Responsive Anti-Slop Checklist (run every time)

1. Mobile-first source order; each size re-composed, never collapsed into one identical-card stack.
2. Most reflow is intrinsic (Grid/Flex auto-fit/minmax/clamp) — breakpoints reserved for real design changes, and there are only a handful.
3. Portable components use container queries, not viewport queries, to adapt to their placement.
4. Breakpoints chosen where the content breaks, in em/rem — not at device-name pixel widths.
5. Fluid type via clamp() with a real rem floor and ceiling; zoom still works (no pure-vw).
6. Every image/media has reserved space (aspect-ratio/width+height); CLS ≤ 0.1 holds.
7. Logical properties (inline-size, margin-inline…) so RTL/vertical modes work; measure capped ~66ch.
8. A named focal point and at least one intentional asymmetry survive at the smallest size too.
9. prefers-reduced-motion, prefers-color-scheme, and coarse-pointer target sizes honoured.
10. Apple surfaces checked across resizable iPhone/iPad/Mac-designed-for-iPhone windows and Safari/WebKit viewport behavior where applicable.

Decision Rules

Capability Contract

• Must inspect the source structure and render at representative and intermediate widths; may resize, measure overflow/CLS, and run accessibility checks.
• Review defaults to read-only. Change markup, styles, or tokens only for requested implementation/remediation, preserving semantic order and unrelated work.
• Do not claim device coverage from named breakpoints alone, or deploy/publish without separate authority and test evidence.

Degraded Mode

• If target widths or content priorities are unknown, stop structural breakpoint decisions and return a discovery matrix.
• If browser rendering is unavailable, provide intrinsic CSS and a viewport/container test plan marked unverified.
• If container queries are unsupported by a required environment, document the feature query and smallest maintainable fallback.
• Recover from overflow, overlap, CLS, or order failure by fixing the earliest governing rule, then retest boundary widths on both sides of it.

Quality Standards

• No horizontal overflow, clipped critical content, hidden action, or semantic-order mismatch at tested boundary and intermediate widths.
• Zoom, text resizing, touch/pointer input, reduced motion, and representative content remain usable where applicable.
• Release evidence names browsers, widths, containers, states, failures, corrections, and residual compatibility risks.

Anti-Patterns

• The desktop mockup with mobile bolted on: designed at 1440 only, then everything stacks into one centred column of identical cards on phones — hierarchy and focal point destroyed.
• Device-width breakpoints: @media (max-width: 768px) chasing yesterday's iPad instead of putting the breakpoint where this content actually breaks.
• Viewport queries for component-level adaptivity: forcing a card to know the window width when it should respond to its own container; the card then looks wrong in any non-default placement.
• Breakpoint soup: a dozen max-width queries hand-tuning every element because the base layout isn't intrinsic; brittle, and it snaps instead of bending.
• Pure-vw font sizing: font-size: 5vw with no floor/ceiling — illegible on small screens, gigantic on ultrawide, and it breaks browser zoom (WCAG 1.4.4 reflow/zoom failure).
• Unreserved media: images with no width/height/aspect-ratio that shove content down as they load — a visible CLS jump and an instant "unconsidered" read.
• Max-width-only (desktop-first) cascades: authoring large then subtracting, which buries the scarcest-space decision instead of confronting it first.
• Ignoring the person: no reduced-motion, no dark-scheme, desktop-sized hit targets on touch.

Sourcing authority (the asymmetry rule)

Grounds only in human design and web-standards authority — never in an AI tool's responsive suggestions, per doctrine/design-doctrine.md §2. Canonical sources for this skill:

• Ethan Marcotte — Responsive Web Design — fluid grids, flexible media, media queries as a single adaptable layout rather than per-device mockups.
• Jeremy Keith — Resilient Web Design and progressive enhancement — build up from the smallest, most robust layer outward.
• Andy Bell & Heydon Pickering — Every Layout — intrinsic, algorithmic layouts that respond to content and space with minimal media queries.
• The CSS specifications (CSS Grid, Containment / Container Queries, clamp() math functions, logical properties) as the standards basis — admissible as standards, not as AI endorsement.
• Builds directly on 03-layout-grid-and-composition/layout-grid-and-spacing (the grid, spacing unit, focal point, and asymmetry this skill makes responsive).

When an AI tool recommends "three max-width breakpoints at 768/1024/1280 with everything stacking on mobile," treat that as the convergent mean to avoid — not as endorsement.

Outputs

• A stated responsive decision before any markup/CSS: the breakpoint set (and the content reason for each), which components are container-query-driven, the fluid-type clamp() floors and ceilings (tied to the type scale), and how the focal point + asymmetry re-compose at each size — including the smallest.
• The responsive CSS itself (intrinsic grid, container queries, fluid type/space) — see examples/responsive-grid-template.md.
• A completed responsive anti-slop checklist, consistent with the Mission in doctrine/design-doctrine.md §0 and within the budgets of doctrine/references/web-performance-budgets-2026.md.

Examples

• examples/responsive-grid-template.md — a complete, real responsive card grid: intrinsic auto-fit/minmax reflow, a container-query-driven card that changes its own internal layout by available width, and fluid type/space via clamp() — annotated against the checklist.

References

• doctrine/design-doctrine.md (§0 Mission — "the moat is looking human-made"; §2 sourcing- authority asymmetry rule).
• doctrine/references/type-scale-and-spacing.md (the scale steps and spacing unit that fluid clamp() interpolates between — clamp does not invent sizes).
• doctrine/references/web-performance-budgets-2026.md (CLS ≤ 0.1, responsive image budgets, font-display/preload — the constraints fluid sizing and media must respect).
• doctrine/references/wcag-2.2-criteria.md (1.4.4 zoom/reflow for fluid type; 2.5.8 target size for coarse-pointer adaptivity).
• 03-layout-grid-and-composition/layout-grid-and-spacing (the grid, spacing unit, focal point, and intentional asymmetry this skill carries responsively across sizes).
• references/container-queries-and-intrinsic.md and references/breakpoint-strategy.md.