Pular para o conteúdo principal

component-token-contract

www# Contrato de Tokens para Componentes

Premissa​

Quando um engenheiro de sistema constrói um componente — ou quando um engenheiro de produto customiza uma tela — ele precisa saber exatamente quais tokens usar, de onde vêm, e o que o engine garante que nunca vai mudar sem aviso. Este documento define esse contrato: as regras canônicas que regulam o consumo de tokens em componentes e UIs.

O contrato tem duas dimensões:

  • Quais tokens usar (Semantic vs Foundation, quando e por quê)
  • O que o engine garante (namespaces reservados, breaking changes, versioning)

A Regra Fundamental​

Sempre use Semantic.
Use Foundation quando existir um alias adequado.
Nunca use Brand, Mode ou Surface diretamente.
CamadaConsumo em componentesPor quê
SemanticSempre — é a camada canônica expostaExpressa propósito, não valor interno. Todos os tokens são calculados, testados e garantidos por WCAG
FoundationQuando um alias adequado já existeAtalho cognitivo para times de produto. NÃO substitui Semantic como fonte de verdade
brand.*, mode.*, surface.*Proibido em código de componenteCamadas internas — qualquer referência a elas quebra com mudanças de arquitetura

Por que Semantic, não Foundation?​

A Foundation é uma camada de redução de carga cognitiva — ela existe para times de produto que constroem telas, não para quem constrói os componentes. Um componente que usa foundation.bg.primary aparentemente funciona, mas depende de que o tema atual tenha esse alias definido. Se o alias não existir ou mudar, o componente quebra silenciosamente.

A Semantic é o contrato estável. Um alias Foundation é opcional e conveniente — nunca obrigatório.

Quem Consome o Quê​

PerfilCamada principalFallback
Engenheiro de DS (constrói componentes base)Semantic — sempre, sem exceção—
Engenheiro de Produto (monta telas com componentes)Foundation — quando o alias existeSemantic quando o alias não cobre o caso
Designer (no Figma via Tokens Studio)Semantic — para componentes; Foundation — para layouts—
AI / Code ConnectSemantic identificado por semantic.*Foundation identificado por foundation.*

Como Reconhecer Tokens​

O prefixo do caminho identifica a camada:

PrefixoCamadaExemplo
semantic.*Semantic — camada canônicasemantic.color.interface.function.primary.normal.background
foundation.*Foundation — alias para Semanticfoundation.bg.primary
component.*Component — tokens de componente específico (quando disponível)component.button.primary.background
brand.*, mode.*, surface.*Camadas internas — nunca usar—

No CSS, os mesmos prefixos são usados com hifens:

/* Semantic */
var(--semantic-color-interface-function-primary-normal-background)

/* Foundation */
var(--foundation-bg-primary)

Mapa de Tokens Semantic por Categoria​

Cores de Marca — semantic.color.brand​

Branding (semantic.color.brand.branding)​

Identidade de marca primária. Use em áreas hero, CTAs de marca e destaques.

Estrutura: semantic.color.brand.branding.{papel}.{intensidade}.{propriedade}

SegmentoValores
{papel}first, second, third
{intensidade}lowest, low, default, high, highest
{propriedade}background, txtOn, border, txt (desde 3.6.0)
/* Botão hero de marca, estado normal */
background: var(--semantic-color-brand-branding-first-default-background);
color:      var(--semantic-color-brand-branding-first-default-txt-on);
border:     var(--semantic-color-brand-branding-first-default-border);

Ambient (semantic.color.brand.ambient)​

Canvas base, neutros e escala de cinza. Use em layout, superfícies e hierarquia de texto — não em ênfase colorida.

Estrutura:

SubgrupoChavesUso típico
contrast.basepositive, negativeCanvas principal, contraste de superfície
contrast.deeppositive, negativeClaro e escuro absolutos
neutrallowest → highest (7 níveis)Painéis elevados, superfícies secundárias
grayscalelowest → highest (7 níveis)Escala de cinza fixa independente de marca
/* Fundo principal do canvas */
background: var(--semantic-color-brand-ambient-contrast-deep-positive-background);

/* Painel elevado */
background: var(--semantic-color-brand-ambient-neutral-low-background);

Controles Interativos — semantic.color.interface.function​

Botões, links, controles e elementos interativos.

Estrutura: semantic.color.interface.function.{papel}.{estado}.{propriedade}

