Skip to content
UX Atlas
Design systemCraft conventionIntermediate

Design System Documentation

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

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 page
  1. Definition
  2. What each component page needs
  3. Keeping it current
  4. Continue from here

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.

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.