Design system context for an agent building interfaces

How interfaces are built here. This is not a component catalogue — it is the set of rules an agent needs so that what it builds belongs to the same product as everything already built.

The failure this prevents

A component built to look right in one state, on one screen size, by someone who already knows what it does. Everything below is what the code cannot tell you.

Tokens are the source of truth

Design values live in {{tokens_path}}. Nothing else defines them.

• Never hardcode a value that exists as a token. Not a hex code, not a pixel spacing, not a radius — including “just this once” and including inside a one-off component.
• If the value you need does not exist as a token, stop. Adding a token is a change to the visual language, not an implementation detail. Propose it, say what it is for and why the existing scale does not cover it, and let someone decide.
• Prefer the nearest existing token to a new one. Almost always the design survives the rounding, and a scale with three near-identical steps is worse than a design that used the step above.

The same applies to type scale, spacing scale, radii, shadows, motion durations and z-index layers. Anything with a scale has a scale for a reason.

Every state is part of the component

A component is not done when it renders. The states that get skipped are the ones people actually hit:

• Default, hover, focus, active, disabled — focus especially, see below.
• Loading — including what it looks like when loading takes longer than expected, which is when the user starts wondering if it is broken.
• Empty — the first thing a new user sees. Usually the most neglected state in any product and the one with the most influence on whether they continue.
• Error — what it looks like when the thing fails, with recovery reachable from that state rather than requiring a reload.
• Too much content — long names, long lists, long words that cannot wrap. Test with the longest plausible real value, not with “Test”.

If a state is genuinely not designed yet, say so rather than inventing one. An invented empty state becomes the empty state.

Accessibility is a floor

{{accessibility_standard}}, and it is not traded against appearance. The full commitment, what is verified and where to stop lives in the accessibility rootnote — it is stated once there rather than three times across this set.

Before building a new component

• Check whether one exists. A near-duplicate is worse than a slightly imperfect fit, because both then need maintaining and they diverge.
• Extend before you fork. If an existing component almost fits, adding a variant is usually right; copying it and editing is usually not.
• Compose from primitives rather than building bespoke layouts, so spacing and alignment inherit the scale instead of being retyped.
• Name it for what it is, not what it looks like. Callout survives a redesign; YellowBox does not.

Responsive and density

State what breaks first as the viewport narrows, and design that deliberately rather than letting it be discovered. Tables, long headings, side-by-side layouts and fixed-width controls are the usual candidates.

Test at the smallest supported width with the longest real content. Both extremes at once is where the layout actually fails, and testing them individually finds neither.

The boundary with the editorial guide

This document owns the container and the behaviour: what a control looks like, how it responds, what states it has, how it is spaced.

The words inside it — button labels, error text, empty-state copy, terminology — belong to the editorial guide. When the two meet, this document sets the constraint and the editorial guide sets the style: this says a button label must fit on one line at the smallest width; the editorial guide says a button label is a verb.

If a component’s design depends on copy that does not exist yet, that is a question for whoever owns the words, not a placeholder to invent.

What needs a human

• Adding or changing a token. That is the visual language itself.
• Introducing a new component pattern that other things will copy.
• Anything that changes how a familiar interaction behaves, where the cost is paid by people who already learned the old one.
• Relaxing an accessibility rule, which is a decision with legal and ethical weight and is never a tidiness matter.

An agent may prepare any of these with a worked example and an argument. It should not merge one.