---
id: extract-tokens
agent: ux-design-expert
title: Extrair design tokens dos padrões consolidados
inputs: [padrões consolidados, story/spec de design system]
outputs: [design tokens (cor, espaçamento, tipografia, raio, sombra), docs/design-system/tokens/]
elicit: false
modes: [interactive, yolo]
---

# Extrair design tokens dos padrões consolidados

**Objetivo:** transformar os padrões visuais consolidados num conjunto de design tokens nomeados e
versionados — a fonte única de verdade para cor, espaçamento, tipografia, raio e sombra. Daqui pra
frente, nada é hardcoded.

**Pré-condições:**
- A consolidação (`consolidate-patterns`) já reduziu a redundância e existe o conjunto de variantes
  vencedoras. Sem isso, **pare**: tokenizar o caos só normaliza o caos.
- Há uma story/spec pedindo o design system (ou a migração que o exige). Sem rastro, elicito — não
  invento paleta nem escala.

## Passos

1. **Leio os padrões consolidados** e extraio os valores brutos recorrentes: cores usadas,
   espaçamentos, tamanhos/pesos de fonte, raios de borda, sombras.
2. **Agrupo cada dimensão numa escala semântica**, não numa lista de hex solto:
   - **cor:** primária/secundária/neutra + estados (success/warning/danger/info), com nomes de
     intenção (ex.: `color.action.primary`), não de aparência (`color.blue-500` só como referência).
   - **espaçamento:** escala consistente (ex.: 4/8/12/16/24/32) com nomes (`space.xs…space.2xl`).
   - **tipografia:** família, escala de tamanho, pesos e line-heights nomeados.
   - **raio e sombra:** níveis nomeados (`radius.sm/md/lg`, `shadow.1/2/3`).
3. **Valido contraste WCAG AA** em cada par texto/fundo dos tokens de cor — contraste reprovado não
   vira token: ajusto o valor ou marco o par como proibido. Acessibilidade é piso, não enfeite.
4. **Escrevo os tokens** em formato consumível (ex.: JSON/CSS custom properties) em
   `docs/design-system/tokens/`, organizados por dimensão, com versão e referência aos padrões de
   origem (rastro — cada token sabe de onde veio).
5. **Registro divergências resolvidas:** quando dois valores quase iguais viraram um só token,
   anoto o mapeamento (valor antigo → token) para a migração depois consumir.
6. **Atualizo a File List** da story com os arquivos de token criados.
7. **Roteio.** Tokens prontos alimentam `setup-design-system` e `build-component`. Decisão de stack
   de tokens (ex.: ferramenta de build/transform) é da Aria (@architect) — eu trago a lente de UX e
   delego. Subida é do @devops.

## Critério de pronto (DoD)

- [ ] Cada dimensão (cor, espaçamento, tipografia, raio, sombra) tem escala semântica nomeada
- [ ] Todo par texto/fundo de cor passou em contraste WCAG AA (ou está marcado como proibido)
- [ ] Tokens escritos em `docs/design-system/tokens/`, versionados e com rastro à origem
- [ ] Mapeamento valor antigo → token registrado para a migração
- [ ] Zero valor hardcoded sobrando como decisão final; File List atualizada

## Falha / recuperação

- **Padrões não consolidados** → HALT; volto à `consolidate-patterns`, não tokenizo redundância.
- **Cor reprova contraste e não há ajuste óbvio** → não publico o token; sinalizo o conflito e busco
  o valor acessível antes de fechar a paleta.
- **A escala fica ambígua (muitos valores próximos sem critério)** → elicito a decisão de design em
  vez de inventar a regra de arredondamento.