A single source of truth for a design system

What it is

A single source of truth is the one place where a design system’s decisions, tokens, and assets live, and the place every other surface is derived from. Not the newest file. Not the person who remembers. One address, and the rule that when two things disagree, this one wins.

Most teams do not have one. They have a Figma library, a token file in a repo, a brand PDF, a Slack thread where the real reason was explained, and a docs site that was last updated two quarters ago. Each is true about something. None of them is true about everything, and nobody can tell you which to trust without asking a person.

What “alive” means

A source of truth is not a document. It is a document plus a habit. Alive means that when a decision changes, the change lands here first and the other surfaces follow. Dead means the reverse: the change lands in one screen, then in one component, then eventually in a note that nobody re-reads, and the document becomes a record of what the team used to think.

It also means somebody owns the update. Not the whole system — the update. The difference between a system that holds and one that does not is usually a single question with a clear answer: when this changes, who writes it down, and by when.

Rot has an order to it. Assets go first, because they are copied the most and versioned the least. Tokens go next, quietly, as values get hardcoded under deadline and never come back. The decisions go last, because by the time the reasoning is gone, the people who could restate it have moved teams.

Why teams pay to keep one alive

Companies pay people to keep a single source of truth alive and communicated across the team. That work is manual, constant, and invisible until it stops. Someone re-explains the spacing scale in a review. Someone catches the wrong logo in a deck. Someone answers the same question about disabled states for the fourth time this month.

It is real work, and it is the kind of work that disappears from the record. When the person doing it moves teams, nothing breaks on the day they leave. It breaks three months later, in a hundred small places, and nobody connects the two.

The cost of re-deciding

When the record is missing, the team does not stop. It re-decides. That is the expensive part, and it is expensive twice.

The first cost is the obvious one: the meeting, the thread, the two days of drafts to settle a question that was settled a year ago. The second cost is worse. The new answer is rarely identical to the old one, so now the product holds both — the old rule in the screens that shipped before, the new rule in everything after. The product simply stops looking like one product, in a way that is hard to point at and harder to bill for.

Written decisions do not stop a team from changing its mind. They change what a change costs. With the reasoning on the page, a revision is an argument against a known position. Without it, every revision starts from nothing.

What belongs in it

Two things, and they are different in kind.

First, the decisions: rules written once, with usage, tone, spacing, and the reasons behind them. A rule without its reason is a rule that gets overturned by whoever argues hardest in the next review.

Second, the material: tokens and assets, versioned. Type, color, logos, components, held in one place, with a history, so “which version is current” has an answer rather than an opinion. In Riyar those two jobs are the Define and Hold modules.

What does not belong is just as clear. Not every screen the team has drawn, not the exploration that lost, not the backlog. A source of truth that grows to hold everything answers nothing.

Who reads it

Designers, engineers, and the brand team, which is the audience a source of truth has always had. And now, coding agents and generative tools, which build production UI and cannot read a Figma comment or infer a rule from a thread. Same source, two very different readers.

A person needs the reasoning. They arrive with a case the rules do not cover, and what they are really looking for is the thinking behind the nearest rule so they can extend it without breaking it. Prose is good for that.

A tool needs the opposite. It needs the exact value, the version that value belongs to, and the constraint stated so plainly it can be satisfied or failed. Prose is where a tool guesses, and a guess that reads well is the hardest kind to catch in review.

Serving both from the same place is the point. Two derived views, one record, so the page a designer opens and the context a tool pulls cannot disagree. That is the split the rest of these pages are about: see design system context for AI tools and decisions, tokens, assets.