joo6077/design-system

Armadilhas

1. Proibir valores concretos na nomeação de tokens — blue-500, primary-blue ✗ → color.text.primary, color.background.brand ✓. Quando o valor muda, o nome fica inconsistente e quebra imediatamente durante rebranding ou transição para modo escuro.

2. Não usar apenas primitivos sem semântica — Conectar color.green.500 diretamente a um componente impede a troca de tema. É obrigatório passar pelas 3 camadas: primitivo → semântico(alias) → componente.

3. Não colocar modo escuro no nome do token — color-dark-text-primary, color-light-surface ✗. Isso torna o consumidor dependente de tema. O padrão é mapear valores por modo em um único token semântico.

4. Proibir valores arbitrários sem escala — Acumular valores aleatórios como 10px, 14px, 18px, 22px quebra o sistema. Defina primeiro uma escala finita (ex.: 2/4/8/12/16/24/32) e rejeite valores fora dela.

5. Não reutilizar tokens de componente como se fossem globais — Usar button.primary.background em outro componente aumenta o acoplamento. Promova a semântico global somente quando for necessário em vários componentes.

6. Tipografia como tokens agrupados, não valores individuais — Usar font-size-14 e line-height-20 separadamente causa erros de combinação. Priorize tokens de estilo semântico agrupados como font.body.medium, que incluem size/weight/line-height.

7. Documentar obrigatoriamente a base de spacing — Se a base não for 4px, documente a justificativa. A consistência em usar apenas a escala permitida é mais importante que o número da base.

8. Regras de nomenclatura DTCG — Não use { } . em nomes de token ou grupo; nomes não começam com $ (prefixo $ é reservado para chaves de atributo como $value · $type). A hierarquia é criada aninhando grupos JSON. O . aparece apenas em referências para unir nomes de grupo ({color.text.primary}), não é um caractere dentro do nome. Fonte: DTCG Format Module 2025.10.

9. Proibir geração de código por stack — Este skill produz apenas princípios e especificações de tokens. Não gere código Flutter/React/CSS diretamente. Delegue isso aos plugins do toolkit correspondente.

10. Usar herança de grupo DTCG $extends — O DTCG 2025.10 adicionou a palavra-chave $extends para herança deep merge entre grupos. Em vez de repetir o mesmo valor primitivo em vários grupos semânticos, crie um grupo comum e referencie-o com $extends. Referências circulares são proibidas e devem ser detectadas pelo parser. Fonte: research-log §A.

11. Variáveis CSS :root em exemplos HTML devem estar consistentes com arquivos existentes do design-kit — Ao incluir snippets HTML com :root { --color-*: ...; } no Passo 4, os valores devem corresponder às variáveis CSS em arquivos HTML existentes em design-kit/docs/ ou design-kit/templates/. Inconsistência de valores é o início da fragmentação do sistema e foi motivo real de REJEIÇÃO (AR-06). Ao adicionar novas variáveis, atualize os arquivos existentes simultaneamente ou documente o motivo da divergência.

12. OKLCH recomendado para primitivos de cor — O Tailwind CSS v4 (anunciado em 2025-01-22; versão estável mais recente v4.3.3, 2026-07-16) mudou sua paleta padrão de rgb para oklch, e o shadcn/ui v4 também completou a migração de HSL para oklch(). OKLCH tem rampas uniformes nos eixos de lightness perceptual (L), chroma (C) e hue (H), e aproveita o wide gamut P3 para superar as limitações sRGB. Ao definir primitivos, priorize a notação oklch(L% C H) e, se necessário fallback para navegadores legados, inclua o hex sRGB. Suporte de navegadores: Safari 16.4+ / Chrome 111+ / Firefox 128+ (mesmo alcance do Tailwind v4). Aviso sobre Figma: A documentação do Figma lista cinco modelos de cor (Hex · HSB · HSL · CSS · RGB) e OKLCH não está na lista (About color models). Não há afirmação explícita de que Variables não aceita OKLCH, portanto não afirme isso categoricamente; é prática comum incluir o hex aproximado ao migrar para Figma (ex.: Obra shadcn kit). Fonte: Tailwind v4 blog, Tailwind v4.3.3, shadcn Tailwind v4, Evil Martians OKLCH, MDN oklch().

