esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

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.

13 min readFree

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.

Key words

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. 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. 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. 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. 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. 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. 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?

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?

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

How is this lesson?

Last updated on 17 November 2026

Learn with me

Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.