Design tokens são organizados em duas camadas (desde 0.7.0). Cada camada tem um papel específico — Semantic referencia Foundation, nunca o contrário.Design tokens are organized in two layers (since 0.7.0). Each layer has a specific role — Semantic references Foundation, never the other way around.
Duas camadas, uma direção: Foundation guarda valores brutos; Semantic aliasa Foundation com nomes de intenção. Componentes consomem só Semantic. Component foi eliminada em 0.7.0.Two layers, one direction: Foundation holds raw values; Semantic aliases Foundation with intent names. Components only consume Semantic. Component was eliminated in 0.7.0.
236 tokens · 9 categorias · hidden from publishing236 tokens · 9 categories · hidden from publishing
Valores brutos com naming numérico. A única camada com hex, rem ou px. Não é consumida diretamente pelos componentes.Raw values with numeric naming. The only layer with hex, rem or px. Never consumed directly by components.
color.blue.600=#2563EBspacing.16=1remradius.8=8px171 tokens × 2 modos · publicada pra Figma171 tokens × 2 modes · published to Figma
Intenção e significado, com naming t-shirt (sm/md/lg). Referencia Foundation via aliases. Light e dark sobrescrevem só esta camada.Intent and meaning, with t-shirt naming (sm/md/lg). References Foundation via aliases. Light and dark only override this layer.
primary.background.default→{color.blue.600}content.default→{color.neutral.900}lightcontent.default→{color.neutral.50}dark
A cadeia é sempre componente → Semantic → Foundation. Trocar a cor primária é mudar o alias de primary.background.default pra outro Foundation (color.cyan.600, color.emerald.600) — o componente não muda. Aliases resolvem em :root; [data-mode="dark"] sobrescreve só Semantic.The chain is always component → Semantic → Foundation. Changing the primary color means re-aliasing primary.background.default to another Foundation entry (color.cyan.600, color.emerald.600) — the component never changes. Aliases resolve at :root; [data-mode="dark"] overrides Semantic only.
Padrão canônico: {layer}.{category}.{type}.{variant}.{state}Canonical pattern: {layer}.{category}.{type}.{variant}.{state}
| FormatoFormat | ExemploExample | OndeWhere |
|---|---|---|
| Caminho JSONJSON path | foundation.color.blue.500 | Arquivos fonte (tokens/)Source files (tokens/) |
| CSS custom propertyCSS custom property | --ds-color-blue-500 | Gerado pelo Style DictionaryGenerated by Style Dictionary |
| Variável FigmaFigma variable | color/blue/500 | Painel de Variáveis do FigmaFigma Variables panel |
-defaultThe -default suffix rule.default gera -default no CSS. Sem exceções, sem colapsar. semantic.primary.background.default vira --ds-primary-background-default, não --ds-color-primary.Every token ending in .default generates -default in CSS. No exceptions, no collapsing. semantic.primary.background.default becomes --ds-primary-background-default, not --ds-color-primary.
Tokens semânticos têm as mesmas chaves em ambos os modos mas valores diferentes. Tokens de foundation e componente são invariantes de modo.Semantic tokens have the same keys in both modes but different values. Foundation and component tokens are mode-invariant.
| Token | Valor lightLight value | Valor darkDark value |
|---|---|---|
background.default | neutral-50 | neutral-950 |
content.default | neutral-900 | neutral-50 |
primary.background.default | blue-600 | blue-400 |
primary.bg-hover | blue-700 | blue-300 |
overlay.subtle | overlay-black-5 | overlay-white-5 |
primary.content-default | white | neutral-900 |
Tokens invariantes de modo (iguais em ambos): todos os space.*, radius.*, border.width.*, focus.ring.width, focus.ring.offset.Mode-invariant tokens (same in both modes): all space.*, radius.*, border.width.*, focus.ring.width, focus.ring.offset.
| # | RegraRule |
|---|---|
| 1 | Consumidores finais (CSS de componente, base, bindings Figma) só consomem Semantic — nunca Foundation direto.Final consumers (component CSS, base CSS, Figma bindings) only consume Semantic — never Foundation directly. |
| 2 | Tokens semânticos referenciam foundation, nunca hardcoded. Nenhum hex ou rgba bruto na camada semântica (exceto rgba documentados em ADR).Semantic tokens reference foundation, never hardcoded. No raw hex or rgba in the semantic layer (except rgba documented in ADR). |
| 3 | Foundation é a única camada com valores absolutos. Naming numérico (radius-8, spacing-16) — não t-shirt.Foundation is the only layer with absolute values. Numeric naming (radius-8, spacing-16) — not t-shirt. |
| 4 | Semantic usa naming t-shirt (radius-md, space-sm) — distinto de Foundation pra evitar redundância.Semantic uses t-shirt naming (radius-md, space-sm) — distinct from Foundation to avoid redundancy. |
| 5 | Todo token tem $type conforme spec DTCG.Every token has $type per DTCG spec. |
| 6 | Tokens não óbvios requerem $description.Non-obvious tokens require $description. |
| 7 | light.json e dark.json devem ter exatamente o mesmo conjunto de chaves.light.json and dark.json must have exactly the same key set. |
| 8 | Novas categorias ou quebras de hierarquia requerem um ADR.New categories or hierarchy breaks require an ADR. |
| JSON (fonte da verdade)JSON (source of truth) | CSS (gerado)CSS (generated) | Variáveis FigmaFigma Variables |
|---|---|---|
foundation.color.blue.500 | --ds-color-blue-500 | color/blue/500 (Foundation) |
foundation.spacing.16 | --ds-dimension-16 | spacing/16 (Foundation) |
semantic.primary.background.default | --ds-primary-background-default | primary/background/default (Semantic) |
semantic.space.md | --ds-space-md | space/md (Semantic) |
semantic.size.avatar.md | --ds-size-xl | size/avatar/md (Semantic) |
A geração de CSS é feita pelo Style Dictionary: caminho direto → nome, sem transforms customizados.CSS generation is handled by Style Dictionary: direct path → name, no custom transforms.
| CamadaLayer | Tokens | ArquivosFiles | Status |
|---|---|---|---|
| Foundation | 236 | 9 arquivos JSON (colors, typography, spacing, radius, shadows, opacity, motion, stroke, z-index)9 JSON files (colors, typography, spacing, radius, shadows, opacity, motion, stroke, z-index) | JSON + Figma vars (hidden) |
| Semantic | 171 × 2 modos171 × 2 modes | light.json + dark.json | JSON + Figma vars |