Token Architecture · Multi-Theme Design System

How I designed a three-tier token architecture that scales to unlimited themes and made design-dev handoff 82% faster

A deep-dive into how I defined the token architecture: three tiers of tokens, a shared naming system, and independent theme layers, so brands and modes never leak into each other. I then connected it to code with a Figma-to-code pipeline: a design decision change now needs zero developer effort, and adding a new brand or theme in code takes about an hour instead of days.

Role: Design System Lead
Timeline: 5 weeks
Domain: Scalable Design Systems for Product Companies

Three floating black tiles stacked like tiers: four small pills at the bottom feed two medium pills, which feed one large pill on top.

Context

The product: A token-based design system with a component library and an automated Figma-to-code workflow. This case study follows its most used component: the Card.
7 independent theme dimensions on the same components
Company size: 1000+
Team size: 20
Used by: Designers and developers

Diamond
Amber
Opal
Diamond
Amber
Opal

Section 01

A black tile with four soft blocks placed unevenly and a broken link between them.

01 · Problem

Naming

Naming is where communication between design and dev breaks down: two teams name the same five decisions, with nothing in common.

Not scalable: Each new component invents its own names.
Not flexible: Nothing can be themed without editing code.
No shared source of truth: There's no way to trace a code value back to its design decision.

Two teams naming the same five design decisions with nothing in common. In Figma: grey/200, surface/default, fontSize/heading/md, price/fontSize, purple/500. In code: card-bprder-color (a typo), #FFFFFF, 32px, text-4xl, btn-primary-bg. Every pair is connected by a broken-link icon, with the caption: two teams naming the same five decisions, with nothing in common.

01 · Problem

Architecture

Get the architecture wrong and the structure can't scale: brands and modes lose their independence from each other, tokens become inflexible, and every design decision means manual rework for developers.

Structure mismatch: Modes in one collection don't map to files per theme. The shapes don't fit.
The handoff breaks: Design changes leave Figma, but never reach the product.
One value, wired to everything: No brand or mode boundary in between. Every wire moves together.

01 · Problem

Pipeline and workflow

Pipeline and workflow: Exporting from Figma to platform code was unreliable: existing plugins produced broken CSS, mishandled variable types, and needed manual fixes for each platform. Planning and creating tokens was slow and repetitive, and every handoff meant manual changes from designers and developers, since there were no free tools for managing themes in code.

This case study focuses on Architecture and Naming. Feel free to ask me later about Pipeline and Workflow.

01 · Problem

Why does this matter?

Unified Language: One naming system shared by Figma and code.
Single source of truth: Every value updates design and code together.
Simplified Change Tracking: A flaw doesn't mean rebuilding tokens and components.
Task Automation: Repetitive handoffs run themselves, automatically.

The team: two faceless figures working side by side on a shared platform. One sits at a table arranging blocks, the other builds a tower, and a conveyor belt carries cubes past on its own.

Section 02

Challenges

How might we…
Figma vs code
Theming structure

A black tile with a puzzle piece floating above its empty slot.

02 · Challenges

How might we…

HMW
Add unlimited themes without ever touching components?
HMW
Let designers change decisions without creating manual work for developers?
HMW
Make Figma tokens and code speak the same language?
HMW
Automate the path from Figma variables to production code?

02 · Challenges

Figma vs code

The challenge: I compared the Figma components with the values in the code and found mismatches and inconsistencies between them.
What I did: I audited the front-end components with developers: how components consume values, and which values are fixed and which are configurable. Only the configurable values became tokens, so new themes can be added without touching the components.
Why: If tokens don't match how components are built in code, automation always breaks. Tokens were treated as API contracts, not visual variables.

A product Card compared between Figma and code. On the left, In Figma: gray.200, surface/default, fontSize/heading/md, price/text/lg, violet.500, over a screenshot of the Card with the headphones, rating, title, price and Add to cart button. On the right, In Code: --product-card-border, #ffffff, 24px, text-4xl, btn-add-to-cart-bg. The caption reads: 5 decisions, 10 names, 0 shared.

02 · Challenges

Theming structure

The challenge: I checked the theming structure and found it was not scalable enough to accept new themes easily.
What I did: With developers, I mapped each theme dimension to the properties it controls, to show what changes and what stays the same.
Why: This defines exactly what needs tokens and keeps each theme independent and combinable.

Section 03

Solutions explored

Structures
Trade-offs

A black tile with a sphere, a rounded square, a ring and a pill in a grid.

Structure 1

Combined themes in many alias collections

