TomasValleDuran/construtor-de-design-system

Construtor de Design System

Um design system é um conjunto de decisões tomadas uma vez para que cada tela não precise redescobri-las. Tokens guardam as decisões, componentes as aplicam, documentação as explica. Escalone o esforço para o projeto: um aplicativo de fim de semana precisa de um arquivo de tokens de 40 linhas e um DESIGN.md; um produto com várias equipes precisa de pipelines e governança. Comece pequeno, cresça por extração.

Processo

0. Leia o que existe

Procure por: arquivos tokens/theme, tailwind config ou blocos @theme, components.json, variáveis CSS, um módulo theme/, links do Figma (use o Figma MCP get_variable_defs/search_design_system se estiver conectado), DESIGN.md/.interface-design/system.md. Em codebases existentes, extraia antes de inventar: grep pelas cores reais, tamanhos de fonte, espaçamentos e raios em uso, agrupe-os e proponha a escala consolidada. Mostre ao usuário o mapeamento antes→depois.

1. Defina a direção (um parágrafo)

Quem usa, como deve parecer (em palavras concretas: "denso como um terminal de negociação", "calmo como um aplicativo de leitura"), plataforma(s), restrições de marca, densidade, claro/escuro. Isso guia todas as escolhas de escala abaixo. Se as skills interface-design ou frontend-design estiverem em jogo, elas são donas desta etapa estética; esta skill transforma a direção em um sistema.

2. Fundações (tokens)

Construa nesta ordem — cada uma depende da anterior:

1. Cor → execute a ferramenta da skill color-theory: python3 <skills-dir>/color-theory/scripts/palette.py system <brand-hex> --format tailwind|css|json (color-theory é uma skill irmã do diretório desta skill). Ela produz rampas primitivas + papéis semânticos claro/escuro verificados.
2. Tipografia → famílias de fontes (≤2, mais mono), uma escala tipográfica com papéis nomeados, alturas de linha, pesos, tracking. Veja references/scales.md.
3. Espaço → grade base de 4px; escala de camiseta ou numérica; espaçamento de layout separado do padding de componente.
4. Forma → escala de raio (e uma regra para aninhamento: raio interno = raio externo − padding), larguras de borda.
5. Elevação → escala de sombra (claro) e passos de clareza de superfície (escuro), camadas de z-index.
6. Movimento → durações + easing como tokens (e comportamento de movimento reduzido).
7. Layout → breakpoints, larguras de container, colunas de grade, áreas seguras (mobile).
8. Tamanho → alturas de controle (sm/md/lg), tamanhos de ícone, alvo mínimo de toque.

3. Arquitetura de tokens

Três camadas — componentes devem consumir apenas a camada semântica (ou de componente):

primitivo   --blue-600, --space-4, --radius-2          valores brutos, nomeados pelo que SÃO
semântico   --color-accent, --space-inset-md, --radius-control   nomeados pela FUNÇÃO, alias de primitivos, alternam por tema
componente  --button-bg, --card-padding                 opcional; apenas para componentes com necessidades reais de tema

Alternância de tema (modo escuro, marcas, densidade, alto contraste) = redirecionar tokens semânticos. Componentes nunca mudam. Regras completas de nomenclatura, formato DTCG, modos: references/token-architecture.md.

4. Envie para a(s) plataforma(s)

• Aplicativo web único: variáveis CSS escritas manualmente + Tailwind v4 @theme é suficiente.
• Web + mobile, ou múltiplos aplicativos: autorize tokens em DTCG JSON (uma fonte), construa com Style Dictionary v5 ou Terrazzo para CSS, Tailwind, TS, Swift, Kotlin/Compose, Flutter, RN. Receitas e exemplos de saída por plataforma: references/platform-outputs.md. Arquivo DTCG inicial: assets/tokens.example.json.

5. Componentes

