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 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.
Badge for your README
Markdown
[](/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
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)
- ---
- name: responsive-craft
- 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."
- argument-hint: "[audit|build|preview]"
- ---
- # 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.
- ### Live Multi-Viewport Preview
- See all breakpoints simultaneously in the browser, with hot reload:
- ```bash
- 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:
- ```bash
- # 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](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 |
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)
- # responsive-craft
- 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.
- ## The Problem
- 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.
- **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.
- ## What It Does
- ### Three Modes
- - **Transform Existing** (`/responsive-craft audit`) — Audits your current codebase's responsive implementation, identifies issues and ambiguous translations, and fixes them in priority order.
- - **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.
- - **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.
- ### Two Interactivity Levels
- - **Adaptive** — Moves fast. Quick discovery, surfaces design decisions inline as they come up.
- - **Guided** — Produces formal behavior specs per component before coding. Best for complex layouts.
- ### Design Forks
- 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.
- 8 fork patterns covered: sidebar content, data tables, multi-panel dashboards, complex heroes, multiple sticky elements, deep navigation, complex forms, and bento grids.
- ## Core Principles
- 1. **Escalation model** — Intrinsic CSS first (`auto-fit`, `flex-wrap`, `clamp()`) → container queries → media queries last
- 2. **Describe before you code** — Behavior notes or specs per component before writing CSS
- 3. **Fluid by default, breakpoints by exception** — `clamp()` for continuous scaling; breakpoints only for structural changes
- 4. **Component containment** — Components respond to their container, not the viewport
- 5. **Test by dragging, not jumping** — Resize continuously from 280px to 2560px
- 6. **Sticky/scroll needs explicit patterns** — These break silently; use documented patterns
- 7. **Recognize design forks** — Don't default silently when there are multiple valid approaches
- ## What's Inside
- ```
- responsive-craft/
- ├── SKILL.md # Core principles, routing, gotchas
- ├── workflows/
- │ ├── transform-existing.md # Audit → forks → fix existing sites
- │ ├── build-responsive.md # Describe → foundation → build mobile-first
- │ └── preview.md # Launch live multi-breakpoint preview
- ├── scripts/
- │ ├── preview.js # Serves preview.html over HTTP, opens browser
- │ ├── preview.html # Multi-viewport iframe UI (dark theme, toolbar, scale toggle)
- │ ├── snapshot.js # Headless screenshots at every breakpoint
- │ └── serve-static.js # Zero-dependency static server with live reload
- ├── references/
- │ ├── modern-css-patterns.md # Container queries, clamp(), subgrid, :has(), viewport units, @layer
- │ ├── sticky-scroll-patterns.md # Sticky coordination, scroll-snap, scroll regions, modals/sheets
- │ ├── responsive-design-forks.md # 8 ambiguous patterns with options and tradeoffs
- │ ├── ai-failure-patterns.md # 13 categories of where AI breaks responsive code
- │ └── testing-checklist.md # Priority viewports, 10-point check, testing strategy
- └── README.md
- ```
- ### Reference Highlights
- - **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.
- - **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.
- - **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.
- ### Live Preview
- 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.
- Run `/responsive-craft preview` to launch it standalone, or it's offered automatically at the end of every audit and build workflow.
- The preview tool:
- - Serves everything over HTTP automatically (no cross-origin iframe issues)
- - Works with any dev server (Vite, Next.js, etc.) or static HTML files
- - Supports custom breakpoints via `--breakpoints` flag
- - Cleans up after itself on exit
- ## Install
- ### One command (all agents)
- ```bash
- 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
- ```bash
- 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:
- ```bash
- git clone https://github.com/kylezantos/responsive-craft.git ~/.claude/skills/responsive-craft
- ```
- ## Usage
- ```
- # Transform an existing site
- /responsive-craft audit
- # Build responsive from scratch
- /responsive-craft build
- # Open a live multi-breakpoint preview
- /responsive-craft preview
- # Claude also auto-detects when you're working on responsive layouts
- "make this responsive"
- "fix the mobile layout"
- "the sidebar breaks on tablet"
- "show me the responsive preview"
- ```
- ## Framework Support
- The skill detects your CSS approach and adapts output:
- - **Tailwind CSS** — Uses responsive modifiers, `@container` variants, `@theme` tokens
- - **Component libraries** (MUI, Chakra, shadcn) — Works with the library's responsive system
- - **CSS-in-JS** — Same patterns, expressed through the library's API
- - **Vanilla CSS** — Patterns applied directly
- ## Cross-Agent Compatibility
- **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.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.