Design systemAI platform · private capital markets2026—

A design system a whole team can build from

Two sources of truth, and neither matched what shipped. I made the build environment canonical, wrote eight rule families a component list cannot carry, and routed anything drawn from scratch to review.

Role

Sole designer. Tokens, components, rules, templates, governance.

Users

Engineers building UI, AI tools generating it, one designer reviewing it.

Scope

Three products and a marketing site. One brand, one codebase. A startup team: one designer, six people building against the system.

Built in

Claude Design as the canonical source; handed to engineering through Claude Code as a portable rule set.

Found on audit · built since

title declarations doing one job, in a single product

tab families, four different bottom edges

components now, each with a contract and a spec card

rule families, plus a decision map and one traced screen

templates as sanctioned starting points

01 — Context

The platform serves private capital markets across three products and a marketing site: an AI toolkit for investment workflows, a network for industry groups, and a marketplace where allocators source and diligence investments.

I am the only designer. Everyone else who builds UI is an engineer, and most new UI arrives through AI tools. The system is read more often by a machine following instructions than by a person browsing a library, so it had to be an instruction set rather than a maintained file: precise enough that whoever builds next gets the same answer I would.

Illustrated with wireframes of the system's own structure rather than product screenshots. Names and values are as specified.

02 — The problem

Two problems. There were two sources of truth and neither one shipped, and a catalogue of components did not stop the drift it was meant to stop.

A component library in one tool, an incomplete implementation in the codebase. The design file was complete but not what shipped; the codebase shipped but was inconsistently styled. Every question about a colour, a variant name or a hover state had two answers and no tiebreak, so the tiebreak was me.

Forty-odd components existed and screens still came out inconsistent. What was missing sat between the components: whether a list page goes white or grey, whether a title is sized by its container or by importance, which of four tab-shaped components is navigation and which is a filter, when a shadow is allowed.

What the audit found

Ten title declarations for one job

Across a single product: ten separate header title declarations, four different bottom edges, five tab families. Each page was individually defensible.
Tokens that pointed at nothing

Two font weights with no font file behind them, so anything set to them was synthesised by the browser. Two shadow scales with near-identical names and different values. Two type scales where the same name meant 14px in one and 18.7px in the other.
AI-assisted building multiplies all of it

A plausible table, banner or title row can be drawn in seconds. It looks finished, so it reads as a decision, and a reviewer cannot tell an approximation from a decision without opening the markup.

As-isTwo answers, no tiebreak

Design file

Complete. Not what shipped.

Codebase

Shipped. Incomplete and inconsistent.

Every value had two answers. Colour, variant name, hover state, spacing.

The tiebreak was one person. Asked the same question repeatedly, in chat.

So following the system was optional. Whoever was building either guessed or waited.

Two libraries, each partially right, and the three costs that followed from having no tiebreak.

03 — Constraints

Tooling that only produces pictures puts the system one translation away from the product. Whatever became canonical had to be the thing people build from directly.

A marketplace kit could have filled the catalogue in an afternoon, with the wrong typeface and a generic palette. Each component is rebuilt on our tokens, reviewed on its own, and given a spec card.

An AI tool fills anything the system leaves unspecified with a plausible assumption. The answer was not to restrict what it can build, but to leave less to assume: every rule resolving to a number, a token or a named component, and the genuine gaps named as gaps rather than left open.

Governance designed for a design team stalls on a team of one. Nothing could block a build waiting for approval, and nothing could require two people to agree.

04 — Approach & key decisions

Four stages, in this order: audit what exists, settle where the truth lives, write the decisions down, build the route a new part takes to reach a designer.

Audit

Every header, token and near-duplicate component catalogued against what shipped.

Where truth lives

One canonical source named, the repo demoted to structural reference.

Rules layer

The decisions between the components, written to pass or fail. Section 06.

A reporting route for anything drawn that the catalogue does not cover.

The system moved to the environment where screens are built, and picture-only design tooling came out of the workflow. The codebase is still read for the structural anatomy of a component, but on any conflict of colour, type, variant naming or behaviour, the canonical source wins. That sentence sits at the top of the readme and of the portable rule set: a tiebreak is only worth having if it is unambiguous.

The system got a layer above the components: the decisions a prop list cannot carry. Which surface a page sits on. Title size set by the container, never by importance. Four legal control heights and six legal radii. One number for sections, cards and insets. Shadow means floating. Two easings. Alongside it, a decision map from job to component — including the wrong choice people were making instead — and one reference screen with every visible decision traced to the rule that produced it.

Parts the system does not cover get drawn. Preventing that produces silent approximations instead, so the rule is: draw it, tag it, and write a row naming what it does, the components considered and why each was wrong. The build continues either way. The row reaches the one reviewer, who can turn it into a component, reject it with the name of what to use instead, or leave it as a proposal until it is seen a second time.

05 — What I built

Four layers and a register. Tokens fix the values, components fix the parts, rules fix the decisions between the parts, templates fix where a page starts.

Each layer exists because the one below it leaves a question open. The register runs alongside all four, for the case where nothing covers the answer. The drift was never in the values or the parts — it was in layer three, which most systems leave to a design review.

The stackEach layer answers what the one below leaves open

Layer 01Tokensno literals

Leaves open: which token, where.

Layer 02Componentsone contract each

Leaves open: which one for this job, and how they sit together.

Layer 03Applied rulespass or fail

Surfaces · titles · geometry · spacing · elevation · states · motion · limits.

Layer 04Templateswhere a page starts

Runs beside all four, for the part no layer covers.

Drawn Reported Reviewed

Tokens → components → rules → templates, and what each layer leaves for the next. The register sits alongside rather than inside, because it handles the case the system has no answer for.

