A button with a short line of quiet words that says what pressing it will do, or why it cannot be pressed now.
Options
| Choice | Values | Default | What it does |
|---|---|---|---|
layoutsmbk-button-note--layout-<value> | besidebelowheader-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. |
Examples
Usage
A button and a quiet line that says what pressing it will do, beside it.
Layouts
Beside, moving under the button when there is no room; below; and at the end of a page header, lined up with its end edge.
With a reason
A disabled button carries its reason. It stays focusable, so the reason is read when it is reached, and pressing it does nothing.
Sizes
The button’s three sizes. The note and the gap stay the same.
Guidelines
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.
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'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.
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.
Say why the button cannot be pressed, so the reader knows what to do next.
A note that repeats the label tells the reader nothing new.
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.
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. |
| EnterorSpace | Presses the button. A disabled button does nothing. |
Source
The files the button note is made of. Its folder on GitHub (opens in a new tab) holds them with its wrapper and its document.
Stylesheet
/* 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
| Token and CSS | Value | Preview | Foundation |
|---|---|---|---|
| space.stack.sm--smbk-space-stack-sm | comfortable: 8pxcompact: 6pxchanges with density | Spacing | |
| space.inline.lg--smbk-space-inline-lg | comfortable: 12pxcompact: 8pxchanges with density | Spacing | |
| space.inline.xs--smbk-space-inline-xs | 4px | Spacing | |
| color.text.subtle--smbk-color-text-subtle | light: #4e555edark: #9ba5b1changes with theme | Color | |
| typography.body-sm--smbk-typography-body-sm-font-family--smbk-typography-body-sm-font-size--smbk-typography-body-sm-font-weight--smbk-typography-body-sm-line-height--smbk-typography-body-sm-letter-spacing--smbk-typography-body-sm-text-transform | fontFamily: Geist, Geist Fallback, system-ui, sans-seriffontSize: 14pxfontWeight: 400lineHeight: 1.5letterSpacing: 0px | The quick brown fox | Typography |
| size.icon.sm--smbk-size-icon-sm | 16px | Size | |
| color.icon.subtle--smbk-color-icon-subtle | light: #4e555edark: #c4cdd8changes with theme | Color | |
| size.button-note.width--smbk-size-button-note-width | 240px | Size |
Manifest
{
"name": "button-note",
"block": "smbk-button-note",
"summary": "A button with a short line of quiet words that says what pressing it will do, or why it cannot be pressed now.",
"adapt": "css",
"axes": {
"layout": {
"values": [
"beside",
"below",
"header-end"
],
"default": "beside",
"description": "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."
}
},
"flags": {},
"parts": [
"note",
"icon",
"text"
],
"figmaNodeId": "7115:2068"
}