A design system that remembers why
What the design system and AI prototyping pipeline of an enterprise ML platformFor five product teams and nine designersProblem the product ran on unconfigured Ant Design, with four heights for one bar chart
A token-governed component system, an institutional memory read by humans and AI agents alike, and a pipeline that turns plain English into working prototypes. Built as product design lead, hands-on across AI, agents and workflows, with the frontend team.
18 min read · 13 min skimmed
Three layers primitive, semantic, component. Pull a token down the chain.
Search its tokens, poke the live components, flip the rule book from prose to machine law. It is the portal as it was handed over, so the counts it shows are the ones from that day, not this file’s.THE SYSTEM, RUNNING
Accessibility: The portal passes axe-core’s WCAG 2.1 AA rules at desk and phone, in both settings, and in the 3 states this file links into; the Storybook below it is the repository’s own build and is not graded here. Not yet tried with a screen reader. The statement
Weight on a first visit: the portal, 60 KB compressed, against a budget of 65 KB. The build fails if a product passes its budget. It is one page, its script and style inside it.
Transcript
- 0:00 The design system’s portal as it was handed over, its counts the ones from that day: tokens, icons, components, patterns, rules and decisions.
- 0:03 The tokens, filtered to colour.
- 0:05 The preview switched to light: the same names resolve to their light values, because a theme is a swap at the bottom of the token chain.
- 0:08 The components, each shown working, with what it is for.
- 0:11 The rule book, written as prose for people.
- 0:14 The same rules as law for machines.
- 0:17 The decisions log: active, superseded and still open.
Every atom, molecule and organism the platform ships, with its controls, its docs page and its themes. Pick a component in the left rail; the canvas is the real code. THE LIBRARY, AS SHIPPED
- I owned
- The design system end to end (tokens, components, documentation and governance), the DS-Brain memory, and the AI prototyping pipeline
- With
- The Head of Frontend Engineering and the frontend team, for five product teams and nine designers
- Theirs
- The products built on the system, by five product teams and nine designers, and the frontend code the Head of Frontend Engineering’s team writes against it
- Constraints
- Ant Design stayed underneath and could not be ripped out, and five product teams kept shipping through 100+ releases, so the system replaced its surface token by token, never in a cliff-edge release
- Friction
- Getting engineers to want the system, which was harder than building it; the rule book and the memory reached them after the library, and should have come first
231 components Every one resolves through the token chain. Nothing in the library owns a colour
Joined to its neighbours A change to one is a change to everything touching it, which is the problem the rules exist for
The same dashboard, two years of debt apart
We didn't rip Ant Design out, the system replaced its surface token by token, wrapping it in OI-prefixed components, so users never met a cliff-edge release. Drag the line.
| Workload | GPU | Util% | Status |
|---|---|---|---|
| llama-70b-ft | 16 | 91 | ok |
| embed-batch-cron | 4 | 64 | OK! |
| asr-eval-suite | 8 | null | wait |
| vision-preproc | 1 | NaN | ERR |
| Workload | GPU | Util% | Status |
|---|---|---|---|
| llama-70b-ft | 16 | 91 | ok |
| embed-batch-cron | 4 | 64 | ok |
| asr-eval-suite | 8 | · | waiting |
| vision-preproc | 1 | · | error |
No hex above this line
Every visual value resolves through a three-layer chain, and a component may never touch a raw value. That one prohibition is the whole trick:
Above the tokens sits the six-layer atomic hierarchy, and skipping a layer fails the build, not the review. The rest of the foundation is deliberately small: 24/12 brick spacing, one chrome accent, Inter for UI and Plex Mono for data, two motion curves.
The chain, as the source has it
Followed from name to name until each one reaches a value, the 3,396 tokens in the stylesheets fall like this.
One chain, end to end--oi-fd-color-text-primary → --oi-color-primary-100 → --oi-teal-300 → #84ebdd: the primary text colour reads the primary colour, which reads teal 300, which holds the value.
Read this plate as text
How 3,396 CSS custom properties resolve, and why dark mode cost no component code. A primitive layer holds raw values and nothing else. A semantic layer names them by role rather than by appearance. A component layer consumes only semantic names and never a raw value, and that refusal is drawn here as a severed connector because it is the load-bearing part of the design. Because components reference roles, switching theme rewrites one layer and everything below it is untouched, so a theme costs zero lines of component code. The whole chain is governed by 91 numbered rules, of which two have been retired with their numbers kept vacant so that no rule number is ever reused.
A system that remembers why
Institutional memory, treated as a product: written once, rendered twice, prose for people, structured rules for machines, so a new engineer and an AI agent read the same canon before touching a component.
The vault itself is the one artifact this site does not serve: it holds the team roster, the full decisions log and the roadmap, and its own security note bars it from public deploys. That refusal is part of the design.

