# Guidelines: The Written Rules That Keep Design System Parts Used Well

> Learn what guidelines are, how to write useful ones, and how a real button guideline turns a shared part into consistent choices.

**In short:** Guidelines are the written rules that explain a design system part, telling readers what it is for, what it should not be used for, and what to do in unusual cases.

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

## What You Will Learn

A design system is a shared set of parts, such as buttons, colours, and text styles, that a team uses to build products. Parts alone are not enough. People also need to know when to use each part, why it exists, and where its limits are. The written rules that answer those questions are called guidelines.

In this lesson you will learn what a guideline contains, what makes one useful, which topics good guidelines usually cover, and how to keep them easy to find and up to date. You will also walk through a real button guideline from Google's Material Design and from Atlassian's design system.

- **Guideline:** A written rule or piece of advice that explains how and when to use a part of a design system.
- **Design system:** A shared collection of parts and rules that a team uses to make its products look and work consistently.
- **Component:** One reusable part of a screen, such as a button, a text field, or a menu.
- **Emphasis:** How strongly a part draws the eye. A high-emphasis button looks more important than a low-emphasis one.
- **Do and don't:** A pair of examples. The 'do' shows correct use and the 'don't' shows a common mistake.
- **Accessibility:** Making a product usable by people with disabilities, such as people who are blind, have low vision, or use only a keyboard.

## What Is a Guideline?

A part in a design system can be seen. A guideline explains the part. It tells the reader what the part is for, what it should not be used for, and what to do in unusual cases. One writer describes usage guidelines as the operational manual for a design system. They say what is acceptable, what is not, and what to do at the edges.

Without guidelines, people make their own guesses. Developers make assumptions about behaviour. Writers guess at tone. Other designers reuse a part in the wrong place. A guideline closes these gaps so that different people reach similar choices without asking the original authors each time.

> **Tip:** A guideline is not the same as a picture of a part. A screenshot of a red button shows how it looks. A guideline says when a red button is the right choice, and when it is not.

- **Visual look:** What the part looks like. This is useful, but it is only the start.
- **Usage rules:** When to use the part, where it belongs on a screen, and how many of it are allowed.
- **Reasoning:** The why behind the rule. Knowing the reason helps people apply the rule to new cases the guideline did not mention.

Many good guidelines also list dos and don'ts. Guidance from one design-system writer suggests that each component should have best practices, including dos and don'ts, and that the rules should come with live examples. Another guide suggests a simple format: say what the part is, where it is used, and what to avoid.

The most useful part of a guideline is often the reason. A rule without a reason gets broken when someone is in a hurry. A rule with a reason helps the reader decide what to do when the screen is new.

Google's Material Design guidance is a good example of this. Its button pages describe the emphasis level of each button type. They also explain how buttons relate to other controls on the same screen. Atlassian's button guidance does the same for its primary and default buttons.

> **Tip:** When you read a guideline, ask two questions. What should I do? Why does this rule exist? If you can answer the second, you can apply the rule to a case the guideline never mentioned.

## The When, Why, and How

A strong guideline answers three questions for each part. These questions are the core of the topic, and most good guidelines follow them whether or not they use these exact headings.

- **When:** The situations where the part fits. For example, a button for the main action of a form is different from a button for a minor action in a toolbar.
- **Why:** The purpose behind the rule. For example, a rule may exist to keep one clear next step on a page, so people do not have to choose between many strong options.
- **How:** The way to use the part correctly, including its placement, its label, its size, and its states, such as default, hover, or disabled.

A guideline that only covers how a part looks will leave most decisions open. A guideline that covers the when and why gives the reader enough to make a choice that fits the goal of the screen.

Material's guidance on icon buttons shows the when clearly. The first line is the when, and the second line is the how and why of keeping a screen calm.

> **Tip:** If a guideline only shows a picture and says 'use this,' it is incomplete. Look for the when, the why, and the how before you trust it.

## What Makes a Guideline Good?

Good guidelines are easy to apply. A reader should be able to look at a screen, read the guideline, and make the right choice without writing to the team that made the system. Three qualities help with this.

- **Specific:** The rule names the exact situation. 'Don't misuse the logo' is too vague. A better rule names the misuse, such as stretching the logo or placing it on a busy photo.
- **Actionable:** The reader knows what to do next. A rule should say 'use the default button for most actions' rather than only saying 'be careful with buttons.'
- **Shown, not only told:** The guideline includes visual examples of correct and incorrect use. Pictures help people see the difference faster than long paragraphs do.

