Making the whole app agree with itself
This case study is password protected.
- Problem
- Everyone agreed with the system and then quietly diverged from it. Not through carelessness — a token file tells you a colour’s name, never what that colour is allowed to mean.
- My approach
- Treated every rejected screen as evidence. If a decision had to be explained twice, it stopped being a preference and became a rule with a name.
- What I built
- One token file as the single source of truth, a set of semantic contracts on top of it, and a check that runs on every prototype so the rules are not left to memory.
- Where it stands
- 14 prototypes, 0 errors, 6 warnings, 10 files completely clean. The rules that exist hold; the gaps in what they cover are named rather than hidden.
Need access? Email ishitabhorework@gmail.com
1% club design system · product design · 2026 — ongoing
A design system that remembers its own mistakes
Most design systems document what to do. This one also records what went wrong, and refuses to let it happen twice. Every enforcement rule in it cites the shipped bug that produced it.
178
NAMED TOKENS IN ONE FILE
10
ENFORCED RULES
14
PROTOTYPES UNDER CHECK
0
ERRORS TODAY
COUNTED FROM THE LIVE FILES ON 5 OCT 2026
THE 30-SECOND VERSION
PROBLEM
Everyone agreed with the system and then quietly diverged from it. Not through carelessness — a token file tells you a colour’s name, never what that colour is allowed to mean.
MY APPROACH
Treated every rejected screen as evidence. If a decision had to be explained twice, it stopped being a preference and became a rule with a name.
WHAT I BUILT
One token file as the single source of truth, a set of semantic contracts on top of it, and a check that runs on every prototype so the rules are not left to memory.
WHERE IT STANDS
14 prototypes, 0 errors, 6 warnings, 10 files completely clean. The rules that exist hold; the gaps in what they cover are named rather than hidden.
MY LEARNING
A design system is not the palette. It is the set of decisions you are no longer willing to re-argue — and the only ones that survive are the ones something checks.
01
What a token file does not solve
I started where everyone starts: a palette, a type scale, a spacing scale, written down and shared. It was correct, it was agreed, and screens kept drifting from it anyway.
The drift was never about the values. Nobody disputed the hex. What a token file cannot carry is meaning — and meaning is where the disagreements actually live.
VALUES
What a token file holds
--blue is #2563EB. Unambiguous, and nobody argues with it
MEANING
What it leaves out
Whether --blue is allowed on something that is not tappable
THE GAP
Where screens diverge
Two people using the same token correctly, to say two different things
A colour used correctly can still be used wrongly. The token is the vocabulary; the rule is the grammar.
So the file stopped being a palette and started being a contract. Each group of tokens carries a comment saying what it means and, in several places, what it is forbidden to do.
tokens.css, annotated — the comments are the system
1508 × 900
02
The contracts, not the colours
Six decisions do most of the work. None of them are about which colour is prettier; all of them are about what a user is entitled to conclude from seeing it.
DASHED
Means empty, not yet filled
An open member seat, an unfilled slot. Never a button
BLUE
The only colour that means tappable
Spending it on decoration spends the affordance
GREEN
Positive, success, confirmed
A full green bar reads as goal complete, not as a neutral proportion
DARK
Onboarding and FIRE forecast only
Never on a Money-tab screen, where it reads as a different product
TYPE
Three sizes per screen, at most
One dominant, one secondary, one caption. More is a layout avoiding a decision
ICONS
Colour for asset categories only
Categories are scannable entities. Control and reassurance lists stay monochrome
Written as contracts they do something a palette cannot: they make a screen reviewable by someone who was not in the conversation. The question stops being do I like this and becomes does this claim something the system does not support.
The same component, inside and outside the contract
1508 × 800
03
Rules that exist because something shipped
This is the part I would defend hardest. Every rule in the check cites the bug that produced it, in a comment, in the file. Not for documentation — so that nobody deletes a rule without first learning what it was protecting.
Every rule below exists because it actually went wrong. Sources are cited so nobody deletes a rule without knowing what it was protecting against.
THE HEADER COMMENT ON THE CHECK ITSELF
THE BUG, THEN THE RULE
PRONOUN
A string with a name carried a pronoun
Shipped: It only works once, and only for her. There is no gender data for group members and never will be
NET WORTH
One screen said it two ways
Total Networth in one place, COMBINED NETWORTH in another. Not a word, and not consistent
DASHED
A dashed chip read as a placeholder
+ New group had no affordance, because dashed means empty seat everywhere else
CODES
An invite code read aloud wrong
BHORE7 contains B and O. Across a table those are 8 and 0
REPEATS
Four asset rows showed one value
Identical currency on every row, not summing to the total. Reads as a failed fetch, not as placeholder data
AS OF
A figure with no date
Every financial value carries an as-of date, or it is a claim about now that nobody verified
Three of those are errors that block delivery. Three are warnings, because they depend on context a checker cannot see. The split is itself a design decision: an error has to be unambiguous, or it trains people to ignore errors.
A rule in the file, with its source comment
1508 × 700
04
Moving the rules out of memory
A rule that lives in a document is a rule someone has to remember at the exact moment they are busy. So each one that could be made mechanical was, and the check runs on every prototype automatically rather than on request.
SCAFFOLD
A new prototype starts wired up
No hand-rolled palette, and a provenance header the check looks for
CHECK
Runs on every save
Errors come back to be fixed; warnings stay advisory
LOOK
A screenshot, then actually look at it
Clipped text, wrapped rows and invisible elements are invisible in code
SHIP
Only after the first three
The order is the point — verification before delivery, not after feedback
The screenshot step is the one I would keep if I could only keep one. Three of the worst layout bugs this year were correct in code and obviously broken on screen.
The pipeline, end to end
1508 × 800
05
When the checker was wrong
The first version over-reported. It flagged six dashed-border violations, and four of them were correct designs — an add-member slot, two ghost rows, an empty tile. All four are exactly the case dashed exists for.
6
FLAGGED AS VIOLATIONS
2
ACTUALLY WRONG
4
FALSE POSITIVES
DASHED-BORDER RULE, FIRST VERSION - 26 AUG 2026
A false-positive-heavy rule gets ignored, which is worse than not having it.
The cause was ordinary: the rule had three code paths and the exemption had been added to two of them. The lesson was not. A check that cries wolf does not degrade gracefully — it gets dismissed wholesale, and takes the rules that were working with it.
Two further bugs surfaced while fixing it. One rule was reading raw markup instead of stripped copy, so a fix that depended on it had been doing nothing at all. And two rules were reporting the same thing twice, which made the output look worse than the files were.
The six findings, with the verdict on each
1508 × 800
06
What it holds today
The fix pass on 26 August moved the whole set of prototypes from 9 errors and roughly 200 warnings to 2 errors and 22 warnings — and both surviving errors were real, on a dashed affordance that had already been rejected in review.
Run against the current prototypes, six weeks later:
14
PROTOTYPES CHECKED
0
ERRORS
6
WARNINGS
10
FILES FULLY CLEAN
AS OF 5 OCT 2026 - FOUR HARDCODED-HEX, ONE REPEATED VALUE, ONE MISSING DATE
The honest reading of that number is narrow. It says the rules that exist are being followed. It does not say the screens are good, and it cannot say anything at all about the things nothing checks.
07
Reading a system back out of Figma
The token file is the source of truth for prototypes, but the Figma library is the source of truth for the product. Keeping them honest meant being able to extract one from the other the same way every time.
CAPTURE
Read the variables and styles
The only step that needs judgement about which collections matter
TRANSFORM
Figma names into token names
Mechanical and documented — order of operations matters
REPORT
What is there, what is missing
A readable account of the gaps is the deliverable; the CSS is the by-product
Given the same capture, the output is byte-identical. That is the whole point of splitting it this way.
It also never overwrites the live token file. It writes a candidate beside it, so adopting a change from Figma stays a decision somebody makes rather than something that happens.
Figma variables to candidate tokens, with the diff
1508 × 900
08
What it still does not check
The most useful thing I can say about this system is what it misses, because that is where the next failure comes from.
CONTRAST
Nothing checks whether a colour pair is readable. A secondary caption on a tinted well passes every rule, passes the screenshot glance, and fails accessibility.
TAP TARGETS
Nothing checks size. A 32px control on a 360-wide artboard is below the threshold and is caught only if someone notices.
MEANING
No rule can tell whether a screen says the right thing. The check protects the floor, not the ceiling.
One proposed addition was rejected and the rejection was kept on the record rather than deleted, so the decision does not get silently re-litigated six months later. Keeping the no is as useful as keeping the yes.
The check protects the floor. It has never once told me a screen was good.
09
What I would measure next
Everything above measures compliance. None of it measures whether the system is doing its job, which is a different question.
RE-ARGUMENT
How often a settled decision gets re-opened in review. A system is working when the same debate stops recurring.
TIME TO FIRST SCREEN
How long a new prototype takes to reach something reviewable. Scaffolding should show up here or it is ceremony.
RULE DECAY
Which rules stop firing. A rule that has not caught anything in months is either internalised or obsolete, and those need opposite treatment.
The second one is the one I would watch first, because it is the only measure that would tell me the system is helping rather than just constraining.
HANDOFF
WHAT IS REUSABLE
The contracts generalise. Dashed means empty, one colour owns tappable, and a bounded type scale are not specific to this product.
WHAT IS NOT
The palette, the semantic pairs and the dark-theme scope are specific to this product and should not be lifted wholesale.
WHAT IS MISSING
Contrast and tap-target checking, and a measure of whether the system saves time rather than only preventing mistakes.
NEXT CASE STUDY
Reach without depth
Turning mutual fund metrics into something people can understand and act on, without crossing into financial advice.