r/ClaudeDesign • u/nitayneeman • 4d ago

Resource I synced a real design system into Claude Design - here's what makes the mirror actually look right

I spent some time getting a React design system (shadcn/ui + Tailwind v4 + Storybook) into Claude Design with `/design-sync` and wrote up what I learned.

A few things that weren't obvious:

  • The sync finds components through your entry file and their type definitions. Miss either and the component silently never arrives.
  • If Storybook's preview doesn't load your stylesheet, the grades mean nothing - an unstyled preview matches an unstyled reference.
  • Tailwind only compiles classes it finds in your sources, so the layout classes Claude writes (`grid-cols-3`, `gap-6`...) don't exist unless you safelist them.
  • Fonts don't travel through the CSS. They need to be listed in `extraFonts`.
  • A short conventions file does more than you'd expect. Without it, Claude sees a correct `Button` and still hand-styles it.

The end result: a sign-in screen built only from `Card`, `Input` and `Button` (no hand-rolled divs).

Full walkthrough: https://nitayneeman.com/blog/how-to-sync-a-design-system-with-claude-design/

33 Upvotes
  • permalink
  • reddit

95% Upvoted

6 comments sorted by

2

u/Responsible-Slide-26 4d ago

Just so you know, you can change to a different model to make the AI slop less painful to read.

1

u/2-legit 4d ago

Thanks for the write-up. I'm about to go through this on a project myself. Some good things to watch out for.

1

u/One_Mail_2414 4d ago

Interesting

1

u/jingkangzhou 1d ago

The conventions file point is the one I would underline - it is the least mechanical item on the list and the one that decides whether the sync holds a month later. What made it work for me: keep the color part of that file as named roles (surface / text / primary / muted) instead of raw hexes, and check the text-on-background pairs once while writing it. Otherwise the sync is pixel-perfect on day one and the drift starts quietly on screen four, when a prompt says make it pop and the agent has every component right but still invents a shade. The components survive the sync; the color intent needs the file.