# Responsive Craft > 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 mobil… - **Type:** Skill - **Install:** `agentstack add skill-tommylower-cortex-responsive-craft` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [tommylower](https://agentstack.voostack.com/s/tommylower) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [tommylower](https://github.com/tommylower) - **Source:** https://github.com/tommylower/cortex/tree/main/design/foundations/responsive-craft ## Install ```sh agentstack add skill-tommylower-cortex-responsive-craft ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 1. **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. 2. **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. 3. **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. 4. **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. 5. **Test by dragging, not jumping** — Slowly resize from 280px to 2560px in DevTools. Don't just check named breakpoints. This catches in-between failures. 6. **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. 7. **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. 1. **`100vh` on mobile** — Use `svh`/`dvh` with `vh` fallback. `100vh` overflows behind mobile browser chrome. 2. **Desktop-first media queries** — Always use `min-width` (mobile-first), not `max-width`. Mobile loads fewer overrides. 3. **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. 4. **`overflow: hidden` kills sticky** — Any ancestor with `overflow: hidden/scroll/auto` breaks `position: sticky`. Use `overflow: clip` for visual clipping. 5. **`transform` breaks `position: fixed`** — Any transform on an ancestor makes fixed children position relative to that ancestor, not viewport. 6. **iOS input zoom below 16px** — Input `font-size` under 16px triggers Safari viewport zoom. Use `font-size: max(16px, 1rem)`. 7. **Missing safe area insets** — Notched devices need `env(safe-area-inset-*)`. Requires `viewport-fit=cover` in meta tag. Don't forget landscape orientation. 8. **Z-index escalation** — Values like `9999` signal misunderstanding of stacking contexts. Use `isolation: isolate` and a tiered z-index scale. 9. **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. 10. **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. Run these commands from this skill directory, or replace `scripts/...` with the absolute path to this skill's `scripts/` folder. ### Live Multi-Viewport Preview See all breakpoints simultaneously in the browser, with hot reload: ```bash node scripts/preview.js http://localhost:3000 node scripts/preview.js ./index.html node scripts/preview.js http://localhost:3000 --breakpoints 375,768,1024,1440,1920 ``` ### Responsive Snapshots Capture screenshots at every breakpoint. Supports before/after comparison: ```bash # Capture current state node scripts/snapshot.js http://localhost:3000 # Capture baseline, make changes, then capture again for comparison node scripts/snapshot.js http://localhost:3000 --before # ... make responsive changes ... node 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](references/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](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 | | [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 | | [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 | | [testing-checklist.md](references/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](workflows/transform-existing.md) | Audit → identify forks → fix responsive issues in priority order | | [build-responsive.md](workflows/build-responsive.md) | Describe behavior → establish foundation → build mobile-first → verify | | [preview.md](workflows/preview.md) | Launch live multi-breakpoint preview in the browser | ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [tommylower](https://github.com/tommylower) - **Source:** [tommylower/cortex](https://github.com/tommylower/cortex) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-tommylower-cortex-responsive-craft - Seller: https://agentstack.voostack.com/s/tommylower - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.