Token Architecture

Token Architecture -- Multi-Tier Design Token System

A structured approach to design tokens that scales across platforms, themes, and teams. Tokens are the single source of truth connecting Figma variables, CSS custom properties, Tailwind config, and native platform code.

The Three-Tier Model

Tier 1: Global Tokens (primitives)
  --blue-500: #3b82f6
  --space-4: 1rem
  --radius-md: 8px

Tier 2: Alias Tokens (semantic)
  --color-primary: var(--blue-500)
  --spacing-component: var(--space-4)
  --radius-default: var(--radius-md)

Tier 3: Component Tokens (scoped)
  --button-bg: var(--color-primary)
  --card-padding: var(--spacing-component)
  --input-radius: var(--radius-default)

Why Three Tiers

A button never references --blue-500 directly. It references --button-bg, which resolves through --color-primary to --blue-500. Changing the brand color only requires updating the alias tier.

Semantic Naming Conventions

Pattern

--{category}-{property}-{element}-{variant}-{state}

All segments after category are optional. Omit segments that do not apply.

Categories

Naming Rules

1. Use lowercase kebab-case exclusively
2. No raw values in names (--color-blue is wrong; --color-primary is correct)
3. State suffixes: -hover, -active, -disabled, -focus
4. Variant suffixes: -muted, -subtle, -inverse
5. Scale suffixes when needed: -xs, -sm, -md, -lg, -xl, -2xl

Theme Switching

CSS Custom Properties Approach

/* Base theme (light) */
:root {
  --color-bg-primary: #ffffff;
  --color-bg-secondary: #f8fafc;
  --color-text-primary: #0f172a;
  --color-text-secondary: #475569;
  --color-border-default: #e2e8f0;
  --color-accent: #3b82f6;
}

/* Dark theme */
.dark {
  --color-bg-primary: #0f172a;
  --color-bg-secondary: #1e293b;
  --color-text-primary: #f1f5f9;
  --color-text-secondary: #94a3b8;
  --color-border-default: #334155;
  --color-accent: #60a5fa;
}

/* Brand variant */
.brand-b {
  --color-accent: #8b5cf6;
  --color-bg-primary: #faf5ff;
}

Theme Toggle Implementation

function setTheme(theme: 'light' | 'dark' | 'system') {
  const root = document.documentElement;
  root.classList.remove('light', 'dark');

  if (theme === 'system') {
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    root.classList.add(prefersDark ? 'dark' : 'light');
  } else {
    root.classList.add(theme);
  }

  localStorage.setItem('theme', theme);
}

Token Export Formats

1. CSS Custom Properties

:root {
  /* Global */
  --blue-50: #eff6ff;
  --blue-500: #3b82f6;
  --blue-900: #1e3a5f;

  /* Alias */
  --color-primary: var(--blue-500);
  --color-primary-hover: var(--blue-600);

  /* Component */
  --button-bg: var(--color-primary);
  --button-bg-hover: var(--color-primary-hover);
}

2. Tailwind Config

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'var(--color-primary)',
        'primary-hover': 'var(--color-primary-hover)',
        'bg-primary': 'var(--color-bg-primary)',
        'bg-secondary': 'var(--color-bg-secondary)',
        'text-primary': 'var(--color-text-primary)',
        'text-secondary': 'var(--color-text-secondary)',
      },
      borderRadius: {
        DEFAULT: 'var(--radius-default)',
        sm: 'var(--radius-sm)',
        lg: 'var(--radius-lg)',
      },
      spacing: {
        'component': 'var(--spacing-component)',
        'page-x': 'var(--spacing-page-x)',
      },
    },
  },
};

3. JSON (W3C Design Token Format)

{
  "color": {
    "primary": {
      "$value": "{blue.500}",
      "$type": "color",
      "$description": "Primary brand color"
    },
    "bg": {
      "primary": {
        "$value": "#ffffff",
        "$type": "color"
      }
    }
  },
  "spacing": {
    "sm": { "$value": "0.5rem", "$type": "dimension" },
    "md": { "$value": "1rem", "$type": "dimension" }
  }
}

4. Dart (Flutter ThemeExtension)

class AppTokens extends ThemeExtension<AppTokens> {
  final Color colorPrimary;
  final Color colorBgPrimary;
  final double spacingSm;
  final double spacingMd;
  final double radiusDefault;

  const AppTokens({
    this.colorPrimary = const Color(0xFF3B82F6),
    this.colorBgPrimary = const Color(0xFFFFFFFF),
    this.spacingSm = 4.0,
    this.spacingMd = 8.0,
    this.radiusDefault = 8.0,
  });

  // copyWith and lerp omitted for brevity
}

Token Governance

Deprecation Protocol

1. Mark token as deprecated with $deprecated flag and migration target
2. Add console warning in dev builds when deprecated token is used
3. Maintain deprecated token for 2 release cycles minimum
4. Remove after migration verified across all consumers

{
  "color-brand": {
    "$value": "{color.primary}",
    "$deprecated": true,
    "$deprecatedMessage": "Use color.primary instead. Removal in v3.0."
  }
}

Versioning

• Tokens follow semver: MAJOR.MINOR.PATCH
• Adding a token: minor bump
• Renaming or removing a token: major bump
• Changing a value within the same semantic intent: patch bump

Review Checklist

• Token name follows semantic naming convention
• Token exists at the correct tier (global / alias / component)
• No hardcoded values bypass the token system
• Dark theme and brand variants are defined
• Token is documented with $description

Cross-Platform Distribution

Use Style Dictionary or a custom Memoire transformer to generate platform outputs from the canonical W3C JSON token file.

Integration with Figma Variables

Sync Direction

Figma Variables  <-->  Token JSON  -->  Platform Outputs
     (source)         (canonical)       (CSS, Tailwind, Dart)

Variable Collection Mapping

Sync Workflow

1. memi tokens pull -- extract Figma variables to token JSON
2. Validate against token schema (Zod)
3. Run transformers to generate platform outputs
4. memi tokens push -- update Figma variables from token JSON (if canonical source is code)

Conflict Resolution

• Figma wins for visual design decisions (colors, spacing, type scale)
• Code wins for platform-specific values (z-index, motion timing, breakpoints)
• Both changes flagged for manual review in memi tokens diff

Design-Dev Handoff via Tokens

Tokens eliminate ambiguity in handoff. Designers reference token names, not raw values.

Handoff Checklist

1. Every color in the design maps to an alias or component token
2. Every spacing value maps to a spacing token
3. Every text style maps to a typography token
4. Component specs reference token names, not pixel/hex values
5. Theme variants (light/dark) are defined and previewed
6. Token changelog is included with the design update