Tokens é o contrato estruturado de valores de design — cores, tipografia, espaçamento, raio, sombra, z-index, motion e breakpoints. É o que transforma as semânticas do Docs/design-system.md em valores consumíveis por código.
Fase: 3 — Design de Produto
Pré-requisito: Docs/design-system.md aprovado
Template: Templates/Full/tokens.json ou Templates/Quick/tokens.json
Artefato oficial: Docs/tokens.json
Usado por: frontend, CSS vars, Tailwind config, style tokens
A distinção fundamental
design-system.md → regra: "o botão primário tem destaque máximo e label verbo + objeto"
tokens.json → valor: color.brand.primary: "#1A56DB", spacing.4: "16px"Docs/design-system.md define o que e por quê. Docs/tokens.json define o quanto — os valores numéricos e hexadecimais que a implementação usa. Um não substitui o outro.
Estrutura do arquivo
O template Full tem 4 seções de primeiro nível:
{
"$schema": "...",
"meta": { ... },
"theme": { ... },
"tokens": { ... },
"aliases": { ... }
}meta — identificação e rastreabilidade
{
"meta": {
"projectName": "[preencher]",
"version": "v1",
"status": "draft",
"description": "Contrato oficial de design tokens do projeto.",
"sourceDocuments": ["Docs/design-system.md"],
"updatedAt": "[yyyy-mm-dd]"
}
}theme — modo visual
{
"theme": {
"name": "default",
"mode": "light"
}
}Para projetos com dark mode, criar segundo objeto de tema com "mode": "dark" e os valores ajustados.
Categorias de tokens
color — cores semânticas por papel
"color": {
"brand": {
"primary": { "value": "[hex]", "description": "Cor principal da marca." },
"secondary": { "value": "[hex]", "description": "Cor secundária da marca." },
"accent": { "value": "[hex]", "description": "Cor de destaque complementar." }
},
"background": {
"base": { "value": "[hex]", "description": "Fundo principal da aplicação." },
"surface": { "value": "[hex]", "description": "Superfície de cards e painéis." },
"elevated": { "value": "[hex]", "description": "Modais, dropdowns e áreas destacadas." },
"inverse": { "value": "[hex]", "description": "Fundo invertido." }
},
"text": {
"primary": { "value": "[hex]", "description": "Texto principal." },
"secondary": { "value": "[hex]", "description": "Texto secundário." },
"muted": { "value": "[hex]", "description": "Legenda ou baixa ênfase." },
"inverse": { "value": "[hex]", "description": "Texto sobre fundo escuro." },
"disabled": { "value": "[hex]", "description": "Texto desabilitado." }
},
"border": {
"default": { "value": "[hex]", "description": "Borda padrão." },
"strong": { "value": "[hex]", "description": "Borda de maior contraste." },
"subtle": { "value": "[hex]", "description": "Borda discreta." },
"focus": { "value": "[hex]", "description": "Anel de foco (acessibilidade)." }
},
"state": {
"success": { "base": {...}, "surface": {...}, "text": {...} },
"warning": { "base": {...}, "surface": {...}, "text": {...} },
"error": { "base": {...}, "surface": {...}, "text": {...} },
"info": { "base": {...}, "surface": {...}, "text": {...} },
"disabled":{ "base": {...}, "surface": {...}, "text": {...} }
}
}spacing — escala de espaçamento
Escala de 0 a 12 em px, progressiva:
| Token | Valor | Uso típico |
|---|---|---|
spacing.1 | 4px | gap mínimo, ícone + texto |
spacing.2 | 8px | padding de badge, espaço entre campos |
spacing.4 | 16px | padding padrão de card, input |
spacing.6 | 24px | gap entre seções |
spacing.8 | 32px | padding de tela |
spacing.12 | 48px | espaçamento amplo entre blocos |
radius — arredondamento de bordas
| Token | Valor | Uso típico |
|---|---|---|
radius.none | 0px | elemento sem arredondamento |
radius.sm | 4px | badges, chips |
radius.md | 8px | inputs, botões |
radius.lg | 12px | cards |
radius.xl | 16px | modais |
radius.full | 9999px | avatares, pill buttons |
borderWidth — espessura de borda
none (0px) · thin (1px) · medium (2px) · thick (3px)
fontFamily — famílias tipográficas
"fontFamily": {
"base": { "value": "[font-family]", "description": "Fonte padrão." },
"heading": { "value": "[font-family]", "description": "Fonte para títulos." },
"mono": { "value": "[font-family]", "description": "Fonte monoespaçada." }
}fontSize — escala de tamanhos
| Token | Valor | Uso típico |
|---|---|---|
fontSize.xs | 12px | legenda, ajuda |
fontSize.sm | 14px | corpo secundário, rótulo |
fontSize.md | 16px | corpo principal |
fontSize.lg | 18px | corpo grande |
fontSize.xl | 20px | título de seção |
fontSize.2xl | 24px | título de módulo |
fontSize.3xl | 32px | título de página |
fontWeight · lineHeight
"fontWeight": { "regular": 400, "medium": 500, "semibold": 600, "bold": 700 }
"lineHeight": { "tight": 1.2, "normal": 1.5, "relaxed": 1.7 }shadow — elevação
none · sm (leve) · md (padrão) · lg (forte)
opacity
"opacity": {
"disabled": 0.5,
"subtle": 0.72,
"overlay": 0.6
}zIndex — camadas
| Token | Valor | Uso |
|---|---|---|
zIndex.base | 1 | camada base |
zIndex.dropdown | 1000 | dropdown, select |
zIndex.sticky | 1100 | header fixo, sidebar |
zIndex.modal | 1200 | modal, dialog |
zIndex.toast | 1300 | notificações |
zIndex.tooltip | 1400 | tooltip |
motion — animação e transição
"motion": {
"duration": {
"fast": "120ms",
"normal": "200ms",
"slow": "320ms"
},
"easing": {
"standard": "ease",
"emphasized": "cubic-bezier(0.2, 0, 0, 1)",
"exit": "cubic-bezier(0.4, 0, 1, 1)"
}
}breakpoint — responsividade
| Token | Valor |
|---|---|
breakpoint.sm | 640px |
breakpoint.md | 768px |
breakpoint.lg | 1024px |
breakpoint.xl | 1280px |
breakpoint.2xl | 1536px |
aliases — composição por componente
Aliases referenciam tokens primitivos com a sintaxe {tokens.categoria.chave} para compor componentes sem duplicar valores:
"aliases": {
"card": {
"background": "{tokens.color.background.surface}",
"borderColor": "{tokens.color.border.subtle}",
"radius": "{tokens.radius.lg}",
"shadow": "{tokens.shadow.sm}",
"padding": "{tokens.spacing.4}"
},
"button": {
"primaryBackground": "{tokens.color.brand.primary}",
"primaryText": "{tokens.color.text.inverse}",
"radius": "{tokens.radius.md}",
"paddingY": "{tokens.spacing.2}",
"paddingX": "{tokens.spacing.4}"
},
"feedback": {
"successBackground": "{tokens.color.state.success.surface}",
"successText": "{tokens.color.state.success.text}",
"errorBackground": "{tokens.color.state.error.surface}",
"errorText": "{tokens.color.state.error.text}"
}
}Os aliases resolvem o problema de sincronização. Se color.brand.primary muda de valor, todos os aliases que o referenciam atualizam automaticamente — sem busca e substituição manual.
Full vs Quick
| Aspecto | Full | Quick |
|---|---|---|
| Seções de cor | brand, background, text, border, 5 states completos | brand, background, text, 4 states simples |
| Spacing | 10 tokens (0–12) | 5 tokens (1, 2, 4, 6, 8) |
| Tipografia | fontFamily, fontSize, fontWeight, lineHeight | fontSize apenas |
| Extras | opacity, zIndex, motion, breakpoint | breakpoint |
| Aliases | page, card, input, button, feedback | page, button |
Prompt para gerar com agente
Atue como UIAgent.
Objetivo: criar Docs/tokens.json com base em Docs/design-system.md
Carregue contexto base:
- GUIDE.md
- Skills/ui-ux.md
- Templates/Full/tokens.json
- Docs/design-system.md
Preencha todos os campos de valor [hex] com base nas semânticas definidas em design-system.md.
Preencha fontFamily com as fontes aprovadas.
Preencha aliases para todos os componentes documentados em design-system.md seção 10.
Mantenha description em cada token.
Atualize meta.projectName e meta.updatedAt.Definição de pronto
O tokens.json está pronto quando:
metapreenchido com nome do projeto, versão e data- Todos os
[hex]substituídos por valores reais fontFamilycom fontes aprovadasstatecompleto — success, warning, error, info, disabled — cada um com base, surface e textaliasescriados para todos os componentes doDocs/design-system.mdseção 10- Valores sincronizados com o que está documentado em
Docs/design-system.md
Valor de token sem correspondência em Docs/design-system.md é valor órfão — não tem papel semântico definido e gera inconsistência na implementação. Todo token deve nascer de uma semântica documentada.
Erros comuns
| Erro | Correção |
|---|---|
[hex] não substituído | Preencher todos os valores antes de usar o arquivo |
Token sem description | Todo token deve ter descrição do seu papel semântico |
| Alias referenciando token inexistente | Verificar a chave exata antes de criar o alias |
| tokens.json desatualizado após mudança no design-system | Atualizar manualmente ou regenerar via agente |
| Dark mode não contemplado | Criar segundo objeto de tema com os valores ajustados |
Relação com outros artefatos
Docs/design-system.md (aprovado)
↓
Docs/tokens.json — formaliza em valores os papéis semânticos definidos
↓
Implementação — CSS vars, Tailwind config, style-dictionary ou tokens-studio