# IconButton

> An action shown as a single symbol, with a name for screen readers.

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

Icon-only action with a guaranteed accessible name. `aria-label` is type-required. Composes Button so every Button intent / emphasis / state behaviour propagates; the geometry is IconButton's own (a circle on the control-height scale, sm | md | lg, with a 44 px touch hit-area). The standard icon button is quiet — `intent="neutral"`, `emphasis="ghost"`, the defaults — and keeps its glyph monochrome; tint the glyph only for `danger`, and reserve the solid accent for the one primary action of a surface.

## Use it for

- Icon-only button → `IconButton`

## Axes

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

## Stories

- [Playground](/?path=/story/components-atoms-iconbutton--playground) · frame: `/iframe.html?id=components-atoms-iconbutton--playground&viewMode=story`
- [Intents](/?path=/story/components-atoms-iconbutton--intents) · frame: `/iframe.html?id=components-atoms-iconbutton--intents&viewMode=story`
- [Variants](/?path=/story/components-atoms-iconbutton--variants) · frame: `/iframe.html?id=components-atoms-iconbutton--variants&viewMode=story`
- [Sizes](/?path=/story/components-atoms-iconbutton--sizes) · frame: `/iframe.html?id=components-atoms-iconbutton--sizes&viewMode=story`
- [States](/?path=/story/components-atoms-iconbutton--states) · frame: `/iframe.html?id=components-atoms-iconbutton--states&viewMode=story`

## Decisions that name it

- ADR-003 — Storybook editorial convention and pattern↔component bidirectionality
- ADR-005 — Visual operational rules: surfaces, interaction, motion
- ADR-013 — PageShell: mobile-nav polymorphism
- ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register
- ADR-016 — NotificationCenter v2: Popover → Drawer + Provider/Hooks
- ADR-017 — Actionable components adopt the `asChild` slot pattern for framework-aware routing
- ADR-030 — Axis vocabulary: one name, one meaning

## 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).