hamzacakmakk/design-system-generator

Gerador de Sistema de Design

Construa o menor sistema que torna o produto consistente. Um sistema de design é um conjunto de decisões, não um grande conjunto de valores: poucos tokens bem nomeados vencem escalas exaustivas que ninguém usa.

Se o skill frontend-design estiver instalado, frontend-design/references/tokens.md contém um conjunto inicial completo e verificado por contraste; comece a partir dele e adapte.

1. Entradas

• Leia o que existe: CSS atual, configuração Tailwind, arquivos de tema, biblioteca de componentes, ativos da marca. Faça um inventário dos valores reais em uso (cores, tamanhos de fonte, espaçamento, raios) e com que frequência cada um ocorre.
• Esclareça (ou deduza e declare) o tom do produto, plataformas (web, iOS, Android), densidade e se o modo escuro e o modo de alto contraste são necessários.

2. Arquitetura: três camadas

1. Tokens primitivos: valores brutos com nomes neutros. --gray-50 ... --gray-950, --blue-600, --space-4, --radius-md. Nunca usados diretamente em componentes.
2. Tokens semânticos: aliases baseados em propósito. --bg, --surface, --surface-sunken, --border, --border-strong, --text, --text-muted, --text-subtle, --accent, --accent-fg, --accent-subtle, --focus-ring, --success, --warning, --danger, --info (+ variantes -subtle). Os temas alternam entre estes.
3. Tokens de componente (apenas quando necessário): --button-height-md, --input-border, --card-padding. Adicione-os quando um componente precisar ser estilizado de forma independente.

Nomeação: categoria-função-variante-estado (--text-muted, --accent-hover). Sem nomes de cores em tokens semânticos (--accent, não --blue).

3. Decisões a tomar

• Espaçamento: base 4px. Escala 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128. (Fluent 2 e Material ambos usam base 4px; a escala padrão do Tailwind é baseada em 4px.)
• Tipografia: uma ou duas famílias; uma escala modular (1.2 denso, 1.25 produto, 1.333+ editorial); funções em vez de tamanhos (display, título, heading, corpo, label, legenda, código); alturas de linha por função; clamp() fluido apenas para tamanhos de display.
• Cor: rampa neutra de 10 a 12 passos (levemente quente ou fria, escolhida propositalmente), uma rampa de destaque, quatro matizes semânticas. Gere rampas em OKLCH para passos perceptuais uniformes.
• Raio: uma família (sharp, soft ou round) com 3 a 4 passos mais full.
• Elevação: no máximo 3 níveis (raised, floating, overlay), sombras neutras de duas camadas; no modo escuro prefira superfícies mais claras em vez de sombras mais pesadas.
• Movimento: 3 durações (rápido ~140ms, base ~220ms, lento ~320ms), 3 easings (out, in, in-out) e uma regra de movimento reduzido.
• Camadas: uma pequena escala de z-index (sticky, dropdown, overlay, dialog, toast, tooltip).
• Breakpoints: orientados por conteúdo; um conjunto comum é 640, 768, 1024, 1280, 1536.

4. Temas e contraste

• Defina claro e escuro juntos. Modo escuro: fundo quase preto (não #000), texto quase branco (não #fff), superfícies mais claras para elevação, destaque clareado e levemente dessaturado.
• Adicione uma variante prefers-contrast: more que fortalece bordas e texto suave.
• Verifique cada par texto/fundo com a fórmula WCAG 2 e publique as taxas: texto 4.5:1, texto grande e IU significativa (bordas de entrada, ícones, anéis de foco) 3:1. Inclua os números na documentação; não declare "em conformidade com AA" sem calculá-lo.

5. Entregáveis

Produza, na pilha do projeto:

1. tokens.css (propriedades customizadas CSS, claro + escuro + alto contraste), e/ou o mapeamento de tema Tailwind (@theme na v4, theme.extend na v3), e/ou tokens.json no formato W3C Design Tokens Community Group se um pipeline (Style Dictionary) for usado.
2. Um breve DESIGN.md documentando: princípios (3 a 5 linhas), as tabelas de tokens com taxas de contraste, funções tipográficas, regras de uso de espaçamento e faça/não faça para os componentes principais (botão, entrada, cartão, diálogo, tabela, toast).
3. Opcionalmente, um único styleguide.html / página de história renderizando cada token e estado do componente em ambos os temas, para que o sistema possa ser verificado visualmente.

6. Migração (produtos existentes)

• Mapeie valores existentes para o token mais próximo; liste valores que desaparecem e por quê.
• Substitua na ordem: cores, depois espaçamento, depois tipografia, depois raios e sombras.
• Mantenha uma camada de alias temporária para nomes antigos se a base de código for grande.

Lista de verificação

• Camadas primitiva, semântica e (apenas onde necessário) de componente estão separadas.
• Componentes referenciam apenas tokens semânticos.
• Temas claro, escuro e alto contraste existem e cada par tem uma taxa calculada.
• Espaçamento é baseado em 4px; uma família de raio; no máximo três níveis de elevação.
• Funções tipográficas cobrem desde display até legenda; no máximo duas famílias, três pesos.
• Tokens de movimento incluem uma regra de movimento reduzido.
• A documentação explica quando usar cada token, não apenas seu valor.