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.

Button: One Reusable Control for Actions That Is Clear and Accessible

Learn how a design system defines a button once, with variants, sizes, and states, and how to use it so every screen stays clear and usable.

In short

A button in a design system is one reusable control for actions, defined once with variants, sizes and states so every screen stays clear and usable.

14 min readFree

What you will learn

A button is the control a person presses to start an action, such as saving a form, sending a message, or paying for an order. In a design system, the button is not drawn fresh on each screen. A team defines it once, with a clear set of options, and every product screen reuses that one definition. This lesson shows what a system decides about a button, how to choose the right type for each action, and how to make the button work for everyone.

Key words

Button
A control that a person presses to start an action on a page or in a form.
Action
The thing that happens after a press, such as saving a file or deleting an item.
Variant
A named style of the same button, such as primary or destructive, that shows how important its action is.
State
The look a button has at one moment, such as when it is hovered, focused, or unavailable.
Focus
The visible mark that shows which control a keyboard user has currently selected.
Touch target
The area a finger or pointer can hit to press a control.
Props
The settings a builder passes to a shared component, such as its variant or size.
Token
A named design decision, such as one brand blue, saved once and reused everywhere.
Contrast
How different the brightness of text is from the background behind it.

What is a button in a design system?

Primer, the design system GitHub uses, describes its button as the control for starting actions on a page or in a form. A button is a building block, not just a rectangle with words in it. The system decides how it looks, how it behaves, and how it is named, so that a team does not have to invent those things again for each new screen.

  • Defined once

    The button has one official design with agreed options. Teams pick from those options instead of creating new looks.

  • Documented

    Written rules say when to use each type, how to word the label, and what to do in every state.

  • Reused

    Product teams take the same button from the shared library, so people see the same behavior across the whole product.

The benefit is consistency. When one blue button means 'do this now' on every screen, people learn it once and trust it everywhere. When each team builds its own version, the same action can look and behave differently from one page to the next.

What anatomy and options does a system define?

A button has a few parts: a container (the fill and border), a label (the words), and optional icons placed before or after the words. A design system does not leave these parts open. It fixes a short list of options for each part and names them. Those names are what designers and builders use when they talk about the button.

What are variants and how strong should an action look?

Variants show how important an action is compared with the other actions on the same screen. Most systems use a small set. Designers often describe four common ones, though names differ between systems.

  • Primary

    The strongest style, used for the main action of a view. Primer calls it the highest-priority action and advises using it sparingly.

  • Secondary

    A quieter style for supporting actions. Primer's default button is the same idea as a secondary button in other systems, and Primer says it is the most common type.

  • Tertiary

    The lowest-emphasis style, often a text-only button for less important actions.

  • Destructive

    A warning style for actions that remove or cancel something. Its job is to make people pause before pressing.

Material Design uses a similar ladder. A system should not create a new variant for every brand color.

Tip

Before you add a variant, ask whether the problem is the button or the screen. If the screen has five strong actions, no new button style will fix it.

What sizes should a button come in?

Sizes change the height and text size of a button. Some systems keep several sizes. Others keep one. People had been picking small sizes because they looked neat, not because they were easy to press.

The lesson for a new designer is simple. Name a short, fixed list of sizes, write down when each one is used, and check that even the smallest one is still big enough to press.

What states does a button have at each moment?

A state is the look and behavior of a button at one moment. A complete system defines each state so builders never guess. The six states below are the ones this lesson uses.

  • Default

    The normal look before anyone touches the button.

  • Hover

    The look when a mouse or pointer rests on the button. Primer's guidance says buttons need a hover state for pointer users.

  • Focus

    The visible outline shown when a keyboard user reaches the button. It must stay on screen and must not be removed.

  • Pressed

    The brief look while the button is being pressed or activated, so people can see that their press registered.

  • Disabled or inactive

    The muted look for a button that cannot act right now. Primer treats an inactive button as a muted style that still responds, which matters for the disabled and loading rules later in this lesson.

  • Loading

    The look while the action is running. The button shows a progress mark inside its own shape, so people know the press worked.

The designer does not draw the spinner or progress visual here. That is a separate job. The button's job is to keep its shape, keep its label, and tell people clearly what is happening.

How options are exposed: props and tokens

The options from the sections above are not left to memory. They are exposed as props, which are the settings a builder chooses when placing the shared component. Its documentation also lists a loading setting and an inactive setting.

Tokens sit underneath. A token is a named value, such as a brand blue or a border width. The button uses tokens for its colors and spacing, so changing one token updates every button that uses it. Designers should name the choice they want, such as 'primary fill', and not a raw color. The Token lesson in this course explains that idea in more depth.

Tip

When you write a button spec, list each variant, size, and state by its agreed name. Those names should match the props and tokens your builders use, so the spec and the product say the same thing.

Usage rules for teams

Once the parts are named, the system needs rules for using them. Good rules answer three questions: which control fits this job, what words go on it, and how many strong buttons can share one view.

Label with clear verbs

The label is the promise. Primer's accessibility guidance says a button's purpose should be clear from its name alone. A good name describes the action and, when needed, the item it acts on. Keep it short. Primer's brand guidance asks for succinct labels with no line breaks, because a broken label stops looking like a button.

