Claude Design can draw with your real components

A September 28 guide on Nitayneeman walks through /design-sync, the Claude Code command that compiles a React component library into a mirror inside Claude Design. With the mirror in place, a prompted screen comes back as <Button>Save</Button> instead of a lookalike <button className="px-4 py-2 rounded bg-blue-600 text-white">. Whether that mirror renders like the product depends mostly on the stylesheet: tokens imported with url() leave every shadcn component unstyled after upload, and the layout classes Claude writes around the components are missing unless they are safelisted with @source inline(...).
The guide’s worked example is small on purpose: three shadcn/ui components (Button, Card and Input), Tailwind v4 and Storybook. The mirror holds no source files. It is one compiled bundle with every component, the stylesheet, the fonts and a copy of React, plus a folder per component with its types, a standalone preview page and a generated usage guide, and a README of the team’s own usage rules. The command reads its settings from a .design-sync/ folder in the repo, builds all of this and waits for approval before uploading anything.
What has to survive the upload
Storybook running through @tailwindcss/vite produces no CSS file, since it loads styles from a JavaScript chunk at runtime. So the guide compiles ds.css with the Tailwind CLI as part of the sync’s build command. If the design tokens (colors, spacing and other named variables) live in a separate file, the import syntax decides whether they travel: Tailwind v4 inlines a string @import './tokens.css' and leaves @import url('./tokens.css') as an external reference. Both work locally. After the upload, only the inlined one still carries the tokens.
The compiled file also holds only the utilities Tailwind found in the sources, and three components scan to a couple of hundred classes, none of them grid-cols-3, gap-6 or max-w-4xl. @source inline(...), added in Tailwind v4.1, generates utilities from brace patterns instead of scanned files. In the guide, nine such lines at the end of src/index.css cover breakpoint-prefixed flex and grid, gaps, padding and margins, widths and heights, text sizes and the token colors with hover: and dark: variants. The stylesheet gets heavier in exchange.
Fonts imported from CSS point back into node_modules and don’t survive the upload, so they are listed under extraFonts in .design-sync/config.json. The sync then copies the woff2 files into the mirror and rewrites the @font-face rules to match. Those paths resolve from the package directory, which is why they spell out ./node_modules/, and in a monorepo climb to ../../node_modules/.
Two quieter failures sit in the entry file. shadcn creates no index that exports everything, so the guide writes src/index.ts by hand, and a component left out of it never reaches Claude Design, with no warning. The sync also finds components through their type definitions: without them it finds nothing and drops every story. The build command therefore runs tsc to emit declarations into dist/, and package.json points "types" at dist/index.d.ts.
Without written rules, Claude sees a correct Button and still writes <Button className="bg-blue-600 px-4">. The config’s readmeHeader field points at a conventions file: no theme provider, dark mode as a class on an ancestor, className for layout only, Card composed from its subcomponents, cn() for merging class names. On the first run the sync appends a table of the utility classes that exist in the compiled stylesheet. That table and the @source inline block have to change together, or Claude writes classes that do nothing.
What does the check compare?
Before uploading, the sync opens each preview in a real browser, screenshots it and grades it. Without Storybook, every component starts as a placeholder card with nothing to compare against, so the automatic checks catch blank or nearly empty previews and variants that all look the same, and Claude grades the rest against a rubric. With Storybook, the stories become both the previews and the reference: Claude compares each preview with its story side by side, grades it match, close or mismatch, and fixes what it can before showing the summary. It may judge only a component’s primary story and trust the siblings when that one is clean.
That comparison has preconditions. Storybook’s generated preview doesn’t load the stylesheet, so .storybook/preview.tsx needs import '../src/index.css'; without it, a pass only means an unstyled preview matches an unstyled reference. Story titles must match the exported name (Button, not Buttons). By default the sync captures up to six stories per component, and a variant with no story still arrives, unverified. Playwright with Chromium has to be installed, and Claude Code’s Bash sandbox blocks the local server and the browser the checks drive; the guide turns it off with /sandbox for the run.
In the guide’s run, all nine stories came back as match. When they don’t, the author reads the grades as a diagnosis:
- Everything unstyled: the build command didn’t run, or a token file is imported with
url(). - Components fine, layouts collapsed: the
@source inline(...)block needs widening. - Right shapes, wrong fonts: the fonts are missing from
extraFonts. - A component that looks off but isn’t: framing, such as a dropdown captured closed, or an Input rendering wider in the preview than in the Storybook canvas.
The last case is why the grades still get a human read. “A grader can’t tell us that a perfect screenshot is the wrong one,” the author writes.
A snapshot, one way
The mirror is no live link. A change in code shows up in Claude Design only after the next /design-sync, and even a re-sync may leave a deleted component in the mirror, so the guide suggests checking the file list after removing one. After the first run the sync saves a projectId in the config, and later runs update the same design system. Getting a finished design back into code is a separate flow, through the /design command in Claude Code.
The approved mirror appears under Settings > Design systems. On Pro and Max it stays personal. On Team and Enterprise, publishing makes it the organization’s, and Enterprise admins can limit who publishes, set the default or delete it.
Existing repos add two traps. In a monorepo, entry takes the full path from the repo root, such as packages/design-system/src/index.ts, while cssEntry stays relative to the package as a bare ds.css, and a mix-up just looks like a missing file. If an existing Storybook entry imports tokens with url(), the fix is a separate CSS entry for the sync with a string import, which can drift from the original: a new @layer base rule in one leaves the other rendering the old design with no error. The guide’s answer is to diff the two before every re-sync.
Up next
Claude Code 2.1.286 stops resume from losing your turns
“Losing every turn after a batch of parallel tool calls” is how the Claude Code 2.1.286 notes describe the resume bug it fixes, and it hit sessions that had crashed or been killed.
Related stories
- Claude Design moves into Artifacts, but projects stay behind
- Tokendoctor cut its author’s Claude Code cost 38%
- memsaga gives Claude Code’s memory files a git history
- Intent-lens spells out Claude Code calls before they run
- Codedict cuts Claude Code tokens 63%, but cost only 26%
- claude-files-pane shows Claude Code’s file reads live
Comments
No comments yet. Be the first.
Join the conversation
Sign in to leave a comment. It appears after moderation.

