Foundations
Token architecture
Tokens come in tiers: reference values, foundation scales, semantic roles, and component roles. A token reads only from its own tier or a lower one, and the generator turns one theme configuration into CSS.
The token layers
Reference tokens (--odd-ref-*) hold the raw scale and palette. Semantic tokens (--odd-color-text-primary, --odd-space-md) name a purpose. Component tokens belong to their component and are normally unset, with a fallback. The validator rejects a reference the category does not allow, such as a foundation token that aliases a component role.
| Category | Tokens | Example |
|---|---|---|
foundation | 67 | --odd-border-width-default |
component | 7 | --odd-card-padding |
semantic | 85 | --odd-color-accent-decorative |
layout | 6 | --odd-layout-gap |
reference | 68 | --odd-ref-brand-50 |
From configuration to CSS
Stages 1 to 7 are pure and live in @oddkin/tokens/generate, which also runs in the browser; file input and output and the command line live in @oddkin/tokens/node. Generation is deterministic: stable key order, fixed number formatting, and no timestamps.
| Stage | Input → output | Notes |
|---|---|---|
| 1. Load & validate | file / object → ThemeConfig | Schema + semantic checks; diagnostics carry JSON-pointer paths |
| 2. Resolve defaults & preset | → complete recipe | Deep merge with documented rules (arrays replace, objects merge) |
| 3. Generate scales & palettes | recipe → reference tokens | Per-domain generators |
| 4. Resolve aliases | reference + semantic + component definitions → graph | Detect missing refs, cycles, tier violations |
| 5. Compose | graph × modes × products × density → scoped graphs | Computes per-scope re-declaration sets (§5) |
| 6. Context validation | scoped graphs → diagnostics | Contrast of real role pairs, unit validity per output, min target size under density |
| 7. Emit | graphs → CSS, SCSS, DTCG JSON, TS types/refs/values, inspection metadata, report | Pure functions; Node layer writes files |
Trace a token
Roles alias the step they use, so a theme changes a step once and every role that reads it follows. card.padding reads a layout role, which reads the space scale:
| Token | Category | Definition | Value |
|---|---|---|---|
card.padding | component | {layout.inset} | 1.5rem |
layout.inset | layout | {space.lg} | 1.5rem |
space.lg | foundation | 1.5rem | 1.5rem |
Aliases and overrides
Configuration precedence: Oddkin defaults, then the preset, then the user configuration, then explicit overrides by stable token name. Each resolved token records its origin, so tools can label it generated, preset, configured, or overridden. Generated files are never edited by hand.
Every value on these pages comes from the default theme as @oddkin/tokens/inspect/default.json and @oddkin/tokens/inspect/default.contrast.json describe it. The theming and token pipeline design has the full rules.