Principles
Six rules that decide arguments. Each one is enforceable — a reviewer can point at a line and cite it.
--color-primary is links, focus rings, category icons and select indicators. --color-cta is the solid button, and nothing else. They are different values on purpose.
Planes separate with a hairline, never a shadow and never a tint. --shadow-card is none by decision, declared so conformant markup resolves instead of failing silently. Only floating layers — popover, overlay, widget — cast anything.
Every tier colour travels with the number, the word, or both. Status is always icon plus text. Filled and empty stars are two different shapes, so the control survives forced-colors mode.
Callout and Toast carry status on a 3px left rule. A status colour never floods a background, and a -fill token never carries text.
A dashboard is not a different typeface at a different scale. All densities share every colour, type and radius token; they differ only in rhythm — and in how many words fit the register.
A user-readable string literal in ui/src/ is a defect. The one exception is RATING_LABELS — product vocabulary, exported so the app can override it.
theme.css.