Show correct and incorrect use side by side. Guidance from one design-system writer describes paired examples of correct and incorrect usage, ideally visual and placed next to each other. Side-by-side pairs let a reader spot the difference in a few seconds.

Real systems do this in different ways. Other systems include live examples that show how a part behaves in different screens. The common idea is that the reader should see the rule working.

> **Tip:** Keep each guideline short. One guidance writer says to be as straightforward as possible and to avoid essays, because nobody reads long essays about a button.

Avoid guidelines that are only a list of forbidden acts. A list that says 'never do this' without showing what to do instead leaves the reader stuck. Pair each don't with a do, so the reader always has a next step.

## What Areas Do Good Guidelines Cover?

A guideline for one part should not stop at looks. Most good design-system guidelines also cover a few common areas. You do not need every area for every part, but you should check each one before you publish.

- **Usage:** When and where the part belongs, how many can appear, and which part to choose when two options seem close.
- **Accessibility:** How the part works for people who use screen readers, keyboards, or who need strong contrast. Contrast means how clearly text or an icon stands out from its background.
- **Behaviour and states:** What happens when someone uses the part, and how it looks in each state, such as default, hover, pressed, selected, loading, or disabled.
- **Content and tone:** What words the part should use, how long its label should be, and how it should sound. The full rules for writing are a separate topic, but each part's guideline should point to them.

Accessibility is easy to forget when a team is focused on looks. A screen reader is software that reads the screen aloud for people who cannot see it.

Behaviour and states matter for buttons too. Without a rule like this, a person may press the same button many times and trigger the action more than once.

Content rules help people know what will happen. Atlassian's button guidance says a button should let users know what will happen when it triggers an action. A label such as 'Delete file' tells the reader more than a vague label such as 'OK.'

## Worked Example: Button Guidelines

This example uses real button guidance from Google's Material Design 3 and Atlassian's design system. It shows how a team would use the guidelines to choose a button for one screen. The steps are a teaching walk-through. The rules come from the two sources.

1. **Find the main goal of the screen:** Start by asking what the one most important action is. On a form, this is usually the submit action.
2. **Choose the emphasis level:** Material describes a range of button types, from the filled style for high emphasis down to the text style for the lowest priority.
3. **Limit the primary buttons:** Atlassian's guidance says a primary button should appear only once per area, and that not every screen needs one. Primary buttons call attention to a form submission or the most important call to action on a page. If you have two bright buttons, the reader cannot tell which one matters most.
4. **Use a lower emphasis for other actions:** Atlassian says default buttons suit most actions that are not the main call to action, and that subtle buttons work well with a primary button for secondary actions. Use a lower emphasis for the rest.
5. **Write a clear label:** Atlassian's guidance is that a button should tell people what will happen. Use a short verb and a clear object, such as 'Save changes' or 'Send invoice.' The pages I read did not give a fixed character limit, so check the live guideline for any exact label rule before you publish one.
6. **Check the do and don't pair:** Compare the correct choice with the mistake. The do is one clear primary button with other actions in lower emphasis. The don't is three bright buttons that compete.

Material also explains how buttons should behave on different screen sizes. This is a rule about the how, and it keeps the layout readable on a laptop or a phone.

> **Tip:** The guideline does not tell you the exact right answer for every screen. It gives you the reasons. Use those reasons when the screen does not match an example.

## What Are the Reasons Behind the Button Choices?

The button example works because each rule has a reason. Knowing the reason helps you make a sound choice when the screen is new.

- **Emphasis guides attention:** A button that looks important tells the reader where to go next. When many buttons look equally important, the reader slows down and has to think.
- **Few strong choices keep a screen calm:** Too many raised buttons make the screen feel busy.
- **Same type for same role:** Mixing styles in a group can make selection and emphasis unclear.
- **Consistency helps trust:** When a team uses the same button for the same job across many screens, people learn what each style means. The next screen feels familiar.

Material also gives a clear example of a reason. The reason is that one option in a set should not look more important than the others by accident.

Guidelines should explain these reasons in plain language. A reader who understands the reason can make a good choice even when the component they need is not in the guideline.

## How Do You Keep Guidelines Findable?

A guideline helps only if people can find it and trust that it is current. A guideline that is hidden or out of date is almost as bad as having none. One guide puts it bluntly: an outdated design system is like having no design system.

