Design system documentation is the written record of how to use a component, not just a picture of it: when to reach for it, a rendered example, the values it is built from, and what not to do with it. Most teams build the components first and document them later, if at all, so a designer or a new hire ends up messaging whoever built the thing, or copying it and hoping. This post covers what belongs on a component's documentation page, how design tokens fit next to it, and what keeps the whole set from going stale.
Key Takeaways
- A component's documentation page needs at least four things: when to use it, a rendered example, the values it is built from, and what not to do with it.
- Design tokens, like
color.brand.primary, get their own reference, separate from the component pages, so one value does not drift across a dozen files.- The U.S. Web Design System shows what a public, well-documented component page looks like: usage guidance, code, and accessibility notes together.
- Design system documentation only stays accurate if one person owns updating it when a component changes.
- TrueKeep connects design system documentation to Claude, ChatGPT, or Cursor through an MCP connection, so an AI tool reads the usage rules before it builds with a component.
What design system documentation covers
A design system is the components themselves: the email header, the slide template, the button. Design system documentation is the explanation that sits next to each one: why it exists, when to use it, and when not to. TrueKeep's portal setup guide covers where documentation fits among a portal's other parts, strategy, guide, assets, and components. Without the second part, a team ends up with a folder of files and no shared understanding of what any of them are for.
The Nielsen Norman Group draws the same line for front-end style guides: a library of components is only useful once it is documented well enough that someone who did not build it can use it correctly on the first try. That is the test for any page in a design system's documentation. Can a person who has never seen this component use it right now, or do they still need to ask someone?
What belongs on a component's documentation page
Four things, at minimum. Skip any one and someone picks the wrong component, or uses the right one incorrectly.
- When to use it. One or two sentences naming the situation, not the component's features. "Use the stacked header on an email with one offer; use the split header when there are two."
- A rendered example. The real thing, not a description of it. A swatch for a color, the actual typeface for type, the finished layout for a template.
- The values it is built from. The design tokens, fonts, and spacing it references, so changing one of those updates the component instead of leaving it out of date.
- What not to do with it. A short, specific rule beats a vague warning. "Do not shorten the headline below two lines" is checkable; "keep it clean" is not.
Shopify's Polaris pairs almost every component with a do-and-don't example side by side, which is the fastest way to show the rule rather than state it. A documentation page that only describes a component in prose is asking the reader to imagine the mistake it is trying to prevent.
Documenting design tokens on their own
A design token is a named value, like color.brand.primary, that stands in for a raw hex code or font size so the same value resolves the same way everywhere it is used. Tokens belong in their own reference, separate from the components built on them, because a color or a type size usually feeds more than one component.
color.brand.primary: "#1C2B33"
color.brand.accent: "#C98A3B"
type.heading.family: "Söhne"
The W3C Design Tokens Community Group is building a shared format for exactly this problem, so a token means the same thing whether a design tool, a slide template, or a line of code reads it. Document each token with its name, its value, and the one sentence that says where it is approved for use. A token with no usage note gets applied wherever it happens to look right, which is how a system ends up with a color used in six places it was never meant for.
Linking documentation back to the brand's judgment calls
A component page should link to the decisions behind it, not restate them. In TrueKeep, those decisions live in a design brief: the words the brand avoids, how formal it is, what never goes in a headline. A component's documentation can point to the one line of the brief that explains why the button copy is short, instead of leaving a new writer to guess.
Documentation that only shows the finished piece, with none of the reasoning behind it, gets followed less carefully over time. People eventually bend a rule they do not understand, but rarely one they can see the reason for.
Keeping documentation current
Documentation goes stale the same way a brand book PDF does: a component changes, and the page describing it does not. The fix is not a longer review cycle. It is making the edit cheap enough that whoever changes the component also updates the page describing it, in the same sitting.
In TrueKeep, editing a component or a token happens in the portal itself, so the update and the documentation are the same action, not two. The tradeoff is real: documentation only stays accurate if one person is responsible for making that edit when something changes. Name that person before launch, not after the first outdated example gets copied into a new project.
Writing documentation an AI tool can use
A designer who reads "use the stacked header for one offer" understands it immediately. An AI tool reading that same line understands it too, provided it can reach the line before it starts building.
TrueKeep connects the portal's documentation to Claude, ChatGPT, or Cursor through an MCP connection, so an AI tool reads the usage rules and the design tokens before it drafts anything, not after someone corrects it. A final pass then checks the output against those same rules and flags what is off before it ships. A rendered example and a named exception help a new hire read the page correctly, and they help a model just as much. What fails both is the vague line: "use your judgment" tells neither of them anything.
For the full set of what a portal holds beyond documentation, strategy, guide, assets, and components together, see what belongs in a brand design system.
FAQ
What should design system documentation include? At minimum, for each component: when to use it, a rendered example, the values it is built from, and what not to do with it. Design tokens get a separate reference with their name, value, and approved use.
What's the difference between a design system and its documentation? The design system is the components and the values they are built from. The documentation is the explanation next to them: why each one exists, when to use it, and when not to. A system can exist without documentation, but nobody can use it correctly without it.
Do design tokens need their own documentation, separate from components? Yes. A token like a brand color usually feeds several components, so documenting it once, with its name, value, and approved use, keeps every component that references it consistent when the value changes.
Who should write design system documentation? Whoever builds or changes a component should write the page describing it, in the same sitting as the change. A brand manager or lead can review it, but a description written by someone other than the builder tends to miss the reason the component works the way it does.
How do you keep design system documentation up to date? Make the edit part of the same action as the change. In TrueKeep, editing a component happens in the portal itself, so there is no separate document to remember to update afterward.
Can an AI tool read design system documentation? Yes, if the documentation is connected to it. TrueKeep connects a portal's documentation to Claude, ChatGPT, or Cursor through an MCP connection, so the AI reads the usage rules and tokens before it builds, rather than needing a correction afterward.
Start with the four things each page needs
Design system documentation works when every component's page answers the same four questions: when to use it, what it looks like, what it is built from, and what not to do with it. Design tokens get their own reference so one value stays correct everywhere it is used. None of it holds up without an owner who updates the page the moment the component changes.
Get started with a portal where editing a component and documenting it are the same step, connected to the AI tools your team already uses.