# Documentation: The Written Home That Explains Every Design System Part

> Good documentation explains what each part is, why it exists, and how to use it, so people can work without asking the builders.

**In short:** Design system documentation is the written home that explains what each part is, why it exists and how to use it, so people can work without asking the builders.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/documentation

## What You Will Learn

This lesson is about documentation, the written home of a design system. Documentation explains what each part is, why it exists, and how and when to use it. When it works well, a designer or developer can use a part correctly without asking the person who built it. This matters most when a team grows and the original builders are busy with other work.

By the end you will know what a good component page contains, who reads it, where it should live, and how a team keeps it accurate after things change. You will walk through a real Button page, then answer two short quiz questions.

- **Design system:** A shared set of parts, styles, and rules that a product team reuses.
- **Documentation:** The written pages that explain those parts and rules.
- **Component:** One reusable piece of an interface, such as a button or a text field.
- **Variant:** A version of one component with a different look or job, such as a filled button and an outlined button.
- **State:** A condition a component can be in, such as hovered, pressed, disabled, or loading.
- **Spec (specification):** The exact measurements and behavior rules for a part, such as its size or spacing.
- **Accessibility:** Making a product usable by people with disabilities, including people who use a keyboard or a screen reader.
- **Snippet:** A short example of how to build a part, which a developer can copy. Designers read these to understand the developer side.
- **Changelog:** A dated list of what changed in each version of the system.
- **Source of truth:** The one place a team trusts for the correct answer.

## What Is Documentation For?

A design system has parts, such as buttons, colors, and icons. It also has rules about how to use them. Without written guidance, people guess. Razorpay's design team said that before its system rolled out, teams often missed small details such as button states or how a text field should show an error. Documentation closes that gap.

Good documentation does three jobs. Each job answers a different question, so it helps to think of it as three layers.

- **The reference:** This layer lists the exact facts: names, sizes, variants, and properties. Good pages keep this kind of reference separate from advice, so the facts stay easy to check.
- **The guidance:** This layer explains when and why to use each part, and when not to. It is the part a new team member reads first.
- **The record:** This layer shows what changed, when, and why. It lets a reader see whether a page still matches the current system.

> **Tip:** When you read any design system page, ask which of the three jobs it does. If a page only lists facts and never says when to use the part, it is missing its guidance.

## What Does a Good Component Page Hold?

Most teams give each component its own page. A common page covers visual previews, variants and states, usage guidelines, code examples, and accessibility requirements. Component pages are often the most visited part of a design system site, so they deserve the most care.

The four parts below are the core of a component page. Each one answers a question a reader will have.

- **Purpose and description:** Say what the part is for in plain words, and name the nearby parts it is often confused with.
- **Usage do's and don'ts:** Show good and bad uses side by side, with a reason for each rule.
- **Variants and states:** List every version and every condition, with a picture or live example of each.
- **Specs and accessibility notes:** Give the measurements, the behavior, and the requirements that make the part usable by everyone.

Sub-topics follow. Read each one as a checklist for your own pages.

### Purpose and description

A component page should begin with one plain sentence about the job of the part. A reader should understand the job in seconds. Good pages also explain when to choose this part instead of its neighbors. One design guide says the best component pages answer two questions quickly: what the part does, and when to pick it over the nearby options. A Button page, for example, should explain how it differs from a link, an icon button, or a split button.

### Usage do's and don'ts

Do's and don'ts turn a rule into a picture. They stop people from guessing. Here are three examples of the kind of rule a good page includes.

- **Keep the button count low:** Material's button guidance warns that too many buttons on a screen can disrupt the visual hierarchy, which is the order in which the eye should read the page.
- **Use buttons for actions, not for navigation:** Atlassian's older AUI guidance says actions change something on an object, while navigation takes you to another place. A link button is the right tool when a control leads to another page.
- **Do not mix styles in one group:** Atlassian's AUI guidance says that in a button group you should choose one style of variation and not mix them.

### Variants and states

A variant is a version of the same part. A state is a condition the part can be in. A good page lists both. Atlassian's token guidance notes that buttons can have several interaction states, and each state needs its own specific style value. A reader who sees only the default look will invent the missing states, and that is how custom parts appear.

- **Appearance:** Atlassian's Forge documentation lists default, primary, subtle, warning, and danger appearances, and says to pair a subtle button with a primary button for a secondary action such as Cancel.
- **Loading:** Atlassian's Forge documentation says to set a loading property so that the button shows it is working.
- **Selected:** Atlassian's Forge documentation also shows a selected state, so a reader knows how a pressed-on choice looks.

### Specs and accessibility notes

