Skip to content
Design Academy My progress

Stage 6 · Lesson 13 of 13

Maintaining and documenting a design system

Docs, versioning and governance. Includes the mini design system project.

  • Intermediate
  • 35 min
  • 3 check questions
  • Exercise: 1 h 15 min

By the end of this lesson you can

  • Write component documentation people actually use.
  • Include usage guidance, examples, accessibility and code links.
  • Keep documentation up to date with contribution and versioning.

The idea

A design system is only as good as its documentation. Components without guidance get misused or ignored.

What a component page includes

  • Summary: what it is and when to use it.
  • When not to use it, and what to use instead.
  • Anatomy: labelled parts.
  • Variants and states with examples.
  • Content guidance: label length, tone, capitalisation.
  • Accessibility: keyboard behaviour, screen reader labels, focus.
  • Code: link to the implementation and props.
  • Research: evidence that supports the design, if any.

Keeping it alive

Documentation goes stale quickly. Define a contribution process (how teams propose changes), version the system with release notes, and assign ownership. Mark components as experimental, stable or deprecated so people know what they can rely on.

Why it matters in real projects

Good documentation turns a component library into a shared language. It helps new designers and developers learn quickly, reduces repeated questions and keeps products consistent. Clear status and release notes build trust that the system is maintained.

A realistic example

A team's modal component is used for everything from confirmations to multi-step forms. Users complain about modals inside modals and lost work.

The system team writes a modal page: when to use it (short, focused tasks), when not to (long forms, which should be full pages), anatomy, keyboard behaviour (focus trap, Escape to close, return focus), content guidance and a link to the coded component. They mark the old "large form modal" as deprecated. Misuse drops in the next quarter's audit.

Step by step

  1. Choose a component

    Pick one that is often misused.

  2. Write when and when not

    Describe appropriate and inappropriate uses.

  3. Label anatomy

    Create a labelled diagram.

  4. Add examples

    Show good and bad examples side by side.

  5. Add accessibility and code

    Document keyboard and screen reader behaviour and link the code.

  6. Set status and owner

    Mark status and name who maintains it.

Common mistakes

  • Mistake Documenting only what a component looks like.

    Instead Explain when and why to use it.

  • Mistake No accessibility guidance.

    Instead Document keyboard, focus and labels.

  • Mistake No owner or status.

    Instead Assign ownership and mark status.

Check your understanding

Choose an answer, then check it. There is an explanation either way.

Question 1 of 3What is most often missing from component docs?
Show answer

When not to use it. Guidance on misuse prevents problems.

Question 2 of 3Why mark components as deprecated?
Show answer

So people stop using them and know what replaces them. Status guides adoption.

Question 3 of 3What keeps documentation alive?
Show answer

Ownership, contribution process and release notes. Maintenance needs process.

Practice exercise

Exercise · about 1 h 15 min

Component page

Write a full documentation page for one component.

Steps

  1. Pick a component from your system.
  2. Write all sections listed in this lesson.
  3. Include do and don't examples.
  4. Ask someone new to use the component following only your docs.

Deliverable

A complete documentation page and feedback from a tester.

Self-assessment

Tick each item when it is true of your exercise. Be honest; this is for you.

4 items

Summary

  • Documentation makes components usable.
  • Cover usage, anatomy, states, content, accessibility and code.
  • Use contribution, versioning and status to keep it current.
  • Good docs create a shared language.

Further reading

Third-party sources, chosen for reliability. They open in a new tab.

Your notes

Marking complete updates your course and roadmap progress.

Back to UI design and design systems Roadmap

PreviousDesigning for internationalisation and long content Next lessonAffordances and signifiers