Design Token & Theme System

You are a design systems architect who builds token-driven design systems that bridge the gap between design tools and production code across multiple platforms. Create a comprehensive design token and theme system for the following project.

Project Details:
Organization Type: [STARTUP/ENTERPRISE/AGENCY/OPEN SOURCE]
Platforms: [WEB ONLY/WEB AND MOBILE/WEB AND NATIVE APPS/ALL PLATFORMS]
Design Tool: [FIGMA/SKETCH/ADOBE XD]
CSS Framework: [TAILWIND/CSS MODULES/STYLED-COMPONENTS/VANILLA CSS]
Theme Requirements: [LIGHT AND DARK/MULTIPLE BRANDS/USER-CUSTOMIZABLE/WHITE-LABEL]
Current Token Status: [NO TOKENS/AD-HOC VARIABLES/PARTIAL SYSTEM/MIGRATING]

Section 1 - Token Architecture and Taxonomy:
Define the three-tier token architecture with global tokens representing raw values like blue-500 equals a hex color and spacing-4 equals 16 pixels, alias tokens that assign semantic meaning like color-primary equals blue-500 and spacing-component-padding equals spacing-4, and component tokens that map to specific UI elements like button-background equals color-primary. Establish the token naming convention using a structured format of category, property, variant, and state such as color-background-surface-hover that communicates the token purpose at every level. Create the complete token category catalog covering color palettes with primitive and semantic layers, typography including font family, size, weight, line height, and letter spacing, spacing scale, sizing for component dimensions, border including width, radius, and color, shadow elevation scale, opacity values, z-index layers, transition timing and easing, and breakpoints. Specify how tokens should handle responsive values where a token like font-size-heading-1 resolves to different pixel values at different breakpoints. Address the token relationship system showing how component tokens reference alias tokens which reference global tokens creating a chain that enables systematic theme changes by modifying alias mappings.

Section 2 - Multi-Theme Implementation:
Design the theme switching architecture using CSS custom properties that are redefined under different class selectors or data attributes to change the entire visual appearance without JavaScript recalculation. Create the light and dark theme token mappings specifying how every semantic color token resolves differently in each theme while maintaining contrast ratios and visual hierarchy. Establish the theme extension pattern for supporting brand themes in white-label or multi-brand scenarios where each brand overrides a subset of tokens while inheriting defaults from the base theme. Specify the theme persistence and detection system including reading the system preference using the prefers-color-scheme media query, storing the user preference in localStorage, applying the theme before first paint to prevent flash of wrong theme, and synchronizing the preference across tabs. Address the theme transition animation implementing smooth color transitions when switching themes using CSS transitions on custom properties while ensuring the transition does not affect performance-sensitive properties like layout.

Section 3 - Token Definition and Source of Truth:
Define the token source file format choosing between JSON, YAML, or JavaScript objects for defining tokens in a platform-agnostic format that can be transformed into any target platform format. Create the token transformation pipeline using Style Dictionary or Tokens Studio to convert source tokens into CSS custom properties, Tailwind theme configuration, iOS Swift assets, Android XML resources, and React Native style objects from a single source of truth. Establish the Figma integration workflow using Tokens Studio or the Figma Variables API to synchronize tokens bidirectionally between the design tool and the code repository ensuring designers and developers always reference the same values. Specify the token documentation generation that automatically creates a visual token reference showing every token with its current value, a preview swatch for colors, and usage examples. Address the token versioning strategy including how to deprecate tokens, how to introduce replacements, and how to communicate breaking changes in the token system through changelog generation.

Section 4 - Component Token Mapping:
Define the component token strategy specifying how each component type maps to specific tokens for its background, text color, border, padding, gap, border-radius, and interactive states. Create the interactive state token system covering default, hover, active, focus, disabled, selected, and error states with consistent relationships between state variations such as hover being 10 percent darker than default across all components. Establish the size variant token system where components like buttons, inputs, and badges have small, medium, and large variants that scale font size, padding, height, and icon size proportionally through token relationships. Specify how to handle composite tokens that combine multiple values such as shadow tokens that include x-offset, y-offset, blur, spread, and color and typography tokens that include font family, size, weight, line height, and letter spacing. Address the token override pattern for cases where a component needs to deviate from the standard token within a specific context such as a button inside a dark header that needs inverted colors.

Section 5 - Token Validation and Quality Assurance:
Define the token validation rules that run automatically in the CI pipeline including color contrast checking between paired foreground and background tokens, value type validation ensuring color tokens contain valid color values, naming convention enforcement, and circular reference detection. Create the visual regression testing approach for themes that captures screenshots of key components in every theme and compares them against approved baselines to catch unintended visual changes from token updates. Establish the token coverage audit that identifies components using hard-coded values instead of tokens and tracks the percentage of design values managed through the token system over time. Specify the cross-platform consistency validation that compares rendered output across web, iOS, and Android to ensure tokens produce visually equivalent results despite platform rendering differences. Address the accessibility audit for token sets ensuring all theme combinations meet WCAG contrast requirements and that the token system prevents designers from creating inaccessible color combinations.

Section 6 - Governance, Contribution, and Adoption:
Define the token contribution workflow specifying how new tokens are proposed through an RFC process, reviewed by the design system team, added to the source of truth, transformed to all platforms, and documented. Create the token adoption tracking system monitoring which tokens are used across products, which products still use hard-coded values, and the overall migration progress from ad-hoc values to systematic tokens. Establish the training materials for designers and developers including the token selection decision tree that guides users to the correct token for any design decision rather than using a raw color value. Specify the token update release process including how token changes are bundled into releases, how consumers are notified of updates, and how migration scripts help adopt breaking changes. Address the token system scaling strategy for how the system evolves as the organization grows including federation models where product teams can extend the token system with product-specific tokens while maintaining compatibility with the core system.