Design Tokens at Scale: How We Unified Five React Apps

When Axelerant consolidated five React micro-frontends into a single design system, we needed a token strategy that could be incrementally adopted — not a big-bang rewrite that would stall feature work for months.

The Token Architecture

We chose a three-tier model: primitive tokens (raw values), semantic tokens (role-based), and component tokens (scoped overrides). This mirrors how Material Design 3 structures its system, and maps naturally onto CSS custom properties.

/* Tier 1: Primitives */
:root { --blue-500: 59 130 246; }

/* Tier 2: Semantic */
:root { --color-primary: var(--blue-500); }

/* Tier 3: Component */
.btn-primary {
  background: rgb(var(--color-primary) / 1);
}

• check_circleKeep primitives in a single source-of-truth file synced from Figma Tokens
• check_circleSemantic tokens are the only values referenced in component code
• check_circleComponent tokens exist only for intentional one-off overrides
• check_circleEnforce the rule via a custom ESLint rule that bans raw hex values in JSX