◉ Claude.ai/2026-04-22Advanced

The Claude Design to Claude Code Handoff — A Production-Ready Playbook

A detailed field guide to chaining Claude Design and Claude Code into one workflow — prompt templates, cleanup commands, and the 12-point checklist I run before shipping.

Claude Design⁸ Claude Code¹⁹⁶ Claude Opus 4.7² workflow³⁷ production¹¹¹

✦ Premium Article

When developers discover that Claude Design can hand directly off to Claude Code, the first reaction is usually "this is going to automate 90% of my frontend work." That was my reaction too. A few weeks in, the correct framing is smaller but more useful: the handoff isn't magic, it's a high-speed relay between well-defined stages. Skip the prompt design or the receiving-side cleanup and you'll produce more chaos, not less.

This post is the log of five days of testing against my own real projects — an app landing page, an admin dashboard, and an investor pitch deck — turned into a repeatable method. I've kept the failures in along with the wins, because the failures are where the sharp edges live.

What's inside the handoff bundle

Hitting "Handoff to Claude Code" in Claude Design produces a bundle shaped like this:

design-bundle/
├── manifest.json       # design-system info: tokens, fonts, colors
├── pages/              # standalone HTML + CSS + JS
├── components/         # React components (TSX)
├── assets/             # images, SVG, font references
├── preview.mp4         # optional interaction recording
└── build.log           # generation-process log

The bundle is hosted at api.anthropic.com/v1/design/h/<hash>, which Claude Code fetches via its WebFetch tool. Crucially, Claude Code doesn't just copy the output in — it reads the manifest and tries to integrate the result into the existing codebase. If your design originates in Figma, the Claude Code + Figma MCP guide covers the tool-to-tool bridge in more depth.

That's where the first failure mode lives. If your project already has a design system (custom CSS variables, a Tailwind config, a component library), the manifest's tokens will collide. In my project, --color-primary existed as #2563EB locally and arrived as #6366F1 from the bundle. Claude Code, trying to be helpful, kept both — so I ended up with dead definitions sitting alongside live ones.

The fix is upstream. Declare your design system authoritatively in CLAUDE.md before you run the handoff:

## Design System (authoritative)
 
Primary color: #2563EB (blue-600)
Font stack: "Inter Variable", system-ui, sans-serif
Component library: shadcn/ui (do not introduce a second library)
CSS approach: Tailwind only, no custom stylesheets

With that in place, Claude Code defers to your existing system instead of merging blindly.

A production-quality LP prompt

Generating a full landing page in one shot requires giving Claude Design both information density and technical constraints. After a lot of iteration, this is the template I've settled on:

[One-line product definition]
[Target customer — a fictional persona is fine]
[Primary conversion goal — download / signup / inquiry]

# Hero
- Headline: 6-10 words
- Sub-copy: 2 lines, max 60 chars/line
- Visual: [specific — gradient mesh / 3D cards / video background]

# Features (3 blocks)
- 6-word headline + 15-word description each
- Icons: Lucide
- Layout: [cards / split / grid]

# Social proof
- No real company names. Use fictional titles and names.
- 3-5 items.

# CTA
- [Strong action verb] + [value delivered]
- Button color: [accent]

# Technical
- Framework: Next.js 16 App Router
- Styling: Tailwind CSS
- Animations: respect prefers-reduced-motion, IntersectionObserver-triggered
- Accessibility: WCAG 2.2 AA, aria-labels required
- Performance: next/image assumed, Lighthouse Performance 90+

Output from this template needs roughly one-third the cleanup that v0 asked for on comparable briefs. The insight is in the "Technical" block: Claude Design responds better to concrete numbers ("Lighthouse 90+") than to abstract adjectives ("fast").

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Why design tokens collide right after the handoff, and the CLAUDE.md declaration that prevents it

✦The concrete failure patterns I hit on LPs, dashboards, and decks, each with the fix prompt that solved it

✦Three custom slash commands and the measured numbers from a five-day test that cut cleanup time ~60%

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Four ways I broke a dashboard

The LP worked on the first try. The admin dashboard took four attempts. For the charting implementation itself, see Claude Interactive Visualizations. The failure modes are worth naming:

Failure 1 — charting library left unspecified. "Place a bar chart and a line chart" produced bespoke SVG charts. Only specifying Recharts fixed it.

Failure 2 — unrealistic sample data. Currency fields came back as ¥1,234,567,890. A prompt constraint — "numeric values between 1,000 and 9,999, in JPY" — solved it.

Failure 3 — responsive breakdown. On mobile, the sidebar overlapped content. Had to spell out: "Below 768px, sidebar becomes a drawer; toggle button sits top-right." Claude Design defaults to desktop-first layout.

Failure 4 — dark mode toggle that didn't toggle. A theme switcher was present but the underlying CSS variables assumed light mode. Fixed by specifying: "Use a data-theme='dark' root selector and override CSS variables inside it."

Combining these lessons, my dashboard prompt now extends the LP template with:

# Data & state
- Chart library: Recharts
- Sample data defined in components/_data.ts (typed, static values)
- State: useState only, no global store

# Responsive
- Below lg, sidebar becomes a drawer; toggle top-right
- Tables become cards on mobile

