A Design System Agents Can Use

System — as of September 2026: design and code verified against each other token by token — 59 literal colours in the prototype replaced by their token, the 4 that remain declared as gaps; third-party library instances → 0 across 20 pages in the prototype. Tested on coding agents: on a page generated from scratch, 0 literal colours in 8 of 9 runs — three per variant.

Impact — client KPI sheet, Sep 2025 → Feb 2026:

• Leads per page view: 0.0038 → 0.0059 · +55%
• Email leads: 3,942 → 6,336 per month · +61% (+54% YoY in February)
• Multi-leads: 913 → 2,296 per month — buyers contacting more than one seller
• Page views: ~1.04M → ~1.08M · flat. None of the lift came from more traffic

Jobs-to-be-Done

I want a place where I can enjoy and relax with friends and family and live my passion for the sea without the cost of a new boat.

Functional: access boats within budget · Emotional: relax and disconnect · Social/identity: live my passion for the sea · Tension: without the financial barrier of a new boat

The Challenge

Rightboat.com is a boat marketplace. In a category where boats cost hundreds of thousands, the platform hadn’t kept up.

Three engineers were carrying a redesign, a feature roadmap and technical debt at the same time. That math only works if each quarter inherits the last one — so the redesign and the design system were built as one piece of work. The redesign paid for the system; the system is why the redesign kept compounding.

Key Constraints

• 3 engineers for everything — redesign, features and tech debt. Quarterly phases, never a big bang.
• No system to start from — components were built in parallel with the redesign, not before it. Nothing was designed twice.
• Two-sided marketplace — buyers and sellers want opposite things. Every component and every feature evaluated through both lenses.
• Mobile growing, desktop converting — 20% YoY mobile growth, 70% of conversions on desktop. Mobile-first components, desktop variants on every one of them.

Building the System — El Captain DS

Foundations, primitives and patterns, with desktop and mobile variants on each: 17 primitives and 18 patterns, on a color foundation of 36 primitive variables across 5 ramps and 23 semantic tokens. Dark mode exists in those semantic tokens; it does not reach the product components.

The sequencing was the decision. A system built up front, before the redesign, would have been a guess about components nobody had built yet. A system built after would never have been funded. So each quarter’s screens were the brief for that quarter’s components: the detail page produced the disclosure and gallery patterns, search produced the cards, the filters and the pagination rules, the homepage produced the boat card and its four real variants.

The point isn’t the inventory. It’s that the fifth quarter costs less than the first — same three engineers, same traffic.

The Pipeline: Figma and the Prototype

A design system that lives only in Figma is a mood board with rules. The work that made this one checkable sits between the file and the prototype.

Code Connect mappings. 47 mapping files, 66 blocks from the Figma library to React components, validated against Figma’s parser. Code Connect mappings written and validated, not published: publishing needs a Figma Organization plan, and the client’s team was on Professional. Coverage measured: 11/17 primitives, 7/18 patterns. Until that changes, the path is written on the component in the file — most primitives in Figma are labelled with the path of the component that implements them.

A navigable React prototype. Next.js 16, React 19, TypeScript, Tailwind v4, shadcn/ui, built with Cursor and Claude Code. Built and validated in that prototype: stakeholders clicked real pages.

Figma read directly by the agent. Through Figma’s MCP server the file is queryable — pages, variable collections, nodes by id, screenshots — and writable through the Plugin API. The agent works from two sources it can check against each other: the Figma file, and the tokens and components in the codebase. Figma measured what publishing Code Connect would add on top of that — −29.5% tokens, −19.6% duration and +1 quality point across 27 design-to-code tasks — which is the case for the plan upgrade.

The chain reaches the prototype. Production stays on Rails + Hotwire, and the prototype is not connected to it — see What’s Next.

The Product Work

Quarterly phases, not a big bang: in 2025, Q1 explored (geographic search, Price History, AI categorization), Q2 took the highest-leverage page, Q3 the homepage, Q4 search. A UX audit to set the agenda. In Q1 2026 I audited the product: 20+ prioritized tasks, each justified by a UX law and estimated in effort. It became the client’s design agenda for the year.

Homepage: five entry points for different buyer types — hero search, category cards, popular models, premium brands, featured brokers. Three layouts tested with six users; visual-first won.

Search: listing cards rebuilt around hero image → title → location → price → specs. Smart badges, always-visible contact CTA, filter sidebar on desktop, bottom sheet on mobile.

Detail page: sticky contact form, AI-categorized gallery, scannable specs in tabs, and Price History — a chart of price evolution over time. The PM was skeptical; 8 of 10 users in interviews asked for pricing transparency. I championed it and prototyped it in Q1: competitors hide prices, the prototype shows them.

Closing the Drift

The system existed. That is not the same as being true.

In August 2026 I audited both sources against each other, with one rule: measure the drift, don’t rebuild anything.

• 53 raw hex values → 0 in the prototype, replaced by tokens. Two were real drift, not noise: an AI tag using a blue that didn’t exist in the palette, and a chart using a stray Tailwind grey.
• A second pass in September found what the first one couldn’t see: six more colours written as rgb() instead of hex, invisible to a search for ”#”. Every one had an exact token. Replaced, with the rendered values checked before and after: identical.
• What stays literal is declared, not forgotten: three shadows and one image overlay, which the system has no tokens for yet; the iOS app-shell prototype, out of scope; and email templates, where mail clients need literal values.
• 26 third-party library instances → 0 across the 20 pages in the prototype. They persisted because three components were missing — a section accordion, an icon-only button and a floating mobile nav. Built, then swapped.
• 137 hand-drawn icon containers on the seller-listing flow migrated to the official library.
• Color and type verified token by token — 36 primitives, 23 semantic tokens, line-heights included. Dark mode exists in the semantic tokens; it does not reach the product components.
• Code Connect mapping coverage measured for the first time: Primitives 11/17, Patterns 7/18 — and the mapping on the most-used component in the library, the boat card, pointed at a property that didn’t exist, so not one of its variants resolved. 13 more nodes were dead after a restructure. All remapped and validated clean.