Construa sobre primitivos acessíveis (veja ui-stack-advisor). API consistente: variant (intenção visual), size, tone/color apenas se necessário, estados via atributos de dados, composição sobre configuração. Cada componente documenta todos os estados: padrão, hover, ativo, focus-visible, desabilitado, carregando, erro, vazio, selecionado, somente leitura. Convenções e checklist: references/components.md.

6. Documente e governe

Escreva DESIGN.md na raiz do projeto a partir de assets/DESIGN.template.md — direção, tabela de tokens, inventário de componentes, faça/não faça e o porquê por trás das decisões. Este arquivo é o que futuras sessões leem para manter a consistência; mantenha-o curto e atualizado. Sistemas maiores adicionam Storybook (ou Ladle/Histoire), regressão visual, um changelog com semver e um processo de contribuição (references/components.md#governance).

Padrões que funcionam (quando o usuário não tem preferência)

Fundação	Padrão
Unidade base	4px; escala de espaçamento 0, 1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96 px
Escala tipográfica	12, 14, 16 (corpo), 18, 20, 24, 30, 36, 48, 60 px (≈razão 1.2–1.25); UIs de produto podem usar 14px de corpo
Altura de linha	1.5 corpo, 1.2–1.3 títulos, 1.1 display; aperte o tracking em tamanhos grandes (−0.01 a −0.03em)
Raio	0, 4, 6, 8, 12, 16, 24, cheio — escolha uma personalidade: afiado (2–4), suave (8–12), redondo (16+) e aplique consistentemente
Controles	alturas 32 / 36–40 / 44–48 px; alvos de toque ≥ 44pt (iOS) / 48dp (Android) / 24px mínimo WCAG 2.2 (mire 44)
Movimento	100 / 150 / 200 / 300 / 500 ms; ease-out cubic-bezier(0.23,1,0.32,1) para entrada, ease-in-out para movimento, molas no mobile
Breakpoints	640, 768, 1024, 1280, 1536 (Tailwind); prefira consultas de contêiner para componentes
Elevação	4–5 níveis de sombra; modo escuro usa superfícies mais claras + bordas sutis no lugar
Z-index	base 0, dropdown 1000, sticky 1100, overlay 1300, modal 1400, popover 1500, toast 1600, tooltip 1700

Padrões são um piso, não um estilo. A distintividade vem das escolhas que variam: tipo de letra, matiz de destaque, temperatura neutra, personalidade do raio, densidade e caráter do movimento.

Barra de qualidade (verifique antes de considerar concluído)

• Nenhum valor bruto em componentes (hex, tamanhos de fonte em px, espaçamento arbitrário) — grep por eles
• Nomes semânticos descrevem funções, não valores ou matizes
• Claro + escuro ambos projetados e verificados quanto a contraste (WCAG 2.2 AA)
• Cada componente interativo tem estados visíveis de foco, desabilitado, carregando, erro
• Escala tipográfica tem papéis nomeados (display, h1–h3, body, label, caption, code), não apenas tamanhos
• Espaçamento consistente: mesma relação → mesmo token
• Variante de movimento reduzido para tokens de movimento
• DESIGN.md escrito e preciso
• Mobile: Dynamic Type / escala de fonte respeitada, áreas seguras tokenizadas, alvos de toque ≥ 44/48

Referências

• references/token-architecture.md — camadas, gramática de nomenclatura, formato DTCG 2025.10, modos/temas, regras de alias
• references/scales.md — tipografia (escalas, tipo fluido, pareamento), espaçamento, raio, elevação, movimento, densidade, breakpoints
• references/platform-outputs.md — CSS, Tailwind v4, theming shadcn, React Native (NativeWind/Unistyles/Tamagui), Flutter, SwiftUI, Compose, pipeline Style Dictionary/Terrazzo
• references/components.md — convenções de API de componente, anatomia, matriz de estados, composição, documentação, testes, governança
• assets/tokens.example.json — arquivo DTCG inicial
• assets/DESIGN.template.md — template DESIGN.md