- 1 · AskedWhy is it like this?By an engineer, a designer or an agent, before a component is touched.
- 2 · The canonRead the same rulesWritten once and rendered twice: prose for people, structured rules for machines.
- 3 · The logFind the decisionAppend-only: nothing is edited or deleted, and a reversal points at what it overturns.
- 4 · AnsweredWith a date on itThe rule’s number, the decision behind it and when it was taken.
- 5 · ChangedOnly by a new entryA rule is followed or retired in the log, and a retired number stays vacant.
91 rules, numbered like case law
Rule 4 No hex above this line. One prohibition, and the whole chain follows from it
Two open squares Retired rules. The numbers stay vacant, so the sequence carries its own history
Two rules were retired and their numbers stay vacant, the sequence carries its own history. Change ships as numbered waves, W11 past W110; there has never been a big-bang release.
Who is allowed to decide what
A rule book says what good looks like. It does not say who gets to change it, and that second question is the one that decides whether a design system survives its author. So the governance file carries a decision-authority matrix: eighteen classes of change, each resolved to the one role whose sign-off the pull request cannot merge without.
One approver, never two. The first operating principle in that file is blunt about why: multiple approvers diffuse ownership and are non-conformant. An optional reviewer may be asked and cannot block. The shape is the argument. A component owner adds an atom without asking anyone; nobody but the DS owner can add an iron rule, and that row has no optional review at all, because a rule anyone can add is not a rule.
Four decisions, from the log
Rule three of the same file: any decision that locks a pattern, picks between alternatives or changes a rule produces an entry in the log, and reverts are recorded. That last clause is the one that costs something. These four are in the permanent record under my name.
The brain was a single contributor's notebook. Handing it to a twelve-person team meant defining and locking six roles, writing the authority matrix above, and separating the no-compile rule, which governs ad-hoc work, from CI, which does not get to skip anything.
What it cost A personal-voice scrub across the whole corpus. The writing stopped being mine, which is the point and still the part I liked least.
Page-level padding came off the canvas and into every brick, as a per-component token. The paddingInline prop came off a layout component's public API entirely.
Why Per-template opt-outs had left a hidden contract: a brick that looked right in one page template looked broken in another, and story-level migration broke every time. The fix retired two of my own earlier decisions and changed a public API, which is the expensive kind of correct.
Earlier that day I locked a canvas-gutter mandate across the system, hardened a rule to enforce it and added a guard grep. Hours later I reverted all three.
Why The mandate was based on a wrong reading of the architecture. Bricks carry their own padding precisely because they are the frame; a gutter on top of that compresses the content. The entry exists so that the next person to have the same idea finds out it was tried.
Five options were compared in a written strategy memo. The one already under construction was killed because its sandbox could not import the real component library, so every prototype it produced was a CSS imitation of the system rather than the system. The feedback that settled it was not diplomatic: not our components, not our style.
What the decision did not decide The model provider, export-to-TSX and authentication, each deferred in writing with a reason. A decision record that does not state its own boundaries is a decision someone else has to make again by accident.
Read this plate as text
The prototyping loop that removed the designer from the critical path. A product manager writes one sentence of plain English. The request is read against the brain, 378 documents and 6,683 cross-links, written once and rendered twice, as prose for people and as structured rules for machines, so an engineer and an agent read the same canon. Ninety-one numbered rules govern it. What comes back is a working prototype built from the 231 shipped components rather than a picture of one, rendered through Storybook, with zero mockups in it. The whole loop runs in about fifteen seconds, and anything that survives it is already made of shipped components, so there is no rebuild step between the idea and the product.
We killed the tool we were already building
Five routes compared in a written memo. We killed the one we were already building the day the evidence landed, and the replacement shipped in two phases. DECISION W110, THE FULL ENTRY, REASONING AND ALL, IS IN THE LOG
A browser sandbox can't import the production component library, so every prototype degraded into a CSS imitation of the system. The post-mortem went into the log like any other entry, and the replacement renders from the library itself:
None of this hands taste to a model. The AI builds under the same constraints as any engineer, the rules, the tiers, the cold-eyed verifier, and when it refuses a request because a component doesn't exist, that refusal routes back to design as a demand signal. The last piece was teaching: an interactive atomic-design class for the whole company, public below as Everyone Builds.