13. Enumerate-before-Act — listar exaustivamente antes de modificar tokens — Ao receber solicitações de melhoria no sistema de design existente (ex.: "implementar modo escuro", "organizar tokens semânticos"), antes de editar, enumere obrigatoriamente na seguinte ordem: (1) lista completa de arquivos de tokens existentes + contagem por categoria, (2) distribuição Tier 1 primitivo / Tier 2 semântico / Tier 3 componente, (3) apresente como lista de violações itens ausentes, violações de nomenclatura e falta de suporte a modo escuro, (4) edite somente após aprovação do usuário. Evite o antipadrão de modificar apenas uma parte e dizer "o resto é seguir o exemplo" (resposta a insights-report #1 "Proactive quality gaps" · princípio skill-design-guide §5.5 Enumerate-before-Act).

14. Conformidade com esquema DTCG v1 — alias são referências com chaves — O Design Tokens Community Group publicou em 2025-10-28 o Design Tokens Format Module 2025.10 como primeiro relatório estável "Final Community Group Report" (DTCG v1). O formato JSON usa prefixos $value, $type, $description; objetos de grupo (sem $value) podem definir valor padrão de $type para o grupo. $extensions é metadado de ferramenta. $schema não está na lista de atributos de grupo do Final Report 2025.10 — se for uma extensão de ferramenta, escreva separadamente da especificação DTCG.

    Notação de alias (ponto frequente de erro): A sintaxe de referência da especificação é string entre chaves {group.token}. A Armadilha 8 proíbe { } em nomes de token porque as chaves são reservadas como wrapper de referência — em valores de referência, as chaves são obrigatórias. As duas regras não conflitam. Uma string com notação de ponto ("color.background.surface") é interpretada como string literal, não como referência. A referência com chaves só pode apontar para tokens completos (objetos com $value); para apontar para propriedades individuais dentro de um valor de token, use $ref no formato JSON Pointer (RFC 6901) (#/path/to/target).

    {
      "color": {
        "brand": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc" } },
        "surface": { "$value": "{color.brand}" }
      }
    }
    

    Proibido: chaves value/type legadas (sem prefixo), chaves customizadas com prefixo $, notação de ponto sem chaves como alias. O valor de um token de cor usa uma estrutura de objeto com colorSpace / components / hex (opcional) / alpha (opcional) — strings hex isoladas não fazem parte da especificação. Ferramentas downstream como Tokens Studio, Style Dictionary e zeroheight assumem este formato. Fonte: W3C DTCG v1 announcement 2025-10-28, W3C Final Report, DTCG Format Module (drafts), Tokens Studio DTCG vs Legacy.

15. Não substituir as cores existentes do app por uma nova paleta (Precedência da Fonte Visual de Verdade) — Ao introduzir tokens em um projeto com esquema de cores já em uso, não crie uma paleta "melhor" baseada em pesquisa. Primeiro, extraia e apresente exaustivamente os valores reais em uso e use como base envolvê-los em tokens. Alterar os valores em si é uma proposta separada que requer aprovação do usuário. Se existirem cores de mockup aprovadas pelo usuário no navegador (registradas em .design/approvals/), elas prevalecem sobre a paleta do projeto — normalizar um valor aprovado para um único matiz ou token accent existente é uma regressão. Tabela de prioridades: ../../references/visual-change-protocol.md §1.

    Ruim:  "Defini os tokens de cor de fundo" (cria uma nova rampa neutra sem ler o fundo real do app)
           → "A cor de fundo ainda está estranha, não devia haver cores originais?"
    Ruim:  Substituir accent do mockup aprovado pelo token accent do projeto → "Por que está usando outra cor?"
    Bom: Extrair exaustivamente os valores existentes → apresentar em tabela → "Vou envolver esses valores em tokens semânticos.
          Se houver itens que precisam de ajuste, por favor me avise."
    

16. Solicitação de alteração parcial — apenas aquele token; proibir ajuste simultâneo de valores adjacentes — Em pedidos como "deixar esta cor de borda mais escura" ou "escurecer apenas a superfície em um nível", não ajuste tokens não mencionados (fundo, fill, texto, raio, elevação) junto. Também não recalcule passos adjacentes sob justificativa de consistência da rampa, pois está fora do escopo da solicitação. Antes de editar, registre uma lista de Alterar / Manter e, após a edição, verifique se os valores da lista de Manter permanecem inalterados. Se um token não intencional mudou, reverta e aplique novamente apenas os mencionados. Rollbacks parciais como "a cor está certa agora, mas o gradiente deve voltar ao anterior" revertem apenas o eixo mencionado. Detalhes: ../../references/visual-change-protocol.md §2.

17. Definir apenas a categoria de token solicitada — proibir extensão arbitrária de scaffolding completo do sistema (resposta a insights-report #1 má interpretação de escopo · #3 superengenharia) — Se a solicitação for apenas para uma categoria específica (ex.: "crie uma paleta de cores", "defina a escala de spacing"), defina apenas essa categoria. Não faça scaffolding completo de todo o sistema (typography, radius, elevation, motion) incluindo categorias não solicitadas. A exigência de "sistema de tokens completo" (outras Armadilhas sobre 3 camadas, semântico obrigatório) refere-se à completeza dentro da categoria solicitada, não à extensão arbitrária das categorias em si. Se o escopo for ambíguo, não estenda por suposição; confirme com uma linha: "Definir apenas as cores ou configurar o sistema completo de tokens?". Se achar que uma extensão tem valor, não a inclua na entrega; em vez disso, faça uma proposta separada como: "Também recomendo configurar tokens de tipografia/espaçamento — devo prosseguir?". O mesmo se aplica à construção completa de 3 camadas (primitivo→semântico→componente) — com base em pesquisa de 2026, a maioria das equipes considera 2 camadas (primitivo+semântico) suficiente; a camada de componente só é necessária em escala empresarial. Não produza 3 camadas como padrão sem solicitação ou justificativa de escala. Fonte: zeroheight Design Systems Report 2026 (duas camadas é o padrão da indústria; três camadas completas é usado por cerca de metade das equipes), material-design.md:281 (adoção incremental).

Processo

Passo 1: Detectar sistema de design do projeto

Pesquise arquivos de tema/token de design na raiz do projeto:

# Padrões de pesquisa (independente de stack)
**/theme/**
**/tokens/**
**/design/**
**/styles/**
**/colors.*
**/typography.*

• Se encontrado: HAS_DS=true, analisar estrutura de tokens existente
• Não encontrado: HAS_DS=false, modo de proposta de novo sistema de tokens

Passo 2: Projetar arquitetura de tokens em 3 camadas

Todos os tokens devem ser separados nas 3 camadas abaixo. Não pule camadas para conectar.

Camada 1 — Primitivo (repositório de valores)
  Ex.: color.palette.green.500 = #22c55e
        space.scale.4 = 4px

Camada 2 — Semântico (alias de papel/intenção)
  Ex.: color.text.success → {color.palette.green.500}
        color.background.surface → {color.palette.neutral.50}  (modo claro)
        color.background.surface → {color.palette.neutral.900} (modo escuro)

Camada 3 — Componente (override de exceções de componente)
  Ex.: button.primary.background → {color.background.brand}
        card.border.radius → {radius.md}
  ※ Promover para Camada 2 somente quando se tornar necessário em vários componentes

Critérios obrigatórios/opcionais por categoria e base de nomenclatura semântica:

Categoria	Obrigatório	Exemplo Semântico	Base de Escala
Cor	Obrigatório	text.primary, text.secondary, text.disabled, background.surface, background.brand, border.default, border.subtle	—
Tipografia	Obrigatório	font.display.lg, font.heading.md, font.body.sm, font.label.xs (agrupado size+weight+line-height)	Escala Modular recomendada (1.125 Major Second ~ 1.618 Golden Ratio). Fluido: clamp(min, preferred, max)
Espaçamento	Obrigatório	space.xs(4), space.sm(8), space.md(16), space.lg(24), space.xl(32), space.2xl(48)	Base 4px. Espaçamento fluido: considerar intervalos contínuos baseados em clamp()
Raio	Obrigatório	radius.none(0), radius.sm(4), radius.md(8), radius.lg(16), radius.full(9999)	Escala finita
Elevação	Opcional	elevation.level-0 ~ level-4 (valores de sombra)	—
Movimento	Opcional	motion.duration.fast(100ms), motion.duration.normal(200ms), motion.easing.standard	—

Nota — Material 3 Expressive (anunciado em 2025-05): A documentação oficial do Material afirma que o M3 Expressive se baseia em 46 estudos e mais de 18.000 participantes para oferecer gama de cores mais ampla, cor dinâmica, personalização e um sistema de física de movimento baseado em spring. Criar uma paleta tonal para cada cor com HCT e atribuir esses tons a papéis de cor não é uma funcionalidade exclusiva do Expressive, mas sim uma descrição geral do sistema de cores M3. Fontes variáveis como Roboto Flex são uma opção para expressão, não fazendo parte da escala tipográfica M3. Mapear tons de paleta tonal como primitivos e papéis de cor como aliases semânticos não é uma regra oficial, mas uma convenção deste repositório de estrutura de tokens em 3 camadas. Fonte: Start building with Material 3 Expressive, Color system, Typography, Motion (acessado em 2026-09-28).

Passo 3: HAS_DS=true → Analisar sistema existente

Compare os tokens existentes com a arquitetura de 3 camadas e produza um relatório:

• Camada ausente: itens que conectam primitivos diretamente a componentes
• Violação de nomenclatura: tokens com valores no nome (blue-500, color-dark-*)
• Falta de suporte a modo escuro: tokens semânticos de cor sem alias de modo
• Desvio de escala: uso de valores arbitrários fora da escala permitida
• Mau uso de token de componente: tokens de componente reutilizados em outros componentes
• Problema de separação de tipografia: quando size/weight/line-height são fornecidos apenas como tokens individuais

Passo 4: HAS_DS=false → Gerar especificação de tokens

Gere a especificação de tokens no formato templates/design-tokens.md. Apresente ao usuário as opções de cada categoria na seguinte ordem e obtenha concordância:

1. Paleta de cores da marca (primitivos)
2. Tokens semânticos de cor — incluindo mapeamento para claro/escuro
3. Escala de espaçamento (padrão base 4px; documentar justificativa se alterada)
4. Conjunto de tokens de estilo tipográfico
5. Escala de raio
6. Elevação/movimento (se necessário)

Passo 5: Verificação da entrega

• Verificar se todas as categorias obrigatórias estão separadas em 3 camadas
• Verificar se tokens semânticos são definidos como alias de primitivos (não valores diretos ✗)
• Verificar se existem mapeamentos semânticos para claro/escuro
• Verificar se não há valores arbitrários fora da escala permitida
• Se houver tokens de componente, verificar se o escopo está limitado ao componente
• Verificação de consistência de variáveis CSS :root (Armadilha #11) — se a entrega incluir snippet HTML :root, comparar com valores de variáveis CSS em arquivos HTML existentes em design-kit/docs/ e design-kit/templates/ para garantir que não haja divergências. Se houver divergência, atualizar os arquivos existentes simultaneamente ou documentar o motivo.
• Orientação sobre pipeline Figma Variables → Tokens Studio → Style Dictionary v5 — Ao gerar a especificação de tokens, oriente o usuário sobre o pipeline: Figma Variables (primitivo + semântico) → exportação Tokens Studio DTCG JSON → transformação por plataforma Style Dictionary v5 → sincronização Git. Recomende ativar Code Syntax, usar o campo Description e limitar o escopo. O v5 requer Node.js 22+ e não aceita mais referências apontando para valores não token, referências com .value, nem reescrita de sintaxe de referência — ao migrar configurações v4, verifique esses três pontos primeiro. A vulnerabilidade de poluição de protótipo na saída de objeto convertTokenData foi corrigida no v5.5.5 (2026-09-20); não use versões anteriores. Fonte: research-log §I, Style Dictionary v5.0.0, v5.5.5, v5 Migration.
• Guia de tipografia fluida — Ao definir tokens de tipografia, apresente a opção de escala fluida baseada em clamp(min, preferred, max), além de tamanhos fixos. Recomende uma proporção de Escala Modular (1.125 Major Second ~ 1.618 Golden Ratio) adequada à natureza do projeto, e consulte a abordagem Utopia (interpolação entre duas escalas para telas pequenas/grandes). Fonte: research-log §E.
• Guia de espaçamento fluido — Para tokens de espaçamento, apresente opções: Fixo, Fluido (clamp()) e Adaptativo (transição por breakpoint). Especifique a regra Interno ≤ Externo (padding interno do elemento ≤ margem externa). Fonte: research-log §F.

Referências

• references/token-principles.md — Detalhes dos princípios de design de tokens
• templates/design-tokens.md — Formato de saída da especificação de tokens
• ../../references/visual-change-protocol.md — Prioridade visual · Isolamento de alterações parciais (SSOT)