Buttons

Selecting styles

Buttons follow the color pairing rules used across the site. There are three defined styles for buttons: standard, call to action, and alternate.

  • Use button--standard for normal scenarios
  • Use button--cta when you need to drive attention specifically to an item or interaction
  • Use button--alt for less frequently used options or low-priority interactions so that they don’t distract from the content

When to use

  • Use buttons for the most important actions you want users to take on your site, such as “download,” “sign up,” or “log out.”

When to consider something else

  • If you want to lead users between pages of a website. Use links instead.
  • Less popular or less important actions may be visually styled as links.

Guidance from the U.S. Web Design System

  • Generally, use primary buttons for actions that go to the next step and use secondary buttons for actions that happen on the current page.
  • Style the button most users should click in a way that distinguishes from other buttons on the page. Try using the “large button” or the most visually distinct fill color.
  • Make sure buttons should look clickable—use color variations to distinguish static, hover and active states.
  • Avoid using too many buttons on a page.
  • Use sentence case for button labels.
  • Button labels should be as short as possible with “trigger words” that your users will recognize to clearly explain what will happen when the button is clicked (for example, “download,” “view” or “sign up”).
  • Make the first word of the button’s label a verb. For example, instead of “Complaint Filing” label the button “File a complaint.”
  • At times, consider adding an icon to signal specific actions (“download”, “open in a new window”, etc).

GitHub issues

<!-- Neutral -->
<div class="slab slab--neutral" style="padding: 1rem 2rem">
    <div>Standard:</div>
    <button class="button--standard" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--standard">Inactive button</button>
</div>
<div class="slab slab--neutral" style="padding: 1rem 2rem">
    <div>Call to action:</div>
    <button class="button--cta" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--cta">Inactive button</button>
</div>
<div class="slab slab--neutral" style="padding: 1rem 2rem">
    <div>Alternate:</div>
    <button class="button--alt" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--alt">Inactive button</button>
</div>

<!-- Primary -->
<div class="slab slab--primary" style="padding: 1rem 2rem">
    <div>Standard:</div>
    <button class="button--standard" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--standard">Inactive button</button>
</div>
<div class="slab slab--primary" style="padding: 1rem 2rem">
    <div>Call to action:</div>
    <button class="button--cta-primary" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--cta-primary">Inactive button</button>
</div>
<div class="slab slab--primary" style="padding: 1rem 2rem">
    <div>Alternate:</div>
    <button class="button--alt-primary" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--alt-primary">Inactive button</button>
</div>

<!-- Secondary -->
<div class="slab slab--secondary" style="padding: 1rem 2rem">
    <div>Standard:</div>
    <button class="button--standard" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--standard">Inactive button</button>
</div>
<div class="slab slab--secondary" style="padding: 1rem 2rem">
    <div>Call to action:</div>
    <button class="button--cta-secondary" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--cta-secondary">Inactive button</button>
</div>
<div class="slab slab--secondary" style="padding: 1rem 2rem">
    <div>Alternate:</div>
    <button class="button--alt-secondary" style="margin-right: 2rem">Basic button</button>
    <button class="is-disabled button--alt-secondary">Inactive button</button>
</div>

<div class="slab slab--{{modifier}}" style="padding: 1rem 2rem">
  <div>Standard:</div>
  <button class="button--standard" style="margin-right: 2rem">Basic button</button>
  <button class="is-disabled button--standard">Inactive button</button>
</div>
<div class="slab slab--{{modifier}}" style="padding: 1rem 2rem">
  <div>Call to action:</div>
  <button class="button--cta{{button}}" style="margin-right: 2rem">Basic button</button>
  <button class="is-disabled button--cta{{button}}">Inactive button</button>
</div>
<div class="slab slab--{{modifier}}" style="padding: 1rem 2rem">
  <div>Alternate:</div>
  <button class="button--alt{{button}}" style="margin-right: 2rem">Basic button</button>
  <button class="is-disabled button--alt{{button}}">Inactive button</button>
</div>
/* Neutral */
{
  "modifier": "neutral",
  "button": ""
}

/* Primary */
{
  "modifier": "primary",
  "button": "-primary"
}

/* Secondary */
{
  "modifier": "secondary",
  "button": "-secondary"
}