What kind of AI system it is
Not an agent left to roam: a short, fixed workflow with two checks after it, which is where Anthropic’s guidance on agents says to start.
| Pattern | Used here | Where |
|---|---|---|
| Prompt chaining | A sentence goes in, the output is rendered from the production components, and what comes out is a Storybook story in the product’s shell | The prompt, the pipeline, the story |
| Routing | To a person: when a request needs a component that does not exist, it is refused and the refusal goes to design as a demand signal | The refusal |
| Evaluator and optimizer | A fresh-context verifier grades finished work cold and cites rule numbers in what it finds; screenshots compare every visual change with the last | The verifier, the screenshot check |
How it fails, and what happens next
- It cannot reach the real libraryThe first route ran in a browser sandbox that could not import the production components, so every prototype degraded into a CSS imitation of the system. That route was killed and the post-mortem went into the log.
- It is asked for something that does not existIt refuses rather than inventing a component, and the refusal is routed to design as evidence that the system is missing a part.
- It produces something that breaks a ruleThe verifier reads the finished work without the conversation that made it and names the rule numbers it breaks; the screenshot check catches a visual change nobody asked for.
One prompt, read line by line
From the pipeline’s prompt library, as written; the company and the deployments in it are invented. What each line is for:
/prototype A deployments list page. Breadcrumb: Workspaces > Acme Corp > Deployments. Title "Deployments" with count badge "108 total". Subtitle "Active model deployments across all clusters".
3 KPIs: Running 84 (up 6), Pending 12 (down 2), Failed 4 (down 1).
Then a 6-row table titled "All Deployments" with columns Name, Status (badge), GPUs, Replicas, Owner. Use names like llama-3-70b-prod, embedding-svc, reranker-stg, translation-en-fr, speech-to-text-test, image-gen-canary. Mix statuses.
- A page type, not a picture“A deployments list page” names a kind of page the library has templates for, so the model fills slots rather than drawing a layout.
- Where it livesThe breadcrumb puts the page inside the product’s own navigation, so the story renders in the real app shell.
- Named parts, in orderHeader, then KPIs, then a table: each maps to a section type in the library, and the order is the page.
- Real-looking dataPlausible names and statuses make the prototype something a person can react to, not a page of placeholders.
- What it does not sayNo colour, no spacing, no font. Those belong to the tokens, and a prompt that set them would be asking the model to break Rule 4.
Nothing below is a screenshot
These are the actual artifacts, the story site in its own tokens, the deck of UX problems that produced the rules, the class that taught the company to build, served from this domain, running live inside this page.
A sentence goes in. Production components come out.
The whole path from a plain-English request to a shipped feature, including the branch we built, measured and killed.
Read this plate as text
End-to-end flow of the design system. Anyone on the team types one sentence of plain English. The pipeline reads the brain before it generates anything. What comes back is a Storybook story built from the 231 real components in the real application shell. A verifier with no memory of the work grades it cold and cites rule numbers in its findings; work that fails goes back and is fixed at the lowest architectural layer that owns the fault, then graded again. Work that passes is promoted against an eight-file contract, where missing a single file means nothing promotes. What ships, ships as a numbered wave in the append-only decisions log. One route is drawn and cut: the playground we were building ourselves, killed at wave 110 because its sandbox could only imitate the component library rather than import it.
The debt, itemised, and what each fix moved
Seven things that were wrong when I arrived, the mechanism that fixed each one, and what it changed afterwards.