{papel}Uso
primaryCTA principal
secondaryAção secundária
linkLinks e ações de texto
activeUI ativa ou selecionada
disabledControles desabilitados (só tem estado normal)
{estado}Mapeia para
normalEstado padrão / repouso
actionHover ou pressed
activeAtivo / selecionado
/* Botão primário — normal */
background: var(--semantic-color-interface-function-primary-normal-background);
color:      var(--semantic-color-interface-function-primary-normal-txt-on);
border:     var(--semantic-color-interface-function-primary-normal-border);

/* Botão primário — hover */
background: var(--semantic-color-interface-function-primary-action-background);

/* Botão desabilitado */
background: var(--semantic-color-interface-function-disabled-normal-background);
color:      var(--semantic-color-interface-function-disabled-normal-txt-on);

Feedback do Sistema — semantic.color.interface.feedback​

Alertas, badges e mensagens de sistema: info, success, warning, danger.

Estrutura: semantic.color.interface.feedback.{tipo}.{variante}.{estado}.{propriedade}

{tipo}Significado
infoInformativo / neutro
successConfirmação / sucesso
warningAtenção / alerta
dangerErro / ação destrutiva
{variante}Uso
defaultFundo suave — surfaces de alerta
secondaryVariante mais saturada — bordas e ícones
/* Alerta de sucesso */
background: var(--semantic-color-interface-feedback-success-default-normal-background);
color:      var(--semantic-color-interface-feedback-success-default-normal-txt-on);
border:     var(--semantic-color-interface-feedback-success-secondary-normal-border);

Regra de acessibilidade: Sempre use background e txtOn do mesmo token. O par garante contraste WCAG. Nunca combine background de um nível com txtOn de outro.

Cores de Texto — semantic.color.text​

Tokens de texto simplificados — planos, sem intensidade, apenas propósito.

TokenUso
semantic.color.text.titleTítulos e texto primário de UI
semantic.color.text.bodyCorpo de texto — conteúdo principal
semantic.color.text.highlightTexto em destaque ou ênfase
semantic.color.text.mutedTexto secundário ou desabilitado
semantic.color.text.labelLabels de formulário e legendas
semantic.color.text.info_defaultTexto de feedback informativo
semantic.color.text.success_defaultTexto de feedback de sucesso
semantic.color.text.warning_defaultTexto de alerta
semantic.color.text.danger_defaultTexto de erro
h1 { color: var(--semantic-color-text-title); }
p  { color: var(--semantic-color-text-body); }
label { color: var(--semantic-color-text-label); }

Cores de Produto — semantic.color.product​

Cores específicas de produto — promoções, cashback, tiers, categorizações. A única área aberta da Semantic onde times de produto podem declarar categorias customizadas.

Estrutura: semantic.color.product.{item}.{variante}.{intensidade}.{propriedade}

SegmentoValores
{item}promo, cashback, premium — ou qualquer nome livre definido no config
{variante}default, secondary
{intensidade}lowest, low, default, high, highest
{propriedade}background, txtOn, border, txt (desde 3.6.0)

Tokens de texto plano também disponíveis em semantic.color.text.{item} e semantic.color.text.{item}_secondary.

[!CAUTION] Custo exponencial. Cada item novo em product gera no mínimo 40 tokens (desde 3.6.0) que se propagam por todas as camadas e todos os temas. Em um sistema com 4 temas, um único item representa +160 tokens. Antes de adicionar, pergunte: "Isso pode ser resolvido com feedback ou brand existentes?" Veja 04-semantic-layer.md para o racional completo.

Gradientes — semantic.color.gradient​

Configuração e passos de gradientes de marca.

GrupoTokens
gradient.config.degreeshorizontal, vertical, toBottom, diagonalLeft, diagonalRight, diagonalBrand, diagonalBrandAlt
gradient.config.steps0, 10, 20, … 100 (paradas em %)
gradient.config.colorsfirst.lowest, first.default, etc.

Gradientes são configurados no arquivo de tema (*.config.mjs) e só aparecem no output se sync:architecture rodar após themes:generate. Veja 04-build-pipeline.md.

Opacidade — semantic.opacity​

Transparência para overlays, estados desabilitados e efeitos de vidro.

SubgrupoChavesUso
opacity.rawtransparent (0), superTransparent (10), semiTranslucid (20), translucid (50), superTranslucid (80), semiOpaque (90), opaque (100)Valor numérico para aplicar a qualquer cor
opacity.color.grayscaleMesmas chavesCor escura pronta com opacidade aplicada
opacity.color.lightMesmas chavesCor clara pronta com opacidade aplicada
/* Overlay de modal */
background: var(--semantic-opacity-color-grayscale-super-translucid);

