Building one design system for design, engineering and their AI tools

The stakes

The team was building an AI-first product for insurance work, moving quickly with a small group of designers and engineers. AI tools were already part of how they designed and shipped. Designs were turned into code with AI assistance, and pull requests came from people and tools alike.

That speed had a cost. Without one agreed reference, every screen, prompt and pull request made its own decisions about colour, spacing, states and behaviour. AI tools made it worse: they fill gaps confidently, so a missing rule turns into a new variation rather than a question.

The product also had to suit insurance. People spend whole days in claims queues, policy records and dense tables. Statuses like escalated or pending need to read the same everywhere. AI suggestions sit next to decisions that affect real claims and real money.

The goal was a single source of truth that design and engineering could ship from, written so that AI tools could follow it as reliably as people.

Starting with references and an audit, then working towards one source of truth

I started outside the product. I looked at how well-built tools handle the jobs this platform does every day:

• finding a record from a half-remembered ID;
• working through long queues;
• editing data in place;
• putting an assistant next to the work without letting it take over.

Each reference earned its place by solving a problem the platform also had, not by how it looked.

Then I audited what already existed in design and code. The same kinds of data appeared again and again: policy and claim IDs, amounts, dates and statuses. They were styled differently from screen to screen. Colours had been picked per component, so near-duplicates had built up.

The audit decided what to keep, what to merge and what to rebuild. Anything already shipped and working was kept exactly as it was, so the system could replace what existed without the product visibly changing.

1. Building foundations for a dark, data-heavy product

The product is dark and dense, and people work in it for hours, so the foundations were designed dark-first. Colours already in the product were pinned to the new ramps, so nothing on screen changed.

2. Giving AI one colour, one place, and clear limits

In an AI-first product, the easiest mistake is letting AI show up everywhere. A sparkle on every feature soon means nothing, and the one label that matters, “a model wrote this”, gets ignored.

So AI has one colour, Orchid, used only for things a model produced: summaries, suggestions and AI actions. It is never used for decoration, gradients or ordinary features. If people learn that Orchid means AI, they can spot model output anywhere in the product at a glance.

AI also has a defined place in the layout. When the assistant works next to a task, it keeps a fixed width and the content gives up space instead, so the conversation never reflows. Next to it, no more than three cards sit side by side.

And AI has limits, written down. Exact matches always rank above an AI suggestion, so someone who types the right command gets it first. Nothing runs on the model’s interpretation without a confirmation step. A command like “close all auto claims” is never executed straight from a guess.

3. Shaping components and patterns around how claims work gets done

I kept the component set small:

• badge;
• button, in two sizes;
• a multi-select menu;
• command search;
• table.

Most of the work went into the patterns built from them, because that’s where insurance work actually happens.

Smart lookup is the Open Claim flow. One panel asks four questions in turn: which policy, what happened, when it happened, then a review before opening the claim.

It recognises policy and claim numbers as they’re typed, so a partial ID finds the right record. Each answer becomes a chip at the top, and tapping a chip goes back to that step.

Every lookup also needs a way out. “Missing? Send report” stays pinned to the bottom of the panel at every step. When a policy can’t be found, the person reports it from where they are, instead of abandoning the claim or working around the system.

Tables come in four patterns, chosen by what someone needs to do with the data:

• Fixed, for read-only history.
• Actionable, for triage, with row actions like assign.
• Editable, for adjusting reserves and assignments in place.
• Bulk, for selecting many claims and reassigning or exporting them together.

Each pattern has three densities and documented loading, empty and error states.

Data cards follow the same structure everywhere: the metric and its period at the top, the numbers in the middle, and a one-line takeaway in plain words at the bottom.

4. Writing documentation that people and AI tools can both follow

Documentation was where this system had to work hardest. An AI tool reads a docs page differently from a person. It doesn’t infer intent or ask a colleague; it does what the page says, and fills any gap with a guess.

So every component and pattern page follows the same structure:

• overview, anatomy and when to use it;
• the types of item it contains;
• every state;
• keyboard behaviour and accessibility rules;
• do’s and don’ts;
• AI anti-patterns;
• React guidance, with the libraries to use and the effort each part takes;
• the API, events and tokens.

Because the structure never changes, a designer, an engineer or an AI tool knows where to look before reading a word.

The AI anti-patterns are the part I’d most want other teams to copy. They name the specific ways a model goes wrong in each component:

• Inventing commands that don’t exist.
• Ranking a generated answer above the exact match someone typed.
• Streaming results into a list while the person is choosing.
• Quietly rewriting a search.
• Presenting an unsourced answer with the same confidence as a verified record.

In insurance, that last one means a made-up claim number that looks real.

The React guidance for each component lists the library to use for each part and how much work it is. That way an engineer, or an AI tool, doesn’t rebuild what a well-tested library already does.

5. Setting up production code across shadcn, React and HTML/JS

The system ships in three tiers:

• shadcn base: simple components start from shadcn and take on the system’s tokens.
• React: complex components and patterns with real state are built in React. That covers tables, lookup, menus and layouts.
• HTML/JS: a framework-free layer of custom elements and helpers, such as the <search-palette> element, carries the same behaviour without a build step.

All three use the same tokens. A single script generates the colour ramps, overlays and semantic tokens as CSS variables for the code, and as structured data for charts, Figma variables and AI tools. Change a value once and it reaches every tier, every docs page and every contrast score.

Every pull request, whether written by a person or an AI tool, links the docs page it was built from and is reviewed against that page’s do’s, don’ts and AI anti-patterns before it merges.

The result is a system that designers, engineers and their AI tools all build from in the same way. The rules live in one place, so speed doesn’t cost consistency.

If you’re considering working together, I’d be happy to walk you through this project and other design system work relevant to your product, industry and tech stack.

Book a call