Specs tell the reader exact sizes, spacing, and how the part behaves. Material's guidance says touch targets, the area a finger or cursor can tap, should be at least 48 by 48 pixels. A spec like this is useful because it removes guessing. Accessibility notes go further. They say which keyboard keys work, how a screen reader should announce the part, and what contrast the text needs. One audit-style guide calls it a common mistake to skip accessibility details for a component. Atlassian's AUI documentation also says that button states are marked with special attributes that tell assistive technology what is happening.

> **Tip:** Write accessibility notes as plain instructions a tester can check, such as 'the button can be reached with the Tab key and activated with Enter.' A vague note like 'make it accessible' does not help anyone.

### Live examples and code snippets

A live example is a working copy of the part that the reader can click and test. Storybook's guide argues that a rendered, interactive component shows exactly what ships, which is better than a screenshot. Snippets are short build examples for developers. Designers do not need to write them, but they should check that the snippet matches the design, and that the page links to it.

## Worked Example: Reading a Button Page

The example below walks through the Button page as Material Design and Atlassian publish it. You do not need to open the sites to follow it. Each step names one part of a good page and shows how the real system handles it.

1. **Read the purpose:** Material's current button guidance says buttons communicate actions that people can take. Atlassian's Atlaskit button page says a button triggers an event or action and lets users know what will happen next. Both pages open by saying the job in one line.
2. **Check the variants:** Material's guidance lists outlined buttons as the right partner for a filled button when you need an alternative, secondary action. It advises text buttons for the lowest priority actions. Elevated buttons, which look raised from the page, should be used sparingly. A reader can now see the ranking from strongest to weakest.
3. **Read the do's and don'ts:** Material's Button page tells designers not to clutter the screen with too many buttons, and not to underline a text button. It also says that on large windows you should limit how wide a button grows, or place it beside other elements. Each rule is short and has a picture next to it.
4. **Check the accessibility notes:** Material's guidance says touch targets should be at least 48 by 48 pixels. Atlassian's AUI notes say button states are shown using special attributes. A designer uses these notes to check the size of a custom layout, and a developer uses them to build the behavior.
5. **Find the code and the rules:** Atlassian's Develop guide says to read the design recommendations in each component, such as the button usage guidelines, before you install and use it. The developer page then shows how to import the button package. You do not need to write that code. Your job is to confirm that the design page and the code page point to each other.

> **Tip:** Read a real page with a checklist: purpose, variants, states, do's and don'ts, specs, accessibility, and code link. If one item is missing, you have found a gap to report.

## Check Your Understanding: A Missing Rule

A new developer joins your team and builds a custom blue button for a Cancel action, because they cannot tell which existing button is meant for a secondary action. Read the scenario, then choose the best answer.

**Quick check:** What was missing from the documentation, and what should the Button page add?

A. A rule that every button on every screen must use the brand blue, so developers never pick a color by mistake.
B. A section that says which variant handles secondary actions, with a do and don't example, and a note on when not to build a custom button.
C. Removing the other variants, so that developers have only one button to choose from and cannot pick the wrong one.
D. A longer list of blue shades on the Button page, so that the custom button looks closer to the approved design.

**Answer:** B. The developer lacked guidance on choosing a variant. A Button page should name the right variant for a secondary action, show a do and don't example, and say which neighboring part to use instead of a custom build. Adding more colors or removing variants does not answer the question of which button to use.

## Who Uses the Docs and Where Do They Live?

Documentation has more than one reader. Magic Patterns notes that designers, engineers, product managers, and content contributors all need different things from the same system. A good page has to serve each of them, so it helps to know what each one looks for.

- **Designers:** Designers look for visual examples, usage rules, and the anatomy of a part, which means the named pieces that make it up.
- **Developers:** Developers look for behavior, states, properties, and snippets. Component pages usually include a table of properties with a name, type, default value, and description for each one.
- **Content writers:** Writers look for where text goes in a part and how long labels can be. Detailed label rules belong in the Writing Guidelines lesson, but the component page should link to them.

Documentation should also live in one trusted place. The design system team calls this the source of truth. Designrush advises teams to structure a system like a toolkit rather than an encyclopedia, so each page is quick to use. Teams often choose a dedicated documentation site, and some keep a live, rendered version of each part there. Figma also lets teams place component descriptions inside design files, so a designer sees the rule while working.

> **Tip:** Make the pages easy to search. Give each part one canonical name, the agreed official name, and use that name in every page, file, and chat. If one button has three names, a search will miss two of the pages.

## How Do You Keep Documentation Useful Over Time?

Documentation goes stale when the system changes and the pages do not. Out-of-date pages cause inconsistent designs, which then reduces trust in the whole system. Keeping pages current needs three habits: clear ownership, version history, and updates with every change.

### Clear ownership

