The Instrument: Design System as Code
"Precision instrument on warm paper" — a design language with budgets, a motion vocabulary with eight entries, and a coach that's a pure function.
Wera's design system (DESIGN.md) is written like an engineering spec: one accent color with an exhaustive usage budget, every numeral in IBM Plex Mono tabular figures, and a motion vocabulary where the scoreboard tick is contractually the loudest thing in the product. Even the encouraging sentence on the dashboard is a deterministic function with unit tests. Design decisions here are enforced and logged like engineering decisions — because they are.
Most side projects treat design as taste applied at the end. Wera treats it as a constitution: a written document with articles (tokens, budgets, banned patterns), an amendment process (a decisions log with dates and rationale), and case law (design-review findings landed as individual style(design) commits). The aesthetic — "a Moleskine notebook that became software" — survives contact with new code because it's specified, not remembered.
The system in five rules
One accent, rationed
Ember #C2410C may appear on exactly five things — quota progress, increment glow, live chips, focus rings, selected filters. It is not a button color. Rarity is what makes the scoreboard glow land.
Numerals are the brand
Every number that matters renders in IBM Plex Mono with tabular figures. The instrument reads like an instrument.
Motion is a closed vocabulary
Eight named motions (tick, needle settle, status stamp, evidence snap, filter reflow, run pulse, freshness warmth, coach swap). New motion must be added to the table first — by amendment.
One human sentence
Newsreader italic appears in exactly one place: the coach line. The number is the reading; the sentence is the coach. It appears nowhere else.
A banned-patterns list
Icon-in-circle feature grids, decorative blobs, hover-lift cards, staggered reveals, confetti — an explicit AI-slop blacklist, checkable in review.
The build journey
Decide the system before the first screen
Fonts, palette, and button language were chosen in a documented consultation — with rejected options recorded — before any UI code.
DESIGN.md: semantic tokens (--ground/--surface/--ink/--muted/--hairline/--ember), a type scale, letterpress buttons, and a decisions log.
Every future session — human or AI — writes UI against written law instead of vibes. The project's CLAUDE.md literally instructs: "Always read DESIGN.md before making any visual decisions."
The log records rejections with reasons: Geist and Instrument Serif rejected on taste; ember removed from buttons entirely to strengthen the scoreboard's signal; dark mode deferred with the future palette already specified.
Make the coach a pure function
The dashboard's one human sentence is generated by rules with strict precedence — and it has a unit test suite.
From apps/web/src/lib/coach.ts — note the comment declaring precedence like an algorithm, because it is one:
export function coachLine(input: CoachLineInput): string {
if (input.ready > 0) {
return `${numberWord(input.ready)} ready to send — finish ${input.ready === 1 ? "it" : "them"}.`;
}
if (input.deadlinesWithin48h > 0) {
return input.deadlinesWithin48h === 1
? "One deadline inside 48 hours — don't let it pass quietly."
: `${numberWord(input.deadlinesWithin48h)} deadlines inside 48 hours — clear them first.`;
}
Given the real state of your pipeline, produce one sentence.
Rule one outranks everything: if work is sitting ready to send, the coach points there —
— with the count spelled out as a word ("Three ready to send") and grammar that respects one vs. many.
Only if nothing is ready do deadlines get the microphone…
…with a singular voice for one deadline…
…and a firmer plural for several.
Encouragement, compiled. Same inputs, same sentence, every time — which is why it can be unit-tested like any other function.
Gate every motion on real state change
Numbers animate when the count changes, timestamps tick on the minute, and the run pulse breathes only while a real background job runs.
Client components with gates: TickNumeral (digit roll only when the value changes), StampChip, RelativeTime ("2m ago", advancing quietly), MotionGate respecting prefers-reduced-motion.
The design thesis: quiet at rest, alive when work moves. Motion attached to decoration is noise; motion attached to state change is information — the difference between a screensaver and a seismograph.
Three easing tokens (--ease-instrument/stamp/reflow) are the only allowed curves; durations come from the vocabulary table; everything animates transform/opacity/background only — never layout properties.
Fill emptiness with structure, not apology
An empty pipeline shows ghost rows teaching the flow; a zero scoreboard renders the 0 in full instrument style; the machine's overnight work is surfaced as a sentence.
Ghost structure (skeleton rows at ~8% ink with real labels), "own the zero," and "logs as love" — "Scanned 214 postings overnight. 3 matched."
This section was added by amendment (2026-07-14) after user feedback that surfaces felt static and bare — the constitution changed through its process, with the feedback, the date, and the synthesis recorded.
Density comes from forecast, context, and provenance — never decoration: the empty state is the tutorial, drawn in the product's own furniture.
The central idea: budgets make identity
A referee's whistle works because it's the only loud thing on the field. Give every player a whistle and the game is chaos — no single blast means anything. Wera's ember color and scoreboard animation are the whistle: the design system's job is mostly to keep everything else quiet, so that when the number moves and glows, your nervous system knows exactly one thing happened — you applied. That's why "ember is not a button color" is written down: every extra use of the accent is stolen from the moment that matters.
This is salience budgeting, and it's enforced the way performance budgets are: an exhaustive allowlist ("nothing else," stated in the spec), review gates ("no ember outside the §7.-1 budget" is in the standing verification checklist), and findings-as-commits when audits catch violations (see 2ab080d: ember "send now" label only when the ready count is live). The motion system works identically — a closed vocabulary table with trigger, properties, and duration columns, plus an amendment requirement for additions.
The tradeoff surfaces in the decisions log: the needle-settle entrance animation was contested — one reviewer voice kept entrances banned, another proposed it, and the user allowed it strictly scoped (numerals only, 250 ms, once per load) "so the scoreboard tick keeps its monopoly on choreography." A design system that can record a disagreement, a decision, and its scope is doing engineering's job: making tradeoffs explicit and reversible.
Apply it
You're adding an "Export PDF" button and want it to stand out. Per DESIGN.md, what do you do?
You want cards to gently scale up on hover in the discovery inbox. What's the legitimate path?
A PM suggests the coach line should "feel fresher" by picking a random encouraging phrase each load. What does Wera's design philosophy say?
Design tokens, budgets & decision logs
The transferable trio: semantic tokens (name colors by role — --ember, not --orange-600 — so meaning survives a palette change), budgets over guidelines (an exhaustive allowlist is checkable in review; "use accent sparingly" is not), and decision logs (record what was rejected and why, so the system can be amended instead of eroded).
Best practices
- Write the design system as a spec with banned patterns — reviewable, greppable, enforceable.
- Attach motion to state changes; animate transform/opacity only; gate on
prefers-reduced-motion. - Make dynamic copy a pure function with declared rule precedence — then unit-test it.
- Log contested decisions with their scope ("numerals only, 250ms, once") so exceptions can't quietly grow.
Common pitfalls
- An accent color used everywhere signals nothing anywhere.
- Entrance animations on everything — choreography without information.
- Empty states that apologize ("Nothing here yet!") instead of teaching structure.
- Design feedback that lands as vibes in Slack instead of findings with commits — untracked erosion.
The accessibility contract every motion in Wera sits behind — with implementation patterns.
↗ Docs Understanding contrast minimum — WCAG 2.1w3.orgThe 4.5:1 floor DESIGN.md treats as binding — what it means and how it's measured.
↗ Article IBM Plexibm.comThe typeface family carrying Wera's "engineering steadiness" — and a masterclass in a corporation publishing a design system.
↗