Responsive Design

Responsive Design

Use this skill when the job is to name the failing responsive surface, choose the smallest viable adaptation packet, and leave behind a short strategy + verification brief.

The job is not to dump generic CSS recipes, paste framework snippets, or absorb every neighboring frontend concern.

This skill should: 1. classify the responsive failure first, 2. choose one primary responsive packet, 3. keep viewport vs container ownership explicit, 4. separate dense-data and media cases from generic layout advice, 5. keep reflow/verification visible, 6. route neighboring frontend work honestly.

Read these support docs first:

• references/intake-packets-and-route-outs.md
• references/layout-decision-checklist.md
• references/handoff-boundaries.md

When to use this skill

• A team says “this page breaks on mobile” and the real responsive surface is still unclear.
• A dashboard, nav, form, card grid, pricing page, table, or embed needs a responsive strategy before more breakpoints are added.
• You need to decide whether the fix belongs in viewport layout rules, container queries, intrinsic layout, responsive media handling, or verification/reflow follow-up.
• A launch-readiness pass uncovered overflow, wrapping, density, or zoom/reflow failures and someone needs one bounded packet instead of a CSS lecture.
• The request mixes page-level adaptation, component reuse, and dense-data pressure and needs routing before implementation.

When not to use this skill

• The main task is reusable primitive / slot / variant API design or component-family ownership → ui-component-patterns
• The main task is keyboard/focus behavior, semantics, labels, contrast, reduced motion, or accessibility-heavy remediation → web-accessibility
• The main task is breakpoint governance, token policy, or cross-product responsive standards → design-system
• The main task is broad UI critique, polish, heuristic review, or launch-readiness audit across many dimensions → web-design-guidelines
• The main task is React hydration, rerender churn, or client-boundary performance behavior → react-best-practices
• The responsive strategy is already clear and the job is just implementation; in that case implement directly instead of re-running the router

Instructions

Step 1: Frame the responsive job before naming CSS

Capture the minimum intake packet first.

responsive_intake:
  surface: page-shell | nav | form | table | dashboard | card-grid | media-embed | component-slot | mixed | unknown
  workflow_type: bug-fix | refactor-plan | launch-readiness | review-follow-up | design-handoff | unknown
  primary_packet: page-layout | component-slot | dense-data | media-behavior | verification-reflow | mixed | unknown
  pressure_source: viewport-width | parent-container | content-density | localization-copy | zoom-reflow | mixed | unknown
  signal_source: bug-report | screenshot | browser-resize | qa-review | design-review | a11y-review | mixed | unknown
  confidence: high | medium | low

Rule: do not start with “add another breakpoint.” First label the failing responsive surface.

Step 2: Choose exactly one primary responsive packet

Use the router in references/intake-packets-and-route-outs.md.

Primary packets: 1. page-layout 2. component-slot 3. dense-data 4. media-behavior 5. verification-reflow

Pick the highest-leverage packet for the current decision. List anything else as follow-up, not as equal co-owners.

Step 3: Keep the invariants visible

These rules survive every answer:

• mobile-first defaults are still the safest baseline for feature delivery
• intrinsic layout beats breakpoint sprawl when it solves the problem cleanly
• viewport rules own page-shell changes; container rules own reusable slot adaptation
• breakpoints should reflect content pressure, not device brand names
• dense tables/toolbars are special cases and often need explicit fallback choices
• responsive media needs intentional srcset / sizes / aspect-ratio thinking, not just width: 100%
• zoom/reflow and long-copy stress are verification requirements, not afterthoughts

Step 4: Build the responsive strategy packet

Return this structure:

# Responsive Strategy Packet

## Scope
- Surface:
- Workflow type:
- Primary packet:
- Confidence: high | medium | low

## Current signal
- Main symptom:
- Pressure source:
- What is already known:
- What still needs direct verification:

## Recommended first slice
1. ...
2. ...
3. ...

## Layout decisions
- Mobile-first baseline:
- Intrinsic layout rules:
- Viewport query layer:
- Container-query usage:
- Dense-data / media fallback:

