Nébula
GitHub

Produto

Tokens

Documentação do artefato tokens.json — estrutura, categorias, aliases e como preencher com base no design system.

tokens.mdMARKDOWNLeitura: 4 minSeções: 23

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"
Importante

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:

TokenValorUso típico
spacing.14pxgap mínimo, ícone + texto
spacing.28pxpadding de badge, espaço entre campos
spacing.416pxpadding padrão de card, input
spacing.624pxgap entre seções
spacing.832pxpadding de tela
spacing.1248pxespaçamento amplo entre blocos

radius — arredondamento de bordas

TokenValorUso típico
radius.none0pxelemento sem arredondamento
radius.sm4pxbadges, chips
radius.md8pxinputs, botões
radius.lg12pxcards
radius.xl16pxmodais
radius.full9999pxavatares, 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

TokenValorUso típico
fontSize.xs12pxlegenda, ajuda
fontSize.sm14pxcorpo secundário, rótulo
fontSize.md16pxcorpo principal
fontSize.lg18pxcorpo grande
fontSize.xl20pxtítulo de seção
fontSize.2xl24pxtítulo de módulo
fontSize.3xl32pxtí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

TokenValorUso
zIndex.base1camada base
zIndex.dropdown1000dropdown, select
zIndex.sticky1100header fixo, sidebar
zIndex.modal1200modal, dialog
zIndex.toast1300notificações
zIndex.tooltip1400tooltip

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

TokenValor
breakpoint.sm640px
breakpoint.md768px
breakpoint.lg1024px
breakpoint.xl1280px
breakpoint.2xl1536px

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}"
  }
}
Dica

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

AspectoFullQuick
Seções de corbrand, background, text, border, 5 states completosbrand, background, text, 4 states simples
Spacing10 tokens (0–12)5 tokens (1, 2, 4, 6, 8)
TipografiafontFamily, fontSize, fontWeight, lineHeightfontSize apenas
Extrasopacity, zIndex, motion, breakpointbreakpoint
Aliasespage, card, input, button, feedbackpage, 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:

  1. meta preenchido com nome do projeto, versão e data
  2. Todos os [hex] substituídos por valores reais
  3. fontFamily com fontes aprovadas
  4. state completo — success, warning, error, info, disabled — cada um com base, surface e text
  5. aliases criados para todos os componentes do Docs/design-system.md seção 10
  6. Valores sincronizados com o que está documentado em Docs/design-system.md
Atenção

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

ErroCorreção
[hex] não substituídoPreencher todos os valores antes de usar o arquivo
Token sem descriptionTodo token deve ter descrição do seu papel semântico
Alias referenciando token inexistenteVerificar a chave exata antes de criar o alias
tokens.json desatualizado após mudança no design-systemAtualizar manualmente ou regenerar via agente
Dark mode não contempladoCriar 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