# Usage Guidance: Teaching Designers When to Use a Part, and When Not To

> Usage guidance turns a library of parts into clear choices, so teammates make consistent decisions without asking the system's authors.

**In short:** Usage guidance turns a library of parts into clear choices about when to use a part and when not to, so teammates decide consistently without asking the authors.

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

## What You Will Learn

A design system is a shared set of parts, such as buttons, text fields, and colors, plus the rules for using them. Parts alone do not stop mistakes. A new designer may pick the wrong button, and a busy team may use a loud message where a quiet note would do. This lesson is about usage guidance. It is the part of a design system's documentation that tells people when to use a component or style, and when not to.

By the end, you will be able to explain the Do and Don't pattern, write a rule that someone can act on, and decide where guidance should live and how to keep it current.

- **Design system:** A shared set of reusable parts and the rules for using them, so a team builds products in a consistent way.
- **Component:** One reusable piece of an interface, such as a button, a checkbox, or a message box.
- **Documentation:** The written and visual pages that explain how a design system works and how to use it.
- **Usage guidance:** Written advice on when and why to use a component or style, and when not to use it.
- **Primary button:** The filled button that marks the main action on a screen.
- **Secondary button:** A quieter button for supporting actions that help the main task but do not finish it.
- **Alternative:** Another component that fits a situation better than the one being described.

## What Is Usage Guidance?

A library of parts without guidance is like a toolbox with no labels. People can see the tools, but they guess which one to pick. Usage guidance answers one question: which part should I use here? For each component, it gives three kinds of help.

- **Purpose:** One or two plain sentences that say what the component is for.
- **Fit:** The situations where this component is the right choice, written as concrete cases.
- **Better choice:** The situations where another component works better, with a link to that component.

Good guidance lets a new designer make a sound choice without asking anyone. One documentation guide describes the goal as detail enough that a new designer can use a component correctly without asking questions. That is the standard to aim for.

Why does this matter? A design system only helps when people use its parts the way its authors meant. Weak or missing guidance leads to misuse, quick workarounds, and sometimes a second, unofficial system that grows next to the official one.

## The Do and Don't Pattern

The most common format for usage guidance is a pair of lists: what to do, and what not to do. Many systems label these 'when to use' and 'when not to use'. The DSDS documentation spec, a public schema for design system docs, shows the same idea in a button entry. It says to use a button for an action that happens in place, like saving a form, and to avoid it for navigation, because a link tells people they are going somewhere else.

Here is a simple method for writing one component's entry. Follow the steps in order.

1. **Write the purpose:** Use one sentence that says what the component does. For a button: it triggers an action on the current screen.
2. **List the fit:** Name two or three concrete situations. For example, saving a form in place, or confirming a change the person just made.
3. **List the don'ts:** Name the situations where the component is wrong. Be specific. Avoid vague lines like 'use with care'.
4. **Name the better choice:** For each don't, point to the component that fits that case, and link to it.
5. **Show a right and a wrong example:** Place them side by side so a reader can compare them at a glance.

The Do and Don't pattern works because it covers both sides of a decision. A reader who only sees the 'do' side can still pick the wrong part when a case falls in between.

Some systems also explain the limit of a rule. In a web tool with several visible panels, more than one primary button can be fine, as long as each panel has one.

Lesson note: the exact list of do and don't items is different for each component. This lesson shows the pattern only. The specs and anatomy of each component are covered in their own lessons.

### Why Does the Don't Side Matter?

Teams often write only the 'do' side, because it feels more helpful. But the common mistakes live on the 'don't' side. It also gives a clear pair. A destructive confirmation dialog fits when a person is about to delete data permanently.

> **Tip:** Ask a teammate to find a screen where a component is misused. If you cannot write a don't for it, your guidance is probably too vague. Write the mistake down, then write the better choice next to it.

## How Do You Write Guidance You Can Act On?

Guidance fails when it is vague. Advice such as 'use sparingly' or 'use when appropriate' leaves every reader to guess. A rule works when a reader can look at a screen and say whether it follows the rule. Three habits help.

- **Short and concrete:** Name the situation. Weak: 'Use buttons carefully.' Strong: 'Use one primary button per screen, for the main action.'
- **Show right and wrong:** A pair of examples says more than a long paragraph. One guide on documenting systems makes this point directly, calling a visual pair more useful than a page of rules.
- **Plain words:** Say 'the main action' instead of 'the dominant call to action'. If a technical term is needed, explain it the first time it appears.

Be clear about how firm each rule is. The DSDS spec uses levels such as must, should, and should-not. Labeling the level stops every rule from sounding equally strict.

> **Tip:** Test each rule with one question. Could a new teammate look at a screen and decide, with no help, whether it follows the rule? If the answer is no, rewrite the rule until it is yes or no.

### How Do You Turn a Rule Into a Visual Pair?

A visual pair works best when only one thing differs between the two sides. Use the same screen and the same words on both sides. Change only the element that breaks the rule. Then add a short caption to each side, such as 'Right: one primary action' and 'Wrong: three primary actions competing'. The caption should state the reason in a few words. Storybook's guidance on documentation recommends paired examples of correct and incorrect use, ideally visual and side by side, for the same reason.

## Where Does Guidance Live and How Does It Stay Useful?

Guidance does no good if people cannot find it while they work. Place it on the component's own page, next to its examples and its design or code files. Storybook's documentation advice aims for a reader who can answer 'how do I use this right now' within about a minute. That goal shapes where the guidance should sit.

- **Next to the component:** Put usage guidance on the component page itself, not in a separate handbook that people must search for.
- **Linked to alternatives:** Each 'when not to use' line should link to the better component. The DSDS spec shows this with a dialog entry that points to a popover as an alternative.
- **Reachable from the design tool:** Good documentation is organized, searchable, and linked from the design tool, so a designer can reach it from the file they are working in.

