Multi-tenant
One codebase serving every product on the platform
30+ live products, all inheriting the same tokens and components.
Case study 03
Enterprise Design System at Scale
A multi-tenant, multi-themed design system built to serve financial institutions worldwide from one codebase — with a governance model designed to survive external team adoption at production scale.
Layer 01
Primitive
colors/sky/700
colors/cyan/900
Layer 02
Semantic
background/action
sky/700
background/action
cyan/900
Layer 03
Component
button/primary/bg
background/action
button/radius
radius/control
Rendered · 2 of 8 themes
Same component set
Client 01
Client 02
344 primitives · 379 components · 8 themes · one shared component set
01The Context
The system that let one codebase serve every tenant without breaking.
A multi-tenant, multi-themed design system running the products used by financial institutions worldwide. Every deployment was a fully branded, client-specific experience — built on the same underlying tokens, components, and patterns.
The system had to hold up under three simultaneous pressures: multi-tenancy across live products, multi-theme rendering on the same components, and daily contribution from external teams building against it.
Multi-theme
8 themes rendered against the same component set
Four client brandings × Light and Dark modes — swap the tokens, never the components.
Multi-team
10+ engineering teams contributing daily
Building against the system, contributing back through governance, consuming continuously.
02The Challenge
External teams kept building around the system. The core team kept becoming the bottleneck.
Technical architecture rarely determines whether a design system survives. Adoption does. External teams stopped reaching for the system when the overhead of finding the right component was higher than building their own.
Two failure modes surfaced repeatedly across the first years of production use. The governance model I built was a direct response to both.
Failure mode 01
Teams building outside the system
↓
Local forks, silent divergence
When external teams needed a component that didn't exist yet, the fast path was to build it locally. Every local build was a fork — one more thing to reconcile later, one more inconsistency in production.
Failure mode 02
External teams waiting on a queue
↓
Days of blocked work per request
Every request routed through the core team. Every proposal, every review, every publish. External teams shipped when we shipped — and we couldn't ship fast enough.
Governance had to solve for both — without slowing the core team, without opening the system to drift.
03What I Did
The system split into three layers so every audience could work at the right level of abstraction.
The core team needed full control over every variable. External teams needed speed — the ability to configure themes, layouts, and workflows without touching the underlying system. Branded client deployments needed a scoped layer where component-level overrides could live without leaking back into the shared system.
Forcing all three audiences through the same layer created the bottleneck. Three distinct layers — with different access rights, different levels of abstraction, and clear ownership boundaries — solved for adoption and integrity at the same time.
System anatomy · Five views of the same component
01 · Library binding
02 · Dev mode output
03 · Mode switch
04 · Code syntax
05 · Component properties
Following the dimension/space/3 token from variable definition, through auto-layout binding, through mode switching, to production CSS output.
Product layer
External teamsconfigure
Configuration layerlayouts · workflows
Design system layer
Core teamgoverns
Primitive layer344 variables · full control
Semantic layerabstracted tokens · consistent
Component layerscoped overrides · sparing use
External teams configure products · Core team governs the design system
Layer 01
Primitive tokens
The raw ingredients — colours, spacing, typography, radius. Owned by the core team. Every change here cascades through the whole system.
colors/sky/700colors/cyan/900radius/md
Layer 02
Semantic tokens
Primitives get a role in the system. Every component references semantic tokens, never primitives directly. Theme switching happens at this layer.
background/actiontext-color/defaultspacing/inline-md
Layer 03
Component tokens
Reserved for cases where a client theme needed component-level overrides. Precise, scoped, used sparingly to keep the system maintainable.
button/primary/bgbutton/radiusinput/focus-border
Multi-theme evidence · 20+ tokens × 5 modes
One semantic token — bg-neutral-primary-soft — resolving to different primitive values across every theme. Same components, entirely different visual identity.
The rule for component tokens
Component tokens were the exception, not the default. Every proposed component token had to justify why a semantic token couldn't solve the problem. Roughly 15–20% of the total token count lived at this layer — enough to serve branded client requirements, contained enough to stay reviewable.
Eight themes, one component set
The same 379 components rendered across 8 themes — Light, Dark, plus specialised client branding. Every theme was a swap of semantic and component token values, not a rebuild of components. A new client brand added roughly a week of theme work.
From Figma to production
Corporate security policies blocked standard cloud-to-cloud automation. The pipeline pulled tokens from Figma variables through the Figma API into a Local Pull CLI workflow — no cloud exposure, tokens propagated across all 900+ screens from a single update.
FigmaVariables
Figma APISecure fetch
Local PullCLI workflow
Tokens StudioToken format
Dev RepoCodebase
Local Pull CLI — no cloud exposure, tokens propagate across 900+ screens from one update
04The Governance Model
Rules the system enforced so the team didn't have to.
Governance in a design system is usually enforced by people — reviewers, gatekeepers, meetings. That model scales linearly with headcount, which is exactly what we couldn't afford.
The governance model I built shifted enforcement from people to process. Every contribution moved through the same track, every deprecation followed the same cycle, every version shipped with the same guarantees. External teams stopped waiting on approval; they followed the process.
01
Proposal
RFC process
Structured requests before code. Async review, no meetings required for most proposals.
02
Contribution
External teams shipping in
Approved RFCs became pull requests. External teams graduated from consumers to contributors.
03
Retirement
Deprecation cycles
Automated warnings in Storybook and code, with a defined window before removal.
04
Documentation
Storybook as source of truth
Every component with variants, states, and usage guidelines. Design and engineering docs unified.
05
Versioning
Semantic versioning
Every release announced its impact. Teams knew exactly what changed before upgrading.
Governance stopped being a queue. It became a system that ran itself.
05Outcomes
The system carried the platform without buckling under scale.
The measure of an enterprise design system isn't whether it launches. It's whether it survives the second year, the fifth external team, the twentieth deployment. Whether new products still reach for it, whether the core team can still ship at pace.
This design system did all of that. Below are the outcomes I can name with confidence.
8 themes · 1 line change · Modern · Enterprise · Standard · Playful
The Modal rendered across all four brand families in Light and Dark modes — same component, different tokens.
344+
Primitive tokens governed
Colours, spacing, typography — owned by the core team as the single source of truth.
379+
Components shipped
Every component aliased to semantic tokens by default, with scoped component tokens reserved for branded overrides.
8
Themes on one component set
Light, Dark, and specialised client branding — swap the tokens, keep the components.
10+
Engineering teams adopting
Building against the system daily and contributing back through the RFC process.
Adoption
External teams shifted from consumers to contributors
Once the RFC and contribution model were in place, external teams stopped building around the system. Requests turned into pull requests. The core team reviewed instead of building from scratch.
Resilience
Zero coordinated migrations across the full production life
Semantic versioning and deprecation cycles meant no downstream team was ever caught by surprise. No emergency migrations, no all-hands rewrites — updates shipped continuously, teams upgraded when they were ready.
Speed
A new client theme shipped in a week
The multi-theme architecture meant onboarding a new client brand was token work, never component work. A full themed deployment — 900+ screens, brand-perfect — turned around in a week of configuration.
Reach
One design language across every product on the platform
The system was the reason the product portfolio held together. Every deployment shared the same interaction patterns, the same accessibility baseline, the same visual grammar — regardless of which team shipped it.
1 / 3
![]()
06What I Learned
01
A design system survives on adoption, not architecture.
The most elegant token graph in the world doesn't matter if external teams don't reach for it. Every governance decision I made after year two was really an adoption decision — reduce friction, remove queues, give teams a clear path from problem to shipped solution.
02
Governance scales when process replaces meetings.
Reviews, sign-offs, and gatekeeping don't scale linearly — they scale worse. Every ritual I built was designed to remove the core team from the critical path where possible. RFCs review async. Contributions merge on process, not opinion. Deprecations announce themselves.
03
Three layers beat two, and two beat one.
Trying to serve every audience through one layer creates a system that's either too rigid for speed or too loose for consistency. Splitting into governed primitives, consumable semantics, and scoped component tokens let every audience work at the right level without stepping on each other.
04
A design system is a product, and its users are engineers.
The consumers of the system are the people writing code against it. Every decision — token naming, component API, documentation format, versioning cadence — is a product decision made for that audience. Design system leads who forget this ship documentation nobody reads.