In a design system's documentation, what makes a component's usage guideline useful, and why pair each do with a don't and a reason?
answer
- misuse, not bugs, erodes consistency
- when to use, and when not
- every don't names a detour
- the boundary needs a counter-example
- the reason covers unlisted cases
basics
~20 sA useful usage guideline says when to use a component, when not to and what to use instead. Pairing each do with a don't and a stated reason shows the boundary and lets readers judge cases the page never listed.
solid answer
~50 sA usage guideline answers a decision, not a description: **when to use** the component, **when not to use it and what to use instead**, and how to use it well. A correct example alone shows one point inside the boundary; placing the wrong version beside it, drawn from a realistic screen and changed in one respect, makes the boundary visible. The **reason** is the most important part. 'Don't give a vehicle card three primary actions' is a rule teams argue with; adding 'because the renter can no longer see which action books the car' turns it into a principle they can apply to cases the page never covered. Good guidance is short, specific, phrased in user situations that designers and engineers both act on, and every 'when not to' links to the component that fits instead.
go deeper
Recall the three parts — when to use, when not to use with the alternative, how to use well — and that each do sits beside a don't with a stated reason.
Explain why a boundary needs a counter-example to be visible, and why a stated user consequence lets teams apply a rule to cases the page never listed.
Show how you source pairs from real misuses found in reviews and support, keep each pair minimal and realistic, and prune pairs nobody gets wrong any more.
Frame guidance as the cheapest consistency lever a system has, and weigh which rules deserve prose and a reason against which deserve an automated check.
## What a usage guideline is for A **design system** is a shared set of reusable parts — design tokens, components, patterns and the guidance around them — that many product teams consume. A **usage guideline** is the part of a component's documentation that answers *should I use this here?* rather than *how is it built?* Anatomy, properties and code examples tell a team what a component is; usage guidance tells them whether it is the right choice for the problem in front of them. This matters because the most common way a system loses consistency is not a bug in a component but a correct component used for the wrong job: a disappearing message carrying a problem the user must fix, a card used as a button, a warning style used for marketing. Each of these renders perfectly and still teaches users that the same visual means different things on different screens. ## The three questions a guideline answers | Section | Answers | Example on a car-rental site | |---|---|---| | **When to use** | The situations the component was designed for | A vehicle card: one car in a list of results the renter compares | | **When not to use** | Tempting misuses, each with the alternative | Not for a single booking summary — use the summary panel | | **How to use well** | Rules that keep correct uses consistent | One primary action per card; price always in the same place | The **when not to** section carries most of the value, because it is the part a reader cannot infer from the component itself. Each entry should name the alternative, so the reader leaves with a decision rather than a bare prohibition. ## Why a do needs a don't A correct example on its own shows one point inside the boundary; it does not show where the boundary is. A **do / don't pair** puts a correct and an incorrect version side by side — ideally the same screen changed in one respect — so the difference is the lesson: - **Do:** a results card with the car's name, daily price and a single 'Select' action. - **Don't:** the same card with 'Select', 'Compare' and 'Add cover' all styled as primary actions. - **Because:** when three actions share the strongest style, the renter can no longer see which one moves the booking forward. Keep pairs **minimal** (change one thing, so the reader knows which thing is wrong), **realistic** (drawn from the product's own screens, not placeholder text) and **marked by more than colour** — a 'Do' / 'Don't' label and an icon as well as green and red — so the page reads for people who cannot tell the colours apart and in a screen reader. ## Why the reason matters most A rule without a reason fails twice. Teams argue with it ('our case is different') and the page has nothing to argue back with; and teams cannot extend it to the case the page never listed. A reason turns a rule into a principle. A useful formula: 1. State the rule in one line. 2. State the **user consequence** of breaking it — what the person on the screen loses. 3. Where it helps, state the **system consequence** — what breaks for other teams, such as a style that stops meaning 'warning'. A reason also makes the guideline **reviewable**: if the reason turns out to be wrong, the rule can be changed deliberately instead of being quietly ignored. ## Writing for designers and engineers at once The same page is read by a designer picking a component in a design editor and an engineer picking one in code, on the web or on native mobile. Guidance works for both when it is phrased in terms of **user situations and outcomes** ('the renter must act before continuing') rather than one discipline's tools. Use the same variant names on both sides, place visual examples next to the equivalent code usage, and avoid rules only one audience can check, such as a raw pixel value with no token name. ## Common failure modes - Guidance that lists only dos — it reads as marketing for the component. - A don't with no alternative — teams comply by building something custom. - Absolutes where the system actually allows exceptions — teams stop trusting the page. - Examples too abstract to match real screens — readers cannot map them to their work. - Guidance that lives far from where the choice is made — correct, and unread. A practical test: show someone new a real screen and the guideline, and ask whether the component is used correctly. If they can answer and say why, the guideline works.
- How many do / don't pairs should a component's usage guidance carry?As many as there are real, recurring misuses — usually a handful, not dozens. Each pair should earn its place by addressing a mistake teams actually make, found in design reviews, code reviews, support questions or audits. A long list of hypothetical don'ts buries the important ones, so prune pairs nobody gets wrong any more and add a pair when a new misuse starts to spread.
- What should a usage guideline do when the system genuinely allows an exception to a rule?Name the exception and the condition under which it applies. A rule stated as an absolute that teams routinely and legitimately break teaches them the page is not to be trusted. A written condition turns 'our case is different' from an argument into a check anyone can make, and it gives the system team a place to tighten or remove the exception later.
A good usage guideline is like a road sign reading 'No lorries — low bridge ahead — use the bypass': the rule, the reason and the detour. Drop the reason and drivers argue with it; drop the detour and they improvise their own route.
saying these in an interview costs you the question
- Showing only correct examples is enough; don'ts just add negativity.
- A don't needs no reason — the system team decided, so teams comply.
- Usage guidance is the same thing as the component's property table.
- A don't is complete without naming what to use instead.
- Green and red colouring alone is enough to mark do and don't examples.