Back to blog

Design system documentation that people and coding agents both read

Design system documentation that lives beside the code: an AGENTS.md index, scoped rules, a doc comment per component and lint, each with an example to copy.

Modeinspect

Design system documentation that people and coding agents both read

Design system documentation is the written half of a design system. It says what each component is for, when to use it, when not to, and which rules apply to tokens and composition. The usual home for it is a documentation site. This post keeps it in four places inside the repo, next to the code it describes. Every site, Storybook page and MCP answer is then a copy generated from there.

The reason is the second reader. A person opens a docs page. A coding agent opens the file it is about to import from. It does not browse your site on its own. Text that sits beside the code reaches both. Each of the four layers below comes with a file you can copy: an AGENTS.md index, a scoped rule file, a doc comment and a lint rule. Building the components themselves is covered in the guide to building a design system in code.

Key takeaways

  • Keep documentation in the repo, in four layers: an AGENTS.md index, scoped rules, a doc comment on each component, and lint.
  • Change the documentation in the same pull request as the component. A page on a separate site is not in the diff, so nothing fails when it goes stale.
  • Write "when not to use" as one line that names the alternative: "Not for navigation: use Link."
  • Generate the docs site, the Storybook page and anything an MCP server returns from the code. Never edit a generated copy by hand.

What design system documentation covers: examples from GOV.UK and Carbon

Documentation answers what the code cannot say about itself. Types list the options a component accepts. Only a sentence says what the component is for, and when something else is the better choice.

The public systems show the shape of a component page. The GOV.UK Design System's tabs page runs "When to use this component", "When not to use this component", then "How it works" (GOV.UK Design System). Carbon's button guidance has a "When not to use" heading too, with lines such as "Do not use buttons as navigational elements" (Carbon). More design system documentation examples, scored on what a coding agent can read, are in ten public design systems compared.

A coding agent arrives with the same questions as a new teammate. It looks for the answers in different places.

A person and an agent ask the same five questions. An answer written once in the repo reaches both.

  1. What is it for?RepoDoc comment on the exportPersonEditor hover, generated docs pageAgentThe file it imports from
  2. When should I not use it?RepoA “Not for” line in that commentPersonThe same hover and pageAgentThe same file
  3. Which options exist?RepoProp typesPersonProps tableAgentTypes, and the type errors
  4. How do the parts fit?RepoOne story per behaviorPersonRendered exampleAgentExample code to copy
  5. What is off limits?RepoAGENTS.md, scoped rules, lintPersonReview comments, lint errorsAgentSession context, lint errors

Write the answer once, in the repo: a doc comment, a "Not for" line, prop types, one story per behavior, and the rules. A person gets the doc comment as a hover in the editor and as a generated page. An agent gets it in the file it reads before it writes the import. Anthropic's Claude Code docs give a test for everything else you are tempted to add: "Could it find this by reading the code?" (Claude Code docs). If it could, leave it out.

Why design system documentation drifts on a separate site

If you own the design system, you have probably built the site already. A zeroheight space or a Notion page, one page per component, links from the Figma library. Then a pull request arrives with a hand-built dropdown, and the docs page for Select still lists a prop someone renamed in March.

A page drifts when it changes on a different schedule from the code. Google's documentation guide for its own engineers puts the fix in one line: "Change your documentation in the same CL as the code change" (Google documentation guide). A CL is Google's word for a pull request. Storybook's team is blunter about the alternative: "Documentation that drifts from the actual components is worse than none, because it actively misleads" (Storybook).

A pull request that renames a Button prop updates the documentation in the repo. The page on the docs site is not in the diff.

In the pull request
  • AGENTS.mdindex, unchanged: it holds no props
  • components/
  • ui/
  • button.tsxMprop, type and doc comment
  • button.stories.tsxMthe example
  • .claude/rules/ui.mdscoped rules, unchanged
  • eslint.config.mjsunchanged
Outside the repo
docs site / Button pagekind="primary"
  1. Written by hand on a hosted page. Nothing in the pull request touches it and no check fails, so it keeps showing a prop that no longer exists.

Example repo. The pull request renames kind to variant.

We hear the same thing on our calls with customers: a design system specialist raises a pull request as the reference for developers. The documentation still gets written afterwards, as a second confirmation.

