# Button

> The action a reader takes, from the one primary call to quiet secondary ones.

- **Level**: atom · **Status**: stable · **Role**: action
- **Import**: `import { Button } from "@rrios-forge/ui/atoms/button";`
- **Source**: `packages/ui/src/atoms/button`

**Purpose.** The verb of the system — a control that *commits an action* with a side effect. Buttons are how users do things; they are not how users navigate.

**When to use.**
- Submit a form, save changes, confirm a dialog, run an operation.
- Trigger a destructive action (`intent="danger"`) where the consequence is reversible only by a counter-action.
- Open a modal, panel or other in-product surface that the user is *staying* in (the URL does not change).

**When NOT to use.**
- The control changes the URL or opens an external page → use `Link`. Buttons break right-click, middle-click, history and crawlability.
- The control is icon-only → use `IconButton`. It enforces square hit-area, focus ring and a required `aria-label`.
- The control is part of a segmented set with persistent selection → use `Tabs` or a `RadioGroup` styled as a toolbar.

**Composes with.**
- `Icon` (decorative leading glyph) reinforces the label without replacing it.
- `Spinner` is rendered automatically by the Button when `loading` is true; do not place a `Spinner` inside the children.
- `Field`, `Dialog`, `FormSection` consume Button as the commit affordance; the Button never owns submit logic itself.

**Accessibility.**
- Renders a real `<button>` element; `Enter` and `Space` activate it; tab-order participates by default.
- `loading` sets `aria-busy="true"` and disables interaction without removing the focus ring; the label remains visible to screen readers.
- `disabled` is exposed as the native attribute and removes the control from the tab sequence.
- Icon-only Buttons are forbidden; the `Button` API requires text children (use `IconButton` instead).

**Related patterns.**
- `Patterns/Decision Matrix · ComponentChoice` — Button vs Link vs IconButton.
- `Patterns/Visual Priority · ActionEmphasisLadder` — primary / secondary / quiet emphasis order on a surface.
- `Patterns/Composition · CompositionChecklist` — how Button slots into Field, Dialog and FormSection.

## Use it for

- Primary CTA → `Button intent="primary" emphasis="solid"`
- Destructive action → `Button intent="danger" emphasis="solid"`
- Quiet secondary action → `Button intent="neutral" emphasis="ghost"`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `emphasis` | — | `solid` `soft` `outline` `ghost` | `solid` | How strongly a control or chip asserts itself, quiet to loud. |
| `intent` | — | `primary` `secondary` `danger` `neutral` | `primary` | What an action does. |
| `size` | — | `sm` `md` `lg` | `md` | Ergonomic scale, in three families (control, text, container). |

## Stories

- [Playground](/?path=/story/components-atoms-button--playground) · frame: `/iframe.html?id=components-atoms-button--playground&viewMode=story`
- [In context](/?path=/story/components-atoms-button--in-context) · frame: `/iframe.html?id=components-atoms-button--in-context&viewMode=story`
- [Intents](/?path=/story/components-atoms-button--intents) · frame: `/iframe.html?id=components-atoms-button--intents&viewMode=story`
- [Variants](/?path=/story/components-atoms-button--variants) · frame: `/iframe.html?id=components-atoms-button--variants&viewMode=story`
- [Sizes](/?path=/story/components-atoms-button--sizes) · frame: `/iframe.html?id=components-atoms-button--sizes&viewMode=story`
- [Focus (keyboard)](/?path=/story/components-atoms-button--focus-visible) — interaction test · frame: `/iframe.html?id=components-atoms-button--focus-visible&viewMode=story`
- [States](/?path=/story/components-atoms-button--states) · frame: `/iframe.html?id=components-atoms-button--states&viewMode=story`

## Patterns consulted

- Patterns/Decision Matrix · ComponentChoice
- Patterns/Visual Priority · ActionEmphasisLadder
- Patterns/Composition · CompositionChecklist

## Decisions that name it

- ADR-002 — Component variants live in `variants.ts` and export their option metadata
- ADR-003 — Storybook editorial convention and pattern↔component bidirectionality
- ADR-005 — Visual operational rules: surfaces, interaction, motion
- ADR-006 — Geometry and typography signature
- ADR-017 — Actionable components adopt the `asChild` slot pattern for framework-aware routing
- ADR-019 — Composer organism (message/post authoring surface)
- ADR-022 — The material family: `solid` and `vibrant`
- ADR-028 — The label is not the fill
- ADR-030 — Axis vocabulary: one name, one meaning
- ADR-043 — The default theme is monochrome

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).
