Designed and implemented a token-driven design system using theme.json to standardize UI behavior across a multi-site WordPress ecosystem for an industrial enterprise platform. Defined a single source of truth for design tokens (color, typography, spacing) and mapped them to CSS variables and reusable Gutenberg components, enabling consistent branding across differently themed sites. Built internal utilities to translate design tokens from Figma into production-ready configurations. The system establishes a scalable foundation for multi-brand consistency, reduces frontend redundancy, and enables teams to ship faster with predictable UI behavior—even as the platform continues to evolve.
Full Case Study
Overview
As part of a migration from a legacy CMS to WordPress + Gutenberg, I led the design and implementation of a token-driven design system to support a multi-site platform with varying brand identities.
The goal was to enable teams to reuse the same components across multiple properties, while allowing each site to express its own branding (colors, typography, iconography) through a centralized system. This required defining a scalable architecture using theme.json, ensuring consistency, flexibility, and long-term maintainability.
Problem
The existing ecosystem lacked a scalable approach to managing design across properties.
- The legacy CMS made content updates difficult and slow
- No unified system existed for design consistency across brands
- Designs were created for multiple site variations, but lacked a production-ready system for implementation
- Without a structured approach, the system risked becoming fragmented and difficult to maintain
This created significant risk:
- Increased technical debt and duplicated styles
- Slower iteration cycles across design and engineering
- Inconsistent UI behavior across properties
- Difficulty onboarding teams into a shared system
Constraints
- Timeline: Multi-site migration with compressed timelines for initial launches
- Team: Multiple frontend engineers, backend support, and design stakeholders
- Technical: WordPress Gutenberg +
theme.json, with evolving API constraints - Business: Required to support multi-brand environments within a single system
- Ambiguity: No predefined token structure or implementation standard
Approach
I approached the problem as a system architecture challenge, not a styling exercise.
First, I:
- Analyzed design outputs from Figma across multiple brand variations
- Identified the need for a centralized token system that could drive all UI decisions
- Defined a structure where tokens could be translated into production-ready configurations
From there, I:
- Established
theme.jsonas the system-level source of truth - Designed a token hierarchy (color, typography, spacing, etc.)
- Mapped tokens to CSS variables, enabling runtime flexibility across sites
- Ensured tokens drove both editor (Gutenberg) and frontend output
To bridge design and engineering, I also:
- Built utilities to transform Figma-exported JSON tokens into
theme.jsonconfigurations - Created a reference layer for token visibility and usage, improving team alignment
Key Decisions & Tradeoffs
1. Native System vs Custom System
- Decision: Use
theme.jsonas the foundation - Tradeoff: Accepted limitations of Gutenberg in exchange for deep CMS integration and long-term scalability
2. Flexibility vs Consistency
- Decision: Enforce structured token usage across components
- Tradeoff: Reduced ad-hoc customization in favor of predictable, scalable UI behavior
3. Abstraction vs Simplicity
- Decision: Introduce token abstraction layers (design → variables → components)
- Tradeoff: Increased upfront complexity vs significant long-term maintainability gains
4. Multi-Site Strategy
- Decision: Enable brand variation through token overrides rather than component duplication
- Tradeoff: Required more thoughtful system design upfront vs avoiding fragmentation later
5. Editor vs Frontend Parity
- Decision: Ensure tokens controlled both editing and rendering layers
- Tradeoff: Additional implementation effort vs reduced QA inconsistencies and alignment issues
Execution
I owned the system architecture and core implementation, enabling a scalable design system within WordPress.
Key implementations included:
- A token-driven system powered by
theme.jsonas the central configuration layer - Mapping of tokens to CSS variables, enabling dynamic theming across sites
- Integration of tokens into Gutenberg blocks and component patterns, ensuring consistent usage
- Development of utilities to convert Figma token exports into usable system configurations
- Creation of a reference interface for viewing and validating token usage
The system was designed to:
- Support multi-site theming through token overrides
- Enable rapid updates via centralized configuration changes
- Maintain alignment between design intent and production output
Outcome / Impact
- Established a consistent design foundation across multiple branded sites
- Reduced reliance on hardcoded styles and duplicated values
- Enabled more predictable and maintainable component behavior at scale
While still in active rollout, the system aligns with proven outcomes from similar implementations:
- Reduced frontend redundancy (~35%)
- Improved scalability across enterprise environments
Qualitatively, it:
- Improves collaboration between design and engineering
- Enables faster iteration through centralized control
- Provides a foundation for long-term system evolution
What This Enabled
- Ability to update global styles across sites through token changes
- Reuse of components across multiple brands without duplication
- Alignment between editor experience and frontend rendering
For teams, this means:
- Faster onboarding through a shared design language
- Reduced cognitive overhead when building new features
- A scalable path forward for multi-site expansion
Key Takeaways
- Design systems must integrate with the platform, not fight it
- Tokenization is a scalability strategy, not just a styling approach
- Upfront system design reduces long-term engineering cost
- Consistency and flexibility can coexist with the right architecture