Build responsive web layouts

Build Responsive Web Layouts

Treat responsive implementation as a layout contract, not a pile of breakpoint patches. Preserve the design's hierarchy at its reference frames and make behavior between them explicit, fluid, and testable.

1. Inspect the layout owners

• Read repository instructions and the installed framework documentation relevant to layout, images, routing, and fonts.
• Locate the site shell, content frames, shared gutters, max widths, breakpoints, overflow rules, and visual tests.
• Inspect the implementation at narrow, intermediate, reference, and wide widths before editing.
• Trace containing blocks, clipping ancestors, transforms, and stacking contexts from the broken child to the root.
• When using Figma, inspect the selected node and its meaningful parent frame; a child alone hides the canvas and gutter contract.

Completion criterion: identify the element that owns width, padding, reflow, clipping, and positioning for every affected region.

2. Freeze the design invariants

Record what must survive resizing:

• source and reading order;
• semantic groups and their ownership;
• vertical versus horizontal composition;
• alignment anchors and gutter relationships;
• media crop/aspect behavior;
• interaction states and controls;
• intentional bleed boundary.

Whitespace is not permission to redesign. A VStack remains vertical until the design or content failure demonstrates a column change. Responsive work may reflow values while preserving structure.

Read design-integrity.md before changing breakpoint structure, interactive rails, overlays, or shared cross-route components.

Completion criterion: every structural change is supported by a supplied design frame, an existing project convention, or a measured content failure point.

3. Write the layout contract

Answer these before editing:

Decision	Required answer
Reference frames	Widths used for exact comparison
Site canvas	Full viewport, capped canvas, or bounded scene
Height contract	Natural document flow, viewport-bounded section, or exact single-screen scene
Content canvas	Max width and symmetric gutter owner
Resize mode	Reflow, hybrid, art-directed scene, or intentional overflow
Design invariants	Groups, order, axis, anchors, and state behavior
Breakpoints	Measured content failure points and supplied design frames
Overflow	Moving child, stage, clipping owner, and allowed axis
Bleed boundary	Content gutter, site canvas, or viewport edge
Images	Size owner, aspect ratio, contain/cover, crop, and source policy
Typography	Fluid bounds, wrapping policy, and readable minimum
Zoom support	Physical screen sizes and browser zoom levels to verify

Read layout-patterns.md when choosing primitives or translating Figma Auto Layout.

4. Classify each region

Choose one mode:

1. Reflow: ordinary text, cards, navigation, forms, and grids. Use intrinsic sizing, Grid/Flex, minmax(), relative units, and content-driven breakpoints.
2. Hybrid: keep semantic content in normal flow; scale or crop only the artwork layer.
3. Art-directed scene: preserve proportional geometry inside a bounded reference scene, with a separate narrow layout.
4. Intentional overflow: declare whether a rail bleeds through a gutter, a capped canvas, or to the viewport.

Never scale an entire ordinary page to simulate responsiveness.

5. Audit hardcoded values

Classify every touched fixed value:

• Intrinsic: border, icon, minimum touch target, media ratio. Keep it.
• Reference geometry: bounded art-directed scene coordinates. Keep it inside that scene.
• Responsive bound: a min/max value. Express it with clamp(), min(), max(), or tokens.
• Container relationship: width, gap, or placement that should derive from the parent. Replace it with Grid/Flex, percentages, minmax(), container units, or shared gutters.
• Screenshot patch: arbitrary offsets, duplicated padding, fixed phone frames, or viewport translations. Remove it by fixing the layout owner.

Read hardcoding-audit.md when a page contains many pixel values, absolute positions, negative margins, or viewport-specific overrides.

Completion criterion: every remaining fixed value has a named reason; ordinary content has no screenshot-sized width or position dependency.

6. Implement shared primitives first

Prefer a small vocabulary:

