Preview brand Custom

Button

Buttons are pills: one filled primary for the main action, an outlined secondary for everything else.

Start a projectSee the work
Start a projectSee the work
Show code
html
<a class="btn-primary" href="/contact/">Start a project</a>
<a class="btn-secondary" href="/case-studies/">See the work</a>
<button class="btn-secondary" type="button">Not now</button>

<!-- Something that can't be undone -->
<button class="btn-secondary btn-danger" type="button">Delete this draft</button>

When to use it

  • For the thing you most want someone to do on a page or in a section: one primary button.
  • For the other things they can do there: secondary buttons.
  • To send a form, open a dialog or change something on the page.

Use something else when:

Variants

VariantClassUse
Primary.btn-primaryThe one action you most want on the page or in a section. One per view.
Secondary.btn-secondaryOther actions. The border turns ember on hover and focus.
Danger.btn-secondary.btn-dangerSomething that can't be undone, such as deleting. The secondary button in the error colour, never the primary look.
Header call to actionnav .ctaA smaller primary (14 px) used only in the site header.

The same two classes go on a link or a button. Which element is the page's choice, and it matters: a link goes somewhere, a button does something.

States

  • Hover: secondary buttons take an ember border and label. Primary buttons take color.action.hover, which is the action colour unless a brand sets its own (Gulo on dark: Claw Gold).
  • Shape and case: corners come from shape.control (a pill; 3 px in Gulo) and letter case from typography.button-case (sentence case; capitals in Gulo).
  • Focus: a 2 px ember ring, offset 2 px, on keyboard focus only (:focus-visible).
  • Busy: while a form sends, the words change to say so ("Sending…") and the button is marked aria-busy and aria-disabled, never disabled. It keeps the keyboard's focus, and the form ignores a second press. The contact form and the newsletter sign-up do this.
  • Disabled: avoided. Explain what's missing instead of greying out the button. Where one is disabled it is faded, with a not-allowed cursor.
  • Size: 51 px high on a wide screen and 54 px on a phone, where the words are larger.

Do and don't

Do

  • A verb and an object: "Send enquiry", "Get the checklist"
  • Keep the same words through a flow: "Send" then "Sent"
  • Sentence case (a brand can switch to capitals with a token, never by typing capitals)

Don't

  • "Submit", "Click here", "Learn more" on their own
  • Two primary buttons side by side
  • Arrows or icons that repeat what the label says

Accessibility

What it does for you

  • The same look on a link and on a real button, so the page picks the element by what it does: a link goes somewhere, a button does something.
  • Words always visible; the primary’s words are the brand’s own on-accent colour, checked against the accent when the tokens are built.
  • A 2px focus ring, 2px off the edge, for keyboard focus only.
  • 51px high on a wide screen and 54px on a phone.
  • Busy while a form sends: aria-busy and aria-disabled, not disabled, so the keyboard’s focus stays on it and the words say "Sending…".

What you need to do

  • The right element: <a href> to go somewhere, <button> to do something. A link dressed as a button still answers to Enter only, not Space.
  • Words that say what happens: a verb and its object.
  • One primary button in a view.
  • If a button must be disabled, say nearby what is missing.

Keyboard

KeyWhat it does
TabMoves to the button.
EnterFollows a link; presses a button.
SpacePresses a button. On a link it scrolls the page, as on any link.

What a screen reader is told

  • A link or a button, named by its words.
  • Busy: the button’s new words, and that it is unavailable for the moment.

This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.

WCAG 2.2

CriterionLevelHow this meets it
1.4.3 Contrast (Minimum)AAThe primary’s words against its fill, and the secondary’s against the page, are checked when the tokens are built and again here.
1.4.11 Non-text ContrastAAThe focus ring is the accent colour, at least 3:1 against the page.
2.1.1 KeyboardANative links and buttons.
2.4.7 Focus VisibleAAA 2px ring on keyboard focus.
2.5.3 Label in NameAThe name is the visible words.
2.5.8 Target Size (Minimum)AA51px high or more.
4.1.2 Name, Role, ValueARole from the element; name from its words; busy and unavailable while sending.

The criteria this component has a part in. A page that uses it still has to meet the rest.

Checked

CheckHowResult
Automated (axe-core)WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in darkPassed
Nothing found, light or dark
Narrow screenNo sideways scrolling at 320px wide (WCAG 1.4.10)Passed
No sideways scrolling
Keyboard and what the browser reportsReal key presses on the live example, and the role, name and state given to assistive technologyPassed
9 of 9 checks pass
On paperSomnia’s print check: no overlaps, stranded headings or controls on the pagePassed
No faults on 6 sheets
Screen readerListened to by a person, in VoiceOver and NVDANot yet
Not yet checked by a person

The 9 checks made with the keyboard, on the example at the top of this page:

  • Passed Tab reaches each button, in the order they are written
  • Passed A link that looks like a button is reported as a link, and a button as a button, each named by its words
  • Passed Enter follows a link
  • Passed Space and Enter both press a real button
  • Passed Keyboard focus shows a 2px ring
  • Passed The ring has at least 3:1 against the page, in light and dark
  • Passed The primary button’s words have at least 4.5:1 against its fill, in light and dark
  • Passed Each is at least 44px high
  • Passed While a form sends, its button says "Sending…", keeps the focus and ignores a second press

Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.

Not yet checked

  • How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
  • Windows high contrast (forced colours) has not been looked at by a person.
  • The secondary button’s edge is a hairline in the border colour, under 3:1 against the page: it relies on its words and weight to read as a button, which has not been tested with people.

Evidence

Where it's used

WhereFor
Every Somnia siteCalls to action, form buttons and dialogs on mediadreams.co.uk, Headland Yachting and the starter.
Somnia CMSPublish, Preview and every dialog’s buttons.

What we saw, and what changed

WhenWhat we sawWhat changed
The running-text link style reached buttons, and hid the primary button’s words in a panel on dark Insight pages.The link style no longer applies to buttons (1.3.2).
Gulo’s style guide sets square corners, capitals and its own hover colour for buttons.Corners, case and hover became brand tokens: shape.control, typography.button-case, color.action.hover (1.12.0).
A disabled button had no look of its own.Disabled buttons are faded, with a not-allowed cursor (1.21.0).
Actions that can’t be undone, such as deleting, had only the ordinary buttons.A secondary button in the error colour, .btn-danger (1.30.0).
This page said a button should be busy, not disabled, while a form sends. The contact form and the newsletter sign-up disabled theirs.Both mark the button busy and keep the focus on it (1.82.0).

From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.

What it rests on

What we don't know yet

  • Which calls to action get pressed, and whether one wording does better than another, has not been measured.

Tokens

color.action.primary, color.action.on-primary, color.border.subtle, color.focus.ring, shape.control, typography.button-case, font.weight.bold, duration.fast.