Use a verb that says what happens. 'Save changes' tells people more than 'OK'. 'Delete draft' tells people more than 'Yes'. Primer also says that when buttons perform the same function, they should use the same label everywhere, so people learn one name for one job.

Tip

Read each label aloud on its own. If it still makes sense without the screen around it, it is clear enough for a screen reader user, who often hears a list of all the buttons on a page.

One primary button per view

Hierarchy means the most important action looks most important. Primer advises limiting each view to just one primary button, and placing it in the visible part of the layout. When every button is strong, none of them stands out.

Other styles carry the rest of the load. Primer notes that secondary buttons can sit beside a primary button for a secondary action.

Quick check

A checkout screen shows three equally styled bright blue buttons: 'Pay now', 'Save for later', and 'Cancel order'. Which set of variants helps shoppers most?

Accessible, reliable behavior

A button is only useful if everyone can find it, understand it, and press it. Accessibility is part of the button's design, not an extra step added at the end. Primer says that every button needs three things: the right element, a look that signals it can be pressed, and a meaningful name.

Use the native button element

Primer's guidance is to use the built-in button element wherever possible. Browsers and assistive technology already know what a built-in button is and how it behaves. A look-alike that is not a real button can be skipped by a screen reader, or fail to respond to a keyboard. For a designer, the rule means you should specify a real button, not a styled box that someone may build as a shape.

Visible focus, contrast, and touch size

Three visual rules protect people with low vision, motor differences, or keyboard-only use. Each one should be written into the button's spec.

  • Visible focus

    Primer says its button focus styles must not be removed.

  • Text contrast

    Primer asks designers to check that button text meets the WCAG 1.4.3 contrast rule against the button's own background.

  • Touch target

    Medium and large buttons usually meet the minimum, but a small one may not when its label is very narrow.

Tip

Do not rely on color alone. Primer warns that a 'danger' or 'primary' look is invisible to screen readers, so the label must say what the button does.

Disabled, inactive, and loading states

Two states can confuse people if they are designed badly: a button that cannot be used right now, and a button that is busy. Primer uses an inactive state for the first case. An inactive button looks muted, but it still accepts the same presses as an enabled button.

The loading state covers a press that takes time. Keep the label and the shape, so the person still knows what is being done. Primer's documentation also links to separate accessibility details for the loading state. Designing the spinner itself belongs to another lesson.

Quick check

A payment service is down. The 'Pay now' button should look muted, but when someone presses it, the screen should explain why. Which state fits?

Worked example: a pull request form

This example uses GitHub's Primer design system. A pull request is a request to merge one set of code changes into another. The form ends with two buttons: 'Create pull request' and 'Cancel'. This walk-through is a teaching model built on Primer's published rules. It is not a claim about how GitHub's live screen is drawn at every moment.

  1. 1

    Name the main job

    Decide which action is the one step the person came to finish. Here it is 'Create pull request'. Primer says each view should have one primary button, placed where it is visible, so this label gets the primary style.

  2. 2

    Give Cancel a supporting style

    'Cancel' ends the form without a change, so it is a supporting action. Primer describes a default button as the common secondary type, and says secondary buttons can sit beside a primary one. It stays visible but never competes with the main action.

  3. 3

    Check the default and hover looks

    In the default state, the primary button has a strong fill and the default button has a lighter look, so the hierarchy reads at a glance. On hover, each button shows its own hover look, so a mouse user sees that the control responds.

  4. 4

    Check focus for keyboard users

    A keyboard user moves to each button in turn. The focus outline must be visible on each one, and it must not be removed. Without it, a person cannot tell where they are on the form.

  5. 5

    Handle the busy and unavailable states

    While the request is being created, 'Create pull request' shows a loading state inside the same shape, and keeps its label so people still know what is happening. If the form cannot be sent yet, the primary button can use the inactive look, which stays responsive and can explain what is missing.

  6. 6

    Read the rules that justify each choice

    Primer says to use the primary style sparingly and the default style most of the time. The same rules explain why 'Cancel' does not get the strongest look and why 'Create pull request' is not repeated elsewhere on the same view.

Mistakes to avoid

  • Too many strong buttons

    When every action is primary, people cannot see which step matters. Give one button the lead and let the others step back.

  • Vague labels

    Words such as 'OK' or 'Submit' leave people guessing. Name the real action, such as 'Save changes'.

  • Removing focus

    Hiding the focus outline to make a design look cleaner blocks keyboard users. Keep a visible focus style in every variant.

  • Using color as the only clue

    Red can mean danger to some people, but not to all. Pair the destructive look with a clear label.

  • Using a look-alike instead of a button

    A styled box that is not a real button may be skipped by assistive technology. Specify the real button element.

Key takeaways

A button in a design system is a shared, documented building block. It has named variants for importance, a short list of sizes, and defined states. Teams use it through props and tokens, not by inventing new looks. Good use means choosing a button only for actions, not navigation, giving each view one primary button, and naming every action with a clear verb.

Good behavior matters as much as good looks. Use the native button element, keep focus visible, meet contrast and touch-size rules, and design the disabled and loading states so people can always tell what is happening.

Tip

Next time you open a screen, count its strong buttons. If there is more than one, decide which action matters most and give only that action the primary style.

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.