Comando /design-sync cria espelho renderizado do design system para o Claude

O problema: ferramentas de design reinventam os componentes

Ferramentas de design com IA como o Claude Design, da Anthropic, transformam um prompt em tela completa em segundos, mas não conhecem o design system do usuário. Sem isso, elas criam botões e outros elementos com classes escolhidas à mão que apenas imitam os componentes reais - o resultado parece suficiente para aprovar, mas exige que um desenvolvedor reconstrua cada peça depois.

O espelho: como funciona o design sync

O comando /design-sync, executado no Claude Code dentro do repositório, cria um "espelho" do design system dentro do Claude Design: uma cópia compilada e autorrenderizável da biblioteca, com um bundle de componentes, a folha de estilo, fontes e uma cópia do React para os componentes funcionarem sozinhos. Cada componente recebe uma pasta de tipos (props e variantes), uma página de pré-visualização e um guia de uso gerado. O espelho não inclui os arquivos-fonte e é uma fotografia unidirecional: mudanças no código só aparecem após nova execução do /design-sync, e componentes removidos podem permanecer no espelho mesmo após re-sincronização.

A qualidade do espelho depende da renderização: um componente sem folha de estilo chega sem estilização e todo design construído sobre ele herda o erro. A pergunta central do artigo é se cada componente aparece no Claude Design exatamente como aparece no produto.

Verificação automática e papel do Storybook

Antes de enviar, o sync abre cada pré-visualização em navegador real, tira screenshots e avalia o resultado. Sem referência, cada card é julgado isoladamente contra um rubric. Com um Storybook no repositório, as stories viram as pré-visualizações e servem de referência: o Claude compara lado a lado cada preview com a story correspondente, atribui nota (match, close ou mismatch) e corrige o que consegue antes do upload. Um "close" não é aprovação, e o autor alerta que algumas falhas são de enquadramento, não de estilo - por isso o humano precisa revisar as notas.

Tutorial com shadcn/ui, Tailwind v4 e Storybook

O artigo constrói um design system mínimo com três componentes shadcn (Button, Card e Input), Tailwind v4 e Storybook. Pontos-chave do processo:

• Arquivo de entrada e tipos: o sync empacota um único entry file; componente não exportado ali simplesmente não chega ao Claude Design, sem aviso. As definições de tipo são obrigatórias - sem elas, o sync não encontra componentes e descarta as stories.
• Folha de estilo compilada: o Storybook com o plugin Vite não gera CSS real, então o sync usa a Tailwind CLI para produzir um ds.css. É essencial importar os tokens como string (@import './tokens.css') e não com url(), pois só o import inline carrega os tokens após o upload.
• Safelisting de utilitários de layout: o CSS compilado só contém classes presentes nos fontes. A diretiva @source inline(...) do Tailwind v4.1 gera utilitários de layout (grid, gap, espaçamentos, cores) que o Claude escreverá ao compor telas - sem isso, os layouts silenciosamente perdem a estrutura.
• Fontes: fontes importadas do CSS apontam para node_modules e não sobrevivem ao upload; listá-las em extraFonts faz o sync copiar os arquivos woff2 e reescrever as regras @font-face.
• Arquivo de convenções: o README com regras de uso (não estilizar manualmente, usar variant e size, compor o Card com subcomponentes, mesclar classes com cn()) evita que o Claude escreva mesmo vendo o botão correto. É descrito como a melhoria de qualidade mais barata.

No exemplo do autor, as nove stories vieram como match. Um pedido de tela de login resultou em composição com Card, CardHeader e Button variant="outline", sem divs feitas à mão - tudo alinhado ao produto.

Repositórios maiores e observações finais

Em monorepos, o entry precisa do caminho completo a partir da raiz, enquanto o cssEntry fica relativo ao diretório do pacote. Com múltiplas fontes, uma entrada extraFonts por folha Fontsource. O artigo recomenda versionar a configuração, as convenções e o NOTES.md, e ignorar no git os artefatos gerados.

A conclusão é que enviar o design system é a parte fácil - garantir que cada componente pareça correto do outro lado é onde está o trabalho real.