For designers

What the source of truth is, what a thing is called on each side, which files to take into a design tool, and what the badge promises a screen.

The source of truth

The system has three sources of truth and each answers a different question. When two of them disagree, the one whose question is being asked decides.

Sources of truth
Question	Decided by	Why
How it looks	The design handoff	It decides shape, density and behaviour. When the implementation and the handoff disagree, the handoff wins — unless a written reason stands beside the difference.
What a value is	The token file	Colours, spacing, radii, shadows, motion and the type scale. The stylesheet and the utilities are both generated from it — no other value exists in the product.
What a component can do	The component page	Variants, sizes, states and what a primitive deliberately cannot do. The page renders the real component, so it cannot promise something the kit does not do.

Naming

In a design the element goes by its selector, in code by its export name. A property is the name of the component's property, a value one member of its set. Nothing is translated between design and code — and because nothing is translated, nothing can drift.

A token is named in a design as it is in the stylesheet — surface-2, not "Background / Secondary". A shared vocabulary between designer and developer is the whole point of the system.
The accent is one family of four tokens, not four colours. There are five families and each has its own light and dark values — ten combinations, switched in a design the way the application switches them.
An icon carries the kit's name — arrow-right, not "right arrow". An operation key is not translated at all: the server holds it.

Files

Four files, all written by the build from the same sources the product is built from. None is written by hand, so none can describe a kit that does not exist.

Files
File	What is inside
Tokens	The whole palette, the scales, the type and the motion in the standard design-token format — the same file the stylesheet is generated from.
Icons (92 SVG)	Both sets as files, drawn by the same component the application draws with.
Components	The primitives with their selector, status, version, tokens and property sets. It answers what a primitive can do without opening the code.

Status and version

The badge beside a component's name tells a developer whether the API can be relied on. In a design it means something slightly different — whether a screen can be built on that component yet.

Stable — the shape does not change without notice. The component may go into a screen and be built on.
Beta — the shape is still being found. Draw with it, but expect it to change; it belongs in a shared library only after it is promoted.
Deprecated — it has a successor and disappears in a named version. New screens may not use it; the old ones are moved over before that version arrives.

The primitive's version stands beside the badge. The components file carries the version of the whole kit, so a library can tell that it is behind — and behind what.

When they disagree

The design wants a value the palette does not have. That is neither the design's fault nor the code's — the system is missing a decision. It is settled in the system: either a token that already exists turns up, or a new one gets a name.
The design wants an element the kit does not have. A new primitive arrives when a concrete screen asks for it — and then as one change: the component, its page, and the first screen that really uses it.
A component looks different in the product than in the handoff. The handoff wins, unless a written reason stands beside the difference. When one does, that reason is worth discussing rather than working around.
A colour, a spacing or a radius written straight into a screen means one of two things: either a token exists and was not found, or the system is missing a decision. Both are settled in the system, not in the screen.