- **Easy to find:** Put guidelines in one searchable place. One guide advises making the system searchable, and another suggests hosting guidelines with search and filters so that teams can locate a rule in seconds.
- **Easy to read:** Write in simple language, avoid jargon, and place visual examples before long text. Keep the page short enough that people will actually read it.
- **Up to date:** Update the guideline when the part changes, and tell the teams that use it. Some guides suggest adding the status of each component and the name of the person responsible for it.
- **Open to feedback:** Give contributors a way to suggest changes. Guidance from one source says a feedback loop matters because the needs of an organisation change and grow over time.

Teams often check guidelines during design reviews, when they start a new project, and when they write code. One design writer suggests bringing new documentation into design critiques, and checking whether a project needs a new component or an update to an existing one.

> **Tip:** Ask each new team member to find one guideline in the first week. If they cannot find it quickly, the guideline needs a better home or a clearer title.

Keep the guidelines specific to the parts they cover. Do not add a long history or a philosophy that nobody needs at the moment of choice. The reader wants the rule, the reason, and an example.

## Check Your Understanding

**Quick check:** A teammate adds three bright primary buttons to one screen because the component library allows it. Which guideline would have told them what to do instead, and what would it likely say?

A. The colour guideline, which says to use only brand colours on every screen.
B. The button emphasis guideline, which says one primary button per area and lower emphasis for other actions.
C. The icon guideline, which says all icons on a screen must be filled.
D. No guideline is needed, because the library already decides which buttons are allowed.

**Answer:** B. The problem is emphasis, not colour or icons. A button guideline would say that a primary button should appear only once per area, and that other actions should use default or subtle buttons. The library allowing something does not mean the team should use it.

Now consider a different case. A team adds a delete icon to each row of a table. The icon has no text, and some people using screen readers cannot tell what it does.

**Quick check:** Which guideline area should the team check first for the delete icon, and what would a good rule say?

A. Behaviour and states, which says the icon should be bigger than the row text.
B. Accessibility, which says an icon-only button needs a clear text description that a screen reader can read.
C. Content and tone, which says every icon must include a joke to make the screen friendlier.
D. Usage, which says delete icons should always be placed at the top of the page.

**Answer:** B. This case is about a person who cannot see the icon. The accessibility area of a guideline covers screen reader text. The other options either focus on size, add an unrelated rule, or move the icon for no stated reason.

Key takeaways

- **A guideline explains use:** It covers when and why to use a part, along with the how. Looks alone are not enough.
- **Good guidelines are specific:** They name the situation, say what to do, and show correct and incorrect examples side by side.
- **Cover the common areas:** Usage, accessibility, behaviour and states, and content should all be checked for each part.
- **Keep them findable and current:** A guideline nobody can find or trusts is of little use. Update it when the part changes.

## Sources

- [Material Design 3: Buttons guidelines](https://m3.material.io/components/buttons/guidelines)
- [Material Design 3: Button groups guidelines](https://m3.material.io/components/button-groups/guidelines)
- [Material Design 3: Icon buttons guidelines](https://m3.material.io/components/icon-buttons/guidelines)
- [Material Design 3: Extended FAB guidelines](https://m3.material.io/components/extended-fab/guidelines)
- [Material Design 3: Floating action buttons guidelines](https://m3.material.io/components/floating-action-button/guidelines)
- [Atlassian Design: Button examples](https://atlassian.design/components/button/examples)
- [Atlassian Design: Content design overview](https://atlassian.design/get-started/content-design)
- [Atlassian AUI documentation: Buttons](https://aui.atlassian.com/aui/latest/docs/buttons.html)
- [Neue: Writing Effective Usage Guidelines](https://www.neue.world/learn/design-system/writing-effective-usage-guidelines-the-importance-of-clear-guidelines-for-each-component-and-how-to-create-them)
- [Storybook: How to document your design system](https://storybook.js.org/blog/how-to-document-your-design-system-best-practices-tools/)
- [Adham Dannaway: How to build a design system](https://www.adhamdannaway.com/blog/design-systems/how-to-build-a-design-system)
- [The Design System Guide: Documentation](https://thedesignsystem.guide/documentation)
- [Smart Interface Design Patterns: Seven Fantastic Design Systems](https://smart-interface-design-patterns.com/articles/design-systems/)
