# Button note

A button with a short line of quiet words that says what pressing it will do, or why it cannot be pressed now.

Block: `smbk-button-note`. Status: experimental. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Desktop and mobile: differ by presentation only.

## Options

| Axis | Values | Default | Meaning |
|---|---|---|---|
| `layout` | `beside`, `below`, `header-end` | `beside` | Beside puts the note next to the button and moves it under when there is no room; below always puts it under; header-end lines both up with the end of a page header. |

Parts: `smbk-button-note__note`, `smbk-button-note__icon`, `smbk-button-note__text`

## Markup

```html
<div class="smbk-button-note smbk-button-note--layout-beside">
  <button
    type="button"
    class="smbk-btn smbk-btn--tone-brand smbk-btn--size-md"
    aria-describedby="button-note-1-note"
  >
    <span class="smbk-btn__label">Name the next release</span>
  </button>
  <p id="button-note-1-note" class="smbk-button-note__note">
    <span class="smbk-button-note__text">Starts the release notes from what merged since 0.1.2.</span>
  </p>
</div>
```

## React

```tsx
import { ButtonNote } from './design-system/components/button-note/button-note.js';
import { Button } from './design-system/components/button/button.js';

<ButtonNote layout="beside" note="Starts the release notes from what merged since 0.1.2.">
  <Button>Name the next release</Button>
</ButtonNote>
```

## Stylesheet

```css
/* smbk-button-note — Button note. Figma "Button note" 7115:2068: Layout × Disabled × Size, 18 variants; the note's
 * words and its info icon are content. A button and a line of quiet words that says what pressing it will do, or
 * why it cannot be pressed now. The size is the button's own: nothing here changes with it. The note stays the
 * secondary text color when the button is disabled, so the reason is always readable. */

.smbk-button-note {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: var(--smbk-space-stack-sm) var(--smbk-space-inline-lg);
}

.smbk-button-note__note {
  display: flex;
  align-items: center;
  gap: var(--smbk-space-inline-xs);
  margin: 0;
  color: var(--smbk-color-text-subtle);
  font-family: var(--smbk-typography-body-sm-font-family);
  font-size: var(--smbk-typography-body-sm-font-size);
  font-weight: var(--smbk-typography-body-sm-font-weight);
  line-height: var(--smbk-typography-body-sm-line-height);
  letter-spacing: var(--smbk-typography-body-sm-letter-spacing);
}

.smbk-button-note__icon {
  font-size: var(--smbk-size-icon-sm);
  color: var(--smbk-color-icon-subtle);
}

.smbk-button-note__text {
  min-width: 0;
}

/* ---- beside (the default): the note sits beside the button, centered on it, at the note width, and moves
   under the button when that much room is not left. ---- */

.smbk-button-note--layout-beside > .smbk-button-note__note {
  flex: 0 1 var(--smbk-size-button-note-width);
}

/* ---- below, and at the end of a page header: the note under the button, never wider than the note width;
   at the header's end both line up with its end edge. ---- */

.smbk-button-note--layout-below,
.smbk-button-note--layout-header-end {
  flex-direction: column;
  flex-wrap: nowrap;
  align-items: flex-start;
}

.smbk-button-note--layout-below > .smbk-button-note__note,
.smbk-button-note--layout-header-end > .smbk-button-note__note {
  max-width: var(--smbk-size-button-note-width);
}

.smbk-button-note--layout-header-end {
  align-items: flex-end;
  text-align: end;
}
```

## Tokens it reads

```json
{
  "space": {
    "stack": {
      "sm": {
        "$type": "dimension",
        "$value": "{{space.8}}",
        "$description": "Gap between things stacked one above another, small."
      }
    },
    "inline": {
      "lg": {
        "$type": "dimension",
        "$value": "{{space.12}}",
        "$description": "Gap between things side by side, large."
      },
      "xs": {
        "$type": "dimension",
        "$value": "{{space.4}}",
        "$description": "Gap between things side by side, extra small."
      }
    }
  },
  "color": {
    "text": {
      "subtle": {
        "$type": "color",
        "$value": "{{color.grey.700}}",
        "$description": "Secondary text: descriptions, metadata."
      }
    },
    "icon": {
      "subtle": {
        "$type": "color",
        "$value": "{{color.grey.700}}",
        "$description": "Quiet icons."
      }
    }
  },
  "typography": {
    "body-sm": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Geist, Geist Fallback, system-ui, sans-serif",
        "fontSize": "14px",
        "fontWeight": 400,
        "lineHeight": 1.5,
        "letterSpacing": "0px"
      }
    }
  },
  "size": {
    "icon": {
      "sm": {
        "$type": "dimension",
        "$value": "{{size.16}}",
        "$description": "Icon box, small."
      }
    },
    "button-note": {
      "width": {
        "$type": "dimension",
        "$value": "240px",
        "$description": "Width of the note beside, under or at the end of a button: beside it, the note stays there while this much room is left after the button and moves under it otherwise. A fixed frame width in Figma with no variable behind it; it should become one."
      }
    }
  }
}
```

## Purpose

A button with a short line of quiet words that says what pressing it will do, or why it cannot be pressed now. A disabled button on its own leaves the reader guessing; with a note it always gives its reason. It differs from a field's help text, which explains what to enter, and from a tooltip, which hides its words until hovered.

## Anatomy

- The block, a row holding the button and its note.
- The button, any button at any size. Its size sets the row's; the note does not change with it.
- The note part, one or two lines of the small body text in the secondary text color.
- The icon part, an information icon before the words. Optional.
- The text part, the words.

## When to use

- A button whose effect is not obvious from its label: "Starts the release notes from what merged since the last release."
- A button that cannot be pressed now, to say why: "Nothing merged since the last release yet."
- A page header's main action, with a line under it that says what it will do.

## When not to use

- To explain a field. Use the [field](field.md)'s help text.
- For a long explanation. Link to it, or put it in the page.
- For words that only matter on hover. A note is always shown.

## Behavior

Three layouts. Beside puts the note next to the button, centered on it; when the row has no room for both, the note moves under the button. Below always puts the note under the button. Header end lines the button and the note up with the end of a page header, the note's words aligned to that edge. The gap between the button and the note is the same at every size.

The note keeps the secondary text color when the button is disabled, never the faded disabled color, so the reason stays readable.

## Accessibility

### What it does for you

- The note is the button's description: a screen reader reads it after the button's name. The wrapper links them.
- A disabled button with a note stays focusable, so the reason can be reached and read. The wrapper turns the disabled attribute into the aria-disabled attribute, and the button does nothing when pressed.
- The note is not a stop in the tab order of its own.
- The information icon is decorative; the words say it all.

### What you must do

- In markup written by hand, give the note an id and point the button's description at it.
- In markup written by hand, turn a disabled button's disabled attribute into the aria-disabled attribute yourself, so the button stays focusable and does nothing when pressed.

### How to test

- Tab to the button: it takes focus and the note does not. A disabled one takes focus too, with the focus ring showing in both themes and in a forced-color mode.
- Press Enter, then Space: each runs the action once. On a disabled button, neither does anything.
- With a screen reader, the button is read by its name, then the note as its description.
- With text at 200% and the page 320 pixels wide, the note wraps and stays whole.

### Keyboard

| Key | What it does |
|---|---|
| Tab | Moves focus to the button. A disabled button with a note is not skipped. |
| Enter or Space | Presses the button. A disabled button does nothing. |

## Usage rules

### Do

- Say why a disabled button cannot be pressed, and what would make it possible.
- Keep the note to a sentence.

### Don't

- Repeat the button's label in the note.
- Put a link or another control inside the note.