/* Estado desabilitado via opacidade */
opacity: calc(var(--semantic-opacity-raw-semi-translucid) / 100);

Tipografia — semantic.typography​

Estrutura:

GrupoTokens relevantes
fontFamiliesmain, content, display, code
fontWeightsPor família × peso × estilo (normal/italic)
fontSizesextraSmall → peta (escala de 13 tamanhos)
lineHeightstight, close, regular × tamanho
letterSpacings, paragraphSpacing, textCase, textDecorationComplementos tipográficos

Os estilos compostos da Foundation (heading, content, display, hierarchy, action, link, code) consomem esses tokens e são a forma preferida para os times de produto. No DS, acesse semantic.typography diretamente para controle granular.

Dimensão — semantic.dimension​

Espaçamento e sizing para layout, padding, margin, gap e dimensões de componente.

GrupoEscala de tokens
sizingzero, pico, nano, micro, extraSmall, small, medium, large, extraLarge, mega, giga, tera, peta
spacingMesma escala (mínimo: micro)

O medium na variante normal corresponde a 16px (1 LayoutUnit). Use sizing para altura de componente, ícone e espessura de borda; spacing para padding, margin e gap.

Borda — semantic.border​

GrupoTokensUso
widthnone, small, medium, large, extraLargeEspessura de contorno, divisores, rings de foco
radiistraight, micro, extraSmall, small, medium, large, extraLarge, mega, circularBorder radius por componente
/* Card com radius médio */
border-radius: var(--semantic-border-radii-medium);
border-width:  var(--semantic-border-width-small);

Profundidade — semantic.depth​

Spread de sombra para elevação.

TokenValorUso
depth.spread.close0Sem elevação
depth.spread.next-2Elevação mínima
depth.spread.near-4Cards e painéis
depth.spread.distant-8Dropdowns
depth.spread.far-12Modais e dialogs

Maior magnitude = mais elevação. Os estilos de elevação compostos da Foundation (elevation.level_one → elevation.level_five) são a forma preferida nos times de produto.

O Par Background + txtOn​

Toda superfície colorida no sistema tem dois tokens complementares: background e txtOn. O txtOn é calculado automaticamente pelo engine para garantir contraste WCAG AA (ou AAA, dependendo da config do tema).

Regra invariável: Sempre use o txtOn do mesmo token que o background.

/* CERTO — par do mesmo token */
.badge-success {
  background: var(--semantic-color-interface-feedback-success-default-normal-background);
  color:      var(--semantic-color-interface-feedback-success-default-normal-txt-on);
}

/* ERRADO — mistura de tokens diferentes */
.badge-success {
  background: var(--semantic-color-interface-feedback-success-default-normal-background);
  color:      var(--semantic-color-text-body); /* ← contraste não garantido */
}

Padrões Proibidos​

Padrão proibidoPor quêO que usar em vez
var(--theme-color-*)Camada internavar(--semantic-color-*)
var(--brand-*), var(--mode-*), var(--surface-*)Camadas internasvar(--semantic-color-*)
Inventar --semantic-color-minha-cor em CSS de produtoViola o contrato — pode conflitar com builds futurosUsar apenas paths que existem no dist/
Hardcoded hex #C40145 em CSS de componentePerde theming automático, dark mode e multi-marcavar(--semantic-color-interface-function-primary-normal-background)
semantic.color.interface.feedback.info_default.background com semantic.color.text.body sobrepostosContraste não garantidoUse o par background + txtOn do mesmo token

Contrato de Versionamento​

O que é garantido​

O engine garante que os caminhos publicados em dist/ (ex.: --semantic-color-interface-function-primary-normal-background) não mudarão sem um bump de versão major. Qualquer path que apareça no build é parte do contrato público.

O que é breaking change​

  • Renomear um caminho de token (semantic.color.interface.oldName → semantic.color.interface.newName) — major version
  • Remover um caminho de token — major version
  • Adicionar um novo caminho — minor version (não quebra consumidores existentes)

Depreciação​

Quando um token precisa ser renomeado, o engine pode optar por uma janela de depreciação: o caminho antigo permanece no build marcado como deprecated na $description, com o caminho novo indicado. A remoção acontece na próxima versão major.

Mudanças são documentadas no CHANGELOG.md do engine, que especifica: caminho antigo, caminho novo, versão de remoção.

Referências​