Every page needs a named owner. Magic Patterns says that if the answer to who updates the docs is no one in particular, or the whole team, the team has a basic problem to solve first. An owner does not write every page alone. The owner makes sure someone checks each page when its part changes.

### Version history and changelogs

A version tells readers which release of the system a page describes. DaaSign warns that without clear versioning, readers cannot tell whether the page matches the current version. A changelog is a dated list of what changed, including new features, fixes, and breaking changes. Figma's guidance adds that a breaking change should come with migration steps, which tell readers how to move their work to the new version.

### Why Update the Docs with Every Change?

The safest habit is to treat documentation as part of the change itself. Designrush advises teams to include documentation updates in the component release process. Figma's guidance goes further: make documentation a required step before a new component or pattern is considered finished. UXPin also suggests a log of recent updates on the site, so readers can see what is new.

> **Tip:** Before you close a design change, ask three questions: Did the variant list change? Did the do's and don'ts change? Did the changelog get a new line? If any answer is yes and the page is not updated, the change is not finished.

## Common Mistakes to Avoid

- **Listing parts without rules:** A page with pictures but no guidance forces readers to guess when to use each part. Add the guidance, even if it is short.
- **Skipping accessibility:** A page that omits keyboard use, screen reader behavior, and contrast leaves those needs to chance. Every component page needs them.
- **Keeping copies in many places:** A PDF in a shared folder becomes wrong the day the system changes. Link to the one trusted page instead of copying it.
- **No version or date:** A reader who cannot tell which version a page describes may build against old rules.

## Check Your Understanding: An Old Copy

A designer saves the Button page as a PDF in a team folder. Six months later the primary button changes its states, but the PDF is never updated. A teammate builds a screen from the old file. Choose the best fix.

**Quick check:** Which practice would have stopped this problem?

A. Adding more pictures to the PDF so readers can compare the states by eye.
B. Keeping one live page on the documentation site with a version and a changelog, and linking to it instead of copying it.
C. Asking the designer to send the latest PDF by chat whenever someone starts a new screen.
D. Printing the PDF every month and placing copies in each team folder.

**Answer:** B. A single live page with a version and a dated changelog gives everyone the same current answer, and readers can see when it changed. More pictures, chat requests, and printed copies all still rely on people remembering to update a copy, which is how stale pages happen.

## Putting It Together

Documentation is the written home of a design system. It gives each part a plain purpose, shows variants and states, explains do's and don'ts, records specs and accessibility needs, and links to a live example or snippet. It serves designers, developers, and writers, so it should be easy to search and kept in one trusted place. It stays useful only when each page has an owner, a version, and an update with every change.

Next time you open a design system page, read it with the checklist from this lesson. If a page lacks a rule that a new team member would need, write that down. Gaps are the best place to begin a contribution.

## Sources

- [Buttons, Material Design 3 guidelines](https://m3.material.io/components/buttons/guidelines)
- [Buttons, Material Design 2 guidelines (touch target size)](https://m2.material.io/go/design-buttons/)
- [Icon buttons, Material Design 3 guidelines](https://m3.material.io/components/icon-buttons/guidelines)
- [Atlassian Design System, Link button examples](https://atlassian.design/components/button/link-button/examples)
- [Atlassian Design System, Develop overview](https://atlassian.design/get-started/develop/atlassians)
- [Atlaskit, Button package](https://atlaskit.atlassian.com/packages/design-system/button)
- [Atlassian Design System, Design tokens examples](https://atlassian.design/components/tokens/examples)
- [Atlassian Forge UI Kit, Button component](https://developer.atlassian.com/platform/forge/ui-kit/components/button/)
- [Atlassian AUI, Buttons documentation](https://aui.atlassian.com/aui/8.0/docs/buttons.html)
- [Figma blog, Design system 103: Documentation that drives adoption](https://www.figma.com/blog/design-systems-103-documentation-that-drives-adoption/)
- [Storybook blog, How to document your design system](https://storybook.js.org/blog/how-to-document-your-design-system-best-practices-tools/)
- [Magic Patterns, Documenting your design system: best practices](https://www.magicpatterns.com/blog/design-system-documentation)
- [UXPin, 9 steps to document your design system](https://www.uxpin.com/studio/blog/design-system-documentation-guide/)
- [UXPin, Ultimate guide to component documentation](https://www.uxpin.com/studio/blog/ultimate-guide-to-component-documentation/)
- [Dom Studio, Guide to design system documentation](https://getdom.studio/blog/design-system-documentation)
- [DaaSign, Design system documentation](https://www.daasign.io/topics/design-system-documentation)
- [DaaSign, What should be included in design system documentation](https://www.daasign.io/answers/what-should-be-included-in-design-system-documentation)
- [DesignRush, Design system documentation: a practical guide](https://www.designrush.com/best-designs/print/trends/design-system-documentation)
