The design system

Grounds

The mechanism the whole palette hangs off. A ground is the only thing allowed to pair a foreground with a background, and it sets all of them at once: text, muted, borders, accent, status. Choosing a background therefore chooses everything that has to read on it.

This is not a convention to remember. A component never names two colours, so putting acid text on cream is not something you must avoid writing; it is something there is no way to write. Four grounds exist and there is no fifth: adding one means adding a row to GROUNDS in tokens.ts, and the contrast test then holds it to the same 4.5 as the other four.

Measured contrast

Computed from the token values as this page renders, so it cannot go stale. test/design-system.test.mjs recomputes every one of these with its own implementation of the formula and fails the build below 4.5. Anything on this table reading anything other than AA or AAA is a bug.

The pairings that are not available

Listed because knowing why acid is never a text colour on a light page is what stops somebody reintroducing it. Acid and brine are for grounds, marks and fills. They carry text on ink, and nowhere else.

Scales

Type, spacing, radius and motion. One definition each, in tokens.ts, referenced everywhere.

Radius

Three steps and a pill, and they are load-bearing rather than decorative: 9px for a chip or an input, 14px for a card, 18px for a panel. Three steps is how nesting reads as nesting.

Motion

Three durations, and a hard rule about what they may touch: colour, opacity, and a one-pixel press. Nothing in this system animates layout, position or size. Two effects that did were built and removed from this product already, one because it produced a repaint artefact and one because it failed to fire for four of seven sections and would have shipped a homepage that rendered blank below the hero. Everything here also stops under prefers-reduced-motion.

The component the whole workstream turns on. There is no button { } rule anywhere in this system: a control looks like a button because it says class="btn". The old stylesheet painted every button with the accent fill, so a tab strip made of buttons had a hovered tab turn dark green and the tab component carried three background: transparent declarations purely to undo it. Variants here are custom properties rather than rules, so there is one hover rule for all five and nothing depends on source order. Loading is aria-busy="true", which is both the hook the styling reads and the thing a screen reader announces.

Styled by element rather than by class, and the distinction from the button is variance, not element type: a <button> is a tab, a chip, a link and an action, while an <input type="text"> is one thing. Invalid keys off aria-invalid for the same reason loading keys off aria-busy: a field cannot be visibly red and silently fine.

Too much data is a designed state here, not an overflow. The practice console lists a portfolio and the register lists every tool a trade owns; both are unbounded, and a table that shows fewer rows than it holds has to say so with the real total. Silent truncation reads as "this is everything", which is the one thing it is not. The empty case keeps the header so the columns still say what is missing.

A card is a bordered block at 14px; a panel is the container a card sits inside, at 18px, with a header row. Never a shadow. .card-interactive is only for a card that is genuinely a link or a button: a hover state on something nobody can click is a promise the page does not keep.

Five tones and no more, because the point of a tone is that a reader learns what it means. The audit page has domain vocabulary of its own (a statutory basis, a contractual one, a bare exposure, three confidence levels) and maps those onto these five in audit-page.ts. Those names used to be tones in the shared stylesheet, which is how a design system ends up knowing what compulsory Employers' Liability is. Status tones are tuned for the paper and ink grounds only.

Live: click them. Selection is aria-selected rather than a class, so a tab cannot look selected while announcing that it is not. The strip scrolls sideways rather than wrapping, because a wrapped strip changes height when the selection moves and shifts everything under it.

A <details>, so it works with no client script at all. That is not a preference: the register page ships no JavaScript on purpose, because a sum insured should never be computed in a browser, and it is the page with the most folded content in the product.

A notice is part of the document: it stays, it can be long, and it is what the engine uses to say that a file did not state which way the money went. A toast is transient feedback about a click. This product is server-rendered and almost every message it has is a fact about the result, which is why notices are everywhere here and toasts are rare. A finding is the same tokens with no fill, for a list where tinting every row would turn the tone into wallpaper by about the third one.

The disclaimer, which travels with every rendered audit and looks the same on every surface including inside a partner's frame.

Neither may be the only place something is said. A lot of this product gets shown on a projector, and a message that appears for four seconds in a corner is a message half the room missed. The modal is a <dialog>, so focus trapping, Escape and the backdrop are the browser's job. The toast fades and does not move: a toast that slides reflows the corner of the screen while a presenter is pointing at it.

A progress bar shows how far along a task is: it only goes up, and full is good. A meter shows a value against a target: it can sit anywhere, and full is not necessarily good. This product needs the second far more, because its central argument is a shortfall. Both are divs with an inline width, because <progress> and <meter> cannot be styled consistently across browsers. The width is data, not design, and aria-valuenow carries the same number to a reader.

A sequence of attempted steps, each with an outcome and how long it took. Watch it fill in: the rows are already on the page at 30% opacity and the script clears them one at a time, so a dead script leaves a faint list rather than an empty box. This product had a hide-until-JavaScript reveal fail to fire for four of seven sections, which would have shipped a homepage that rendered blank below the hero, and that is why this one is visible-by-default.

An exchange with the tool calls shown. The tool block is the reason it is a component at all: most chat styling is a bubble, and the thing that matters here is that a reader can see the tool name and the payload, because the claim the agent page makes is that a real tool returned a real answer.

The chip is the second component the button trap bit, after the tab: it arrived painted solid green and had to be repainted back. The brand chip's off state is the one that matters, because three of the five ways into this product are not built and each has to say so on its own face.

{
  "product": "employers_liability",
  "basis": "legal",
  "triggered_by": ["payroll_seen_2026-03"]
}

Domain-shaped rather than generic, and that is the right call: this is a design system for one product, and turning an extracted fact into a declared one is the move the whole engine is built around. The "changes" line is not decoration. A confirm card that does not say what it affects is asking somebody to answer a question with no stated consequence.

The most-used component in the product, because the engine's discipline is that every fact carries its source and its confidence. Two variants, and the second exists because of a real failure: with a long label the two-column form wraps every value into a column two words wide. Below 560px the first becomes the second on its own.

Six containers, and between them they replaced almost every inline style= on two surfaces. Spacing is never set on a child; it is set by whichever container the child sits in. That is why a new screen needs no new CSS: you are choosing containers, not writing margins. .prose exists because the same max-width:78ch had been written eleven times.

The deliverable, not an afterthought. All four are the same three things: a short statement of what is true, one line of why, and at most one action. Never an illustration, never a heading that says "No results", and never a dead end. An empty state with no action is a page telling somebody it cannot help them.