## Verification plan
- Narrow-width checks:
- Zoom / reflow checks:
- Overflow / wrapping checks:
- Content-density / localization checks:

## Ownership and route-outs
- Primary owner:
- Adjacent skills / teams:

Step 5: Use the packet, not a giant CSS tutorial

Pull the packet from references/intake-packets-and-route-outs.md.

Packet rules:

• page-layout → page shell, nav/sidebar shifts, grid columns, spacing density, viewport breakpoints
• component-slot → reusable card/panel/module behavior that changes by parent width; container queries or intrinsic component rules
• dense-data → tables, toolbars, filter bars, dashboards, and intentional fallback choices such as summary, disclosure, or horizontal scroll
• media-behavior → image/video/embed sizing, srcset / sizes, aspect ratio, crop strategy, and art-direction edge cases
• verification-reflow → zoom, reflow, overflow, long labels, localization, and screenshot-vs-manual follow-up before release

Step 6: Separate mechanism choice from ownership choice

Use this split in every serious answer:

• Mechanism — intrinsic layout, viewport queries, container queries, responsive media rules, fallback presentation
• Ownership — responsive-design, ui-component-patterns, web-accessibility, design-system, web-design-guidelines, or react-best-practices

If the request starts from a screenshot, QA note, or “mobile is broken” report, say explicitly that the screenshot is the signal artifact, not the finished responsive strategy.

Step 7: Route adjacent work explicitly

Use these route-outs when the problem crosses boundaries:

Output expectations

A strong answer from this skill should: 1. identify the primary responsive packet, 2. recommend one bounded adaptation strategy, 3. name the manual verification still required, 4. avoid treating framework helpers as a complete strategy, 5. route broader frontend ownership questions outward instead of absorbing them.

Examples

Example 1: dashboard overflow on mobile

Input

Our dashboard filter bar and data table force horizontal scrolling on mobile. Help us fix the responsive behavior.

Output direction

• choose dense-data
• keep a mobile-first shell but make the table/toolbar fallback intentional
• include zoom/reflow verification and long-label checks
• route accessibility-heavy remediation to web-accessibility if it becomes the main issue

Example 2: reusable card in many slots

Input

The same card lives in a sidebar, a feed, and a 2-column grid. Should we use container queries or more viewport breakpoints?

Output direction

• choose component-slot
• explain why parent-container width is the main driver
• recommend container queries or intrinsic layout at the card-shell boundary
• route primitive/API redesign to ui-component-patterns if the structure itself is wrong

Example 3: pricing page before launch

Input

Review this pricing page before launch. Cards feel cramped on mobile and the hero wraps badly.

Output direction

• keep responsive-design on the layout-adaptation slice only
• produce one packet for page layout plus dense mobile sections
• route broader hierarchy / CTA / polish review to web-design-guidelines
• keep accessibility remediation separate unless it becomes primary

Example 4: system-wide breakpoint debate

Input

Our teams all use different breakpoint and spacing rules across products. Is responsive-design the right skill?

Output direction

• explain that shared breakpoint/token governance is broader design-system work
• keep responsive-design narrower than cross-product standards
• avoid over-triggering on governance-only requests

Example 5: zoom and reflow failure

Input

This form still breaks at 400% zoom and keyboard users lose context. Should we keep fixing it in responsive-design?

Output direction

• choose verification-reflow first if layout ownership is still unclear
• include zoom/reflow verification explicitly
• route keyboard/focus remediation to web-accessibility
• split the work instead of forcing one skill to own everything

Best practices

1. Start with the failing responsive surface, not the syntax trick. 2. Prefer intrinsic layout before adding another breakpoint. 3. Keep viewport and container ownership explicit. 4. Treat tables, toolbars, and dense dashboards as packet-worthy special cases. 5. Treat screenshots and device-mode checks as inputs, not proof of completion. 6. Keep verification honest: zoom, reflow, long copy, and overflow still matter. 7. When unsure, route neighboring frontend work explicitly instead of inflating this skill.

