Sincronização do Design System
Visão Geral
Quando um design system já existe no código, a ferramenta de design deve espelhá-lo, não reinventá-lo.
- Importar traz os tokens do código e os componentes que a pessoa seleciona para a ferramenta, sob os mesmos nomes.
- Exportar leva as alterações feitas no guia da ferramenta de volta ao código como um diff revisado.
Um pequeno arquivo na raiz do projeto, design-sync.json, armazena o que foi sincronizado por último. O código permanece como fonte da verdade até que a pessoa indique o contrário: as alterações são desenhadas primeiro na ferramenta e aterrissam no código por meio de uma exportação aprovada.
Quando usar
- Uma tarefa de design está prestes a começar em um projeto com um design system no código e nenhum guia na ferramenta.
craft-setupecraftdelegam para este skill. - "Importar / trazer nosso design system (tokens, componentes) para o Paper / Figma / ferramenta de design."
- "Aplicar / enviar / sincronizar as alterações do guia para o código."
Quando NÃO usar
- Nenhum design system no código:
craft-system(modo criar). - Uma revisão, opções ou uma pequena edição em tal projeto: esses skills trabalham a partir do código como ele está.
- Um valor de token único que a pessoa ditou ("tornar o accent #3d7f69 no código"): edite diretamente, atualize
design-sync.jsonpara aquele nome, diga o que isso afeta.
Antes de começar
- Leia
DESIGN.md(a Marca diz onde o sistema vive) edesign-sync.jsonse existirem. - Escolha o adaptador da sua ferramenta em
references/adapters/(paper.md,figma.md,html.md). Se nenhum adaptador corresponder à sua ferramenta, faça os mesmos verbos em sua ferramenta e diga quais você mapeou manualmente. Sem nenhuma ferramenta de design, construa em HTML (html.md). Se tudo o que você tem é uma imagem, diga que os valores lidos dela são estimativas.
design-sync.json
{
"source": "packages/ui/tokens.css",
"tool": "paper: arquivo 'Fieldnote', página 'Guia'",
"naming": "Nomes de propriedades custom CSS como escritos na fonte",
"synced": "2026-11-15",
"tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
"components": { "Button": "desenhado", "Badge": "desenhado", "Input": "apenas no código" }
}
tokenscontém os valores que ambos os lados concordaram na última sincronização, e apenas esses.- Uma importação de componente altera apenas sua própria entrada em
components.
Importar (código → ferramenta de design)
-
Detecte com os sinais. Encontre a fonte da verdade para valores (a fonte do token, não uma saída gerada) e a regra de nomenclatura que a ferramenta usará. Dois pacotes UI → liste ambos e pergunte qual é a fonte.
-
Inventarie, depois pare. Use o formato de inventário:
- tokens por função, com contagens e caminhos;
- componentes (agrupados com contagens quando houver mais de cerca de 15);
- documentos de diretrizes;
- lacunas;
- conflitos: qualquer nome que já exista na ferramenta com um valor diferente, e qualquer tipo de token que a ferramenta não pode armazenar.
Pergunte quais componentes desenhar agora, sugerindo 3-6 para as próximas telas, e como resolver cada conflito. Nunca desenhe tudo por padrão.
-
Construa na ferramenta após as respostas:
- registre os tokens sob a regra de nomenclatura; nunca sobrescreva um valor da ferramenta que a pessoa não resolveu;
- crie uma página de guia de fundamentos, com documentos de diretrizes como legenda;
- crie um índice de componentes: nome, caminho do código, status (
desenhado/apenas no código), com variantes preenchidas uma vez desenhadas; - desenhe os componentes selecionados com sua matriz de estados, usando valores do código. Um estado que o código não define é desenhado e rotulado como "proposto".
-
Autoverificação. Renderize o guia. Se o código puder renderizar o componente (Storybook, uma página de demonstração), compare no mesmo tamanho. Caso contrário, diga que os valores foram lidos do código, não renderizados.
-
Registre:
- escreva
design-sync.json(todos os valores de tokens agora iguais em ambos os lados, mais os status dos componentes); - em
DESIGN.md, a Marca recebe "Fonte do Design System:<caminho>; o guia o espelha", e o log de Decisões recebe uma linha de importação datada; - se não houver
DESIGN.md, crie um cuja primeira linha seja<!-- sync record only: run craft-setup for the brief -->com apenas a Marca e o log de Decisões.crafttrata umDESIGN.mdsem uma seção de Produto como ausente.
- escreva
Importação de um componente (do craft)
A pessoa já concordou em espelhar o sistema, então não há parada de inventário:
- desenhe esse componente;
- defina sua entrada em
componentscomodesenhado; - deixe
tokensinalterado.
Se a ferramenta ainda não tem guia, ou a pessoa nunca concordou com uma importação (ou recusou), pergunte uma vez: "Input existe apenas no código. Importá-lo para o guia primeiro?"
Exportar (ferramenta de design → código)
-
Leia os valores do guia (adaptador) e os valores do código, por nome.
-
Classifique cada nome com
design-sync.jsone o formato de diff:- iguais agora → sincronizado;
- guia alterado → propor;
- código alterado → oferecer atualizar o guia;
- ambos alterados → mostrar os três valores e perguntar qual vence.
Sem
design-sync.json, liste cada diferença e pergunte a direção para cada uma. -
Proponha as edições nos arquivos fonte (nunca uma saída gerada): arquivo e linha, o que cada uma afeta, e o contraste para cores. Estados "Proposto" e fontes substituídas não são alterações para exportar. Pare.
-
Aplique apenas o que foi aprovado, atualize o guia para qualquer coisa decidida a favor do código, e execute as verificações do projeto (lint, typecheck, testes, testes visuais), ou diga que não há nenhuma.
-
Registre:
- atualize
design-sync.jsoncom os valores agora iguais em ambos os lados; - adicione uma linha datada ao log de Decisões em
DESIGN.md; - adicione conflitos em aberto a Perguntas em aberto.
- atualize
Regras
| Regra | Por quê |
|---|---|
| Mesmos nomes no código e na ferramenta, por uma regra de nomenclatura escrita | Um nome por decisão; sem mapeamento para desvio |
design-sync.json registra apenas valores acordados | Sem o último valor acordado, "quem mudou isso?" é um palpite |
| Inventário e escolha antes de desenhar; conflitos listados lá | Pacotes grandes e tokens existentes na ferramenta precisam da opinião da pessoa |
| Valores do código, nunca de capturas de tela | Capturas de tela arredondam cores e tamanhos |
| Estados ausentes desenhados como "proposto" | O guia não deve afirmar que o código faz o que não faz |
| Exportar propõe, depois para; edita a fonte, não a saída gerada | O código é enviado aos usuários; um arquivo gerado é sobrescrito na próxima build |
| Ambos alterados → perguntar | Sobrescrever qualquer lado perde a decisão de alguém |
| O código é a fonte da verdade até que a pessoa diga o contrário | Corresponde a "o código vence um resumo desatualizado" |
Concluído quando
- Importação: inventário e conflitos resolvidos; componentes selecionados desenhados; guia renderizado (ou "não renderizado" declarado);
design-sync.jsoneDESIGN.mdescritos. - Um componente: desenhado, com seu status atualizado.
- Exportação: edições aprovadas aplicadas, as verificações executadas (ou "nenhuma" declarado),
design-sync.jsonatualizado, conflitos decididos ou em aberto.
Erros comuns
| Pensamento | Realidade |
|---|---|
| "O código tem o sistema, então o setup só precisa do resumo" | Ofereça a importação, ou a ferramenta nunca terá um guia e as telas se desviam do código. |
| "Vou construir fundamentos e um índice, componentes depois" | Mostre o inventário e pergunte quais componentes desenhar agora. |
"Vou renomear --sand-200 para um nome de função ao importar" | Mantenha o nome do código; proponha uma função como uma pergunta em aberto. |
"A ferramenta já tem --color-accent, vou atualizá-lo" | Isso é um conflito para a parada de inventário, não uma sobrescrita silenciosa. |
| "Guia e código diferem, então o guia está desatualizado" | Verifique design-sync.json: pode ser a alteração não exportada da pessoa. |
| "O diff é pequeno, vou apenas aplicar" | Proponha, pare, depois aplique e execute as verificações do projeto. |