Design Tokens Architecture Theming

Token System Scaling

Building a scalable token architecture from 30 app-specific tokens to 320+ cross-platform primitives and semantic tokens.

320+

Total tokens

Platforms supported

Token layers

The Challenge

The existing token system was built for a single app and consisted of just 30 hardcoded values. As the design system expanded to support web, iOS, Android, and email, this approach became unsustainable. Different platforms had different needs, and there was no systematic way to ensure consistency.

We needed an architecture that could scale across platforms while maintaining a single source of truth—and that could support future needs like theming and dark mode.

Two-Layer Architecture

I designed a two-layer token architecture that separates raw values from their semantic meaning:

Primitive tokens define the raw values. Semantic tokens reference primitives and describe how values should be used.

Primitive Tokens (150+)

color.blue.500

#0074bf

color.blue.600

#005a94

color.grey.100

#f5f5f5

Semantic Tokens (170+)

colour.fill-brand

{color.blue.500}

colour.fill-brand-hover

{color.blue.600}

colour.surface-secondary

{color.grey.100}

Token Categories

The system includes comprehensive coverage across all design decisions:

Colour scales: 10 colour ramps (blue, fuschia, green, grey, grey-warm, orange, purple, red, teal, yellow) with 100-900 steps
Spacing: 22 values from 0px to 128px following a consistent scale
Typography: 40+ tokens covering font sizes, weights, line heights, and composite text styles
Border radius: 6 values from 0 to full (9999px)
Semantic colours: Organised by use case—text, fill, surface, border, icon, link, input

Typography Tokens

Typography tokens combine multiple properties into composite tokens that can be applied consistently:

                
// Semantic typography token structure
body.medium: {
  font-family: {font-family.brand} // Montserrat
  font-size: {font-size.300} // 16px
  font-weight: {font-weight.regular} // 400
  line-height: 150%
  letter-spacing: 0%
}

heading.5xl: {
  font-family: {font-family.brand}
  font-size: {font-size.1000} // 56px
  font-weight: {font-weight.bold} // 700
  line-height: 110%
}
                
            

Cross-Platform Support

The architecture includes platform-specific considerations:

Web: CSS custom properties with fallbacks
iOS/Android: Native font families (SF Pro, Roboto) with brand alternatives
Email: Arial fallback font family for maximum compatibility

This allows each platform to consume the same semantic tokens while respecting platform conventions and technical constraints.

The Outcome

The new token architecture has transformed how we make design decisions:

320+ tokens providing comprehensive coverage
Consistent design language across web, iOS, Android, and email
Foundation ready for dark mode and theming
Clear separation between raw values and semantic meaning
Easier onboarding—designers use semantic tokens, not arbitrary values

Next Project

AI Documentation Automation

View Case Study