### How Do You Keep Guidance Up to Date?

Usage guidance is a living part of the system. It should change when people change how they use the parts. Use these steps to keep it useful.

1. **Watch for misuse:** When reviewers find the same wrong use again and again, the guidance is missing a don't or a clearer example.
2. **Track repeated questions:** If the same question reaches the system team more than once, answer it in the guidance itself, with a short line or a visual pair.
3. **Change the rule, then tell people:** Update the written rule first, then tell the teammates who use the part what changed and why.
4. **Remove what no longer fits:** When a part is replaced, update the alternative links on the old page, so nobody follows a dead end.

A common warning is against treating a design system as a finished project instead of a living one. The answer to the update question is simple: documentation should change as often as the system changes.

## Worked Example: A Checkout Screen

Here is a real kind of screen to test the ideas on: a checkout page in a shopping app. The main job is to pay. The page also offers 'Edit cart', a coupon field, and a link to help. The usage guidance for a primary Button says to use only one per view for the main action, such as 'Pay now'. Other actions use a secondary style.

1. **Read the purpose:** The button triggers an action on the current screen. The primary style is for the main action that finishes the task.
2. **Apply the one-primary rule:** 'Pay now' is the main action, so it gets the one filled primary button on the page.
3. **Give supporting actions a secondary style:** 'Edit cart' helps the person but does not finish the purchase, so it uses a secondary button. Secondary buttons are lower-emphasis buttons for the other calls to action on the page.
4. **Check the wrong example:** The guidance also shows a wrong version with three competing primary buttons: 'Pay now', 'Apply coupon', and 'Save for later', all filled. Nothing tells the eye where to go first, and the person has to think about which one matters most.
5. **Fix the wrong version:** Keep 'Pay now' as the one primary button. Make 'Apply coupon' and 'Save for later' secondary. Keep help as a link, because it takes the person to another page.
6. **Check the full entry:** The guidance now names the purpose, the right example, the wrong example, and a better choice for the help link. A teammate can use it without asking the authors.

> **Tip:** When you are unsure which action is the main one, ask what the person most likely wants to do next on this screen. That action is the usual candidate for the primary style.

## Common Mistakes When Writing Guidance

- **Everything looks important:** When every action uses the primary style, none of them stands out. Use the hierarchy to show which action matters most.
- **Description in place of guidance:** A line like 'a button is a clickable element' tells a reader what the part is, not when to use it.
- **No alternatives:** When the page never names the better choice, people invent their own solution. Name the alternative and link to it.

## Quick Check

Answer these two short scenarios. Each one needs the ideas from this lesson.

**Quick check:** A teammate designs an editor screen. Users must choose between 'Save draft' and 'Publish'. The teammate wants both to be primary buttons so that neither is missed. Using usage guidance for buttons, what should they do?

A. Make both buttons primary, so neither is missed, and let people choose.
B. Make 'Publish' the primary button, make 'Save draft' a secondary button, and label each with its action.
C. Make 'Save draft' primary because it is safer, and turn 'Publish' into a text link.
D. Make both buttons secondary so the screen looks calm, and add a note that explains which to press.

**Answer:** B. The guidance asks for one primary button per view, for the main action. Secondary buttons are lower-emphasis buttons for the other actions on the view. Clear labels such as 'Save draft' and 'Publish' also tell people what each action does.

**Quick check:** On a settings page, a teammate adds a button whose only job is to send people to the help center on another page. Which choice follows the usage guidance?

A. Use a secondary button, since help is a supporting task.
B. Use a primary button, so the help option is easy to find.
C. Use a link, since the action takes people to another page, and avoid a button for navigation.
D. Use a button with no label, so the page stays tidy.

**Answer:** C. A button is for an action that happens on the current screen. Navigation belongs to a link, and the guidance should name that choice as the better one.

## Key Takeaways

- **Guidance turns parts into decisions:** Each component needs a purpose, the situations where it fits, and the situations where another part is better.
- **Write rules a reader can check:** Use short, concrete lines, label how firm each rule is, and show right and wrong examples side by side.
- **Keep it where people work:** Place guidance on the component page, link alternatives, and update the rules when misuse or repeated questions show a gap.

## Sources

- [Carbon Design System: Button guidelines](https://www.carbondesignsystem.com/building-blocks/core/components/button/guidelines)
- [Design System Doc Spec (DSDS) 0.23.1](https://designsystemdocspec.org/)
- [ServiceNow Horizon Design System: Button](https://horizon.servicenow.com/workspace/components/now-button)
- [Uber Base Design System: Button](https://base.uber.com/6d2425e9f/p/756216-button/b/336373)
- [Magic Patterns: Documenting Your Design System, Best Practices](https://www.magicpatterns.com/blog/design-system-documentation)
- [Storybook: How to document your design system, best practices and tools](https://storybook.js.org/blog/how-to-document-your-design-system-best-practices-tools/)
- [UXR: UX Design System Documentation, What It Is and How to Create It](https://uxr.cl/en/learn/deliverables/design-system-documentation/)
- [JobCannon: Design System Documentation](https://jobcannon.io/skills/design-system-documentation)
- [WP Dean: Design System Documentation, What to Include](https://wpdean.com/design-system-documentation/)
- [DesignRush: Design System Documentation, A Practical Guide for Teams](https://www.designrush.com/best-designs/print/trends/design-system-documentation)
- [Nathan Curtis: Component Design Guidelines](https://nathanacurtis.substack.com/p/component-design-guidelines-eca706100e7c)
