| name | design-handoff |
| description | Use this skill whenever a user receives a Claude Design handoff bundle and wants to implement it in code using Claude Code. Triggers include: "I got a handoff bundle from Claude Design", "implement this Claude Design prototype", "turn this design handoff into code", "I exported from Claude Design and want to build it", pasting a bundle URL from claude.ai/design, or any mention of a Claude Design → Claude Code export. Also trigger when a user says "build this from the design spec" and a bundle URL or zip is present. This skill is essential — do not attempt a Claude Design handoff without it.
|
Claude Design Handoff Skill
Claude Design exports a structured handoff bundle when you click Export → Hand off to Claude Code.
This bundle contains everything needed to implement the design in production code.
What's in a Handoff Bundle
The bundle includes:
- design files — SVG/HTML snapshots of each screen/section
- design tokens — colors, spacing, typography as named variables (often Tailwind or CSS custom properties)
- component tree — named components and their nesting structure
- interaction notes — hover states, transitions, edge cases (empty/error/loading states)
- copy variants — text strings tested in the tweaks panel
- README.md — Claude's own instructions for how to interpret and implement the bundle
- prompt.txt — a ready-made prompt you can paste into Claude Code (or any coding agent)
Step-by-Step Implementation Workflow
1. Receive the Bundle
The user will have one of:
- A bundle URL (e.g.
https://claude.ai/design/handoff/...) — fetch and read the README + prompt
- A downloaded zip — unzip and read
README.md first
- A pasted prompt from
prompt.txt — proceed directly from step 3
2. Read the README First
The README is authoritative. It tells you:
- Which framework/stack to target (React, Next.js, Vue, plain HTML, etc.)
- Which design system or component library is expected (Tailwind, shadcn/ui, MUI, etc.)
- Any codebase-specific conventions extracted during Claude Design's brand extraction phase
- Which files to create or modify
Always follow the README over your own assumptions.
3. Extract Design Tokens
Before writing any component code, extract and declare all tokens:
:root {
--color-primary: #1a1a2e;
--color-accent: #e94560;
--font-heading: 'Inter', sans-serif;
--spacing-section: 4rem;
--radius-card: 0.75rem;
}
Or for Tailwind projects, extend tailwind.config.js with the extracted values.
Key rule: Never hardcode hex values or pixel sizes inline. Always reference tokens.
4. Build the Component Tree Top-Down
Follow the component tree from the bundle. Typical order:
- Layout shell (page wrapper, grid/flex containers)
- Navigation / header
- Hero / primary content sections
- Reusable cards, lists, form elements
- Footer
- Overlay states (modals, drawers, tooltips)
For each component:
- Match the exact name used in the design chat (names carry through from Claude Design)
- Implement the happy path first, then add edge states (see step 6)
5. Match Typography and Spacing Exactly
Claude Design's brand extraction is precise. Match:
font-family, font-weight, font-size, line-height, letter-spacing- Margin/padding using the token values, not approximations
- Color contrast — check accessibility of text/background pairs
6. Implement All Edge States
The bundle's interaction notes document states that must be coded:
- Empty state — no data / first-time user
- Loading state — skeleton or spinner matching the layout
- Error state — inline messages or banners
- Different data volumes — short text, long text, many items, zero items
Do not skip these. They are part of the handoff, not optional.
7. Wire Up Interactions
From the interaction notes, implement:
- Hover and focus styles (use CSS transitions matching bundle specs)
- Toggle/accordion behavior
- Navigation transitions
- Form validation feedback
8. Verify Against Design Snapshots
Once implemented, compare your output to the design files in the bundle:
- Layout alignment (use browser dev tools grid overlay if needed)
- Color accuracy (eyedrop-verify key brand colors)
- Spacing rhythm (check consistent use of token spacing units)
- Responsive breakpoints (Claude Design prototypes are usually desktop-first; add mobile breakpoints)
9. Report Back
After implementation, summarize:
- Files created or modified
- Any design decisions made where the bundle was ambiguous
- Any tokens or components not yet implemented (with reason)
- Recommended next steps (e.g. "connect API endpoints", "add animation library")
Common Issues and Fixes
| Issue | Fix |
|---|
| Bundle URL returns 403 | Ask user to download the zip and share files directly |
| Framework mismatch | Check README; ask user to confirm their stack if unclear |
| Missing font | Add Google Fonts or local font import matching the token |
| Token names don't match codebase | Map bundle token names to existing project variables |
| Design uses components not in codebase | Build a new component; name it exactly as in the bundle |
Tips for Linked-Codebase Bundles
If the user's codebase was linked in Claude Design during the design phase, the bundle is production-aware — it references real components and patterns. In this case:
- Import real components instead of creating new ones
- Respect existing naming conventions
- Check the
components/ or src/ directory for matching implementations before writing anything new
This is the most valuable scenario: the handoff is a diff on existing code, not a greenfield build.
