Recipe: Theme token system design

A single-source-of-truth token architecture that keeps Meridian's violet-pink identity consistent across every surface.

Problem

Hardcoded hex values scattered across components, pages, and marketing materials drift over time. One designer tweaks a shade in Figma; three codebases miss the update.

Solution

A flat JSON token file consumed by Tailwind config, CSS custom properties, and design tool exports. Every color, spacing unit, and typography scale flows from one canonical source.

Token shape

{
  "colors": {
    "brand": {
      "violet": "#8B5CF6",
      "pink":   "#F472B6",
      "dark":   "#0A0612"
    },
    "surface": {
      "card":  "#1a1025",
      "input": "#231535"
    }
  },
  "typography": {
    "heading": { "family": "Inter", "weight": 700 },
    "body":    { "family": "Inter", "weight": 400 }
  }
}

Tailwind bridge

The Tailwind config reads the JSON at build time and generates utility classes like bg-brand-violet and text-surface-card. No manual class name drift.

CSS fallback

A build step also emits :root custom properties so non-Tailwind contexts (email templates, static landing pages) stay in sync.

Guardrails

CI lint rejects raw hex values outside the token file.
Figma exports must match the JSON schema before merge.
Token changes trigger a chromatic diff in Storybook.