# Button

Starts an action on the current screen, such as saving a form or sending an offer.

* Kind: component
* Page: https://design.werklist.com/components/button
* Version: 2.1.2

## When to use it

* The result happens on this screen, such as a save or a dialog that opens.
* Primary for the one action per surface (page, dialog, sheet, panel) that moves the task forward.
* Secondary beside a primary, or for the main action when none leads.
* Quiet for frequent minor actions in toolbars and rows.
* Outline for an action that sits among fields, such as Add filter beside a search field: it has the fill of a text field.
* Danger for the confirming button of a destructive step, inside its confirmation.
* Danger quiet for a destructive action among other actions. It leads to a confirmation or offers undo.
* Toggle: a quiet button with aria-pressed, for filters and view options in a toolbar.
* Menu button: a chevron after the label and aria-haspopup menu, for a family of at least three related actions.
* A call to action that opens another page: a link drawn as a button.

## When not to use it

* Navigation in running text: use Link.
* A second primary button on the same surface.
* A primary button in a table or list row.
* A danger button as the default of a form or a dialog, or with initial focus.
* Quiet, outline or danger quiet over a picture.
* A setting that persists: use Switch.
* Choosing one option from several: use Select or Segmented control.
* A label that wraps, truncates or has no verb.
* Two icons in one button, except the start icon and chevron of a menu button.

## Anatomy

* Container: height 36, 44 or 48 px, minimum width equal to the height, radius 8 px, as wide as its content (--radius-lg)
* Side padding: 12, 16 or 20 px (--space-3, --space-4, --space-5)
* Label: one line, no wrap, no truncation. 13 px on 20 px at small, 14 px on 20 px at medium and large, weight 500 (--type-caption, --type-nav)
* Icon: 16 px, at most one, at the start or the end, 8 px from the label, currentColor (--space-2)
* Spinner: 16 px, one turn per second, replaces the start icon or sits over the transparent label, appears after 300 ms (--duration-slow)
* Focus ring: outline 2 px, offset 2 px (--focus-ring, --focus-ring-width, --focus-ring-offset)
* Touch target: 44 px on coarse pointers, the small size extending its hit area 4 px above and below
* Group: 8 px between buttons, the primary at the trailing end. Below 640 px a form or dialog ends in a full width stack with the primary on top (--space-2)

## Variants

* primary: The one action per surface that moves the task forward.
* secondary: Cancel beside a primary, or the main action when none leads.
* quiet: Frequent minor actions in toolbars and rows. The only variant that toggles.
* outline: An action among fields, with the fill of a text field.
* danger: The confirming button of a destructive step, inside its confirmation.
* danger-quiet: A destructive action among others, leading to a confirmation or undo.

## Sizes

* sm: height 36 px, padding 0 12 px, type 13 px on 20 px, weight 500
* md: height 44 px, padding 0 16 px, type 14 px on 20 px, weight 500
* lg: height 48 px, padding 0 20 px, type 14 px on 20 px, weight 500

## States

* rest: Primary: brand blue fill and white label in both themes. Secondary: gray fill and text ink. Quiet: no fill and muted ink. Outline: the field material. In dark that is --glass-fill-input with an inset 1 px --input-border edge and --glass-ring, in light the 5 percent ink wash of --glass-fill-hover with no edge. Danger: --error in light and --badge-alert in dark, white label. Danger quiet: no fill and --error ink. (--brand-true, --on-brand, --surface-control, --text, --text-muted, --glass-fill-input, --input-border, --glass-ring, --glass-fill-hover, --badge-alert, --error)
* hover: Primary darkens to --brand-blue-dark in light, and to the brand blue mixed 72 percent with --navy in dark. Danger drops to opacity 0.9. Secondary and outline lay --glass-fill-hover over their fill. Quiet gains --glass-fill-hover and text ink. Danger quiet gains --error at 10 percent. Only on a pointer that can hover. (--brand-blue-dark, --navy, --glass-fill-hover, --error)
* pressed: The hover paint, on touch too, and a scale of 0.98 over 150 ms unless motion is reduced. (--duration-fast, --ease-standard)
* focus-visible: Outline 2 px at offset 2 px in the focus ring color. As an outline it survives forced colors mode. (--focus-ring, --focus-ring-width, --focus-ring-offset)
* disabled: aria-disabled true on a focusable button, drawn at opacity 0.5 in the colors of its variant. Presses and implicit form submission are canceled, and hover does not apply. Contrast minimums do not apply to a disabled button. The reason is visible text, linked with aria-describedby.
* loading: aria-busy and aria-disabled true at once, focus kept, presses ignored. After 300 ms a 16 px spinner in the label ink replaces the start icon, or sits centered over the label, which turns transparent. Width and label do not change. Under reduced motion the spinner fades between opacity 1 and 0.5 each second instead of turning. (--duration-slow)
* toggle on: Quiet variant with aria-pressed true: --seg-selected fill and text ink. On hover --glass-fill-hover lies over it. In a board toolbar a pressed tool takes the brand tint instead (see Toolbar). (--seg-selected, --text, --glass-fill-hover)
* menu open: aria-expanded true. The button holds its hover paint and the chevron turns 180 degrees in 150 ms, without the turn under reduced motion. (--duration-fast)

## Keyboard

* Tab, Shift+Tab: Move focus in document order, disabled and loading buttons included.
* Enter: Press. On a menu button, open the menu with focus on the first item. On a button that opens a page, follow the link.
* Space: Press on release, flip a toggle, or open a menu button's menu. Not on a button that opens a page.
* Down arrow: On a menu button, open the menu with focus on the first item.
* Up arrow: On a menu button, open the menu with focus on the last item.
* Escape: Close an open menu and return focus to the menu button.

## Accessibility

* A native button element with type button, or type submit in a form. An a element with href when the button opens a page.
* The name is the visible label. Icons are aria-hidden.
* Label on fill at 4.5 to 1, icon and focus ring at 3 to 1, in every enabled state and both themes.
* Disabled and loading use aria-disabled, not the disabled attribute, so focus stays and the reason is reachable.
* States exposed with aria-pressed, aria-expanded, aria-haspopup, aria-busy, aria-disabled and aria-describedby.
* Targets of 44 px on coarse pointers.
* Forced colors: a 1 px ButtonText border, ButtonText on ButtonFace, the toggle on in Highlight, focus as an outline in Highlight.

## Content

* A verb first, plus the object when the verb alone is vague: Send offer, Publish job, Add candidate.
* Two or three words, sentence case, no final period, no exclamation.
* Answer the question of the dialog: Delete CV and Cancel, not Yes and No.
* Cancel stops a task and keeps nothing. Close dismisses what changed nothing.
* No OK, no Submit, no ellipsis at the end.
* The label does not change while loading.

## Tokens

* --brand-true
* --brand-blue-dark
* --navy
* --on-brand
* --surface-control
* --text
* --text-muted
* --glass-fill-hover
* --glass-fill-input
* --input-border
* --glass-ring
* --badge-alert
* --error
* --seg-selected
* --focus-ring
* --focus-ring-width
* --focus-ring-offset
* --radius-lg
* --space-2
* --space-3
* --space-4
* --space-5
* --type-caption
* --type-nav
* --duration-fast
* --duration-slow
* --ease-standard