Showcase · Design systems · 01 of 03
Design system architecture — from the inside.
A hands-on walkthrough of design system architecture - tokens, components, theming, governance, scale, AI, and the documentation that makes it all usable. Break things. Fix them. Learn why it matters.
01 / 07 · Tokens
Every system starts with ashared language.
Design tokens are named values that store visual decisions — colours, spacing, type. Change one token and every element that references it updates. That's the contract.
01 · Primitive
The hue you set.
Source value. The slider drives this; everything else inherits. 500 is the step the cascade picks up.
02 · Semantic
Names the role.
A primitive referenced by intent. These names survive a rebrand.
03 · Component
Names the address.
One token per element. This is where the cascade actually lives.
--btn-primary-bg
var(--color-surface-primary)
--toggle-active-bg
var(--color-surface-primary)
04 · Rendered
Two consumers. One token. One shift.
Connection · intact
Now ignore the cascade.
What happens when a developer hardcodes a colour and bypasses the system? The button stops listening. The toggle keeps updating. One shortcut, one fracture.
Hue
Blue · 210° oklch(70% 0.15 210)Ramp
Connection
A token isn’t a variable. It’s a contract.
Every prop you add doubles the variants you don’t have to build.
The brand lives in the tokens, not the code.
You’ve seen the pieces. Now watch them move together.
The system exists. Now — how do people know when to use it?
If you can’t write the doc, the API isn’t done.
Epilogue · Beyond building
Getting teams to actuallyuse the system.
Every system I've built went through the same arc: early enthusiasm from the design team, skepticism from engineering, slow adoption through embedding in sprint workflows, and a tipping point when teams started contributing back.
Start with tokens, not components.
Colors and spacing are non-controversial. Components are political. Get the vocabulary adopted first.
Embed, don’t announce.
I sat in sprint plannings, not all-hands meetings. Adoption happened pair by pair, team by team.
Track builds, not surveys.
Component usage in production was my adoption metric. What teams ship tells you more than what they say.
Make the right path the easy path.
Linting rules that flag non-system colors. PR templates that surface component reuse. Friction for the wrong choice, not the right one.
Opening the system to contribution.
A system only one person maintains is a bottleneck. I designed contribution tiers so teams could participate at the level that matched their context.
Tier 1 — Use
Consume components as documented. No contribution required.
Tier 2 — Extend
Add variants within existing APIs. Reviewed async by the DS team.
Tier 3 — Create
New components go through an RFC process — problem statement, API proposal, DS council review.
§ Continue
That's the system. The rest of my work runs on one of these.
Two more showcases follow — the UX process behind the work, and where the line moves when AI joins the team.
— the system is the pitch.