brand-system-tokens

name	brand-system-tokens
description	Use when establishing or migrating to a token-based design system. Covers the multi-layer token architecture (primitive → semantic → component), naming conventions, theming patterns, and how to migrate from hard-coded values without a full rewrite.

Brand System Tokens

A token system is the contract between design and code. Without it, every component is reinventing the wheel.

Token layers (three deep)

Primitive tokens (raw values)

--blue-500: #3B82F6;
--gray-50: #F8FAFC;
--space-4: 16px;
--radius-md: 8px;

Raw values. Never used directly in UI components.

Semantic tokens (intent-based)

--color-text-primary: var(--gray-50);
--color-bg: var(--gray-900);
--color-accent: var(--teal-500);
--space-card-padding: var(--space-5);
--radius-card: var(--radius-md);

Semantic = "what role this color plays." This layer is what changes between themes.

Component tokens (per-component)

.button-primary {
  --bg: var(--color-accent);
  --text: var(--color-bg);
  --padding: var(--space-3) var(--space-5);
}

Per-component overrides if needed. Most components only use semantic tokens.

Naming conventions

Prefix	Example	Use
color-	--color-bg, --color-text-primary	Colors
space-	--space-4, --space-card-padding	Spacing
radius-	--radius-md	Border radius
shadow-	--shadow-card	Box shadows
motion-	--motion-fast	Durations
font-	--font-display, --font-body	Type stacks

Use consistent prefixes. Avoid abbreviations.

Theming with tokens

Theme = swap semantic tokens to point at different primitives:

:root {
  --color-bg: var(--gray-900);
  --color-text-primary: var(--gray-50);
}
[data-theme="light"] {
  --color-bg: var(--gray-50);
  --color-text-primary: var(--gray-900);
}

Components don't change. Just toggle data-theme on root.

Migrating from hard-coded values

Step 1: Audit existing colors / spacing. Count unique values. Step 2: Build the token ladder based on what's actually used. Step 3: Replace component-by-component. Use grep + sed to find all #3B82F6 and replace with var(--color-accent). Step 4: Test theming works by adding light theme variant.

Common mistakes

• One layer only (no primitive layer, semantic only) — can't share primitives across themes
• Too many semantic tokens (--color-button-primary-bg-hover-active-light) — keep it sparse
• Semantic names that lock to color ("blue") instead of intent ("primary")
• Token tree too deep (4+ levels) — hard to debug

Where this fits in X3 Compass

X3 Compass uses two-layer (primitive + semantic) in brand/palette.css. Components consume semantic tokens. Future light-mode = swap semantic vars on :root.