One set of design rules that designers, code and AI tools all follow.

Every output is regenerated on each change and compared with the token file, so a hand edit to any of them fails the build.

React first, on purpose. The spec is written so a second framework can be generated from it rather than rewritten. That part is still a plan.

The behaviour of the harder components, focus traps and keyboard handling, comes from Base UI, an open-source library. Every pixel still comes from Vela's tokens.

White-label means a brand colour arrives from someone else, and it can't be trusted to work. So the brand is an input the system checks, not one it obeys.

• Colour first. One brand colour. Radius and type come in later phases.
• A short allow-list. A brand can set the primary button, links and selected states. A test fails if it touches anything else.
• Why violet. Orange already means Severity minor and Status medium. An orange brand would make every primary button look like a warning. Violet sits in the widest unused stretch of the colour wheel.
• When to refuse. A brand gets a warning if it shares a hue with a meaning. It is refused only when primary can't be told apart from destructive or critical.

Severity, Risk and Status never mix. Three separate scales, so a risk can't be shown as an outage. Most systems fold them into one "status" and spend years pulling them apart.

Every rule in the docs carries a tag saying how it is caught. A check reads the tags and fails the build if a rule meant for the compiler or a test has no proof behind it, so a rule added later can't skip the gate.

Where a rule sits between two levels, it is filed at the lower one. Understating what is enforced is the safe direction.

Contrast works the same way: every text and background pair, in both themes, fails the build if it drops below AA.

Vela animates for three reasons only: feedback, orientation and continuity. How fast depends on how often people trigger it. A button pressed a hundred times a day gets feedback under 200 ms. Nothing animates from the keyboard.

This pass comes from Emil Kowalski's essay "Great animations": ease-out for things that enter, one spring for a few chosen moments, and every animation interruptible. I left out JavaScript animation libraries, because the core package has no dependencies, and I left out springs everywhere, because most motion should go unnoticed.

Measured in the press test: 9 of 12 mouse presses near the edge were lost, and 0 of 12 by touch. On the shipped button, 10 of 30 were lost without the fix, and none with it.

Tabs left this list because they shipped, and the motion changed on the way. The old underline slid across the row to the new tab. When the selected tab was far away or scrolled out of view, it arrived from somewhere you weren't looking. Now a short bar appears under the tab you point at, and a click grows that same bar into the underline, right where you are looking. Sliding and growing scored a tie, 94.1% against 93.5%, so I chose growing by eye. A version that followed the pointer lost: too lively for a control used all day.

How it gets built

Separate agent sessions own the repo, the Figma library and the specs, and every spec is pressure-tested by one that didn't write it. Review has caught an invented example and a legal claim that went too far.

At first, agents opened every change for my review and I merged each one. Once the work held up, I automated it: agents now merge their own changes. Publishing the Figma library is still my job, only because AI can't do it yet; I last published it on 1 November. npm releases follow it.

Why publish specs before code

So the design can be argued with in the open. The cost is that API changes happen in public, and every rule is labelled untested until an analyst has tried it.