The decision map

Most drift was not invention. It was a reasonable component used for the wrong job: a filter drawn as a second row of navigation, a status pill used as a count, a menu hand-built from a button and a chevron. The map names the job, the component that does it, and the substitute people reach for instead. The substitute is always plausible, which is why it kept being chosen.

Decision map · job → component → wrong choice
The job	Use	Reached for instead
Move between a record's sub-pages	Underline tabs	The filled segmented switcher, which means a view and not a route
Narrow a list to this quarter	Toggle group in the toolbar	A second tab row: a filter drawn as navigation
Open a status or download menu	Menu button	Button plus chevron plus a hand-built surface
Show a count beside a nav row	The rail's built-in numeral	A badge, which in this system means a status
Lay cards out in columns	Card grid	A hand-rolled grid, which gives every card its own height

Five rows from the map. Naming the wrong answer changed behaviour more than naming the right one.

The register

Every prototype eventually needs something the catalogue does not have. The register is the route that part takes to a designer: drawn and tagged, a row written with its picture, its spec and the components rejected with reasons, then handed over. Three kinds are judged by three tests. The same part drawn in two projects is one row with two sightings, which is what makes recurrence countable.

01 Drawn

Tagged in the prototype. The build keeps going.

02 Reported

Picture, spec, and what was rejected and why.

03 Reviewed

Approved to buildRejected, with the name to use

One reviewer. A rejection has to name the replacement.

04 In the system

Rebuilt on tokens with a spec card. The hand-drawn markup is deleted.

Component

Seen twice · not composable · tokens only.

Variant

A different meaning, not a different look.

Composition

Same arrangement twice · carries decisions · shorter than the markup it replaces.

Four states and three tests. The row travels; the build never waits for it.

06 — The rules

Eight rule families. Every answer is a number, a token or a named component.

The test for every rule: could an engineer who has never spoken to me apply it, and could a reviewer check it without opening the design file. “Use generous spacing” fails. “Twenty-four for sections, cards and every inset” passes. Writing to that standard made the rules usable by an AI tool and by a person for the same reason — neither can resolve a rule that rests on taste.

Every value was read out of the component source rather than restated from memory. A rules document that disagrees with the components is a third source of truth.

Family	The rule
Surfaces	Page, then card, then content. Never a third fill. Floating layers are lighter than what sits under them, and one grey is hover only.
Titles	Size is set by the container, never by importance. One size per container type, listed.
Body and weight	One default for body, cells and field values. Four weights with a named job each, and two deleted because no font file backed them.
Geometry	Four legal control heights and six legal radii. Nothing else, including “close enough”.
Spacing	A short ladder, and one number for sections, cards and every inset, so page rhythm cannot be renegotiated per screen.
Elevation	No shadow by default. A shadow means the thing floats. It never signals importance.
States	Eight required states per component, each with one treatment. Every list owes an empty state and a loading state.
Motion	Durations by interaction type, two easings, and nothing animates layout.

The self-check, and the override rule

The rules end in a check short enough to run: no colour literals anywhere; radii and control heights only from the legal sets; font sizes only from the scale; spacing only from the ladder; no raw table, button, input or select; shadows only on floating layers. It is mechanical on purpose — a rule that needs interpretation comes back as a question.

On overriding a component: layout properties are yours, and anything encoding what the element is — background, colour, border, radius, height, padding, type — is not. If no variant gives you what you need, that is a variant discussion. This is the rule that stopped the catalogue being forked at the call site.

A system written to pass or fail is also cheaper to hand a model than a component library to read. Closed gaps mean fewer invented parts, and fewer invented parts mean fewer screens generated twice.

Two lists published as gaps

The undecided list — page width, grid, breakpoints, layering, the success, warning and info colours, validation timing, table density — carries one instruction: ask, do not invent. The not built list names components that do not exist, from a mobile nav drawer to charts, with the same instruction: name the gap, do not ship a lookalike.

This was the least intuitive decision and it changed the most. An approximation looks finished, so it reads as a decision, and a reader cannot tell the two apart. Naming the gap keeps an unfinished system honest.

07 — Outcome

The system is in use and still growing. Three things are true of how the team works now.

Engineers and AI tools build against the guidelines directly, without a designer in the loop for each screen. The answers that used to need my taste are now a number, a token or a named component.

Anything drawn outside the catalogue is tagged in the file and reported as a row with its picture, its spec and the alternatives it rejected. Review is reading a list rather than auditing markup, which is the only version that scales to one reviewer.

The undecided and not-built lists ship with the rules. Someone who needs breakpoints or a chart finds out before they build, and asks, rather than inventing an answer that has to be unpicked later.

Adoption, review time and how often the register is used are not measured yet. The counts above the fold are scope, not evidence.

08 — What this case doesn't cover

Adoption, review time and register use are not measured yet. The token cost of a generated screen should fall as gaps close, but I haven't instrumented it, so that figure is not reported here.

Naming one canonical source made the repo knowingly behind. Bringing it back into line has not happened.

Forty-eight components each have their own decisions, states and spec card. This case is the structure, not a tour of the parts.

Dark-theme tokens exist and are not specified in use. Charts, a drawer and an accordion are named gaps.

The system serves six active users and one reviewer. At that size it assumes local decisions win and rows arrive because someone files them. Both assumptions are deliberate, and both are untested above this size. Whether they hold with more designers and more projects is the next thing to find out.

Design systems

Let’s make a system your whole team can build from.

Tokens and components are the easy half. I write the decisions between them, and the governance that keeps a system honest while a whole team and its tools build on it.

Let’s talk