Design decisions that can't quietly erode
Problem
Design systems rarely fail at launch. They erode, one defensible shortcut at a time.
Role
Designer and builder, end to end: tokens, behaviour, components, docs and process.
Approach
Contracts written before components, built with Claude Code, checked on every build.
Status
30 components in the registry, 26 fully built, seven brands, live docs.
Ratā is a self-initiated design system for web apps and websites: 30 components across eight families, on a token layer that can retheme everything from a handful of decisions. Every layer was designed and built end to end, from the tokens and accessibility behaviour to the components, the documentation site and the process for adding to it.
Design systems erode. A colour gets hardcoded because the right token was hard to find, a focus ring gets removed because it clipped a layout, a second button style appears because nobody knew the first one covered it. Each is defensible on the day. So the question was never how to document the rules. It was how to make them hold.
30
components in the registry, 26 fully built
7
brand themes from the same tokens
37
contrast pairings verified every build
345
documented design tokens
Thinking
Five decisions, and what each one gave up
One principle ran through all of them: when a decision stops being true, the system should fail loudly instead of drifting quietly.
Rules enforced by the build
Not chosen: A usage guideChosen: Build checks
A guide describes the system on the day it is written. Checks keep describing it: contrast is re-measured and every component is compared to its approved API on each build.
Trade-offA broken promise blocks the build, so drift gets fixed right away instead of scheduled for later.
The contract comes before the component
Not chosen: Figma file as the sourceChosen: Written contract
What a component does, announces and forbids is agreed in a spec first. Figma is where visual ideas are explored, but the contract is what the code is checked against.
Trade-offNo full Figma library yet. Its column reads future for 29 of 30 components, published honestly.
One seed colour per brand
Not chosen: Hand-tuned palettesChosen: One accent seed
Most themes state one thing, the accent. The palette re-tones from it and every contrast promise is re-measured, so a new brand costs one choice and no separate QA pass.
Trade-offLess per-brand nuance. Two brands turn more dials, through the same mechanism rather than a fork.
Disabled controls stay discoverable
Not chosen: Native disabledChosen: Announced, click blocked
A natively disabled button leaves the tab order and goes silent, so keyboard and screen reader users never learn the action exists. Ratā announces it as disabled and blocks the click.
Trade-offThe click has to be blocked in code, which the browser would otherwise handle for free.
Answers for the AI reader
Not chosen: Docs site onlyChosen: Generated lookups
Code written with AI recalls an API from memory and invents what it forgets. Options, rules and tokens can be looked up in seconds, generated from source so they can't go stale.
Trade-offOne more output to trust, so its effect is measured with a benchmark rather than assumed.
Design
What the system holds in place
The hard part of a component was never how it looks. It is what it means: which decision it represents, when to reach for something else, and what using it obliges. That knowledge usually lives in someone's head. Here it is part of the system.
Every option documents what it is for, what to avoid and what it requires. Real rules from the button's contract:
Two primary buttons in one view — the tier is a claim about priority, and two claims cancel out.
variant · don't
Shrinking to sm to fit a cramped layout — fix the layout budget instead.
size · don't
Variant is visual only. A destructive action still needs its own confirmation step — colour is not a warning.
variant · accessibility
Any action whose icon is not already conventional — an unlabelled novel icon is unreadable.
iconOnly · don't
Contrast is measured, not audited
Thirty-seven text and background pairings are re-measured from real values on every build, in light and dark, for every brand.
Focus is never removed
Every control draws its focus ring from the same tokens, and never offsets it to zero where it would vanish into a fill.
Colour never carries a state alone
A status colour is always paired with a message, so anyone who can't tell the hues apart still gets the information.
Most themes state one thing, the accent colour. Spacing, radius, type and motion inherit, and every contrast promise is re-measured against the new colour.
Workflow
How a component becomes real
Most systems go wrong when adding to them: a component gets styled around behaviour nobody agreed, then wired to tokens that get renamed later. So the order is gated, and each stage is approved before the next one starts.
01 · Figma
Explore
Visual directions and layouts are tried out quickly, before anything is decided.
02 · Spec · contract
Agree the behaviour
What it does, announces and forbids, approved first, while changing it is still free.
03 · Contract
Map the tokens
Each state gets a semantic token, one state at a time. A missing token is its own decision.
04 · Claude Code
Build
The CSS and React are the approved decisions rendered, not a place to make new ones quietly.
05 · Build
Keep checking
Once marked built, the component is checked against its contract. An undocumented prop fails.
Because a contract stands on its own, it can exist before the component does. Two components are at that stage now: their pages are live and their options documented, and where the component would render, the gallery says plainly that it isn't built yet. A status matrix that only ever reads green is one nobody trusts.
Designing for the reader that isn't human
A growing share of the code that uses a design system is written with AI. That reader doesn't browse the docs; it recalls the API from memory, and a half-remembered API doesn't fail loudly. It invents a plausible option, drops in a hex value, hand-rolls a hover state.
So the system answers questions about itself, generated from source so the answers can't go stale. Whether that changes what gets written is measured: the same twelve tasks are answered with and without the token guidance, and both are scored against the system's own rules. If the difference ever disappears, that is a failure too.
Status
Where it stands, and what's next
Live at rata-design.vercel.app, with 26 of 30 components built and every number on the site measured by the build.
Build the two approved specs
Both already have live pages and documented options. The build starts from what was agreed.
A Figma library
Figma components from the same tokens, moving that column off future one component at a time.
Keep the benchmark honest
Rerun the twelve AI tasks as the system grows, and treat a shrinking gap as a failure.