The documentation platforms now answer agents with an MCP server. zeroheight says "The zeroheight MCP gives your agents full context" (zeroheight). Supernova's "Scoped MCP serves the same documentation to Cursor, Copilot, and Claude Code" (Supernova). That delivers the page to the agent. For any fact someone typed into the page, staying current still depends on that person editing it after each component change. Storybook and Figma each offer a server too. The open question is how much MCP a design system needs.

Hardik Pandya wrote up how he exposes a design system to language models. His rule: "Spec files live in the repo next to the code they govern, not in a wiki or a Figma comment" (Hardik Pandya).

Design system documentation best practices: four layers in the repo

Consistent structure, real examples and a changelog all depend on one practice: where the text lives. Four layers in the repo cover it, and each reaches its reader at a different moment.

LayerFileA person meets itAn agent meets it
IndexAGENTS.md at the rootWhen they open the repoAt the start of every session
Scoped rulesA rule file with a path patternIn code reviewWhen it touches a matching file
Component docsA doc comment on the exportOn hover, and on the generated pageWhen it reads the component file
EnforcementLintAs an error in the editor and in CIAs an error it has to fix

What goes in each layer is listed in putting instructions next to the code they govern, the guide's fifth step. The sections below show one example file per layer.

AGENTS.md examples: an index for a design system

The agents.md site describes the file as "a README for agents" (agents.md). Cursor "supports AGENTS.md in the project root and subdirectories" (Cursor docs). Claude Code reads it when the repo has no CLAUDE.md, and otherwise through an @AGENTS.md import (Claude Code docs).

For a design system, the file is an index. It says where the system lives, which rules apply everywhere, and what each component is for.

An AGENTS.md index for a design system fits on one screen: where it lives, the rules, and one line per component.

AGENTS.md
## Design system
Components live in components/ui. Import from "@/components/ui".
Run `pnpm lint` and `pnpm typecheck` before you finish.
## Rules
- Colors and spacing come from theme tokens. No hex values.
white and black are fine for overlays.
- No new variants in components/ui without asking. Doc comment edits are fine.
- Raw <button> and <a> fail lint. Use Button and Link.
## Components
- Button (ui/button.tsx): actions. Not for navigation: use Link.
- Dialog (ui/dialog.tsx): one blocking decision. Not for long forms: use a page.
- Tabs (ui/tabs.tsx): views of the same content. Not for steps: use Stepper.
Each file's doc comment has the parts, props and an example.
  1. Where the system lives and how to import it.
  2. The checks to run, as commands an agent can execute.
  3. A rule on one line, with the exception you allow.
  4. One line per component: name, path, what it is for and what it is not for.
  5. A pointer to the detail. The index does not copy it.

Example file for a product repo. Swap in your own paths, commands and components.