• SiteFrame: centered capped site canvas;
• ContentFrame: one owner for responsive symmetric gutters;
• ContentGrid: reflowing columns with minmax(0, 1fr);
• MediaFrame: explicit aspect, crop, and overflow ownership;
• ResponsiveScene: bounded scaler for approved art-directed geometry;
• ViewportBleed: a named breakout whose stage reaches the viewport and clips the moving track there;
• OverlayLayer: fixed or absolute UI that does not participate in main-content flow.

Reuse shared navigation, cards, and route modules when their design is shared. Put route-specific content and order in data, not copied markup.

7. Implement from containers outward

• Fix shell and section geometry before child offsets.
• Use normal flow, Grid, and Flex before positioning.
• Give flexible text/media children min-width: 0.
• Use aspect-ratio and stable media boxes; distinguish intrinsic image dimensions from rendered CSS size.
• For a viewport-bounded scene, derive scale from both available width and available height. Subtract the real header and safe-area space before fitting; never assume width-only scaling is enough.
• Keep circular media clipping on one stable frame. During a media change, overlap outgoing and incoming layers and crossfade them; do not reveal the frame background between mounts.
• Preserve DOM reading order when visual layout changes.
• Make overlays cover the intended region without pushing main content.
• For moving rails, keep the active item aligned to the content gutter while the stage escapes padding and clips at its declared boundary.
• Keep controls enabled/disabled according to real navigation state, not presentation defaults.

8. Validate invariants across the interval

Test actual project breakpoints plus 320, 390, 768, 1024, 1280, 1440, and a wide viewport. Test one pixel on each side of structural breakpoints. For desktop compositions, also test representative physical screens at 90%, 100%, and 110% browser zoom; zoom changes the effective CSS width and height.

Assert:

• no unintended document-level horizontal overflow;
• symmetric gutters and correct max-width centering;
• preserved group order and intended stack axis;
• no text, label, or control collisions;
• intentional bleed reaches its declared boundary and is clipped by the correct owner;
• overlays do not change main-content position;
• images preserve aspect/crop and reserve normal-flow height;
• controls expose correct interactive states;
• 200% text zoom and narrow reflow keep content reachable.
• exact single-screen pages satisfy scrollHeight <= innerHeight while all copy and controls remain visible;
• circular media remains circular, has no blank flash or dark halo during changes, and only the selected video plays;
• rapid repeated carousel navigation still settles the selected item at the intended anchor without a visible reset.

Prefer geometry and behavior assertions over screenshot-only tests. Read qa-matrix.md before declaring completion. Read viewport-height-and-zoom.md for height-bounded scenes, browser zoom matrices, intentional bleed, circular video transitions, and true infinite rails.

Read official-standards.md when explaining responsive, reflow, zoom, image, or containing-block decisions to the user.

Completion criterion: the entire supported resize interval passes invariant tests, not only the supplied screenshot width.

9. Report the contract

State:

• resize mode and preserved design invariants for each changed region;
• shared primitives or tokens changed;
• viewport widths and breakpoint boundaries tested;
• intentional overflow and its final clipping owner;
• remaining design ambiguity or known exceptions.

Failure signals

Stop and fix the owner when:

• a phone-sized frame merely centers inside a wider viewport;
• breakpoint work changes a supplied vertical composition into columns without evidence;
• one side clips while the opposite gutter remains;
• a rail is clipped by content padding instead of its declared stage;
• an overlay pushes the page or ends before its intended region;
• ordinary text requires horizontal scrolling;
• fixed offsets repair only one screenshot width;
• overflow: hidden merely hides broken geometry;
• the same shared module renders differently across routes without a design reason;
• a control looks disabled while its action is available.
• a one-screen composition scrolls or clips at supported browser zoom levels;
• document overflow is suppressed at the root instead of tracing the offending child and its local clipping owner;
• a circular image or video becomes elliptical, flashes white, or exposes a black fallback during transition;
• an “infinite” rail visibly animates from the last item back to the first;
• the active state or media playback waits for a long settle timeout after the selected item has already changed.