Button

Contract

:focus-visible — the ring appears from the keyboard and does not appear from the mouse. In a group the focused button rises by z-index so that its neighbour does not cut the ring off.

Every variant's label holds 4.5:1 in five themes, and the primary fill is capped in lightness (0.545 for the default petrol). The target is 32px at md and 24px at sm; compact takes sm to 22px, below the 24px of WCAG 2.5.8 — hence compact is for dense tabular views, not the main navigation.

Variants

A variant is two lines: it changes only the inner variables rather than rewriting the rule.

<button class="inst-btn" type="button">Default</button>
<button class="inst-btn inst-btn--primary" type="button">Primary</button>
<button class="inst-btn inst-btn--soft" type="button">Soft</button>
<button class="inst-btn inst-btn--outline" type="button">Outline</button>
<button class="inst-btn inst-btn--ghost" type="button">Ghost</button>
<button class="inst-btn inst-btn--danger" type="button">Danger</button>

The ladder of weights

Weight answers "how loudly does the button ask to be pressed", and the answer is measurable: presence is area weighted by the step in lightness against the ground.

Monotone in all five themes, neighbouring steps no closer than 0.022 — checked by cmd/contrast as "ladder: soft against default". The outline's border is decorative, not load-bearing.

Tone

A tone is the kit's shared vocabulary, the same one the badge, the dot, the meter and the banner use. A button reads --tone-ink from it for the label and --tone-bg for hover.

<button class="inst-btn inst-btn--ghost" type="button" data-tone="running">Add context</button>
<button class="inst-btn" type="button" data-tone="ok">Accept</button>
<button class="inst-btn" type="button" data-tone="error">Delete</button>
<button class="inst-btn inst-btn--danger" type="button">Delete</button>

inst-btn--danger is the tone error written as a class — a destructive action occurs often enough to deserve the short spelling.

A ghost with the tone running is the action-as-a-link: "add context", "add a row", "create the first object" — a press invited without arguing with the principal button.

A switch of a value

There is a control whose point is the value, with the label only saying what the value is of: the current repository, branch, environment, account. "master" by itself means nothing, and "Current branch" cannot be removed.

<button class="inst-btn inst-btn--stacked" type="button" style="inline-size:15rem">
  <svg class="inst-icon" aria-hidden="true"><use href="#i-book"/></svg>
  <span class="inst-btn-stack">
    <span class="inst-btn-label">Current repository</span>
    <span class="inst-btn-value">instrument-ui-kit</span>
  </span>
  <svg class="inst-icon inst-icon--sm" aria-hidden="true"><use href="#i-chevron"/></svg>
</button>

What becomes a column is the text, so .inst-btn-stack is required: a control like this carries a leading icon and a chevron, and stacking the whole button would put them above and below instead. Two lines are a property of this variant rather than permission to wrap any button.

A button in the clothes of a field

<button class="inst-btn inst-btn--field" type="button" style="inline-size:18rem">
  <svg class="inst-icon" aria-hidden="true"><use href="#i-list"/></svg>
  Choose a file or a command
</button>

It opens a palette or a list but stays a button. The border is load-bearing here: it is the control.

As a link

The class on an <a> gives exactly the same button, with no underline.

<a class="inst-btn" href="#button">Open the report</a>
<a class="inst-btn inst-btn--primary" href="#button">Go to the run</a>
<button class="inst-btn" type="button">Run</button>

Sizes

<button class="inst-btn inst-btn--xs" type="button">xs</button>
<button class="inst-btn inst-btn--sm" type="button">sm</button>
<button class="inst-btn" type="button">md</button>
<button class="inst-btn inst-btn--lg" type="button">lg</button>

The height comes from the role tier (--control-h-*), so a button and a field of the same size cannot part. Density retunes all three at once.

