System documentation

01 Why a site and not a file

A design system is two things: the pieces and the rules. The pieces live well in Figma. The rules do not, because a rule is conditional prose: “one primary action per screen, except in a dialog, where the destructive one goes on the right”. On a canvas that is a text box. You cannot search it, you cannot link it from a ticket, there is no history when it changes, and when an AI agent reads it, it gets a node tree, not the rule.

So the rules live in markdown, in a repository. A person reads them with a search box, the AI reads them as they are, and every change is recorded with its reason. The site is the public view of those files, at textplus-design-system.vercel.app.

I designed and built the site end to end, alongside the system it documents: information architecture, content, tone, mobile behaviour and publishing, with an AI agent as a pair for the mechanical work. In a team of three, documentation is what lets the developer, or whoever joins next, decide without asking me.

02 The architecture

Six sections: Getting started, Foundations, Brand, Guidelines, Components and Tokens. Almost every public system has the first five. The deliberate difference is Guidelines: the rules between components, written down.

Most systems leave those rules implicit and trust the judgement of whoever is designing. Here the consumers are a three-person team and an AI agent, and neither can infer. So Guidelines says when a secondary button is used instead of a primary one, what happens with two buttons together, when tertiary text shows up, and why yellow acts and green confirms. Every rule carries its rationale next to it, so a newcomer understands the decision rather than just obeying it. And every component page follows the same skeleton, so the developer knows where to look without learning each page.

03 Design decisions

• The header is cream, never green. Brand green means confirmation inside the app, and it cannot colonise the documentation. Areas are separated by tone, with no lines.
• No invented colours. Everything you see comes from the tokens exported from Figma, in all three modes. If the site needs a colour that does not exist in the system, the problem is in the system.
• WCAG AA is mandatory and fixed at the source. When a token pair fails contrast, it gets fixed in Figma, not patched on the site. The documentation cannot lie about the system it documents.
• Licensed icons served as raster. The icon set is paid. The original SVGs are not published; the gallery is generated as PNG masks so the site can be public without breaking the licence.
• Mobile at 360 as a requirement, not an extra. The same device floor as the app. On narrow screens the title collapses to initials, the mode toggle hides and search becomes an icon: adaptive behaviour by design, not an afterthought.

04 Result

Twenty-six pages in Astro Starlight with search, three modes with a toggle and the system’s real typography, live on Vercel with automatic deploys on every change: updating a rule and publishing it is the same gesture. Built with an AI agent as a pair: the AI does the mechanical part, from the structure to the generated colour bands, and I decide the content, the tone and what gets published. Tokens and icons come from the same files the app consumes, so design and documentation cannot drift apart.

05 Learning

Documentation has to live where people and machines read it at the same time. If only people read it, it ages in a file. If only a machine reads it, nobody argues with it. A repository with markdown and tokens in JSON, and a site on top, solves both with the same file. And writing the reason next to each rule took longer than writing the rule, but it is what lets the system outlive whoever built it.

---

Documenting is not explaining what was done. It is deciding what can be done without asking.