This site runs on the system this page describes.

Four layers, one direction

Tokens flow one way: raw values feed semantic aliases, aliases compile to CSS custom properties, and components only read the compiled aliases. Nothing skips a layer.

1. 1 · Raw scales

   color.blue.600 = #2563eb

   What values exist. Twelve JSON files in tokens-source/raw/ — color ramps, a spacing scale, type sizes, durations, easings. No opinions about usage; just the palette of possible values.

   ↓
2. 2 · Semantic aliases

   t.color.brand, t.color.bg.surface

   What values mean. One JSON file per functional theme (light, dark, high-contrast) assigns raw values to roles: surface, text, border, focus. Aesthetic themes (brutalist, terminal) are additional alias files, nothing more.

   ↓
3. 3 · Generated CSS

   --t-color-brand: #2563eb;

   What the browser gets. Style Dictionary compiles the JSON into CSS custom properties — functional themes inlined in core CSS, aesthetic themes lazy-loaded from /public/themes/ only when selected.

   ↓
4. 4 · Components

   background: var(--t-color-bg-surface);

   Components only ever read semantic tokens. No component knows a hex value exists. That single rule is why five themes ship without five stylesheets.

A theme is a set of alias overrides — nothing more

41 of the 95 tokens are overridden by at least one theme; those are the tables below. The other 54 — the spacing scale, the type ramp, z-index — are never touched by any theme. Skins change, structure holds. That split is the whole theming model: dark mode is ~40 color decisions, brutalist is colors plus zeroed radii and instant motion, and no theme can move a layout.

From JSON to pixels

The build tool is Style Dictionary — Amazon's open-source token compiler. The same architecture scales from this portfolio to enterprise systems, which is the point of practicing it here. Sources are JSON; a prebuild hook compiles them before every dev server start and production build, so the generated CSS can never drift from the source of truth.

{
  "t": {
    "color": {
      "bg": {
        "base":           { "value": "#fafaf5" },
        "surface":        { "value": "#ffffff" },
        "surface-raised": { "value": "#f0f0eb" }
      },
      "brand":  { "value": "#2563eb" },
      "border": {
        "focus": { "value": "#2563eb" }
      }
    }
  }
}

const lightTokens = flattenTokens(readJSON('tokens-source/alias/light.json'));
const darkTokens  = flattenTokens(readJSON('tokens-source/alias/dark.json'));

const aliasCSS = [
  toCSSBlock(':root', lightTokens),
  toCSSBlock('[data-theme="dark"]', darkTokens),
  // + prefers-color-scheme fallback for first paint before JS
].join('\n');

.pre {
  padding: var(--t-space-4);
  background: var(--t-color-bg-surface);
  border: 1px solid var(--t-color-border-default);
  border-radius: var(--t-radius-md);
}

.pre:focus-visible {
  outline: 2px solid var(--t-color-border-focus);
}

The unglamorous parts matter as much as the architecture: a pre-hydration script sets data-theme before first paint so there is no flash of the wrong theme, and theme switches run through the View Transitions API so changing 100+ custom properties reads as one calm crossfade instead of a repaint storm.

What would make this fail

Token architectures rarely die of bad structure. They die of governance. These are the failure modes this system is designed against — and the ones I watch for.

• A component hardcoding one hex value.That is the drift seed. It works in the current theme, breaks silently in the other four, and recruits imitators in code review. The rule is absolute so the exceptions are visible.
• Naming by appearance instead of role.--blue-dark dies in the first rebrand; --t-color-bg-surface survives any palette. Aliases exist to make renaming values cheap and renaming meanings unnecessary.
• Themes forking components.The moment a theme needs its own Button, the system has failed. Themes may only override alias values — if a theme needs new structure, that is a design conversation, not a stylesheet.
• Tokens added without a decision.A token is a naming decision before it is a value. Every addition should answer: what role does this play that no existing token plays?
• No owner.Design systems do not die of bad architecture; they die of unreviewed additions. Someone has to be able to say no. Here that is easy — there is one of me. At team scale, name the owner or watch it drift.

Go deeper