xs is the odd one: its box is the badge's rather than the control tier's, because below sm the neighbour in a row is a chip and not a button. It is for a control that belongs to something else — the icons under an answer, the session controls under a composer. Its tap area stays --tap-min through a pseudo-element, so the drawing shrinks and the target does not — which means the row owes it --space-3: at compact the box is 18px, and a narrower gap makes two enlarged areas overlap. A primary standing on its own stays sm.

States

<button class="inst-btn" type="button">Ordinary</button>
<button class="inst-btn" type="button" disabled>Unavailable</button>
<button class="inst-btn inst-btn--primary" type="button" aria-busy="true">Run</button>

Busyness

<button class="inst-btn inst-btn--primary" type="button" aria-busy="true">Run</button>
<button class="inst-btn" type="button" aria-busy="true">Cancel</button>
<button class="inst-btn inst-btn--icon" type="button" aria-busy="true" aria-label="Refresh">
  <svg class="inst-icon" aria-hidden="true"><use href="#i-refresh"/></svg>
</button>

The label is dimmed rather than removed, so the width holds and a screen reader still reads it. The button keeps its focus — disabled would throw it out of the tab order under the hands of whoever came by keyboard — and only the mouse is taken away; guarding against a second press belongs to the handler.

With icon

<button class="inst-btn" type="button">
  <svg class="inst-icon" aria-hidden="true"><use href="#i-refresh"/></svg>
  Refresh
</button>
<button class="inst-btn inst-btn--icon" type="button" aria-label="Refresh">
  <svg class="inst-icon" aria-hidden="true"><use href="#i-refresh"/></svg>
</button>

An icon button is square: the width comes from the same control height, so it holds at all three sizes and every density.

Composition

A group

<div class="inst-btn-group">
  <button class="inst-btn inst-btn--sm" type="button">Left</button>
  <button class="inst-btn inst-btn--sm" type="button">Centre</button>
  <button class="inst-btn inst-btn--sm" type="button">Right</button>
</div>

Several different actions standing flush — see the section index for how a group differs from a segmented control and a chip.

Patterns

The action bar of a form

The principal action stands at the outer edge of the bar. Here the bar is pushed to the end of the line, so the principal one goes last with cancel before it; aligned to the start the order is the reverse — see the form.

<form class="inst-panel">
  <div class="inst-panel-body">
    <div class="inst-field">
      <label class="inst-label" for="p-name">Run name</label>
      <input class="inst-input" id="p-name" type="text" value="nightly-4127">
    </div>
    <div class="inst-form-actions inst-form-actions--end">
      <button class="inst-btn" type="button">Cancel</button>
      <button class="inst-btn inst-btn--primary" type="submit">Save</button>
    </div>
  </div>
</form>

The actions of a table row

A dense row takes ghost and sm: a border on every button in a table would turn the column into a grid. A destructive action keeps its border — it is the one thing in the row that has to be noticeable.

<div class="inst-cluster">
  <button class="inst-btn inst-btn--sm inst-btn--ghost" type="button">Open</button>
  <button class="inst-btn inst-btn--sm inst-btn--ghost" type="button">Retry</button>
  <button class="inst-btn inst-btn--sm inst-btn--danger" type="button">Delete</button>
</div>

Customization

A variant of your own is two lines. What is overridden are the variables rather than the rule.

.my-btn--accent {
  --btn-fg: var(--accent-on);
  --btn-bg: var(--accent-solid);
}

Two limits that are easier to break than to notice:

• Hover changes only --btn-bg. Do not override background directly — the variable will stop being read, and the variant will lose its hover.
• A fill under a white label cannot be lighter than the bound for its hue in OKLCH — 0.545 at 215°, 0.568 at 250°, 0.576 at 275°, 0.580 at 45°. Above that white text stops holding 4.5:1. For the same reason --btn-bg-hover moves away from the colour of the label. A mirrored "lighter in the dark theme" drops the label's contrast to 2.61.

API

Related

Button groupSegmented controlMenuToolbarChipComposer