Button
Buttons are pills: one filled primary for the main action, an outlined secondary for everything else.
Show code
<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:
- It only goes to another page from a sentence: a link.
- It turns one thing on or off: a switch. A choice of view: a segmented control.
- It prints the page: the print button. It asks Claude for words: the Suggest button.
Variants
| Variant | Class | Use |
|---|---|---|
| Primary | .btn-primary | The one action you most want on the page or in a section. One per view. |
| Secondary | .btn-secondary | Other actions. The border turns ember on hover and focus. |
| Danger | .btn-secondary.btn-danger | Something that can't be undone, such as deleting. The secondary button in the error colour, never the primary look. |
| Header call to action | nav .cta | A 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 fromtypography.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-busyandaria-disabled, neverdisabled. 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-busyandaria-disabled, notdisabled, 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
| Key | What it does |
|---|---|
| Tab | Moves to the button. |
| Enter | Follows a link; presses a button. |
| Space | Presses 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
| Criterion | Level | How this meets it |
|---|---|---|
| 1.4.3 Contrast (Minimum) | AA | The 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 Contrast | AA | The focus ring is the accent colour, at least 3:1 against the page. |
| 2.1.1 Keyboard | A | Native links and buttons. |
| 2.4.7 Focus Visible | AA | A 2px ring on keyboard focus. |
| 2.5.3 Label in Name | A | The name is the visible words. |
| 2.5.8 Target Size (Minimum) | AA | 51px high or more. |
| 4.1.2 Name, Role, Value | A | Role 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
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 9 of 9 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 6 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not 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
| Where | For |
|---|---|
| Every Somnia site | Calls to action, form buttons and dialogs on mediadreams.co.uk, Headland Yachting and the starter. |
| Somnia CMS | Publish, Preview and every dialog’s buttons. |
What we saw, and what changed
| When | What we saw | What 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
- ARIA Authoring Practices: Button: Space and Enter both activate a button, and where focus goes afterwards depends on what the button did.
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.