Status: Approved · v3 · SPEC-UX-TOKENS-001

depends_on: SPEC-BRAND-001

used_by: IS-ZERO-00.2, IS-MVP-01.1, IS-MVP-17.1, IS-MVP-17.2, IS-MVP-17.3, IS-MVP-17.4, IS-MVP-19.2

Design tokens v3 — quatro modos

Fonte canônica para web, mobile, componentes e renderização de cards. Os valores abaixo espelham as variáveis .tz e [data-theme="light"] .tz dos artefatos design/*.dc.html.

1. Princípios

• O shape é { identity: raiz|neutral, luminosity: dark|light }; ausência de preferência usa neutral/dark.
• Preferência legada dark|light migra para raiz/<valor>.
• Parser rejeita campos/enums desconhecidos e storage corrompido; o fallback é neutral/dark, sem logar o valor bruto nem persistir até uma escolha válida.
• Componentes consomem nomes semânticos, nunca cores físicas ou hex solto.
• primary depende da identidade: Raiz #EA580C; Neutro Dark #E8E4DC; Neutro Light #2A2520.
• on-primary é o texto/ícone obrigatório sobre primary; componentes não calculam nem escolhem esse contraste localmente.
• accent, success e danger qualificam informação; cor nunca substitui texto/ícone.
• O logo usa os assets oficiais de assets/new_brand/; #FB923C é reservado ao FC/asset de marca e não vira token de ação.

2. Cores semânticas canônicas

Token	Noite de Holofote (dark)	Editorial Terrão (light)	Uso obrigatório
background	#111111	#FBF7ED	canvas da aplicação
surface	#1B1816	#FFFFFF	cards, barras, painéis e overlays
surface-alt	#2A2420	#F3E7CE	seleção neutra, controle agrupado, skeleton
text	#F7F5EB	#0B0B0C	texto principal
text-muted	#B2A79E	#655B53	metadata e ajuda não crítica
border	#3B302A	#E4C99B	divisores, contornos e estruturas
primary	por identidade	por identidade	ação principal, seleção e navegação ativa
on-primary	por identidade	por identidade	texto e ícone sobre primary
accent	#F2B230	#C44121	holofote/contexto e destaque secundário
success	#58A96C	#2F8F46	validada, vitória e sucesso
danger	#E06555	#C63F3F	contestada, derrota, erro e destrutivo

Token auxiliar documentado nos artefatos:

Token	Dark	Light	Uso
chip-overlay	rgba(255,255,255,.06)	rgba(0,0,0,.05)	fundo neutro de chip; nunca para texto

Mapeamento literal dos artefatos

CSS do protótipo	Token semântico v3
--bg	background
--sur	surface
--sur2	surface-alt
--txt	text
--mut	text-muted
--bor	border
--pri	primary
--acc	accent
--ok	success
--dng	danger
--chip	chip-overlay

Não criar primary-dark, asfalto, terra ou nomes similares no consumo. Primitivos podem existir internamente, mas a API pública do tema é semântica.

Matriz de identidade

Identidade	Dark	Light	Regra
raiz	primary #EA580C; on-primary #0B0B0C	primary #EA580C; on-primary #0B0B0C	ação e seleção com identidade RaizFC
neutral	primary #E8E4DC; on-primary #111111	primary #2A2520; on-primary #FFFFFF	ação e seleção neutras; logo oficial não é recolorido

VIVID_RED #E8342A é token semântico dedicado a cartão vermelho e gol contra. Não substitui danger, que continua erro/contestação/destrutivo.

3. Identidade de marca e entidade

Valor	Papel
#EA580C	laranja RAIZ e primary somente na identidade Raiz
#FB923C	laranja claro FC, somente marca/asset
#0B0B0C	preto tinta do brand kit e texto do tema claro
#FFFFFF	branco papel e surface clara

Cor de time/torcida não entra na paleta global. Ela é uma prop contextual (entityColor) aplicada somente a hero/card de entidade, depois de validação de formato e contraste. Falha de contraste retorna ao fundo Noite de Holofote; o escudo nunca é recolorido.

4. Tipografia

Famílias

Token	Família	Pesos	Uso
font-body	Inter, system-ui, sans-serif	400, 500, 600, 700, 800	toda UI, texto, ação e formulário
font-impact	'Bebas Neue', sans-serif	400	placares, números de stats e títulos de impacto

É proibido usar Bebas Neue em texto corrido, label, helper, placeholder, botão, menu, tabela ou formulário.

Escala Inter extraída dos artefatos

Token	Tamanho/linha	Peso permitido	Uso
label-xs	10.5/14 px	500–600	eyebrow, badge e legenda técnica curta
caption	11.5/16 px	400–600	metadata compacta
body-sm	12.5/20 px	400–600	helper, descrição e lista densa
body	14/22 px	400–650	interface e ação padrão
body-lg	16/24 px	400–600	texto de leitura e informação principal
content-title	22/28 px	700	título editorial de conteúdo

Escala Bebas Neue extraída dos artefatos

Token	Tamanho/linha	Uso permitido
impact-sm	20/20 px	número compacto/score em card denso
impact-md	24/24 px	título de impacto compacto
stat-md	30/30 px	número de stat e scoreboard padrão
impact-lg	34/34 px	título de tela/fluxo de impacto
stat-lg	44/44 px	stat/placar destacado
score-xl	58/58 px	placar/card protagonista
display	78/74 px	capa institucional; não usar em UI operacional

Tamanhos intermediários vistos em composições exportáveis são variações do renderer por formato, não novos tokens de produto. O exportador pode escalar proporcionalmente mantendo família, hierarquia e safe area.

5. Espaçamento e dimensões

Escala: 0, 4, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 32, 36, 44, 48, 56, 64, 72, 96, 128 px. Os valores 10, 14, 18, 22, 26, 28, 36, 44, 72, 96 e 128 existem porque são usados pelos componentes ou safe areas canônicos; não autorizam espaçamento arbitrário.

Token/regra	Valor
control-height	48 px
touch-target-min	44 × 44 px
switch	44 × 26 px
form-control-sm	32 × 32 px
avatar-stack	32 × 32 px, overlap 10 px
card-padding-mobile	16 px
content-padding-mobile	16–20 px
section-gap-mobile	32 px
content-max-public	1240 px

6. Radius e bordas

Token	Valor	Uso
radius-form	10 px	botão, input, segmented e busca
radius-feedback	11 px	toast, banner, dropdown e upload
radius-game	12 px	card de jogo/pendência
radius-card	14 px	card e modal
radius-sheet	16 px 16 px 0 0	bottom sheet
radius-pill	999 px	switch, toggle, avatar circular e badge de status aprovado
border-default	1 px	estrutura
border-focus	2 px	foco/seleção visível

Sombra é discreta e complementar: cards comuns devem funcionar só com surface, border e espaço. Overlays podem usar sombra para separação.

Botões, tabs acionáveis e chips de filtro usam radius-form (10 px), nunca radius-pill.

7. Estados e derivações

• hover: altera superfície/contraste por derivação do token, sem introduzir nova cor de marca.
• focus: ring de 2 px em primary; quando houver conflito com o conteúdo, accent é permitido com contraste validado.
• disabled: mantém label legível, remove ênfase e bloqueia ação; não depende apenas de opacidade.
• loading: preserva largura/altura, mantém nome acessível e impede duplo envio.
• selected/active: primary + on-primary; não usar verde como seleção.
• victory/validated: success + texto/ícone.
• draw/waiting-validation: accent + texto/ícone.
• defeat/contested/error: danger + texto/ícone; mensagens diferentes não podem depender da mesma cor sem label.
• scheduled/provisional: surface-alt/chip-overlay + text-muted + label.

8. Skeleton e motion

Skeleton usa surface-alt → border → surface-alt, background-size: 200% 100%, ciclo de aproximadamente 1.4 s e radius 8 px, sempre espelhando a hierarquia final. Reduced motion remove o shimmer ou o substitui por pulso mínimo sem deslocamento.

Transições funcionais ficam em 120–240 ms. Motion não atrasa tarefa e não comunica estado sozinho.

9. Exportação de cards

Renderers reutilizam cores e tipografia semânticas, mas operam em pixels do formato. O placar continua Bebas Neue; metadata e assinatura continuam Inter. Preview e PNG devem compartilhar a mesma fonte de tokens. Formatos e regras estão em SPEC-UX-SHARE-VISUAL-001.

10. Critérios de aceite

• Valores de luminosidade e identidade são equivalentes aos valores canônicos listados nesta spec.
• Default Neutro Dark, fallback inválido/corrompido, migração legada e preferência persistida são cobertos por teste; não ocorre flash visível de tema incorreto.
• Web, mobile e renderers de card consomem a mesma API semântica.
• Nenhum componente de produto usa hex global ou nome de cor física diretamente.
• Todo conteúdo renderizado sobre primary usa on-primary; contraste é validado nas quatro combinações.
• Bebas Neue é limitada a placar, stat e título de impacto; Inter cobre o restante.
• Estados esportivos combinam cor, texto e/ou ícone.
• Contraste, foco, fonte ampliada e reduced motion são verificados nos quatro modos.
• Cor de entidade tem fallback seguro e nunca altera o asset do escudo.

11. Migração

Os tokens e providers atuais de luminosidade dark|light serão evoluídos pelo EP-MVP-19.3. Durante a migração, aliases temporários podem existir somente dentro do package; consumers usam uma única API semântica e a preferência legada é convertida conforme ADR-015. A remoção de aliases exige busca por consumidores e teste de rollback no mesmo EP.

12. Histórico

• 3.0 — modelo bidimensional Raiz/Neutro × dark/light, default Neutro Dark e migração compatível conforme ADR-015.
• 2.2 — tokens v2 dark-first, valores exatos dos protótipos e Bebas Neue oficial.
• 2.1 — paleta terrão light-first anterior, preservada no histórico Git.