Foundations

Token architecture and tiers

A value is written once, as a primitive. Everything after that is a name pointing at a name, so changing one primitive re-themes every control that depends on it.

Token cascade: primitives #9C3B22, #E3D5C0 and #1B1F28 feed the semantic tokens --primary, --border and --bg-elevated, which lock into component tokens such as button.primary.bg and card.bg.

Three tiers

Tier 1

Core primitives

Raw values with no meaning: primitive/terracotta: #9C3B22. The only tier allowed to hold a hex.

Tier 2

Semantic tokens

A role, pointing at a primitive: semantic/primary: var(--jv-terracotta). This is what product code binds to.

Tier 3

Component tokens

One property of one component: button/primary/background: var(--primary). Lives in the component's own stylesheet.

The cascade

Pick a chain to light its connectors and see how the component resolves. Change the primitive and both tiers above it follow, with no hex anywhere below tier 1.

Tier 1: core primitivesTier 2: semantic tokensTier 3: component tokens

Primary action: how it resolvesbutton/primary/bg var(--primary) var(--jv-terracotta) #9C3B22

Raise PO

Naming

Names say the role, never the colour. A token called --orange stops being true the day the brand changes; --primary stays true.

Primitives ship as --jv-* on a bare :root, so they resolve everywhere.
Semantic tokens ship inside [data-ds="v1"], the scope every migrated screen opts into.
Status families come in threes: --success, --success-bright for text and icons, and --success-soft at 16% alpha for fills.

No hex below tier 1

.badge {
  background: var(--success-soft);
  color: var(--success-bright);
}

Do: bind a semantic token. A theme change or a recalibration reaches this rule for free.

Avoid

<span className="bg-[#22B573]/20
  text-[#3DDB94]">Received</span>

Avoid: hex brackets in JSX. The value forks from the token and gate C2 fails the pull request.

More in Foundations and concepts

Design principlesFour human commitments for software on a shop floor, and the engineering rule that keeps each one.Color and the monotonic ladderSix charcoal rungs measured in L*, text contrast, and status hues that name conditions.Typography and data formatsSix sizes, the one 10px tier, and when a number takes the data face.Data visualization and charts20 chart archetypes at three sizes, timeline rules, the series colour contract, and accessible charts.Layout patterns and shell slotsThe five shell slots, drawer anatomy, and density that steps inward.Light theme architectureWhy light mode is not an inverted ladder, the chrome hover fix, and the contrast math.