Derivation engine

Derivation fills every semantic slot you didn’t author. Concretely, on the Acme example: 42 authored DTCG tokens produce 281 resolved slots per mode, which the shadcn exporter alone turns into 131 CSS custom properties. The other 239 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, or for a whole completeness level. 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. It’s one line, visible in your token files and 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’s 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 on-color picks (on-solid, on-tint, a role’s text) aim at WCAG 2.1 AA by default. With derivation.contrast: "apca" (the default when check.contrast.standard is apca) they pick by APCA instead: the candidate with the larger |Lc|, and walks that stop at Lc 60. The rule names then carry it (contrast-pick(apca), contrast-pick(subtle, apca)), so transtyle explain shows which contrast picked a value. On a mid-tone fill the two often disagree: see WCAG 2.1 or APCA.

More contrast, reduced motion#

Two rules read the reserved dimensions of the combination they run in, and like every rule they only fill holes:

• contrast: more: the on-brand walks (<role>.on-tint, <role>.text) step until 7:1 (WCAG AAA) instead of 4.5:1, and text.muted / text.subtle mix toward the surface only as far as 7:1 / 4.5:1 allow. Provenance reads contrast-more(<rule>), for example contrast-more(mix-toward-surface(0.12)). on-solid is still the better of white and near-black; when that falls short of 7:1, the warning asks for a darker or lighter solid for contrast: more.
• motion: reduced: every unauthored duration.* is 0ms (rule motion-reduced, derived). Easings are unchanged.

An authored value, including one carried over from the default mode, is never re-derived for either: check measures every contrast: more combination at 7:1 and names the authored value to write. transtyle explain primary.on-tint --mode light+more shows which rule ran (the mode is the combination’s key, one value per declared dimension in declaration order; an unknown one lists them all).

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. 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. 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. 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 absent rather than present-and-empty. An exporter with a binding for it emits nothing and reports 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. Some are picked per mode and stay defaulted: the default page is white or near-black by color scheme, and the default body text is whichever of the two contrasts more with the page. Your tokens decide which constant applies, never what it is. 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 classifies that carry-over derived in coverage instead of authored, so audits see it as it is. It doesn’t yet compute a 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, and the engine won’t take it from you silently. The page and body text are the exception, because they aren’t brand colors. Leave the page out and author the text with no dark value, and dark mode gets the light pair swapped rather than your dark text on a dark default page (TST1206 says so). An authored page is never touched.
• Have taste. Derivation guarantees coherence, not art direction. On the Cathode terminal theme, derived info comes out conventionally blue. That’s 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.

What to author next: completeness levels#

Three levels say which slots to author, in the order they pay off. Each one extends the one before. build and check print where you stand on one line (authored 1/14 recommended), and transtyle check --completeness <level> lists what is left, in this order:

Every path is under semantic. except component.control.*. Authoring means a value of your own or an alias to one: binding a slot to your vocabulary counts. An item still to author is missing (nothing fills it), derived, defaulted, or carried over: a neutral whose dark value is its light one (the same test as TST1204). A scale is one item, done once you author one of its steps: the engine fills the others.

npx transtyle check --completeness recommended
#
# Completeness recommended: 1/14 authored. To author next:
#    1. semantic.color.elevation.0.surface  defaulted by default-canvas
#       the page background: text, on-colors and contrast checks are measured against it
#    2. semantic.color.elevation.1.surface  derived by alias(elevation.0.surface)
#       cards and panels
#    …
#   13. semantic.font.mono  missing
#       the code font: without it every target keeps its own

That is a design system with only primary.solid, in light and dark. Right after transtyle init (the recommended preset), recommended is done and complete is next. The levels are advice: the exit code doesn’t change. To make one a rule for your team, require it: "derivation": { "require": ["completeness:recommended"] } fails the build with TST1202 for each item left. check.completeness picks the level the summary line reports on (configuration).

No example reaches complete: each one leaves scrim, type.* and component.control.* to the engine. Acme stops at 15 of 24 on purpose, leaving its second brand color, status colors and focus ring to derivation (its README says why).

Practical workflow#

1. Author the minimum you have opinions about: the recommended level above (brand color, neutrals, dark neutrals, radius, fonts).
2. Build; read report.json and the · derived comments in the output. transtyle check --completeness complete lists what else needs a decision.
3. Where a derived value is wrong for you, author that token. Repeat. Your token file grows exactly as fast as your opinions do.