The complete token architecture, annotated

A members-only walkthrough of every layer of the token system — primitives, semantic roles, and the theme map that binds them.

Updated Sep 5View as Markdown

This is the long version of the design-system distillation: every token, why it exists, and how the layers compose.

Three layers

The system is deliberately thin — three layers, each mapping onto the next:

  1. Primitives — the raw oklch values, defined once.
  2. Semantic roles — --background, --foreground, --accent, and friends.
  3. The theme map — @theme inline binding roles to Tailwind utilities.

Only the semantic layer is used in components. Nothing references a primitive directly, which is what makes a re-theme a single edit.

The one accent rule

There is exactly one accent hue. Everything expressive routes through it, so the brand reads as one voice:

--accent: oklch(0.72 0.13 250);

Use it for the thing you want the eye to land on — a primary action, a live badge — and nowhere else. Restraint is the feature.