The last number is the useful one: the remaining gap is no longer mapping, it’s React components that haven’t been built yet. Knowing which of the two you’re looking at is the whole value of measuring.

The same week, the homepage was rebuilt from the Figma frame, pixel-checked at three breakpoints, and validated in the React prototype. Three reusable components fell out of it that hadn’t existed before.

Tested on an Agent

A design system now has a second reader. If a coding agent can’t find the system in the code, it doesn’t fail with an error. It produces a screen that looks right and is built from raw values and reinvented components. That is the expensive failure, because nobody sees it.

So I tested the system the way I’d test a flow on a user. A new page, the poorest prompt I could write — “use the Rightboat design system” — and an audit of the source, not the render. A screen that looks right proves nothing here.

The eval. Nine runs with Claude Code, three per variant: the full repo, the same repo with every agent-facing document removed, and the repo as it stood in February. Each ran in a clean copy outside the project, with its transcript saved.

• All nine used the system’s tokens, reused the boat card without being told and invented no imports; eight of nine wrote 0 literal colours.
• The agent read the documentation written for it, and it made no measurable difference. What did the work was in the code: brand tokens in CSS since the first commit, and a predictable folder structure.
• In all nine runs the agent went beyond what was asked — further with the documentation than without it: 7–8 files touched against 3–5.

The failure mode. On a homepage branch generated with Cursor, the agent replaced 14 literal values with tokens. 9 of the 14 changed the rendered value: radii of 8, 15 and 16 px became 12 and 20. It obeyed “don’t hardcode” and rounded to the nearest token. Everything compiled. The design moved and nobody decided it.

The fix is one rule and a few tokens: never alter a value traced to Figma; if no exact token exists, keep the literal and flag the gap. The audit found 26 such gaps, which is the backlog.

Three runs per variant and one branch for the failure mode: patterns, not statistics. My first version of the eval ran inside the project folder, so every variant loaded its CLAUDE.md, the “no documentation” one included. Saving the transcripts is what caught it.

Where Agents Fit — and Where They Don’t

Most of that audit was executed by coding agents. It only worked because of what surrounded them.

What they did: read the Figma file live, count instances, resolve node ids, diff tokens against CSS, find dead mappings, migrate icons, re-run the checks after each fix.

What they were not allowed to do: decide. Every brief carried the same hard constraints — name the source you’re working in before touching anything, because Figma, the prototype and production are three different truths; report first, fix only when asked; never rebuild, modernise or unify anything on the way past.

The design work stayed mine: the three missing components, the variants each one needed, which drift is a bug and which is a decision.

And the review is the job. On the boat-card mapping, the plausible failure was the agent quietly editing the component so the mapping would fit — which would have made the report green and the system wrong. That’s what I was reading for.

Speed of production isn’t quality of product. What agents bought here wasn’t hours: it was a number on the drift.

Results

The traffic didn’t move. The efficiency did.

• +55% leads per page view — 0.0038 → 0.0059
• +61% email leads per month — 3,942 → 6,336, and +54% year over year in February
• 913 → 2,296 multi-leads per month: buyers contacting more than one seller, which is liquidity on both sides
• Flat page views (~1.04M → ~1.08M) — the constraint that gives the rest its value

Two years, three engineers, quarterly phases, no system to start from. The figures are the client’s, Sep 2025 → Feb 2026, on flat traffic. The redesign was built and validated in the React prototype; the system is why the next quarter of design starts from the last one instead of from zero.

What’s Next

The engagement closed in September 2026 with the chain reaching the prototype. Closing it takes three things, in order:

One artifact, three consumers. Figma variables exported through Style Dictionary into CSS custom properties for production, a Tailwind theme for the prototype and JSON for tooling — so alignment stops being manual. Left blocked on a single open brand decision on the client side, not on engineering.

Publish the Code Connect mappings, then point them at production. Code Connect mappings written and validated, not published: they cover the prototype’s React components and are waiting on the Figma plan. Publishing them, then extending them to the Rails + Hotwire codebase, is the difference between a design tool and a team tool.

A design-system MCP server. Five queries against material that’s already written: token values, component specs, “does this component exist”, compliance checks, open questions. Its value isn’t serving the people who already follow the system — it’s answering the ones who would otherwise guess.

The order matters. An MCP doesn’t fix incomplete documentation; it serves it faster and with more authority. Which is why the drift got measured first.

What I Learned

• A design system is only real when the drift is measured. I audited both sources, found the mapping broken on the most-used component in the library, and fixed it. The audit is the deliverable. The mappings stay written and validated, not published.
• Agents scale execution, not judgment — they counted, diffed and migrated. What kept the output usable was the constraints in the brief and reading the result like it might be wrong.
• Phased delivery beats perfect plans — Q2 mobile data reshaped the Q3 homepage. Impossible in a big bang, and only affordable because each quarter inherited the last one’s components.
• Measure which part of the system does the work — I wrote rules for agents, and I put tokens and structure in the code. When I removed the rules and ran it again, nothing measurable changed. The code was doing the work.