tmj-90/design-system

Construir um design system sistemático

O skill brand decide a identidade; o skill frontend-design decide como uma superfície se parece. Este pack decide como essa aparência é estruturada para escalar: uma arquitetura de tokens de três camadas com uma única fonte da verdade, especificações de componentes que cobrem todos os estados e verificações que impedem que valores brutos voltem a vazar. Consulte uma referência quando precisar de profundidade:

Tópico	Referência
Camadas, nomenclatura, modo escuro, JSON DTCG, migração de tokens planos	references/token-architecture.md
Variantes, tamanhos e matrizes de estado para botão/input/card/badge/alert/diálogo/tabela	references/component-specs.md
Prioridade de estados, anéis de foco, padrões de erro/carregamento, ARIA por estado	references/states-and-variants.md

A arquitetura em uma frase

/* PRIMITIVO — valores brutos, sem significado. Mudam raramente. */
--blue-600: oklch(55% 0.2 264);
/* SEMÂNTICO — propósito. A costura do tema: claro/escuro/marca substitui apenas esta camada. */
--color-primary: var(--blue-600);
/* COMPONENTE — ajustes por componente, referenciando tokens semânticos. */
--button-bg: var(--color-primary);

Componentes consomem tokens de componente ou semânticos — nunca um primitivo, nunca um literal. Temas (escuro, alto contraste, uma segunda marca) redirecionam tokens semânticos e nada mais.

Fonte da verdade. Se o repositório mantém tokens como JSON do W3C Design Tokens Community Group (DTCG) — formato que atingiu sua primeira versão estável, 2025.10, em outubro de 2025 — esses arquivos são a fonte: tokens carregam $value e $type, aliases são escritos {color.blue.600}, e uma ferramenta de build (Style Dictionary ou equivalente do repositório) gera variáveis CSS, tema Tailwind e valores nativos. Edite o JSON e regenere; nunca edite manualmente a saída gerada. Se o repositório tiver apenas propriedades CSS personalizadas, essas são a fonte. Não introduza uma segunda fonte.

Passos

1. Leia o que existe. Use search_lore para ADRs de design system; encontre arquivos de tokens (*.tokens.json, tokens/, theme.ts, blocos :root, config Tailwind), o comando de build que gera as saídas e dois componentes similares. Estenda o sistema existente em seu idioma; nunca adicione um concorrente.
2. Audite antes de adicionar. Conte literais nos estilos dos componentes (comandos abaixo). Cada vazamento que você toca é substituído por um token existente ou justifica um novo.
3. Coloque cada novo token em sua camada. Primitivo apenas para um valor bruto genuinamente novo; semântico para um novo propósito (--color-surface-raised, --space-section); componente apenas quando um componente deve divergir. Nomes descrevem propósito, não aparência (--color-danger, não --color-red). Primitivos de cor em oklch (idioma da casa), tipo em uma escala fluida com clamp(), espaçamento em uma unidade base (4px ou 8px).
4. Tematize na costura semântica. Modo escuro e outros temas substituem tokens semânticos em um bloco ([data-theme="dark"], .dark ou @media (prefers-color-scheme: dark), conforme o repositório) e definem color-scheme para que controles nativos e barras de rolagem acompanhem. Um tema que substitui um token primitivo ou de componente significa que a costura está no lugar errado.
5. Verifique contraste por tema. Para cada par semântico primeiro plano/fundo realmente usado (texto sobre superfície, texto sobre primário, borda sobre superfície, indicador de foco sobre superfície), calcule a taxa de contraste WCAG em cada tema: 4.5:1 para texto corrido, 3:1 para texto grande, limites de UI e indicadores de foco. A luminosidade de oklch não é a taxa WCAG — calcule (um script, o verificador do repositório ou um teste). Registre a tabela.
6. Especifique componentes completamente. Variantes, tamanhos (altura explícita, padding, token de fonte), e a matriz de estados — padrão, hover, focus-visible, ativo, desabilitado, carregando, erro, além de selecionado/marcado quando relevante — com o ARIA que cada estado expõe. Prioridade quando vários se aplicam: desabilitado > carregando > erro > ativo > foco > hover > padrão. Foco é sempre visível (anel :focus-visible de --color-ring, nunca outline: none sozinho). Detalhes: as referências.
7. Recomendar um sistema para um novo produto: raciocine a partir do produto, não de um kit — (a) padrão e densidade (marketing, dashboard denso em dados, fluxo transacional), (b) direção (delegue a brand), (c) postura da paleta (papéis semânticos incluindo sucesso/ aviso/perigo/info; modo escuro apenas se os usuários precisarem), (d) metas de acessibilidade e desempenho declaradas de antemão. Produza uma justificativa breve mais o arcabouço de tokens e componentes; entregue a execução visual a frontend-design.
8. Verifique e evidencie. Regere as saídas de tokens se o repositório as construir e confirme que o diff é apenas o que você pretendia; execute lint, type-check e testes; execute as verificações de vazamento; renderize os componentes alterados em cada tema por meio do componente do repositório ou testes de screenshot onde existirem. Registre evidências por AC com o skill record-evidence (contagem de vazamentos antes/depois, tabela de contraste), então pare.

Verificações de vazamento

Execute nos arquivos de componente e estilo alterados (exclua os próprios arquivos de token):

• cores brutas: grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components
• tamanhos de tipo brutos: grep -rEn 'font-size:\s*[0-9.]+px' src/components
• primitivos referenciados de componentes: grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components
• valores arbitrários Tailwind onde tokens existem: grep -rEn '\[(#|[0-9]+px)' src/components

Ajuste caminhos e nomes de primitivos para o repositório. Novas correspondências em seu diff são defeitos para o construtor corrigir, a menos que a linha seja em si uma definição de token; um revisor as lista como (opcional) a menos que uma quebre um AC ou o contraste de um tema.

Concluído quando

Nenhum novo literal ou referência primitiva em componentes; cada tema substitui apenas tokens semânticos; a tabela de contraste passa em cada tema; a matriz de estados de cada componente tocado está implementada com foco visível; as saídas geradas correspondem à fonte.

Capturar lore

A arquitetura de tokens de um repositório — a divisão de camadas, a convenção de nomenclatura, a costura do modo escuro, ou uma regra "nunca referencie um primitivo em um componente" — é exatamente o fato que o próximo agente precisa antes de começar. Esse tipo de fato é lore. Capture-o via o protocolo de captura de lore em seu brief (CLAUDE.factory.md, etapa 11 "Contribuição de memória"): chame o Memory MCP suggest_lore uma vez no encerramento do seu trabalho — apenas convenções reutilizáveis, pegadinhas, decisões e limites, nunca triviais por ticket.