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.

Create a free website with Framer, the website builder loved by startups, designers and agencies.