Derivation engine

Derivation fills every semantic slot you didn’t author. Concretely, on the Acme example: 40 authored DTCG tokens produce 271 resolved slots per mode, which the shadcn exporter alone turns into 103 CSS custom properties. The other 231 slots are the engine’s work.

It’s built on three promises, because a tool that silently invents brand values deserves rejection:

1. Deterministic. Pure functions over OKLCH color math. Same inputs, same outputs, forever, on every machine. No ML, nothing environment-dependent.
2. Explainable. Every derived value records the rule that made it and the inputs it used — visible in report.json and in the generated CSS comments (· derived).
3. Governable. Authored values always win. derivation.require lets you forbid derivation for specific tokens. Rule packs are version-pinned in config.

Rules only fill holes

Derivation behaves like water finding its level: it fills what you left empty and flows around everything you placed. The engine walks the semantic catalog; any slot with an authored or aliased value is untouched. Overriding a derived value is authoring that token — one line, visible in your token files, versioned with your design system.

Worked example: one value, traced

transtyle explain prints the actual rule and the actual inputs, recursively, for any slot:

$ transtyle explain semantic.color.primary.tint --cwd examples/acme

semantic.color.primary.tint = oklch(0.95 0.017 255)  [#e7effa]
 └─ derived by rule mix-toward-surface(0.92)@standard@1
    inputs: semantic.color.primary.solid = oklch(0.55 0.18 255)  [#026fd7]
     └─ aliased → option.color.blue.600
    inputs: semantic.color.elevation.1.surface = oklch(0.985 0.003 255)  [#f9fafc]
     └─ aliased → option.color.gray.50

Read bottom-up, that is the whole story of a value nobody wrote: Acme authored a blue and a near-white gray, aliased them to primary.solid and elevation.1.surface, and the tint is those two mixed 92% toward the surface. Change the blue and this recomputes; author semantic.color.primary.tint yourself and the rule stops running for that slot. Nothing else in the chain changes either way.

The standard@1 rule pack: the role grid

Every color role fills a grid — prominence × interaction state — not a flat list; see the language reference for the full shape and why.

Approximate OKLCH values in this table are produced by real color math in packages/core/src/color.js — including proper OKLab↔sRGB conversion and WCAG 2.1 contrast ratios.

The component tier: defaults that layer

component.* slots derive too, but by a different mechanism: each one declares a defaultFrom — the semantic slot it falls back to when you say nothing.

The component: prefix is what makes the tier layered rather than flat, and it is the difference between two authoring intentions that would otherwise be indistinguishable:

• Author component.control.radius → buttons and inputs both move. You changed the shared control shape.
• Author component.button.radius → only buttons move. You made a button-specific decision, and inputs keep following the control default.

That asymmetry is the whole point. One line expresses either intent, and the exporters reproduce it on targets that model the relationship completely differently — Bootstrap chains buttons and inputs through a shared $input-btn-* root, PrimeNG keeps button.* and formField.* fully separate, and the same authored token lands correctly in both.

A slot can have no default at all. component.tooltip.max-width declares none, because the IR has no rung meaning “a readable measure” and synthesizing one would mean adopting a number on one library’s authority. So it exists only when you author it — and when you don’t, Bootstrap and PrimeNG each keep their own default, which happens to be the same 200px. That agreement is why the slot exists: both libraries independently constrain the same element the same way at the same measure, and PrimeNG carries only two maxWidth slots in its entire 2759-slot surface (proposal 0004).

If the source doesn’t exist, neither does the slot. A design system that authors no radius scale has no semantic.radius.control, so component.control.radius is simply absent rather than present-and-empty — and an exporter with a binding for it emits nothing, reporting a dropped coverage row that names the slot to author. See a three-token design system is valid.

Provenance classes

derived values track your brand: change primary and every derived value follows (hover tints, on-colors, the whole chart palette — see it live by editing the Acme example and rebuilding). defaulted values are catalog constants with no user input. The distinction matters for audits: the report can tell you “on this target, your theme is 42% native, 53% derived, 3% approximated, 3% dropped”.

What derivation refuses to do

• Invent your dark theme. An unauthored dark value for a role’s .solid anchor just carries the light one over (TST1204), autoDark or not. autoDark: true correctly classifies that carry-over derived in coverage instead of authored, so audits see it honestly — but it doesn’t yet compute a genuinely different dark color: that transform (darkBrandAdjust) is a still-open, deliberately deferred question (roadmap), not something invented here without more cross-target evidence. Dark brand adjustment is a design decision either way; the engine won’t take it from you silently.
• Have taste. Derivation guarantees coherence, not art direction. On the Cathode terminal theme, derived info comes out conventionally blue — coherent, aesthetically wrong for a monochrome CRT, and fixed by one authored line. That boundary is by design.
• Run your code. Rules are declarative and shipped in versioned packs; there is deliberately no JS escape hatch in token processing. If the rule language is insufficient, that’s a spec conversation, not a plugin.

Practical workflow

1. Author the minimum you have opinions about (brand color, neutrals, dark neutrals, radius, fonts).
2. Build; read report.json and the · derived comments in the output.
3. Where a derived value is wrong for you, author that token. Repeat. Your token file grows exactly as fast as your opinions do.