Communitygithub.com

craft-sync

Use quando uma tarefa de design está prestes a começar em um projeto cujo design system já vive no código (um pacote de UI, tokens de design, uma biblioteca de componentes) mas não está na ferramenta de design, quando solicitado a importar ou trazer o design system, tokens ou componentes para a ferramenta de design, ou para aplicar, enviar ou sincronizar mudanças do guia da ferramenta de design de volta ao código.

O que é craft-sync?

O skill craft-sync gerencia a sincronização bidirecional entre um design system que existe em código (como tokens CSS, componentes de uma biblioteca) e a ferramenta de design (Paper, Figma, HTML). Ele garante que a ferramenta de design espelhe o código, mantendo o código como fonte da verdade até que o usuário decida o contrário. O skill suporta duas operações principais: *Importação* (código → ferramenta), que traz tokens e componentes selecionados para a ferramenta de design com os mesmos nomes, e *Exportação* (ferramenta → código), que aplica mudanças do guia da ferramenta de design de volta ao código como um diff revisado. Um arquivo `design-sync.json` registra o estado acordado da última sincronização para evitar conflitos e garantir rastreabilidade. Este skill é útil para equipes que já possuem um design system implementado em código e desejam manter a ferramenta de design atualizada sem reinventar ou dessincronizar os dois ambientes.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/craft/tree/HEAD/skills/craft-sync

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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-setup e craft delegam 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.json para aquele nome, diga o que isso afeta.

Antes de começar

  1. Leia DESIGN.md (a Marca diz onde o sistema vive) e design-sync.json se existirem.
  2. 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" }
}
  • tokens conté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)

  1. 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.

  2. 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.

  3. 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".
  4. 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.

  5. 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. craft trata um DESIGN.md sem uma seção de Produto como ausente.

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 components como desenhado;
  • deixe tokens inalterado.

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)

  1. Leia os valores do guia (adaptador) e os valores do código, por nome.

  2. Classifique cada nome com design-sync.json e 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.

  3. 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.

  4. 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.

  5. Registre:

    • atualize design-sync.json com 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.

Regras

RegraPor quê
Mesmos nomes no código e na ferramenta, por uma regra de nomenclatura escritaUm nome por decisão; sem mapeamento para desvio
design-sync.json registra apenas valores acordadosSem 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 telaCapturas 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 geradaO código é enviado aos usuários; um arquivo gerado é sobrescrito na próxima build
Ambos alterados → perguntarSobrescrever qualquer lado perde a decisão de alguém
O código é a fonte da verdade até que a pessoa diga o contrárioCorresponde 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.json e DESIGN.md escritos.
  • Um componente: desenhado, com seu status atualizado.
  • Exportação: edições aprovadas aplicadas, as verificações executadas (ou "nenhuma" declarado), design-sync.json atualizado, conflitos decididos ou em aberto.

Erros comuns

PensamentoRealidade
"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.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Habilidades Relacionadas