Design system documentation nearly always dies the same way. A good document exists somewhere, the code changes a few times, and within two months the document and the screen say different things. From then on nobody opens it, and because nobody opens it, it drifts further.
The cause is not length, it is location. Documentation that lives away from the code does not change with the code.
Three forms that live with the code
The first is the strongest. When a token name states its role precisely, it is already documentation: --color-success-bg needs no gloss.
The second is a document file in the repository. What matters is that it changes in the same commit. Add a token without touching the document and review notices.
The third is a style guide page hosted on the site itself. Unlike a separately built documentation site, it is rendered by the real stylesheet, so it is always true. Change a token and the swatches on that page change with it. Colour swatches, button states, the spacing scale and the type ladder are enough — and keep it out of search.
Write the reasoning, not the values
Writing --space-4: 16px into a document is waste: the value is in the code, and the code is always more accurate. What documentation owes you is the part the code cannot hold.
The “decided not to do” entries earn the most. They are exactly the ideas the next person will reach for again: why vendor tokens are never edited directly, why exceptional spacing is refused, why the editor colour picker was closed. Without the reasoning written down, those decisions are quietly reversed six months later.
Pin down a short change procedure
The last page of the document should be a procedure, not more rules. Four steps cover what to do when a new token or component is needed.
The first box does the heavy lifting. Most systems grow not because something was needed but because the existing thing could not be found. Role-based names and documentation next to the code shorten that search, and duplication falls with it.
Wherever a convention can be checked by a search, write the search itself into the document. Conventions kept by attention disappear when the people change; conventions that can be checked stay.
Closing the series
Across eight parts you named things (1–3), planted them in the theme and the editing screen (4–6), narrowed the boundary with vendor tokens down to a single bridge file (7), and set up the documentation to hand it all on (8). WordPress takes this structure remarkably well — custom properties, theme.json and child themes are all core facilities. What causes trouble is never the tool, it is time accumulating without a structure, and that is always reversible.
Further practical writing continues in the development workflow archive. Installing this structure into a site that has been running for years — theme cleanup, upgrades, performance and security review — is handled as one job by our optimization program, and the order the work runs in is published on the process page.