Responsive Design

Responsive Design

Overview

Use this skill to turn responsive design into a repeatable test-and-fix workflow instead of checking one screen width and hoping for the best.

Validate with screenshots across the standard viewport suite, fix layout with fluid rules first, and do not stop until overflow, collisions, awkward density, and obviously accidental whitespace are gone.

Workflow

1. Build context.

• Identify the page, route, or component to test.
• Preserve the existing design system unless the user explicitly asks for a redesign.
• Read references/responsive-rubric.md or run scripts/viewport_matrix.py --format markdown to load the standard viewport suite.

2. Capture a baseline.

• Start the page locally.
• Take screenshots at all 10 viewports before editing.
• Capture the states users actually see, not only the default rest state: hover/crosshair, focus, open dropdowns/date pickers, loading/refresh, stale-while-refreshing, selected/disabled toggles, zoomed/unzoomed charts, empty/error states, and table scroll states when those states are relevant. Run these state captures in parallel when the tooling allows it so coverage is broad without wasting time.
• Prefer automated browser tooling when available. If automation is unavailable, use the best environment-supported screenshot path and say so explicitly.
• Do not claim responsive validation without screenshot evidence.

Browser Automation Cleanup

• Use an isolated Playwright browser for responsive captures, not /Applications/Google Chrome.app or the user's Chrome profile.
• Every standalone launch must close in finally, including assertion, navigation, or screenshot failures: let browser; try { browser = await chromium.launch(...); ... } finally { await browser?.close(); }.
• Do not leave a headless browser or test process running after the capture suite. If a run fails or is interrupted, verify its browser process has exited before continuing.

3. Audit every viewport.

• Check for horizontal overflow, clipped content, overlapping text, broken grids, bad wrapping, unusable tap targets, and awkward aspect-ratio transitions.
• Pair screenshot review with a DOM overflow assertion when browser tooling permits it: compare the document and relevant scroll containers' scroll width with their client width. Repeat this for open menus, drawers, and other states that can introduce overflow.
• Verify responsive navigation behavior, not only its appearance. Primary destinations and actions must remain reachable; when navigation collapses, its trigger must open and close correctly and the resulting menu must fit the viewport without hiding controls.
• Check text legibility at the rendered size. Treat text that technically fits but is too small or tightly packed to scan or tap comfortably as a failure.
• Check images, video, canvas, and other media for intrinsic-size overflow, distorted aspect ratios, accidental cropping, and excessive dominance at narrow widths or short heights.
• Check fixed and sticky surfaces such as headers, footers, drawers, modals, and toasts. They must respect viewport edges and safe areas, avoid covering essential controls, and remain usable at short viewport heights.
• Check interactive state overlays as first-class layout: hover labels, chart readouts, dropdown panels, popovers, zoom controls, and loading badges must fit inside their intended container at every tested viewport.
• For anchored overlays such as date pickers, dropdowns, menus, and popovers, verify the attachment geometry. The overlay should share a clean edge with its trigger or with the surface it intentionally covers; avoid arbitrary floating widths, half-overlaps, or offsets that make it look detached from the underlying grid.
• Check related form-control rows for flush alignment: equal-role labels should reserve consistent vertical space, and the boxes/buttons beneath them should share top and bottom edges at every viewport.
• Before stacking related controls, check whether the row has usable horizontal space. Keep compact status/action controls on one horizontal line when they fit, with text flexing and square icon buttons staying size-matched, instead of adding vertical height unnecessarily.
• During refresh/loading states, preserve the last successful populated layout when possible. A responsive pass should verify that stale-while-refreshing charts, tables, controls, and status labels remain aligned and usable instead of collapsing into a smaller placeholder that creates layout jump.
• When a control or state toggle appears or changes, verify that it stays self-contained: it should not re-scroll the viewport, add surprise vertical height, or shove nearby content if the same action can fit cleanly in existing space. Movement is acceptable only when it is deliberate, useful, and easy to explain.
• For repeated visual units such as charts, cards, or panels, prefer viewport compositions that reveal an integer number of useful units at common sizes. A large viewport that shows one huge unit plus half of the next is usually clunky; tune density, grid columns, and chart height so users can scan more complete information at once.
• Treat "dense content next to dead whitespace" as a failure, not a minor aesthetic issue.
• Treat whitespace as intentional only when it creates hierarchy, pace, or focus.

4. Fix with fluid rules first.

• Prefer clamp(), min(), max(), minmax(), fractional grid tracks, percentages, ch, flex wrapping, grid auto-fit or auto-fill, and container-aware sizing.
• Let type, gaps, media, and sections expand and contract smoothly with available space.
• Remove brittle fixed widths, fixed heights, rigid gaps, and unnecessary absolute positioning when they cause collisions or stranded whitespace.
• Use breakpoints only for real structural changes such as navigation mode shifts, column-count changes, or major artwork repositioning.

5. Re-capture and verify.

• Re-run the full 10-viewport suite after changes.
• Compare before and after screenshots.
• Keep iterating until each viewport clears the rubric in references/responsive-rubric.md.
• Call out residual risks explicitly if any viewport still feels compromised.

Standards

• Never accept horizontal scrolling for core page content unless the product explicitly requires it.
• Never leave overlapping, clipped, or truncated text in normal use.
• Never allow words to wrap mid-word or get visually cut off by the viewport. Reflow the layout, widen the track, or restack the section before accepting a broken label.
• Keep spacing even and proportional. Small text blocks should not be stranded inside oversized gutters.
• Keep line lengths, padding, and margins readable rather than merely technically non-broken.
• Keep primary actions, forms, cards, and navigation usable on phone widths.
• Keep repeated controls in a row aligned as a grid. Label wrapping must not stagger the input/button edges when the controls are the same kind of choice or numeric field.
• Make anchored overlays feel mechanically placed, not casually dropped. Date pickers, dropdowns, and popovers should align flush to the input, button, or panel they belong to, and should cover or avoid neighboring content in a visibly intentional way.
• Preserve horizontal alignment for related controls whenever the viewport has room. Stacking is a fix for real width pressure, not a default response to smaller screens.
• Preserve symmetry when the composition calls for it, but do not force symmetry if it makes density worse.
• Keep state changes quiet and local when possible. Loading, zoom reset, expanded controls, and selected states should avoid scroll jumps, viewport repositioning, and unnecessary moving pieces unless the motion itself is the intended interaction.

Breakpoint Rules

• Use continuous scaling for typography, spacing, media, and section widths whenever possible.
• Add breakpoints for layout mode changes, not for every small visual paper cut.
• Explain why fluid math was insufficient when you add a breakpoint.
• Favor a small number of meaningful breakpoints over a pile of local patch rules.

Deliverables

• Report the exact viewports tested.
• Give every viewport a PASS, WARN, or FAIL result and name the affected state or component for every non-pass result.
• Confirm that screenshots were taken before and after the changes.
• Summarize the main responsive failures found.
• Summarize the layout changes used to fix them.
• Mention any remaining risk or viewport that still needs follow-up.

Resources

• scripts/viewport_matrix.py: Emit the standard viewport suite in plain text, Markdown, or JSON.
• references/responsive-rubric.md: Viewport rationale, audit checklist, and fluid-layout heuristics.
• Pair this skill with a frontend design skill when the task also needs stronger visual direction or more ambitious UI treatment.