Design tokens
Four tiers from a few dials, resolved per context, written once in the DTCG format and generated for every platform.
A design token is a named design decision. Tanrei stores every color, size, type style, radius, shadow, duration and opacity as a token in the Design Tokens Community Group format (version 2025.10), under tokens/ in the repository. That directory is one of the project’s two sources of truth.
Under the three tiers below sits a fourth, dial: the eight numbers every derived value comes from. See Design systems and customization for dials, layers and how a product customizes Tanrei.
| Tier | Prefix | Holds | Example |
|---|---|---|---|
| Reference | tanrei.ref.* |
Raw material: tonal palettes, alpha ramps, typefaces and weights. | tanrei.ref.palette.neutral.10 |
| System | tanrei.sys.* |
Decisions with a role: what a color or size is for. Themes change this tier. | tanrei.sys.color.primary |
| Component | tanrei.comp.* |
Bindings from a component’s parts to system tokens. | tanrei.comp.button.filled.container.color |
Each tier may only point downward: component tokens alias system tokens, and system tokens alias reference tokens.
Two rules keep the tiers useful, and both are enforced by pnpm validate:
- Component tokens contain no literals for color, type, shape, motion or opacity. A component token is always an alias, so a theme can restyle every component by changing the system tier alone.
- Components contain no hardcoded design values. If a value is missing, the fix is a new token, not a magic number.
A token does not have one value; it has a value per context. Tanrei resolves two context axes today:
- Theme: light or dark.
- Contrast: standard, medium or high.
That gives six resolved permutations. They are described by a DTCG resolver file (tokens/tanrei.resolver.json) and written to design/tokens/ as fully resolved files, which is what the token reference on this site renders.
A token’s name is its path. Platforms spell the same path in their own convention:
| Platform | tanrei.sys.color.primary becomes |
|---|---|
| CSS | --tanrei-sys-color-primary |
| Swift, Kotlin, Dart, TypeScript | a generated constant under the package’s token namespace |
The namespace, CSS prefix and tag prefix come from a single file, tanrei.config.json. Nothing else in the repository is allowed to hardcode them.
tokens/
source of truth, edited by handref/sys/comp/themes/
input to the color scheme generatorgenerated/
palettes and schemes written by the generatortanrei.resolver.json
design/tokens/
six resolved permutationspackages/web/src/generated/tokens.cssswiftui/…/Generated/TanreiTokens.swiftcompose/…/tokens/flutter/lib/src/generated/tokens.g.dartreact-native/src/generated/tokens.ts
pnpm generate rebuilds every derived file. CI regenerates and fails on any difference, so a generated file can never be edited by hand and survive.
Note
In CSS, color tokens are emitted as light-dark() pairs. One stylesheet serves both themes, and a subtree can switch theme simply by changing its color-scheme.