@trismegisto/tokens

Design tokens do Hermes: as custom properties --hm-* (tokens.css), as famílias de cor (HERMES_FAMILIES) e os breakpoints (HERMES_BREAKPOINTS) para TS.

import '@trismegisto/tokens/tokens.css';
import { HERMES_FAMILIES, HERMES_BREAKPOINTS, hermesMediaQuery } from '@trismegisto/tokens';

Fonte → build

src/tokens.css, src/families.ts e src/breakpoints.ts são gerados. Não edite à mão: a fonte é JSON no formato W3C Design Tokens (DTCG) em src/tokens/, e o Style Dictionary gera o resto.

npm run tokens   # só regenera src/tokens.css, families.ts e breakpoints.ts
npm run build    # regenera + compila o TS + copia o CSS para dist/

Camadas

| Pasta | Camada | Vira CSS? | |---|---|---| | primitive/ | Valores crus: paleta (primitive.color.*), régua de px (primitive.size.*), rampas da paleta de dados | Não — só através de quem os referencia | | family/ | As 12 famílias (mitologia grega): accent/panel-bg por tema e as superfícies do escuro | Só as superfícies do escuro ([data-family='x'][data-theme='dark']); o resto gera families.ts | | semantic/ | Vocabulário que os componentes consomem: espaço, raio, tipografia, movimento, camadas (z-index), breakpoints, cores de superfície/ação/status, paleta de dados | Sim | | component/ | Tokens com dono: header-*, nav-*, navbar-*, tab-*, skeleton-*, check-size, focus-color | Sim | | mode/ | Conjuntos que reescrevem tokens num escopo: theme-dark, density-compact, font-* | Sim, no seletor do modo |

O nome da custom property é o caminho do token unido por hífen: space.md → --hm-space-md, panel.bg → --hm-panel-bg, surface-raised → --hm-surface-raised. Como o DTCG não deixa um nó ser token e grupo ao mesmo tempo, --hm-radius e --hm-radius-control são chaves irmãs (radius, radius-control), não grupo.

Referências e derivados

• {primitive.…} e {family.…} viram o valor literal no CSS.
• Referência a qualquer outro token vira var(--hm-…) — continua viva no escopo.
• Token da base cujo valor referencia outro token emitido (color-mix(in srgb, {accent} 12%, {surface}), calc({control-height} + …)) é derivado: o gerador o tira de :root e o põe sozinho no bloco redeclarado em todos os escopos (CLAUDE.md §2). O seletor desse bloco também é calculado: :root + [data-theme]/[data-density]/… de cada modo que sobrescreve alguma dependência (transitiva) de algum derivado. Hoje dá :root, [data-theme], [data-density] (as fontes não afetam derivados e ficam de fora; as famílias exigem data-theme no mesmo elemento, então [data-theme] as cobre).
• Token de um modo que referencia outro token fica no próprio seletor do modo (ex.: o --hm-hover do escuro).
• Família: o gerador só escreve a regra [data-family='x'][data-theme='dark'] com as superfícies que diferem do tema escuro padrão — a família padrão (poseidon, que o theme-dark referencia) não gera regra.

Receitas

• Token novo: acrescente no JSON da camada certa, com $type e $description (a descrição vira comentário no CSS). Se ele muda no escuro ou no compacto, acrescente o mesmo caminho em mode/theme-dark.tokens.json / mode/density-compact.tokens.json (o gerador recusa token de modo que não exista na base).
• Token derivado: escreva o valor com referências ({accent}); o gerador cuida do escopo.
• Família nova: acrescente o grupo em family/families.tokens.json (label em $extensions["br.hermes"].label, frase em $description). HERMES_FAMILIES e a regra CSS saem dali. Ids antigos ficam em family.$extensions["br.hermes"].aliases.
• Modo novo: crie mode/<nome>.tokens.json e registre em MODES no build-tokens.mjs (seletor e seletor de cobertura do eixo).

Tokens de referência rápida

• Breakpoints: --hm-breakpoint-sm/md/lg/xl = 640/768/1024/1400px. Custom property não funciona dentro de @media: em TS use HERMES_BREAKPOINTS / hermesMediaQuery('md') (→ (min-width: 768px)) ou hermesMediaQuery('md', 'down') (→ (max-width: 767.98px)).
• Camadas (z-index): sticky 10 · fixed 50 · overlay 100 · menu 200 · scene 200 · toast 300 · tooltip 400. Empilhamento local de componente usa -1…3; variação de uma camada, calc(var(--hm-z-menu) + 1).
• Tipografia: --hm-font-size-xs…xxl, pesos regular/medium/semibold/bold, entrelinha tight (1) / snug (1,25) / normal (1,5). Classes utilitárias no @trismegisto/core: .hm-text-xs…xxl, .hm-text-regular…bold, .hm-heading-1…6.

Paleta de dados (gráficos)

--hm-data-categorical-1…8, --hm-data-sequential-1…5, --hm-data-diverging-1…7, com degraus próprios no claro e no escuro.

• Categórica (qual série é qual): use na ordem 1, 2, 3… sem pular nem reciclar — a ordem é o que separa os vizinhos para daltônicos. 9ª série vira "Outros" ou small multiples. Em gráficos onde qualquer par se toca (dispersão, mapa), só as 3 primeiras são seguras em todos os pares.
• Sequencial (quanto): 1 = menor valor. Um matiz (azul), escurece no claro e clareia no escuro.
• Divergente (de que lado da referência): 1–3 azul, 4 cinza neutro, 5–7 vermelhão.
• Não use para interface nem para status (status tem cores próprias e sempre vem com ícone + rótulo). Cor nunca é a única pista: legenda, rótulo direto ou tabela acompanham o gráfico.

O build valida a paleta (scripts/check-data-palette.mjs) e falha se ela regredir:

• contraste ≥ 3:1 de toda cor contra todas as superfícies do tema (surface, surface-raised e, no escuro, as superfícies das 11 famílias);
• categórica: luminosidade OKLCH na faixa do tema (claro 0,43–0,77; escuro 0,48–0,67), croma ≥ 0,10, vizinhos com ΔE OKLab×100 ≥ 8 sob deuteranopia e protanopia simuladas (Machado, Oliveira & Fernandes 2009, severidade 1,0) e ≥ 15 em visão normal;
• sequencial: luminosidade monotônica com passo ≥ 0,06; divergente: meio sem matiz, braços monotônicos e passos simétricos distinguíveis sob daltonismo.

Resultado atual (saída do build):

claro: contraste mínimo 3,13:1 (sequential-1 #4b88e2 sobre #eef1f5; 2 superfícies)
claro: categórica — vizinhos ΔE mín. 12,3 sob protan/deutan (≥ 8), 22,7 visão normal (≥ 15); todos os pares passam até a cor 3
claro: sequencial — L 0,63 → 0,54 → 0,45 → 0,37 → 0,29
claro: divergente — polos ΔE 19,9 sob protan/deutan
escuro: contraste mínimo 3,49:1 (categorical-4 #c74b47 sobre #282000; 24 superfícies)
escuro: categórica — vizinhos ΔE mín. 12,0 sob protan/deutan (≥ 8), 22,6 visão normal (≥ 15); todos os pares passam até a cor 3
escuro: sequencial — L 0,62 → 0,71 → 0,80 → 0,88 → 0,95
escuro: divergente — polos ΔE 11,2 sob protan/deutan