# Theme
- Dark mode via data-theme attribute
- CSS variables prefixed --color-*, --bg-*, --text-*

Three slash commands that earn their keep

I keep three custom commands under .claude/commands/ for the post-handoff phase. The mechanics of defining commands are covered in Claude Code Custom Slash Commands.

/design-intake — merge the bundle into the existing project

---
description: Integrate a Claude Design bundle into the project
---
 
Execute these steps in order:
 
1. Read `design-bundle/manifest.json` and identify any conflicts with `src/config/design-tokens.ts`
2. When conflicts exist, prefer the existing tokens; leave the bundle values commented out for reference
3. Copy `design-bundle/components/*.tsx` into `src/components/design-intake/`
4. Rewrite imports to match the project's absolute-path + @/ alias convention
5. Place `design-bundle/pages/*` into `src/app/preview/` so existing routes aren't touched
6. Print a summary of files added and modified

/design-cleanup — strip noise out of the imported code

---
description: Remove unused code and duplicates from the intake
---
 
1. Remove unused imports from TSX under `src/components/design-intake/`
2. Detect unused Tailwind utility classes (via `tailwindcss-prune` if available, otherwise grep) and list removal candidates
3. Detect duplicate TypeScript types and propose consolidation targets
4. Propose only — don't make destructive changes

/design-ship — pre-production checklist

---
description: Final verification before shipping UI from Claude Design
---
 
Check the following 12 items and report as a Markdown table:
 
| # | Item | Result | Note |
| 1 | Responsive (sm/md/lg/xl) | | |
| 2 | Dark mode toggle | | |
| 3 | prefers-reduced-motion handling | | |
| 4 | WCAG 2.2 AA (contrast, aria) | | |
| 5 | Keyboard-only navigation | | |
| 6 | Projected Lighthouse Performance 90+ | | |
| 7 | next/image usage | | |
| 8 | Font subsetting / preload | | |
| 9 | i18n coverage (ja + en) | | |
| 10 | SEO metadata (title/description/OG) | | |
| 11 | Error boundaries | | |
| 12 | Unused dependencies | | |
 
For any failing item, propose a fix as a concrete diff.

Running these three in sequence after every handoff shaves roughly 60% off the cleanup time, in my measurement. /design-ship in particular catches the "I forgot to do X" bugs that plague solo projects.

Pitch decks require a different mindset

Slide decks require inverting the instinct you've built for LPs and dashboards: information density must go down, not up. A PPTX slide is a single page that assumes a speaker is narrating, so crowded slides fight the medium.

For deck generations, I always append:

# Slide design principles
- Max 5 elements per slide
- Text limited to headline + 3 keywords
- Diagrams lead; prose supports
- Type: 36pt+ (headline), 24pt+ (body)
- 3 colors max across the deck

Without those constraints, I get "report-style" slides with five paragraphs each — the anti-pattern for any deck you'll actually present.

What the handoff won't do for you

Five areas where manual work is non-negotiable, even after the handoff:

Japanese typography tuning. When you put Japanese into a design built for Latin fonts, baselines and line heights shift. font-feature-settings and line-height adjustments are almost always required.
i18n extraction. The output contains hardcoded strings. Replacing them with next-intl keys is mechanical but time-consuming.
Real API integration. Dashboards come back with mock data. Wiring real endpoints is manual.
Taming animation. Claude Design tends toward rich motion. You'll need to build the prefers-reduced-motion path yourself.
Accessibility polish. aria-label and role appear but aren't always correct. Running axe DevTools is still required.

These aren't "automation failures" — they're areas where Claude Code accelerates you but the work doesn't vanish. A well-tuned /design-ship command is how you turn them from ad-hoc to systematic.

The numbers from five days of testing

"It felt faster" isn't a reason to pay for anything, so here are the measured values from a single project I run as an indie developer — the admin dashboard for one of my wallpaper apps that surfaces AdMob revenue. All are medians over three to four runs.

Stage	Before	After	What moved it
Cleanup time per landing page	~45 min	~15 min	Numeric targets in the Technical block
Dashboard round-trips	3.5 avg	1.5 avg	Chart lib, responsive, theme all pre-specified
Token collisions	3 of 3 projects	0 of 3	Authoritative design system in CLAUDE.md
Pre-ship check	~25 min (manual)	~10 min	`/design-ship` 12-point table
Bundle fetch to intake done	—	~8 min avg	`/design-intake` fixes the merge steps

Laying the numbers out side by side, most of the savings come from fewer redos, not from raw generation speed. Dropping round-trips from 3.5 to 1.5 changes how the work feels far more than shaving seconds off a prompt. The corollary: skip the upfront declaration and those round-trips reappear as wall-clock time. The highest-leverage move I found wasn't a clever prompt — it was a few lines of CLAUDE.md.

What to do next

The Claude Design → Claude Code chain is becoming one of the highest-leverage AI workflows for solo developers. The prompts and slash commands in this post are ready to copy into your own project.

Start with one concrete action: write a design-system declaration into your project's root CLAUDE.md. That single change eliminates most of the post-handoff conflicts. Then try a single round-trip on a real project — a half-finished landing page, a one-pager you owe someone — and you'll get the feel of where it fits in your workflow.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.