Three open-source UI projects publish theirs, and each shows one habit to copy:

  • Storybook keeps it to pointers. Its file tells maintainers to "Keep this file to the always-on rules and pointers" and links a guideline document per task (Storybook's AGENTS.md).
  • Base UI ties docs to the change. After naming where the public documentation sits, it adds "Alter the docs where necessary when changes must be visible to library users" (Base UI's AGENTS.md).
  • Carbon marks its generated files. Its token reference "should not be edited directly", because a build writes it (Carbon's AGENTS.md).

Keep the index short. Claude Code's docs say to "target under 200 lines per CLAUDE.md file", because longer files "reduce adherence" (Claude Code docs). One line per component fits that budget. A props table per component does not, and the types already hold it.

Scoped rules: load with the files they govern

Rules that apply only to UI files should load only with UI files. In Claude Code, that is a Markdown file in .claude/rules/ with a paths: list at the top. "A path-scoped rule loads when Claude uses the Read, Write, or Edit tool on a matching file" (Claude Code docs).

---
paths:
  - "app/**/*.tsx"
  - "components/**/*.tsx"
---

# UI rules

- Colors: semantic tokens only (bg-surface, text-foreground). white and black are fine for overlays. No dark: color utilities.
- Icons come from components/ui/icon.tsx. One size prop, no inline SVG.
- Before you build a component, search components/ui. If one is close, use it and ask for the variant.

Cursor has the same idea in another format: .mdc files in .cursor/rules, where a rule can apply "When file matches a specified pattern" (Cursor docs).

That is two formats for one rule. A team that uses both tools keeps two copies, and two copies drift. The portable option is a second AGENTS.md inside the components folder, since "the closest one takes precedence" (agents.md). It costs you the path patterns, and a repo with a CLAUDE.md has to import it there for Claude Code to read it. No shared format for scoped rules exists yet.

The rule about dark: utilities only works when a token exists to use instead. That needs semantic tokens that switch per mode.

The doc comment: when to use a component, and when not to

The component's own documentation is a comment above its export. It is the layer both readers are most likely to see, because it travels with the import. It answers five questions in order: what the component is for, when to use it, when not to, which parts it has, and one full example.

A doc comment that answers five questions. Each “Not for” line names the component to use instead.

components/ui/tabs.tsx
/**
* Tabs switch between views of the same content in one place.
*
* Use when people need one view at a time and labels are short.
* Not for steps in a sequence: use Stepper.
* Not for moving between pages: use NavigationMenu.
*
* Parts: Tabs, TabsList, TabsTrigger, TabsContent.
* orientation="vertical" stacks the list, and arrow keys follow it.
*
* @example
* <Tabs defaultValue="usage">
* <TabsList>
* <TabsTrigger value="usage">Usage</TabsTrigger>
* </TabsList>
* <TabsContent value="usage">…</TabsContent>
* </Tabs>
*/
export function Tabs(props: TabsProps) {
  1. What it is for, in one sentence. An editor shows it first on hover.
  2. When to use it.
  3. When not to use it, with the alternative by name.
  4. The parts, and any behavior that looks the same at rest.
  5. One example that shows the whole tree.

Example component. Stepper and NavigationMenu stand for whatever your library offers instead.

People get it without opening a docs site. VS Code's docs describe the mechanism: "Hover over a JavaScript symbol to quickly see its type information and relevant documentation" (VS Code docs). Storybook turns the same comment into a page: "Descriptions can be written as JSDoc comments above stories, meta, or components" (Storybook docs).

How to write "when not to use a component"

The line has two halves around a colon: the situation, then what to use instead.

  • "Not for steps in a sequence: use Stepper."
  • "Not for navigation: use Link."
  • "Not for content everyone needs to see: put it on the page."

GOV.UK writes the first half well: "Do not use the tabs component if the total amount of content the tabs contain will make the page slow to load" (GOV.UK Design System). For an agent, add the second half, so the line names what to import.

The lines come from review. The second time a reviewer writes the same correction on a pull request, it becomes a "Not for" line. That loop is part of how changes get into a design system.

Two more habits fit in the comment. Mark a component you are retiring with @deprecated, which TSDoc defines as a tag "followed by a sentence describing the recommended alternative" (TSDoc). Editors then show the name struck through wherever it is used (TypeScript handbook). And give each behavior that looks identical at rest its own line, as in documenting behavior, not only looks.

To list the components that have no such line yet, run the audit check for a missing "when not to use".

Lint: documentation that appears at the mistake

A lint message is documentation delivered on the line where the rule broke. In ESLint's no-restricted-imports rule, "Custom messages for a particular module can also be specified" (ESLint). Use the message to name the replacement.

// eslint.config.mjs: add this object after your existing config
export default [
  // ...your existing config (Next.js, typescript-eslint)
  {
    files: ["app/**/*.tsx"],
    rules: {
      "no-restricted-imports": ["error", {
        paths: [{
          name: "@radix-ui/react-dialog",
          message: "Import Dialog from @/components/ui. It carries the tokens and the focus rules.",
        }],
      }],
    },
  },
]

Move a rule here when the written version keeps failing. Claude Code's docs name the signal: "If you keep adding emphasis to a CLAUDE.md line and Claude still misses it, that's a sign the line belongs in a hook" (Claude Code docs). A lint error is the same step for a rule about code.

Lint can require the documentation too. The jsdoc/require-jsdoc rule "Checks for presence of JSDoc comments, on class declarations as well as functions" (eslint-plugin-jsdoc). Scoped to components/ui and set to error, it fails lint for a function component that ships without a comment. Components written as arrow functions need its require.ArrowFunctionExpression option. Which other rules are worth an error is covered in enforcing design system rules on AI-generated code.

Storybook and other design system documentation tools

A documentation tool is safe when it reads from the repo. It causes drift when people type component facts into it by hand.

  • Storybook generates a page per component. Its docs call Autodocs "a powerful tool that can help you quickly generate comprehensive documentation for your UI components" (Storybook docs). A Storybook design system site renders your stories and doc comments.
  • Docusaurus "is a static-site generator" (Docusaurus). Its pages are Markdown files that can live in the same repo and the same pull request.
  • zeroheight hosts the documentation: "Document your entire system in one place" (zeroheight). It suits readers who never open the repo, such as content designers and product managers.
  • Supernova connects sources. Its documentation product promises that "the documentation stays current" when the design system data changes (Supernova).

Backlight, which older tool lists still include, shut down in June 2025 (Backlight).

Storybook's own advice on combining these tools is the rule to keep: "the component-level reference should be generated from the code, and everything else should link to it rather than copy it" (Storybook).

Not everything fits beside the code. User research on a component, content guidelines and patterns that span several components are long, and people outside engineering read them. They still need a page, and that page still needs an owner.

For the Figma side, see which copy to trust for components, variants and docs.

Using AI to generate component documentation

An agent drafts the parts of a doc comment that are already in the code: the parts list, the props and an example taken from real call sites. It cannot know what the component is not for. A respondent in zeroheight's design systems report said it plainly: "AI can help us document faster, but it can't decide what's worth documenting" (zeroheight report).

So split the work. Ask the agent to draft the comment from the component file and its three most common usages. Write the "Not for" lines yourself, from the corrections you remember making. Review the result in a pull request like any other change.

Where to start

  1. Pick your five most-used components. Give each a doc comment with one sentence on what it is for and one "Not for" line that names the alternative.
  2. Add a design system section to AGENTS.md: where the components live, three to five rules, one line per component.
  3. Move UI-only rules into one scoped rule file. A nested AGENTS.md works too, imported from CLAUDE.md if you have one.
  4. Take the correction you wrote most often last month and turn it into a lint message that names the fix.
  5. Open your docs site and find every component fact someone typed by hand. Replace each with a generated block or a link to the source.

Tools that work on the codebase read the same files. Modeinspect supports Next.js React codebases that use Tailwind, and its coding agent reads and follows the repo's CLAUDE.md, AGENTS.md and rule files. Tokens in its design panel are offered from your Tailwind theme, not enforced.

Start with the first step today. Open your most-used component and write its "Not for" line.

Frequently asked questions

What is design system documentation?

Design system documentation is the written guidance that goes with a design system's tokens and components. It says what each component is for, when to use it, when not to, how its parts fit together, and which rules apply across the system. People read it as pages and editor hovers. Coding agents read it as files in the repo.

What should design system documentation include?

For each component, write one sentence on its purpose, when to use it, and when not to, with the alternative named. Add its parts, any behavior a screenshot cannot show, and one full example. For the system, say where components live, what the token rules are, and how to propose a change. Props tables come from the types and should be generated.

What are good design system documentation examples?

The GOV.UK Design System puts "When to use this component" and "When not to use this component" on its component pages. Carbon's button guidance has a "When not to use" heading. In code, Storybook's, Base UI's and Carbon's public AGENTS.md files show how a UI project documents itself for coding agents.

What is the best tool for design system documentation?

It depends on who reads the docs. Storybook generates a page per component from stories and doc comments. Docusaurus builds a site from Markdown in your repo. zeroheight and Supernova host documentation for readers who never open the repo. Whichever you choose, generate component facts from the code instead of typing them in.

Can you document a design system in Storybook?

Yes. Storybook's docs say its documentation features let you "create UI library usage guidelines, design system sites, and more" (Storybook docs). Autodocs builds a page per component, and the description comes from the doc comment above the component. Keep the comment as the source and the Storybook page as the view.

What goes in AGENTS.md for a design system?

Say where the components live, how to import them, and which commands to run before finishing. Add three to five rules with their exceptions. Then give each component one line: name, path, what it is for, what it is not for. Leave props and long guidance in the component files and point to them.

How do you document a design system?

Write it in the repo, in four layers. An AGENTS.md index lists the components, and rule files scoped to UI paths hold the rules. Each component gets a doc comment with a "Not for" line that names the alternative. Lint messages name the fix. Then generate the docs site and Storybook pages from those files.

How do you keep design system documentation up to date?

Change it in the same pull request as the component. Keep component facts in doc comments and types, generate pages from them, and never hand-edit a generated copy. Use lint to fail CI when a component in the system has no doc comment.