Skip to content
Back to search

responsive-craft

SkillWorks with Claude CodeGitHub

"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."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kylezantos--responsive-craft/badge.svg)](/listings/kylezantos--responsive-craft)

HTML

<a href="/listings/kylezantos--responsive-craft"><img src="/api/listings/kylezantos--responsive-craft/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One command (all agents)

npx skills add kylezantos/responsive-craft

Auto-detects your installed agents and installs to each. Works with Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Windsurf, and [35+ more](https://github.com/vercel-labs/skills).

Target specific agents

npx skills add kylezantos/responsive-craft -a claude-code
npx skills add kylezantos/responsive-craft -a codex -a opencode

Manual install

Copy the entire `responsive-craft/` directory into your agent's skills path:

| Agent | Path | |-------|------| | Claude Code | `~/.claude/skills/responsive-craft/` | | Codex | `~/.codex/skills/responsive-craft/` | | OpenCode | `~/.config/opencode/skills/responsive-craft/` | | Cursor | `~/.cursor/skills/responsive-craft/` | | Gemini CLI | `~/.gemini/skills/responsive-craft/` | | Windsurf | `~/.codeium/windsurf/skills/responsive-craft/` |

Or clone:

git clone https://github.com/kylezantos/responsive-craft.git ~/.claude/skills/responsive-craft

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 192 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: responsive-craft
  3. description: "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."
  4. argument-hint: "[audit|build|preview]"
  5. ---
  6. # Responsive Craft
  7. Implement responsive design that works across all viewports — compensating for the lack of a visual canvas by making deliberate decisions upfront.
  8. ## Quick Start
  9. **Transform an existing site:** `/responsive-craft audit` or "make this responsive" or "fix the mobile layout"
  10. **Build responsive from scratch:** `/responsive-craft build` or "build this mobile-first" or "create a responsive layout"
  11. **Preview all breakpoints:** `/responsive-craft preview` or "show me the responsive preview" or "open the breakpoint preview"
  12. ---
  13. ## Core Principles
  14. 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.
  15. 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.
  16. 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.
  17. 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.
  18. 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.
  19. 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.
  20. 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`.
  21. ---
  22. ## The Three-Layer Responsive System
  23. | Layer | Tool | Handles |
  24. |-------|------|---------|
  25. | Continuous | `clamp()`, fluid tokens, `cqi` units | Smooth scaling — font size, padding, gap |
  26. | Component | Container queries (`@container`) | Adapting to context — card layout, nav items |
  27. | Structural | Media queries (`@media`) | Page-level shifts — grid columns, nav transform, sidebar |
  28. ### Escalation Decision Tree
  29. ```
  30. Does this need to change layout?
  31. No → clamp() for sizing. Done.
  32. Yes → Does it depend on CONTAINER size?
  33. Yes → Container query
  34. No → Does it depend on VIEWPORT?
  35. Yes → Media query (page-level only)
  36. No → :has() or intrinsic sizing (auto-fit, flex-wrap)
  37. ```
  38. ---
  39. ## Mode Selection
  40. This skill operates in three modes. Detect from `$ARGUMENTS` or ask.
  41. ### Detection
  42. - `$ARGUMENTS` contains "preview", "show breakpoints", "live preview" → **Preview**
  43. - `$ARGUMENTS` contains "audit", "transform", "fix", "improve", "retrofit" → **Transform Existing**
  44. - `$ARGUMENTS` contains "build", "create", "new", "from scratch" → **Build Responsive**
  45. - User is working in an existing codebase with responsive issues → **Transform Existing**
  46. - User is starting a new page/component → **Build Responsive**
  47. - Ambiguous → Ask
  48. If AskUserQuestion is available:
  49. - **Transform existing** — Audit and improve responsive behavior of current code
  50. - **Build from scratch** — Design responsive layout from the start
  51. - **Preview** — Launch a live multi-breakpoint preview in the browser
  52. Otherwise: "Are you transforming an existing site's responsive design, building something new, or just previewing?"
  53. ### Interactivity Level
  54. **Skip for Preview mode** — go straight to routing.
  55. After mode selection, determine interactivity:
  56. If AskUserQuestion is available:
  57. - **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.
  58. - **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.
  59. 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?"
  60. **Default to Adaptive** if the user doesn't express a preference.
  61. **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.
  62. ---
  63. ## Routing
  64. After mode and interactivity are selected:
  65. | Mode | Read workflow | Load immediately |
  66. |------|-------------|-----------------|
  67. | Preview | `workflows/preview.md` | None |
  68. | Transform Existing | `workflows/transform-existing.md` | `references/ai-failure-patterns.md` |
  69. | Build Responsive | `workflows/build-responsive.md` | `references/modern-css-patterns.md`, `references/ai-failure-patterns.md` |
  70. Load other references on demand:
  71. - `references/sticky-scroll-patterns.md` — when sticky, scroll-snap, or independent scroll regions are involved
  72. - `references/responsive-design-forks.md` — when an ambiguous responsive translation is detected
  73. - `references/testing-checklist.md` — during verification step
  74. - `references/modern-css-patterns.md` — during Transform mode when implementing fixes
  75. ---
  76. ## Gotchas — Where Claude Fails at Responsive Design
  77. These are the most common mistakes. Check every responsive output against this list.
  78. 1. **`100vh` on mobile** — Use `svh`/`dvh` with `vh` fallback. `100vh` overflows behind mobile browser chrome.
  79. 2. **Desktop-first media queries** — Always use `min-width` (mobile-first), not `max-width`. Mobile loads fewer overrides.
  80. 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.
  81. 4. **`overflow: hidden` kills sticky** — Any ancestor with `overflow: hidden/scroll/auto` breaks `position: sticky`. Use `overflow: clip` for visual clipping.
  82. 5. **`transform` breaks `position: fixed`** — Any transform on an ancestor makes fixed children position relative to that ancestor, not viewport.
  83. 6. **iOS input zoom below 16px** — Input `font-size` under 16px triggers Safari viewport zoom. Use `font-size: max(16px, 1rem)`.
  84. 7. **Missing safe area insets** — Notched devices need `env(safe-area-inset-*)`. Requires `viewport-fit=cover` in meta tag. Don't forget landscape orientation.
  85. 8. **Z-index escalation** — Values like `9999` signal misunderstanding of stacking contexts. Use `isolation: isolate` and a tiered z-index scale.
  86. 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.
  87. 10. **Optimizing for one viewport** — Code that looks perfect at 1440px breaks at 320px, 768px portrait, and ultrawide. Always test the full range.
  88. For the complete list with code examples, see `references/ai-failure-patterns.md`.
  89. ---
  90. ## Tools
  91. This skill includes two CLI tools in `scripts/` for visual responsive verification.
  92. ### Live Multi-Viewport Preview
  93. See all breakpoints simultaneously in the browser, with hot reload:
  94. ```bash
  95. node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000
  96. node ${CLAUDE_SKILL_DIR}/scripts/preview.js ./index.html
  97. node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000 --breakpoints 375,768,1024,1440,1920
  98. ```
  99. ### Responsive Snapshots
  100. Capture screenshots at every breakpoint. Supports before/after comparison:
  101. ```bash
  102. # Capture current state
  103. node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
  104. # Capture baseline, make changes, then capture again for comparison
  105. node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000 --before
  106. # ... make responsive changes ...
  107. node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
  108. # → generates comparison.html with before/after at each breakpoint
  109. ```
  110. Both tools require no dependencies — just Node.js. Snapshots require `dev-browser` for headless screenshots.
  111. ---
  112. ## Reference Index
  113. | File | Contents | Load when |
  114. |------|----------|-----------|
  115. | [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 |
  116. | [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 |
  117. | [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 |
  118. | [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 |
  119. | [testing-checklist.md](references/testing-checklist.md) | Priority viewports, 10-point check, edge cases, three-tier testing strategy, Playwright patterns | Verification step after implementation |
  120. ## Workflow Index
  121. | Workflow | Purpose |
  122. |----------|---------|
  123. | [transform-existing.md](workflows/transform-existing.md) | Audit → identify forks → fix responsive issues in priority order |
  124. | [build-responsive.md](workflows/build-responsive.md) | Describe behavior → establish foundation → build mobile-first → verify |
  125. | [preview.md](workflows/preview.md) | Launch live multi-breakpoint preview in the browser |
README.md · README · 152 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # responsive-craft
  2. A Claude Code skill for implementing responsive design across websites and web apps — from standard mobile-first layouts to complex patterns like sticky element coordination, independent scroll regions, responsive data tables, and dashboard layouts.
  3. ## The Problem
  4. When you're building responsive layouts in Claude Code (or any code-first environment), you don't have a visual canvas like Figma or Framer where you can see all breakpoints side by side. This means responsive design decisions get made reactively — you write code, preview, resize, and fix — instead of deliberately.
  5. **responsive-craft** compensates for this by front-loading the right decisions: describing responsive behavior before writing CSS, using an escalation model that picks the simplest tool for each job, and surfacing design forks where there's no single correct answer.
  6. ## What It Does
  7. ### Three Modes
  8. - **Transform Existing** (`/responsive-craft audit`) — Audits your current codebase's responsive implementation, identifies issues and ambiguous translations, and fixes them in priority order.
  9. - **Build From Scratch** (`/responsive-craft build`) — Helps you design responsive behavior before writing CSS, establishes a mobile-first foundation, and builds with the right CSS tool for each pattern.
  10. - **Live Preview** (`/responsive-craft preview`) — Opens a multi-breakpoint preview in your browser with interactive iframes at 375px, 768px, 1024px, and 1440px, all pointing at your dev server. Scroll, click, and navigate each viewport independently. Also offered automatically after completing an audit or build.
  11. ### Two Interactivity Levels
  12. - **Adaptive** — Moves fast. Quick discovery, surfaces design decisions inline as they come up.
  13. - **Guided** — Produces formal behavior specs per component before coding. Best for complex layouts.
  14. ### Design Forks
  15. The skill's key differentiator. When a responsive translation has multiple valid approaches — a sidebar that could become a drawer, tabs, or an accordion; a data table that could scroll, stack as cards, or hide columns — the skill presents 2-3 options with tradeoffs and asks you to choose instead of silently picking one.
  16. 8 fork patterns covered: sidebar content, data tables, multi-panel dashboards, complex heroes, multiple sticky elements, deep navigation, complex forms, and bento grids.
  17. ## Core Principles
  18. 1. **Escalation model** — Intrinsic CSS first (`auto-fit`, `flex-wrap`, `clamp()`) → container queries → media queries last
  19. 2. **Describe before you code** — Behavior notes or specs per component before writing CSS
  20. 3. **Fluid by default, breakpoints by exception** — `clamp()` for continuous scaling; breakpoints only for structural changes
  21. 4. **Component containment** — Components respond to their container, not the viewport
  22. 5. **Test by dragging, not jumping** — Resize continuously from 280px to 2560px
  23. 6. **Sticky/scroll needs explicit patterns** — These break silently; use documented patterns
  24. 7. **Recognize design forks** — Don't default silently when there are multiple valid approaches
  25. ## What's Inside
  26. ```
  27. responsive-craft/
  28. ├── SKILL.md # Core principles, routing, gotchas
  29. ├── workflows/
  30. │ ├── transform-existing.md # Audit → forks → fix existing sites
  31. │ ├── build-responsive.md # Describe → foundation → build mobile-first
  32. │ └── preview.md # Launch live multi-breakpoint preview
  33. ├── scripts/
  34. │ ├── preview.js # Serves preview.html over HTTP, opens browser
  35. │ ├── preview.html # Multi-viewport iframe UI (dark theme, toolbar, scale toggle)
  36. │ ├── snapshot.js # Headless screenshots at every breakpoint
  37. │ └── serve-static.js # Zero-dependency static server with live reload
  38. ├── references/
  39. │ ├── modern-css-patterns.md # Container queries, clamp(), subgrid, :has(), viewport units, @layer
  40. │ ├── sticky-scroll-patterns.md # Sticky coordination, scroll-snap, scroll regions, modals/sheets
  41. │ ├── responsive-design-forks.md # 8 ambiguous patterns with options and tradeoffs
  42. │ ├── ai-failure-patterns.md # 13 categories of where AI breaks responsive code
  43. │ └── testing-checklist.md # Priority viewports, 10-point check, testing strategy
  44. └── README.md
  45. ```
  46. ### Reference Highlights
  47. - **modern-css-patterns.md** — The 2026 CSS responsive toolkit: container queries, `clamp()` with Utopia-style fluid scales, subgrid, `:has()` for content-conditional layouts, modern viewport units (`svh`/`dvh`), scroll-driven animations, CSS nesting, `@layer`, logical properties. Includes Tailwind mappings.
  48. - **ai-failure-patterns.md** — 13 specific, recurring mistakes AI makes with responsive CSS: `100vh` on mobile, desktop-first queries, missing `min-width: 0` on flex children, `overflow: hidden` killing sticky, iOS input zoom, z-index escalation, and more. Each with bad output, why it breaks, and the correct pattern. Includes a pre-flight scan checklist.
  49. - **sticky-scroll-patterns.md** — Production patterns for the complex stuff: coordinating multiple sticky elements with CSS custom properties, debugging sticky failures, scroll-snap carousels, independent scroll regions (dashboard pattern), sticky + responsive transitions, IntersectionObserver for stuck detection.
  50. ### Live Preview
  51. The standout verification tool. When you can't drag-resize a browser in a code-first environment, this gives you the next best thing — all your key breakpoints rendered simultaneously in real, interactive iframes. No screenshots, no mocking — actual live pages you can scroll and click through.
  52. Run `/responsive-craft preview` to launch it standalone, or it's offered automatically at the end of every audit and build workflow.
  53. The preview tool:
  54. - Serves everything over HTTP automatically (no cross-origin iframe issues)
  55. - Works with any dev server (Vite, Next.js, etc.) or static HTML files
  56. - Supports custom breakpoints via `--breakpoints` flag
  57. - Cleans up after itself on exit
  58. ## Install
  59. ### One command (all agents)
  60. ```bash
  61. npx skills add kylezantos/responsive-craft
  62. ```
  63. Auto-detects your installed agents and installs to each. Works with Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Windsurf, and [35+ more](https://github.com/vercel-labs/skills).
  64. ### Target specific agents
  65. ```bash
  66. npx skills add kylezantos/responsive-craft -a claude-code
  67. npx skills add kylezantos/responsive-craft -a codex -a opencode
  68. ```
  69. ### Manual install
  70. Copy the entire `responsive-craft/` directory into your agent's skills path:
  71. | Agent | Path |
  72. |-------|------|
  73. | Claude Code | `~/.claude/skills/responsive-craft/` |
  74. | Codex | `~/.codex/skills/responsive-craft/` |
  75. | OpenCode | `~/.config/opencode/skills/responsive-craft/` |
  76. | Cursor | `~/.cursor/skills/responsive-craft/` |
  77. | Gemini CLI | `~/.gemini/skills/responsive-craft/` |
  78. | Windsurf | `~/.codeium/windsurf/skills/responsive-craft/` |
  79. Or clone:
  80. ```bash
  81. git clone https://github.com/kylezantos/responsive-craft.git ~/.claude/skills/responsive-craft
  82. ```
  83. ## Usage
  84. ```
  85. # Transform an existing site
  86. /responsive-craft audit
  87. # Build responsive from scratch
  88. /responsive-craft build
  89. # Open a live multi-breakpoint preview
  90. /responsive-craft preview
  91. # Claude also auto-detects when you're working on responsive layouts
  92. "make this responsive"
  93. "fix the mobile layout"
  94. "the sidebar breaks on tablet"
  95. "show me the responsive preview"
  96. ```
  97. ## Framework Support
  98. The skill detects your CSS approach and adapts output:
  99. - **Tailwind CSS** — Uses responsive modifiers, `@container` variants, `@theme` tokens
  100. - **Component libraries** (MUI, Chakra, shadcn) — Works with the library's responsive system
  101. - **CSS-in-JS** — Same patterns, expressed through the library's API
  102. - **Vanilla CSS** — Patterns applied directly
  103. ## Cross-Agent Compatibility
  104. **Degrades Gracefully** — Core functionality works on any AI coding agent. Claude Code users get tappable mode selection via AskUserQuestion; other agents get plain-text fallbacks.
  105. ## License
  106. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.