Responsive Craft
Implement responsive design that works across all viewports — compensating for the lack of a visual canvas by making deliberate decisions upfront.
Quick Start
Transform an existing site: /responsive-craft audit or "make this responsive" or "fix the mobile layout"
Build responsive from scratch: /responsive-craft build or "build this mobile-first" or "create a responsive layout"
Preview all breakpoints: /responsive-craft preview or "show me the responsive preview" or "open the breakpoint preview"
Core Principles
Escalation model — Intrinsic CSS first (auto-fit, flex-wrap, clamp()) → container queries next (component-level) → media queries last (page-level only). If a simpler layer solves it, stop there.
Describe before you code — Without a canvas, explicitly describe responsive behavior before writing CSS. In Adaptive mode, use inline behavior notes (CSS comments). In Guided mode, write formal behavior specs (tables per component). Both catch design decisions a canvas would reveal passively.
Fluid by default, breakpoints by exception — Use clamp() for typography, spacing, sizing. Reserve hard breakpoints for structural changes: nav transforms, column count shifts, sidebar visibility.
Component containment — Components respond to their container, not the viewport. Use container queries. A card in a sidebar and a card in a full-width section should use the same CSS.
Test by dragging, not jumping — Slowly resize from 280px to 2560px in DevTools. Don't just check named breakpoints. This catches in-between failures.
Sticky/scroll needs explicit patterns — Sticky coordination, z-index stacking contexts, overflow ancestors, safe areas, virtual keyboards. These break silently. Use the patterns in references/sticky-scroll-patterns.md, don't improvise.
Recognize design forks, don't default silently — When a responsive translation has multiple valid approaches, present 2-3 options with tradeoffs and ask the user to choose. See references/responsive-design-forks.md.
The Three-Layer Responsive System
| Layer |
Tool |
Handles |
| Continuous |
clamp(), fluid tokens, cqi units |
Smooth scaling — font size, padding, gap |
| Component |
Container queries (@container) |
Adapting to context — card layout, nav items |
| Structural |
Media queries (@media) |
Page-level shifts — grid columns, nav transform, sidebar |
Escalation Decision Tree
Does this need to change layout?
No → clamp() for sizing. Done.
Yes → Does it depend on CONTAINER size?
Yes → Container query
No → Does it depend on VIEWPORT?
Yes → Media query (page-level only)
No → :has() or intrinsic sizing (auto-fit, flex-wrap)
Mode Selection
This skill operates in three modes. Detect from $ARGUMENTS or ask.
Detection
$ARGUMENTS contains "preview", "show breakpoints", "live preview" → Preview
$ARGUMENTS contains "audit", "transform", "fix", "improve", "retrofit" → Transform Existing
$ARGUMENTS contains "build", "create", "new", "from scratch" → Build Responsive
- User is working in an existing codebase with responsive issues → Transform Existing
- User is starting a new page/component → Build Responsive
- Ambiguous → Ask
If AskUserQuestion is available:
- Transform existing — Audit and improve responsive behavior of current code
- Build from scratch — Design responsive layout from the start
- Preview — Launch a live multi-breakpoint preview in the browser
Otherwise: "Are you transforming an existing site's responsive design, building something new, or just previewing?"
Interactivity Level
Skip for Preview mode — go straight to routing.
After mode selection, determine interactivity:
If AskUserQuestion is available:
- Adaptive — Moves fast. 1-2 discovery questions, then starts working. Surfaces design forks inline as they arise. No formal specs — decisions are made in the moment.
- Guided — Produces deliverables. Full discovery, writes behavior specs per component before coding, gets explicit approval before each stage. Best for complex layouts or when the user wants a spec to reference later.
Otherwise: "Do you want (1) Adaptive — fast, I'll ask as I go, or (2) Guided — I'll write behavior specs per component and get your approval before coding?"
Default to Adaptive if the user doesn't express a preference.
When to recommend Guided: If the layout has 5+ distinct responsive components, multiple sticky elements, or a dashboard-style layout, suggest Guided — the behavior specs prevent expensive rework later.
Routing
After mode and interactivity are selected:
| Mode |
Read workflow |
Load immediately |
| Preview |
workflows/preview.md |
None |
| Transform Existing |
workflows/transform-existing.md |
references/ai-failure-patterns.md |
| Build Responsive |
workflows/build-responsive.md |
references/modern-css-patterns.md, references/ai-failure-patterns.md |
Load other references on demand:
references/sticky-scroll-patterns.md — when sticky, scroll-snap, or independent scroll regions are involved
references/responsive-design-forks.md — when an ambiguous responsive translation is detected
references/testing-checklist.md — during verification step
references/modern-css-patterns.md — during Transform mode when implementing fixes
Gotchas — Where Claude Fails at Responsive Design
These are the most common mistakes. Check every responsive output against this list.
100vh on mobile — Use svh/dvh with vh fallback. 100vh overflows behind mobile browser chrome.
Desktop-first media queries — Always use min-width (mobile-first), not max-width. Mobile loads fewer overrides.
Missing min-width: 0 on flex children — Default flex min-width is auto (content size). Long text/images overflow. Add min-width: 0 when content is dynamic.
overflow: hidden kills sticky — Any ancestor with overflow: hidden/scroll/auto breaks position: sticky. Use overflow: clip for visual clipping.
transform breaks position: fixed — Any transform on an ancestor makes fixed children position relative to that ancestor, not viewport.
iOS input zoom below 16px — Input font-size under 16px triggers Safari viewport zoom. Use font-size: max(16px, 1rem).
Missing safe area insets — Notched devices need env(safe-area-inset-*). Requires viewport-fit=cover in meta tag. Don't forget landscape orientation.
Z-index escalation — Values like 9999 signal misunderstanding of stacking contexts. Use isolation: isolate and a tiered z-index scale.
Missing align-self: start on sticky in flex/grid — Without this, the element stretches to full height and sticky has no room to stick. The #1 silent sticky failure.
Optimizing for one viewport — Code that looks perfect at 1440px breaks at 320px, 768px portrait, and ultrawide. Always test the full range.
For the complete list with code examples, see references/ai-failure-patterns.md.
Tools
This skill includes two CLI tools in scripts/ for visual responsive verification.
Live Multi-Viewport Preview
See all breakpoints simultaneously in the browser, with hot reload:
node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000
node ${CLAUDE_SKILL_DIR}/scripts/preview.js ./index.html
node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000 --breakpoints 375,768,1024,1440,1920
Responsive Snapshots
Capture screenshots at every breakpoint. Supports before/after comparison:
# Capture current state
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
# Capture baseline, make changes, then capture again for comparison
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000 --before
# ... make responsive changes ...
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
# → generates comparison.html with before/after at each breakpoint
Both tools require no dependencies — just Node.js. Snapshots require dev-browser for headless screenshots.
Reference Index
| File |
Contents |
Load when |
| modern-css-patterns.md |
Container queries, clamp(), subgrid, :has(), viewport units, scroll-driven animations, nesting, @layer, logical properties |
Writing or reviewing responsive CSS |
| sticky-scroll-patterns.md |
Sticky coordination, scroll-snap, independent scroll regions, responsive data tables, modals/sheets, IntersectionObserver |
Working with sticky, scroll, or complex layout patterns |
| responsive-design-forks.md |
8 ambiguous desktop→mobile translations with options and tradeoffs |
When a responsive translation has no single right answer |
| ai-failure-patterns.md |
13 categories of AI responsive failures with bad/good code examples, pre-flight scan checklist |
Pre-flight scan before outputting responsive code |
| testing-checklist.md |
Priority viewports, 10-point check, edge cases, three-tier testing strategy, Playwright patterns |
Verification step after implementation |
Workflow Index
| Workflow |
Purpose |
| transform-existing.md |
Audit → identify forks → fix responsive issues in priority order |
| build-responsive.md |
Describe behavior → establish foundation → build mobile-first → verify |
| preview.md |
Launch live multi-breakpoint preview in the browser |
1---
2name: responsive-craft
3description: "Implement responsive design for websites and web apps — from standard mobile-first layouts to complex patterns (sticky elements, scroll coordination, data tables, dashboards). Three modes: transform existing sites, build responsive from scratch, or launch a live multi-breakpoint preview. Surfaces design forks where there's no single right answer. Use when building responsive layouts, fixing mobile issues, adding breakpoints, working with sticky/scroll patterns, previewing breakpoints, or when the user mentions responsive, mobile, breakpoints, viewport, adaptive design, or responsive preview."
4argument-hint: "[audit|build|preview]"
5metadata:
6 source: https://skillmd.com/skills/kylezantos/responsive-craft
7---
8
9# Responsive Craft
10
11Implement responsive design that works across all viewports — compensating for the lack of a visual canvas by making deliberate decisions upfront.
12
13## Quick Start
14
15**Transform an existing site:** `/responsive-craft audit` or "make this responsive" or "fix the mobile layout"
16**Build responsive from scratch:** `/responsive-craft build` or "build this mobile-first" or "create a responsive layout"
17**Preview all breakpoints:** `/responsive-craft preview` or "show me the responsive preview" or "open the breakpoint preview"
18
19---
20
21## Core Principles
22
231. **Escalation model** — Intrinsic CSS first (`auto-fit`, `flex-wrap`, `clamp()`) → container queries next (component-level) → media queries last (page-level only). If a simpler layer solves it, stop there.
24
252. **Describe before you code** — Without a canvas, explicitly describe responsive behavior before writing CSS. In Adaptive mode, use inline behavior notes (CSS comments). In Guided mode, write formal behavior specs (tables per component). Both catch design decisions a canvas would reveal passively.
26
273. **Fluid by default, breakpoints by exception** — Use `clamp()` for typography, spacing, sizing. Reserve hard breakpoints for structural changes: nav transforms, column count shifts, sidebar visibility.
28
294. **Component containment** — Components respond to their container, not the viewport. Use container queries. A card in a sidebar and a card in a full-width section should use the same CSS.
30
315. **Test by dragging, not jumping** — Slowly resize from 280px to 2560px in DevTools. Don't just check named breakpoints. This catches in-between failures.
32
336. **Sticky/scroll needs explicit patterns** — Sticky coordination, z-index stacking contexts, overflow ancestors, safe areas, virtual keyboards. These break silently. Use the patterns in `references/sticky-scroll-patterns.md`, don't improvise.
34
357. **Recognize design forks, don't default silently** — When a responsive translation has multiple valid approaches, present 2-3 options with tradeoffs and ask the user to choose. See `references/responsive-design-forks.md`.
36
37---
38
39## The Three-Layer Responsive System
40
41| Layer | Tool | Handles |
42|-------|------|---------|
43| Continuous | `clamp()`, fluid tokens, `cqi` units | Smooth scaling — font size, padding, gap |
44| Component | Container queries (`@container`) | Adapting to context — card layout, nav items |
45| Structural | Media queries (`@media`) | Page-level shifts — grid columns, nav transform, sidebar |
46
47### Escalation Decision Tree
48
49```
50Does this need to change layout?
51 No → clamp() for sizing. Done.
52 Yes → Does it depend on CONTAINER size?
53 Yes → Container query
54 No → Does it depend on VIEWPORT?
55 Yes → Media query (page-level only)
56 No → :has() or intrinsic sizing (auto-fit, flex-wrap)
57```
58
59---
60
61## Mode Selection
62
63This skill operates in three modes. Detect from `$ARGUMENTS` or ask.
64
65### Detection
66
67- `$ARGUMENTS` contains "preview", "show breakpoints", "live preview" → **Preview**
68- `$ARGUMENTS` contains "audit", "transform", "fix", "improve", "retrofit" → **Transform Existing**
69- `$ARGUMENTS` contains "build", "create", "new", "from scratch" → **Build Responsive**
70- User is working in an existing codebase with responsive issues → **Transform Existing**
71- User is starting a new page/component → **Build Responsive**
72- Ambiguous → Ask
73
74If AskUserQuestion is available:
75- **Transform existing** — Audit and improve responsive behavior of current code
76- **Build from scratch** — Design responsive layout from the start
77- **Preview** — Launch a live multi-breakpoint preview in the browser
78
79Otherwise: "Are you transforming an existing site's responsive design, building something new, or just previewing?"
80
81### Interactivity Level
82
83**Skip for Preview mode** — go straight to routing.
84
85After mode selection, determine interactivity:
86
87If AskUserQuestion is available:
88- **Adaptive** — Moves fast. 1-2 discovery questions, then starts working. Surfaces design forks inline as they arise. No formal specs — decisions are made in the moment.
89- **Guided** — Produces deliverables. Full discovery, writes behavior specs per component before coding, gets explicit approval before each stage. Best for complex layouts or when the user wants a spec to reference later.
90
91Otherwise: "Do you want (1) Adaptive — fast, I'll ask as I go, or (2) Guided — I'll write behavior specs per component and get your approval before coding?"
92
93**Default to Adaptive** if the user doesn't express a preference.
94
95**When to recommend Guided:** If the layout has 5+ distinct responsive components, multiple sticky elements, or a dashboard-style layout, suggest Guided — the behavior specs prevent expensive rework later.
96
97---
98
99## Routing
100
101After mode and interactivity are selected:
102
103| Mode | Read workflow | Load immediately |
104|------|-------------|-----------------|
105| Preview | `workflows/preview.md` | None |
106| Transform Existing | `workflows/transform-existing.md` | `references/ai-failure-patterns.md` |
107| Build Responsive | `workflows/build-responsive.md` | `references/modern-css-patterns.md`, `references/ai-failure-patterns.md` |
108
109Load other references on demand:
110- `references/sticky-scroll-patterns.md` — when sticky, scroll-snap, or independent scroll regions are involved
111- `references/responsive-design-forks.md` — when an ambiguous responsive translation is detected
112- `references/testing-checklist.md` — during verification step
113- `references/modern-css-patterns.md` — during Transform mode when implementing fixes
114
115---
116
117## Gotchas — Where Claude Fails at Responsive Design
118
119These are the most common mistakes. Check every responsive output against this list.
120
1211. **`100vh` on mobile** — Use `svh`/`dvh` with `vh` fallback. `100vh` overflows behind mobile browser chrome.
122
1232. **Desktop-first media queries** — Always use `min-width` (mobile-first), not `max-width`. Mobile loads fewer overrides.
124
1253. **Missing `min-width: 0` on flex children** — Default flex `min-width` is `auto` (content size). Long text/images overflow. Add `min-width: 0` when content is dynamic.
126
1274. **`overflow: hidden` kills sticky** — Any ancestor with `overflow: hidden/scroll/auto` breaks `position: sticky`. Use `overflow: clip` for visual clipping.
128
1295. **`transform` breaks `position: fixed`** — Any transform on an ancestor makes fixed children position relative to that ancestor, not viewport.
130
1316. **iOS input zoom below 16px** — Input `font-size` under 16px triggers Safari viewport zoom. Use `font-size: max(16px, 1rem)`.
132
1337. **Missing safe area insets** — Notched devices need `env(safe-area-inset-*)`. Requires `viewport-fit=cover` in meta tag. Don't forget landscape orientation.
134
1358. **Z-index escalation** — Values like `9999` signal misunderstanding of stacking contexts. Use `isolation: isolate` and a tiered z-index scale.
136
1379. **Missing `align-self: start` on sticky in flex/grid** — Without this, the element stretches to full height and sticky has no room to stick. The #1 silent sticky failure.
138
13910. **Optimizing for one viewport** — Code that looks perfect at 1440px breaks at 320px, 768px portrait, and ultrawide. Always test the full range.
140
141For the complete list with code examples, see `references/ai-failure-patterns.md`.
142
143---
144
145## Tools
146
147This skill includes two CLI tools in `scripts/` for visual responsive verification.
148
149### Live Multi-Viewport Preview
150
151See all breakpoints simultaneously in the browser, with hot reload:
152
153```bash
154node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000
155node ${CLAUDE_SKILL_DIR}/scripts/preview.js ./index.html
156node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000 --breakpoints 375,768,1024,1440,1920
157```
158
159### Responsive Snapshots
160
161Capture screenshots at every breakpoint. Supports before/after comparison:
162
163```bash
164# Capture current state
165node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
166
167# Capture baseline, make changes, then capture again for comparison
168node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000 --before
169# ... make responsive changes ...
170node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
171# → generates comparison.html with before/after at each breakpoint
172```
173
174Both tools require no dependencies — just Node.js. Snapshots require `dev-browser` for headless screenshots.
175
176---
177
178## Reference Index
179
180| File | Contents | Load when |
181|------|----------|-----------|
182| [modern-css-patterns.md](references/modern-css-patterns.md) | Container queries, clamp(), subgrid, :has(), viewport units, scroll-driven animations, nesting, @layer, logical properties | Writing or reviewing responsive CSS |
183| [sticky-scroll-patterns.md](references/sticky-scroll-patterns.md) | Sticky coordination, scroll-snap, independent scroll regions, responsive data tables, modals/sheets, IntersectionObserver | Working with sticky, scroll, or complex layout patterns |
184| [responsive-design-forks.md](references/responsive-design-forks.md) | 8 ambiguous desktop→mobile translations with options and tradeoffs | When a responsive translation has no single right answer |
185| [ai-failure-patterns.md](references/ai-failure-patterns.md) | 13 categories of AI responsive failures with bad/good code examples, pre-flight scan checklist | Pre-flight scan before outputting responsive code |
186| [testing-checklist.md](references/testing-checklist.md) | Priority viewports, 10-point check, edge cases, three-tier testing strategy, Playwright patterns | Verification step after implementation |
187
188## Workflow Index
189
190| Workflow | Purpose |
191|----------|---------|
192| [transform-existing.md](workflows/transform-existing.md) | Audit → identify forks → fix responsive issues in priority order |
193| [build-responsive.md](workflows/build-responsive.md) | Describe behavior → establish foundation → build mobile-first → verify |
194| [preview.md](workflows/preview.md) | Launch live multi-breakpoint preview in the browser |