Keeping one system

Keeping one system: owners, guards, and exceptions

A design system rarely breaks in one bad screen. It breaks when two pages state the same fact and one of them changes. The useful systems treat documentation as data: one owner per fact, every restatement checked against it, and every exception written down where it happens. The guards on this page run in contradiction-guard.test.mjs on every build.

• One owner per fact. Every number, color, and rule has exactly one file that defines it. Every other page links to it or quotes it. A second definition is not a backup; it is the next contradiction. AG-015 already says this. The rest of this page is how we prove it.
• A restated number is a test. When prose repeats a token, a table row, or a size, a check parses the claim and compares it with the owner. The Surfaces block, the light table, the type table, control heights, radii, and platform target sizes in DESIGN.md are all compared with src/styles.css and the Native contract on every build.
• Every way into a theme is the same theme. Light chosen in Settings and light inherited from the system must paint the same tokens. They drifted: the field, the raised panel, and the panel rim differed by path. A guard now compares the two blocks token by token.
• Cite by id, and every id must exist. D, AG, and HIG rules are cited by number across skills, pages, and data. A citation that points at a rule nobody defines is a broken promise. The build fails on any id its owner does not define.
• An exception is written where it happens. Weights stay 400 and 500. A drawing of host chrome, such as an iOS large title or a controller glyph, may keep the host weight with a type-scale-exception note on the same line. No note, no exception. Silent exceptions become the next default.
• Debt only goes down. Where a rule cannot land in one change, record a baseline and let checks fail on anything above it. Never raise a baseline to make a check pass. AG-005.
• Print the rule from the data. The logo page and logo Markdown read one file. The constitution mirror is checked byte for byte. A page generated from the owner cannot disagree with it. A page copied from the owner always will, eventually.
• Tokens carry their meaning and their retirement. The Design Tokens Format Module 2025.10 gives every token a type, a description, aliases, and a deprecated flag. Exporting our tokens in that shape would let native apps, Figma, and decks read the same values and the same reasons instead of copying hex. Proposed, not adopted.
• Words are linted like code. Prose linters such as Vale run substitution rules (Ticket becomes Job, Submit becomes the verb, 7am becomes 7 a.m.) and existence rules on every document. The Words table in DESIGN.md is already that list. Proposed, not adopted.
• A newer rule supersedes; it never sits beside. Decision records carry a status: proposed, accepted, superseded by. When a rule changes, the old wording is marked superseded and linked, not left to compete. Normative words stay few and literal: MUST, SHOULD, MAY.
• Name what no check reads. A guard only checks what it parses. Geometry described in sentences, motion described in words, and images are still read by a person. Each guarded owner says which sections a reviewer must still read by eye.

Sources: Design Tokens Format Module 2025.10, A design system drift guard, Automating design systems, Mozilla use-design-tokens, PostHog on Vale, Datadog on Vale, RFC 2119, and Design decision log.