Devesh JoshiCo-founder, product
Nine years building AI platforms serving 12,000+ engineers. LLM platforms, agentic systems (MCP), and multi-model safety evaluation.
Structuring design system tokens for scale and dark mode
How a three-tier token architecture prevents CSS bloat, ensures visual harmony across web and mobile, and eliminates dark mode flickering.
The problem with hardcoded utility values
As web applications scale across multiple routes and platforms, hardcoded hex values (`#ccff00`) and arbitrary margin classes (`mb-[18px]`) create inconsistent interfaces and fragile themes. Refactoring dark mode becomes a nightmare of scattered conditional classes.
The three-tier token hierarchy
1. Primitive Tokens: Store raw visual constants (`color-lime-500: #ccff00`, `space-4: 16px`). These are never referenced directly inside UI component code.
2. Semantic Tokens: Define contextual intent (`color-brand-accent: var(--color-lime-500)`, `surface-primary: #050505`). Dark mode overrides occur exclusively at this layer.
3. Component Tokens: Map semantic tokens to specific elements (`button-primary-bg: var(--color-brand-accent)`). This keeps component stylesheets decoupled from global theme shifts.
Topic Focus & Target Concepts
This is the work behind our design practice — UX, design systems, and motion built into the engagement from day one rather than bolted on after the architecture is set.
Product and interface designRunning into this in your own stack? Twenty minutes, no deck.
Book the call