Decisions, tokens, assets

Decisions: the rules and the reasons

The top layer is what the team decided and why: usage, tone, spacing, and the reasoning behind each. This is the layer that is almost never written down, because it feels obvious to the people who settled it.

A rule with its reason survives a new hire, a redesign, and an argument. A rule without one is trivia, and trivia gets overruled. Written once, in one place, it stops being something a person has to be in the room to defend.

A decision looks like this. Destructive actions never use the primary button; they use the quiet button with destructive text, because the primary style is the one the eye lands on first, and the action you least want taken by accident should not be the one that pulls the cursor. Two sentences. The rule, then the reason. Everything that makes it useful a year from now is in the second sentence.

Most teams have a hundred of these and have written down none. They live as review comments and as the shape of the screens that already shipped.

Tokens: values with versions

The middle layer is the values themselves — type, color, spacing — held as tokens and versioned. Versioning is the part that does the work. A token without a version is a number someone copied, and copies go stale silently.

With versions, “is this current” has an answer, and a change has a before and an after that anyone, or anything, can resolve. Without them, the same colour exists four times at slightly different values and nobody can say which one is wrong.

A token looks like this: a name, a value, and where it belongs. Surface, secondary, a hex, at version four of the palette. The name is the durable part. When the value changes, everything pointing at the name moves with it, which is the entire reason to name a colour instead of writing the hex.

Assets: the approved material

The bottom layer is what actually ships: logos, type files, color, components. The approved set, in one place, rather than the set that happens to be in someone’s downloads folder.

Tokens and assets are the same job in Riyar — the Hold module — because both answer the same question: what is the current, correct material, and where do I get it. A logo that is hard to find is a logo that gets replaced by whatever was easy to find, and that substitution never shows up in a review until it is already in production.

An asset looks like this: the wordmark, as an SVG, at the current version, with the clear-space rule attached and the retired variant marked retired so it stops circulating. An old asset that is merely unused is still available, and available is all it takes.

How the layers map to Figma, code, and docs

These three surfaces each hold a slice, and each loses the rest. Figma holds the drawing and the components; the reasoning sits in comments that only people can read. Code holds the token values and the built components; it does not carry usage or tone. Docs hold the prose; they go stale the moment either of the others moves.

Follow one decision across all three and the gap is obvious. The destructive-button rule exists in Figma as two variants sitting next to each other, with nothing to say which goes where. In code it exists as two props, either of which compiles. In docs it exists as a sentence, if somebody wrote it, in a page that may predate the current button. The rule is real on all three surfaces and enforced on none of them.

The point of keeping the three layers in one place is that the surfaces stop being three competing sources and become three views of one. Figma renders the material, code consumes the values, docs present the reasoning, and all three are derived rather than maintained in parallel.

What breaks when a layer is missing

Each absence fails in its own way.

No decisions, but good tokens and assets: everything is on-brand and nothing is coherent. Every value in the product is a real one and the screens still do not agree with each other, because there was never a rule about which value goes where. This is the most common state.

No tokens, but written rules and approved assets: the system is right in principle and approximate in practice. The rules describe a scale that the product implements four slightly different times. The gap between the documentation and the build widens until the documentation is treated as aspirational, and then stops being read.

No assets, but rules and tokens: the parts a person cannot regenerate go missing. Colour and spacing hold, because those are values. The logo does not, because somebody needed it at four in the afternoon and used the one in last quarter’s deck. This is the failure most visible from outside the company.

All three, held together, is the case for a single source of truth, and the precondition for serving that system to AI tools.