Tokens are canonical

Status: accepted · Owner: Head of Design · Scope: Aleris Group · Version: v0.1 · Updated: 2026-08-06

Author: Torfinn · Audience: product teams, designers, and the assistant

Supersedes: — · Related: [[schemas/design-token]], [[data-products/tokens]]

1. Tokens are the single source of truth

data-products/tokens/aleris-tokens.css holds every token value. No other document — governance pages, reference tables, the hard-rules list in BASELINE.md, a package mirror — may restate a token's value. They name the token; they do not repeat its hex, its pixel size, or its ratio.

Implication: A value that appears twice in the corpus is a value that can drift. Anything that needs to state a value outside the token file names the token instead.

Detection of violation

Checked two ways. Machine: tokens.test.ts already asserts the generated baseline-tokens.json matches the CSS byte-for-byte (card 21/22's divergence guard) — extending the same pattern to catch a raw value restated in prose is not yet built. Review: every past breach was caught this way, not by a test. Card 8 found the hover token duplicated in six places, three of them package mirrors that shouldn't be edited directly. Card 24 found a seventh location — the CSS file's own @usage annotation contradicting every document that referenced it, in the file that was supposed to be the source of truth. Hard rule 5 in BASELINE.md now carries the sentence "other documents reference it rather than restating it" — written after exactly this failure was found once already.

Origin

Harvest provenance: No single already-ratified page states this generally, but the principle is already live in baseline/BASELINE.md's Token system section — "the CSS remains the source of truth", "never use raw values... everything goes through tokens" — and has been enforced incident by incident since card 8 (2026-07-30) first found a token value restated in six places. Cards 21, 22 and 24 each found a further instance of the same failure mode, in a different document each time. This page generalises an already-proven pattern rather than proposing a new one.

External lineage: Fitness-function thinking (Ford/Parsons/Kua) via documentation/aleris-meta-alignment.md — the same lineage accessibility-is-foundational.md's contrast floor draws on.

Open

Phase B step 6 — the BASELINE.md split — has its home now. Once this page is accepted, the Token system section and hard rule 5's closing sentence in BASELINE.md become pointers to this page rather than restatements of it. Not done here; this is what unblocks that step.

[[schemas/design-token]] — the formal shape of a token record
[[data-products/tokens]] — the canonical token set