Skip to content
UX Atlas
Plate SYS·003 · Design systemGrid D3 · Rev. 2026-09-14

Design System Documentation

Documentation is the product. An undocumented system is a component library nobody can adopt correctly.

Design systemCraft conventionIntermediate

Definition

Design system documentation explains what exists, when to use it, and why. It serves designers, engineers, writers and product managers, each of whom needs different things from the same page.

Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.

On this plate
  1. 1Definition
  2. 2What each component page needs
  3. 3Keeping it current
  4. 4One page, five readers
  5. 5Writing pages people finish
  6. 6Local chart
  7. 7Continue from here

Reach for this when

  • Publishing any shared component.
  • Adoption is low despite a complete library.

Common mistakes

  • Documentation that describes appearance but not usage.
  • Static screenshots that drift from the code.
  • No guidance on when not to use something.
  • Accessibility notes omitted.

What each component page needs

  1. 1.What it is, in one sentence.
  2. 2.When to use it, and explicitly when not to, with the alternative named.
  3. 3.A live, interactive example, not a static image.
  4. 4.Every variant and state, shown rather than described.
  5. 5.The API: props, defaults and types.
  6. 6.Accessibility notes: keyboard behaviour, required labels, known limitations.
  7. 7.Content guidance: how to write the labels, with real examples.
  8. 8.Do and do not examples showing the common misuse.

Keeping it current

  • Generate the API documentation from the source, so it cannot drift.
  • Render examples from the real component, not from screenshots.
  • Version the documentation alongside the code.
  • Record decisions and their reasoning, so future maintainers do not relitigate them.
  • Track which pages get traffic. Unread pages are either unnecessary or unfindable.

One page, five readers

ReaderArrives askingWhat fails them
Product designerWhich component is right, and where its limits areA page that shows the component but never names the alternative.
EngineerProps, defaults, and what it actually rendersProse describing the API instead of types generated from the source.
Content designerWhat the label can say, and how long it can bePlaceholder text in every example, so no real length is ever tested.
Accessibility reviewerRole, keyboard behaviour, announced stateA line claiming the component is accessible with nothing testable in it.
Product managerWhether this already existsSearch that only matches the system's own vocabulary.

Writing pages people finish

Do

  • Open with the one-sentence purpose, because it is the only part most readers finish.
  • Show the misuse beside the correct use. The pair teaches faster than either alone.
  • Use real product content in examples, including the longest label the component will actually receive.
  • Date the page and name an owner, so a reader can judge how much to trust it.

Do not

  • Do not record intent in a design file comment, where it is invisible to everyone reading the code.
  • Do not restate visual specifications in prose when the live example already shows them.
  • Do not keep a changelog by hand. A stale one is worse than none, because it implies completeness.
  • Do not leave a deprecated component's page up without the replacement named at the top.

Local chart

SYS·003 · Region VI · Grid D3

This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.

Help and DocumentationHEUR·010 · PRINCIPLES BEHIND THISConfluenceTOOL·045 · OFTEN USED WITHNotionTOOL·044 · OFTEN USED WITHStorybookTOOL·037 · OFTEN USED WITHSupernovaTOOL·039 · OFTEN USED WITHzeroheightTOOL·038 · OFTEN USED WITHComponentTERM·037 · SHORT DEFINITIONComponent LibraryTERM·085 · SHORT DEFINITIONDesign SystemTERM·084 · SHORT DEFINITIONDesign System to DocumentationAI·007 · RELATED CONCEPTComponent Anatomy, States and VariantsSYS·009 · RELATED CONCEPTComponent API DesignSYS·002 · RELATED CONCEPT

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Principles behind this

The reasoning this solution is an application of.

Often used with

These usually appear in the same screen or the same decision.

Short definition

The one-paragraph version, for when that is all you need.

Related concept

Connected closely enough to change how you apply this.