References

• MDN: Responsive design
• MDN: Using media queries
• MDN: Container queries
• MDN: Responsive images
• web.dev: Learn Responsive Design
• W3C WAI: Understanding Reflow

Handoff Boundaries for responsive-design

Use this file when multiple frontend skills could plausibly activate.

Keep work in responsive-design when

• the main job is viewport/container adaptation, overflow control, reflow planning, responsive media, or layout verification
• the user asks about breakpoints, mobile-first baselines, container queries, wrapping, or layout collapse across widths
• the problem is deciding how a page or layout surface should adapt across available space

Route to ui-component-patterns when

• the real question is reusable primitive or component-family API design
• the issue is variants, slots, compound components, or controlled-vs-uncontrolled ownership rather than responsive layout rules

Route to web-accessibility when

• the main problem is reflow remediation, touch targets, semantics, keyboard/focus behavior, labels, or manual accessibility verification
• accessibility is the core task rather than one verification dimension among several

Route to design-system when

• the task is about shared breakpoint policy, token scales, primitive naming, or governance across many products/components
• multiple component families need one system-level responsive rule before local implementation can proceed

Route to web-design-guidelines when

• the user wants a broad UI/design audit instead of implementation-first responsive strategy
• the request is mostly about overall interface quality, consistency, or guideline compliance

Mixed cases

When a request spans multiple skills, split the answer explicitly:

• responsive-design owns layout-adaptation strategy and verification
• neighboring skills own reusable component APIs, accessibility remediation, system governance, or broad UI review

Do not hide unclear ownership by dumping every frontend concern into breakpoint advice.

Responsive Intake Packets and Route-Outs

Use this file after the intake is classified. The goal is to pick one primary responsive packet and keep neighboring frontend work outside the main answer unless it is truly primary.

Packet router

Selection rules

1. Pick the packet that answers the current decision, not every possible downstream concern. 2. If both page-shell and component-slot work are involved, choose whichever change is blocked right now and list the other as follow-up. 3. If the only honest answer is “the screenshot proves too little,” choose verification-reflow. 4. If the real problem is component contract sprawl, token governance, or accessibility remediation, route out early instead of hiding it under responsive language.

Invariants

• Prefer intrinsic layout before breakpoint sprawl.
• Use viewport queries for page-shell shifts and container queries for reusable slot behavior.
• Treat tables and crowded toolbars as explicit fallback-design problems, not generic CSS bugs.
• Keep manual verification visible: narrow widths, zoom/reflow, long copy, localization, overflow, and responsive media checks.

Output reminder

A good responsive answer ends with one short packet:

• primary packet
• first slice
• layout decisions
• verification plan
• route-outs

Layout Decision Checklist for responsive-design

Use this checklist before adding more breakpoints or local overrides.

1. Problem surface

• Is this mainly a viewport layout problem, a container-driven component problem, a media-sizing problem, or a verification problem?
• Which screen sizes, zoom levels, or parent-container widths expose the failure?

2. Intrinsic layout first

• Can flexible widths, wrapping, minmax(), auto-fit grid, or sensible max-width solve the issue before conditional rules?
• Is the layout depending on placeholder-short content instead of real content lengths?

3. Viewport vs container ownership

• Does the entire page/region change with viewport size?
• Or does the component simply need to adapt to the width of its parent slot?
• If the latter, should a container query be used instead of more viewport breakpoints?

4. High-risk responsive surfaces

• Navigation: wrapping, menu triggers, label lengths
• Forms/toolbars: stacking, action placement, helper/error text
• Tables/data views: stack, summarize, scroll, or preserve tabular layout intentionally?
• Media: aspect ratio, srcset, sizes, crop strategy

5. Verification

• What happens at narrow widths and common breakpoints?
• What happens at high zoom / reflow-equivalent conditions?
• Are overflow, clipping, truncation, and two-dimensional scrolling acceptable or accidental?
• Should any follow-up be routed to web-accessibility?