VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Read the help articleButton
<forma-button>
Native button (or a link styled as one) with a 44px minimum target and perceptual hover/press feedback; .forma-actions groups actions that wrap.
- Authoring tag
<forma-button>- Category
- Actions
- Behavior owner
- Native HTML
- Canonical source
patterns/button.html
Purpose
Forma styles every native button element directly, so an ordinary <button type="button"> or <button type="submit"> is already a Forma button. The forma-button class gives the same treatment to a link (<a href>) when the action is navigation that should look like an action. forma-actions is a wrapping flex row for a set of related actions. In the application layer there is exactly one visual style: a bordered, full-weight button. A filled primary style (data-forma-variant="primary") and a dashed unavailable style exist only inside a marketing .forma-site shell. The browser owns activation, focus, form submission and disabled state; the application decides what the action does and whether it is currently allowed.
Use when
- The user starts an action: save, submit, cancel, open a dialog, run a command.
- A link navigates somewhere but must read as a call to action in a row of actions; use
<a class="forma-button" href>. - Several related actions sit together and must wrap on narrow screens without overflowing; place them in
forma-actions.
Avoid when
- The control sets an on/off preference: use Switch. It selects one of several options: use Segmented control or Choice group.
- The action leads to another page and appears in running text: use an ordinary link, not a button-styled one.
- Commands need a visible task label or a named group: use Command group; secondary commands that do not fit belong in Overflow command disclosure or a Action menu.
- You need a filled primary, destructive, icon-only or loading variant in an application screen: Forma does not provide those in the application layer. Express priority through order and wording, and report the gap rather than adding local CSS.
Behavior to know
- Every
buttonand.forma-buttonhas a 2.75rem (44px) minimum block size, a functional border and bold label text. - Hover and press change only the surface color; the hit target never moves or shrinks.
- Press feedback starts immediately on pointer or key down and never delays activation.
forma-actionswraps its children onto new lines instead of shrinking or overflowing them.
Basic example
The smallest correct markup: the canonical pattern from patterns/button.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal button
Rendered from the canonical pattern file.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-button class="forma-component-tag">
<div class="forma-actions">
<button type="submit">Save changes</button>
<button type="button">Cancel</button>
<a class="forma-button" href="#button-help">Read the help article</a>
</div>
</forma-button>
Click or tap the code once to select all of it, then copy.
Examples
Save in progress
The application set aria-busy="true" and aria-disabled="true" on the button it just submitted and changed the label to name the work. Forma draws an in-place busy ring before the label; the button keeps its size and place, stays focusable, and loses hover feedback. The status line beside it carries the announcement. The application must ignore further activation until the save completes or fails.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-button class="forma-component-tag">
<form class="forma-stack" action="#" method="post">
<div class="forma-actions">
<button type="submit" aria-busy="true" aria-disabled="true" aria-describedby="button-pending-save-status">Saving changes</button>
<button type="button">Cancel</button>
</div>
<p id="button-pending-save-status" role="status">Saving changes to the launch checklist.</p>
</form>
</forma-button>
Click or tap the code once to select all of it, then copy.
Marketing call to action
Inside a marketing .forma-site shell, data-forma-variant="primary" fills a link-button with the action tone, and aria-disabled="true" gives a dashed, not-allowed treatment. Both hooks only work inside .forma-site. An aria-disabled button is still focusable and still fires click, so the application must ignore activation; the reason is linked with aria-describedby because the button stays in the focus order.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-button class="forma-component-tag">
<div class="forma-site">
<div class="forma-actions">
<a class="forma-button" data-forma-variant="primary" href="#button-marketing-primary-pricing">See pricing</a>
<a class="forma-button" href="#button-marketing-primary-docs">Read the documentation</a>
<button class="forma-button" type="button" aria-disabled="true" aria-describedby="button-marketing-primary-waitlist-note">Join the beta</button>
</div>
<p id="button-marketing-primary-waitlist-note">The beta is full. New places open on 1 November.</p>
</div>
</forma-button>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Wrapping action row on a phone
Three actions with long, translated labels in forma-actions. At 320px the row wraps instead of shrinking targets or scrolling sideways, and long labels break inside their button.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
forma-actionsis a wrapping flex row: buttons that do not fit move to the next line in source order.- Each button keeps its 44px minimum height; a label longer than the viewport wraps inside the button rather than widening the page.
- There are no breakpoints. Source order is the reading, focus and visual order at every width, so put the most likely action first.
- Buttons do not stretch to full width automatically; inside a Dialog at narrow widths the dialog action row does that for you.
<forma-button class="forma-component-tag">
<div class="forma-actions">
<button type="button">Enregistrer les modifications</button>
<button type="button">Enregistrer comme brouillon</button>
<a class="forma-button" href="#button-mobile-wrapping-actions-help">Aide</a>
</div>
</forma-button>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
type | button | button | submit | reset | submit (inside a form) | Always write it. Omitting it inside a form makes the button submit the form. |
disabled | button | boolean | absent | Natively disables the button: not focusable, not activatable, not submitted. In the application layer it only removes hover and press feedback; inside .forma-site it also gets the dashed treatment. |
href | a.forma-button | URL | — | A link styled as a button. It keeps link semantics: Enter activates it, Space scrolls the page. |
aria-disabled | button or a.forma-button inside .forma-site | true | absent | Marks an unavailable action that must stay focusable (for example to expose its reason). It does not block activation; the application must ignore it. |
aria-busy | button or a.forma-button | true | absent | Marks an action whose work is in flight. Forma draws a busy ring before the label (static under reduced motion) and removes hover and press feedback. Pair it with aria-disabled="true" and ignore repeated activation in the application; Forma cannot block a keyboard submission. |
aria-describedby | button | id | — | Links a visible explanation, such as why an aria-disabled action is unavailable. |
data-forma-variant | a.forma-button or button.forma-button inside .forma-site | primary | absent (outlined) | Marketing-only filled primary treatment. Has no effect outside a .forma-site shell. |
aria-hidden | decorative glyph span | true | — | Hides a decorative icon or glyph so the visually hidden text is the whole accessible name. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-button | Block class | — | Applies the native button treatment to a non-button element, normally a link. Inside .forma-site it becomes the marketing button (inline-flex, tone-aware colors, brand radius). |
[aria-busy] | Attribute hook | "true" | Pending selector: :where(button, .forma-button)[aria-busy="true"] draws the busy ring (::before) and removes hover and press feedback. |
[aria-disabled] | Attribute hook | "true" | Marketing only (.forma-site .forma-button[aria-disabled="true"], also :disabled): dashed border, secondary surface and a not-allowed cursor. |
[data-forma-variant] | Attribute hook | "primary" | Marketing only (.forma-site .forma-button[data-forma-variant="primary"]): filled with the action tone background and text, with its own hover tone. |
.forma-actions | Block class | — | Wrapping flex row for related actions with a consistent gap. Global (not limited to .forma-site), although it ships in the marketing stylesheet. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves focus to and from the button. Natively disabled buttons are skipped; aria-disabled ones are not. |
| Enter | Activates a button or follows a button-styled link. |
| Space | Activates a button on key release. On a button-styled link Space scrolls the page, as for any link. |
| Event | Description |
|---|---|
click | Native activation event from pointer, Enter or Space. Forma adds no events. |
submit (on the form) | Fired by the form when a type="submit" button is activated and the form is valid. |
Form behavior
A type="submit" button submits its form and contributes its own name=value when it has a name; type="reset" restores initial values. Disabled buttons never submit. Links styled with forma-button do not participate in forms.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Rest | default | Primary surface, functional border, bold label, 44px minimum height. |
| Hover | :hover (not :disabled) | Surface shifts to the secondary surface color by perceptual interpolation. |
| Pressed | :active (not :disabled) | A darker mix of the secondary surface, applied instantly on press; release fades back. |
| Focus | :focus-visible | Two-tone focus ring (gap outline plus ring shadow) visible on light and dark surfaces. |
| Disabled | disabled attribute | Not focusable or activatable. In the application layer the only visual change is the absence of hover and press feedback; inside .forma-site the button becomes dashed with a not-allowed cursor. |
| Pending | aria-busy="true" (with aria-disabled="true") | A busy ring before the unchanged-position label, progress cursor, no hover or press feedback. Under reduced motion the ring is static and dotted. The application owns the label text, duplicate-activation refusal and the completion or failure message. |
| Marketing primary | data-forma-variant="primary" inside .forma-site | Filled action-tone button for the single most important marketing action. |
| Marketing unavailable | aria-disabled="true" inside .forma-site | Dashed border and not-allowed cursor while remaining focusable. |
Accessibility
Forma provides
- Styles the native element, so role, name, focusability and Enter/Space activation come from the platform.
- Guarantees a 44px minimum block size for every button and
.forma-button. - Provides a visible two-tone focus indicator that does not rely on hover styling.
- In forced-colors mode buttons keep a CanvasText border (ButtonText for marketing buttons), so the target outline stays visible.
Your application supplies
- Write a label that names the action and, where it helps, its object ("Delete draft", not "OK").
- Always set
type; do not rely on the submit default. - Explain why an action is unavailable in visible text. A disabled application-layer button is visually almost identical to an enabled one.
- For icon-only buttons, supply the accessible name in
forma-visually-hiddentext and hide the glyph with aria-hidden. - When using aria-disabled, prevent the action in application code and keep the reason reachable.
- Use a link (
a.forma-button) only for navigation and abuttononly for actions, so assistive technology announces the right role.
Responsive behavior
- Buttons size to their label with a 44px minimum height; long labels wrap inside the button and never force page overflow (
max-inline-size: 100%). forma-actionswraps onto multiple lines at any width and keeps source order.- There are no button breakpoints. Inside a Dialog at 44rem and below, action buttons stretch to full width; inside Verification frame act regions they do the same.
- The app-layer
a.forma-buttonis not given a block display, so its minimum height does not apply as it would to a real button; preferbuttonfor standalone touch targets.
Motion
- Hover and release are perceptual interpolation of background and border color only (
--forma-motion-perceptual-duration, about 120ms). Nothing moves, so the hit target is stable under the pointer. - Press onset uses the direct-manipulation duration (0ms): the pressed color appears as soon as the pointer or key goes down and never delays activation.
- Under
prefers-reduced-motion: reducetransitions are shortened to effectively instant; state colors are unchanged. Marketing buttons remove transitions entirely.
Usage guidance
Do
- Put the most likely action first in
forma-actions; order is the only priority cue in the application layer. - Keep labels short and specific, and use the same verb as the dialog or page it leads to.
Avoid
- Adding local CSS for primary, destructive or loading buttons; report the missing variant instead.
- Using
data-forma-variantor aria-disabled styling outside.forma-siteand expecting it to render. - Relying on a disabled button alone to explain that an action is unavailable.
- Styling a
divorspanas a button; it loses keyboard activation and role.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.