YesWorks in Figma
NoFlexibility to change components independently
Needs confirmationIndependent modes (light and dark change on their own)
Needs confirmationIndependent brands (one brand's values never affect another)
NoThemes expand without Figma limitations
NoConverts cleanly from Figma → JSON → CSS, no manual fixes
NoNo code changes needed for design updates

Structure 2

Switching from alias to semantic naming

YesWorks in Figma
YesFlexibility to change components independently
Needs confirmationIndependent modes (light and dark change on their own)
Needs confirmationIndependent brands (one brand's values never affect another)
NoThemes expand without Figma limitations
NoConverts cleanly from Figma → JSON → CSS, no manual fixes
NoNo code changes needed for design updates

Structure 3

Separating themes into independent collections across token levels

YesWorks in Figma
YesFlexibility to change components independently
Needs confirmationIndependent modes (light and dark change on their own)
NoIndependent brands (one brand's values never affect another)
YesThemes expand without Figma limitations
YesConverts cleanly from Figma → JSON → CSS, no manual fixes
YesNo code changes needed for design updates

Structure 4

Making every token collection brand-aware

YesWorks in Figma
YesFlexibility to change components independently
YesIndependent modes (light and dark change on their own)
YesIndependent brands (one brand's values never affect another)
YesThemes expand without Figma limitations
YesConverts cleanly from Figma → JSON → CSS, no manual fixes
YesNo code changes needed for design updates

03 · Solutions explored

The four structures compared

Each structure fixed more of the problems than the one before, and only Structure 4 fixed them all

The four structures compared against the evaluation checklist
Checklist item	Structure 1	Structure 2	Structure 3	Structure 4
Works in Figma	Yes	Yes	Yes	Yes
Flexibility to change components independently	No	Yes	Yes	Yes
Independent modes (light and dark change on their own)	Needs confirmation	Needs confirmation	Needs confirmation	Yes
Independent brands (one brand's values never affect another)	Needs confirmation	Needs confirmation	No	Yes
Themes expand without Figma limitations	No	No	Yes	Yes
Converts cleanly from Figma → JSON → CSS, no manual fixes	No	No	Yes	Yes
No code changes needed for design updates	No	No	Yes	Yes

03 · Solutions explored

Trade-offs

1 → 2
Semantic naming stopped changes from spreading to other components and modes.
2 → 3
Splitting every token level into its own collection let themes expand past Figma's limits and convert to code automatically.
3 → 4
Making every token level brand-aware finally gave each brand its own independent values.

Section 04

Final solution

The architecture
What each theme controls
The output

A black tile with three interlocking soft rings.

04 · Final solution

The architecture

Why this solution

Every brand, mode and dimension is fully independent

Safe design iteration: designers change decisions without breaking code

Full automation from Figma to code

New themes can be added without hitting Figma's limits or needing manual fixes

04 · Final solution

What each theme controls

Each theme is independent and controls its own properties

The seven themes, their modes, and the properties each one controls
Theme	Modes	Controls
Brand	Diamond, Amber, Opal	Colors (with Color theme)
Color	Light, Dark	Colors (with Brand theme)
Language	English, Arabic	Direction, text content, left/right border width, plus typography (with Typography theme)
Typography	Serif, Sans-Serif	Font family, size, weight, line height (with Language theme)
Density	Comfortable, Compact	Padding, margin, gap
Radius	Square, Round, Pills	Border radius
Shadow	Flat, Subtle, Default, Raised	Shadow X, Y, blur

04 · Final solution

The output

Design System Documentation

A Storybook-style guide to every component, its variants and guidelines, with copy-ready code and a source of truth for AI.

Coming soon

A screenshot of the design system documentation guide.

Section 05

Validation

Pilot test

Proving the system early, on one very small component
- Planned tokens
- Assigned variables
- Defined the theme structure
- Exported to code
- Changed a decision without touching code
- Added a new mode, no Figma limits hit
Iterations

From one component to many
- Proved the structure on one component
- New components followed the same structure, with their own tokens
What it confirmed

Validated in both design and code
- Changed a decision without editing code
- Added new components with no restructuring
- Exported to code with zero manual fixes
- Added the new theme without a developer

Section 06

Impact

Measurable outcomes

From days to hours

Measured results of the multi-theme design system
Metric	Before	After	Improvement
Design decision change	2 to 5 days	0 developer effort	100%
Add new theme in Figma	1 day	10 minutes	98%
Add new theme in code	5 days	1 hour	98%
Design iteration & debugging time	80 hrs/sprint	56 hrs/sprint (24 hrs saved)	30%

A black tile with three ascending bars and a rising arrow.

The Figma → code pipeline

Extra mile

I built a Tokens Generator, a Variables to JSON plugin, and a Theme Manager to remove human error from Figma to code, and shared all three with the community for free.

Open Design Tokens Toolbox (dttb)