The platform ran on unconfigured Ant Design. One bar chart carried four control heights, one button family carried three teals, and a single Select wrapper carried !important seventy times over.
A three-layer token chain, primitive, semantic, component, with one prohibition: a component may never read a raw value. Rule 4, no hex above the token line, fails the build rather than the review.
3,396CSS custom properties now carry every visual value, and dark mode shipped at the cost of zero component code.COUNTED FROM SOURCE · SEE THE COLOPHON
Anyone wanting to try an idea queued behind a designer, and browser-sandbox prototypes degraded into CSS imitations of the system because they could not import the production library.
A plain-English pipeline that renders from the component library itself, inside the product's own app shell, after we shipped two phases of our own playground and killed it in a day when the evidence said no.
~15 sper iteration, and roughly two dozen production-track prototypes authored by people who do not write components.DECISION W110 · THE FULL ENTRY IS IN THE LOG
Nobody could say why a decision had been made, so settled arguments reopened every few months and reversed rules crept back in unnoticed.
An append-only decisions log at the centre of the vault. Nothing is edited or deleted; a reversal is a new entry pointing at the one it overturns, reasoning attached, dated.
378 / 6,683documents and cross-links, written once and rendered twice, prose for people, structured rules for agents.COMPUTED FROM THE VAULT MANIFEST
Design review was taste against taste, and the finished work was graded by the person who built it.
91 rules numbered like case law, cited by number in review, plus a fresh-context AI verifier that grades work cold and quotes rule numbers in its findings.
The argument moved from pixels to rules: a disagreement now cites a number, looks up why it exists, and either follows it or retires it in the log. Two rules have been retired; their numbers stay vacant.FROM THE RULE BOOK
One table job was being done by dozens of near-identical implementations, ten filter patterns, eight pagination types, nine footer variants.
Wave 74 audited every consumer and rebuilt them bottom-up as a single slot-configured OITable family, rather than adding one more variant.
37 → 1table consumers now sit on one canonical organism.WAVE W74 · DECISIONS LOG
Layers leaked. Pages inlined spacing, molecules rebuilt atoms, and nobody agreed who owned the gap between two components.
A six-layer hierarchy where skipping a layer fails the build, an eight-file promotion contract, and one spacing law: atoms own their insides, never their outsides, the brick wrapper owns the gaps.
Spacing became arithmetic instead of judgement: 24 at every canvas edge, 12 between rows, by construction rather than by review.RULES 82–84
Replacing the surface of a live enterprise product usually means one cliff-edge release that users meet on a Monday morning.
No big bang. Each change shipped as a numbered wave, scoped, preservation-gated, verified, logged, wrapping Ant Design in OI-prefixed components token by token.
100+waves from W11 to W110 and counting, and no release that users had to relearn the product for.WAVE NUMBERS FROM THE LOG
Nobody waits for a designer any more
| It worked if | Result | Status |
|---|---|---|
| No component touches a raw value | Counted in the source: 0 of the 1,304 colour declarations in the system’s component stylesheets is a hex, rgb, hsl or named colour | |
| Dark mode costs no component code | Shipped as a token swap; no component code was touched | |
| A sentence becomes a prototype without waiting for a designer | About 15 seconds from plain English to a working Storybook prototype in the production components | |
| A decision outlives the person who made it | Numbered rules, retired ones kept, and an append-only decisions log read by people and agents |
Every figure above is one I can count from the system itself and show you the command for.
The measure of the system is who uses it. Nobody waits for a designer to try an idea any more, a PM with a sentence of plain English gets a working prototype in the product's own components, and the design conversation moved from pixels to rules: when we disagree now, we cite a number, look up why it exists, and either follow it or retire it in the log.

What I would do differently
- Win the engineers before the library. The system was not the hard part; getting engineers to want it was. I would put the rule book and the memory in front of them before the first component, not after.
- Read the architecture before writing a rule. I once mandated a gutter across the system, hardened it into a rule and a guard, and reverted all three hours later: bricks carry their own padding because they are the frame. The decision log keeps the entry so nobody repeats it.
- Compare the options before building one. The prototyping route that was killed was already under construction when five options were finally compared in a written memo. The memo should have come first.
Source notes
- Every figure on this page is counted from the design-system source, which lives in the same repository as this site: 3,396 distinct --oi-* custom properties and 4,255 declarations of them, 231 components across the three live layers, 23 frozen legacy and 14 templates. The counting method, the command that reproduces each number and the date the source was last touched are published in full on the colophon.
- Those numbers used to read 216, 220 and 3,491, depending on which part of this site you were standing in. They were each true of a different count taken at a different time, and nothing was watching, so they drifted apart in public. That is fixed in the way a design system fixes things: one canonical source, and a test that fails the build when a page disagrees with it.
- The token count then read 3,444 until v7.38. It had a command, but the command counted the token docs and story files as well as the stylesheets, and nothing ever ran it again. Now a suite runs every command before each release and fails if one prints a different number.
- Brain figures (378 documents, 6,683 cross-links, 17 sections) computed from the vault manifest.
- Wave and rule numbers (W11–W110+, 91 numbers, 89 live rules, two retired) from the append-only decisions log.
- The artifacts are served in full on this domain, the story site, the deck and the class, embedded above.



