An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:IconButton authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-25 owners: [cixzhang] review_triggers: [public-api, behavior, layout, accessibility] verified_by: [ packages/core/src/IconButton/IconButton.test.tsx, packages/core/src/IconButton/tests/IconButtonAudit.a11y.chromium.spec.ts, packages/core/src/Button/tests/Button.a11y.test.tsx, packages/core/src/Button/tests/Button.a11y.chromium.spec.ts, ] modules: [] families: [family:buttons] design_specs: [design:reduced-motion] architecture: [architecture:component-size-cascade, architecture:public-component-api] contributing: []
system_specs: [spec:AST-085]
IconButton component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | None changes. IconButton takes Button's props without isIconOnly, children, and endContent, and requires icon. |
| Behavior | IconButton always renders Button's icon-only mode: a button, square by default, named by label through aria-label, with no visible text. Every other behavior is Button's. |
| End-user impact | People see a compact, square-by-default action with the same feedback as any Button. Screen-reader users hear label. Sighted users get a visible hint only when the caller adds one. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Button's disabled-focusability, reduced-motion, and self-colored-content gaps apply unchanged; all three are listed under Current-state impact. |
| Review checks | Reject an IconButton that renders visible label text or end content, is not square with the default aspect and no width, loses its aria-label, or behaves differently from Button's icon-only mode. |
| Governing rules | family:buttons FR1, FR7, AV2, AV6; component:Button; spec:AST-085 FR1, FR4; design:reduced-motion DR1, DR3; architecture:component-size-cascade; architecture:public-component-api. |
This table is a review projection; the body below is authoritative.
Intent
IconButton is the explicit icon-only projection of Button that
family:buttons names. It gives callers one greppable component for a compact
action that shows only an icon, without creating a second action model.
Consumer usage lives in IconButton.doc.mjs.
Compatibility and migration
- Released default preserved:
yes; defaults are Button's - Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- Fixing Button's content mode to icon-only.
- The prop surface: a required
icon, and noisIconOnly,children, orendContent.
Does not own / non-goals
- Every rendered behavior: element, naming rules, size, default square geometry,
click and
clickActionhandling, pending, disabled, link mode, tooltip, elevation, feedback, and thebuttontheme target — owned bycomponent:Button. - An automatic tooltip from
label— not provided; a caller addstooltip(family:buttonsAV6). - Icon rendering — owned by
component:Icon.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Icon-only mode | always on | The icon is the only visible content. | Every variant, size, and state. | on | component:IconButton |
Stable | TypeScript rejects isIconOnly, children, and endContent. |
| Icon | caller node | The visible glyph; required. | Every state; hidden behind the Spinner while pending, unless it paints its own colors (component:Button FR8 gap). |
required | component:IconButton |
Stable | TypeScript rejects a missing icon. |
Every other concept (variant, size, elevation, pending, availability, link mode, width, tooltip) is Button's, with Button's defaults.
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | IconButton renders exactly one Button in icon-only mode with the caller's icon and every other supplied prop, including ref. It adds no element, state, or behavior of its own. |
family:buttons AV2; current source |
| FR2 | The accessible name is label through aria-label whenever label is non-empty; no label text is rendered visibly. |
family:buttons FR1; current source and tests |
| FR3 | With the default icon-only aspect and no caller width, the control is square at the resolved size with no padding. An Astryx Icon without an explicit size renders sm in sm and md IconButtons and md in lg ones; an explicit Icon size wins. |
family:buttons FR7; current tests |
| FR4 | Variant, size, elevation, onClick, clickAction, loading, disabled, and press feedback follow component:Button, including its implementation gaps: disabled follows component:Button FR10 and, with href, FR11, loading follows FR8, whose Spinner MUST appear at once under reduced motion with a fine pointer (design:reduced-motion DR3), and press feedback follows FR15, whose press scale MUST NOT apply under reduced motion (DR1). |
component:Button; design:reduced-motion; current tests |
Allowed variation
- AV1 — Icon content. Any caller node may fill the icon slot; IconButton does not inspect it.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| At rest | Square by default, named by label; icon only. |
Variant, size, theme paint. |
| Floating (elevation) | Shadow for the chosen tier on the surface. | Tier. |
| Loading | Button's pending state: Spinner, aria-busy, still focusable. |
Spinner delay. |
| Disabled | Button's disabled state (component:Button FR10). |
Tooltip present or not. |
Transformation and precedence order
- ORD1 — Content mode. Icon-only always; no caller prop overrides it.
Performance and resources
- PR1 — No added work. IconButton adds no state, effect, listener, or element beyond Button's.
Accessibility contract
- AR1 — Name.
labelis the only accessible name; the icon never substitutes for it (family:buttonsFR1). - AR2 — Visible hint. IconButton shows no visible text. A visible hint
exists only when the caller sets
tooltip, which also describes the button unless it repeats thelabel(component:ButtonFR12). - AR3 — Target size. With the default square aspect, the smallest
IconButton with no
widthis 28 by 28 CSS pixels, above the WCAG 2.5.8 24 by 24 minimum. A callerwidthor theme icon-only aspect that narrows it below 24 CSS pixels leaves target size to that caller or theme. - AR4 — Everything else. Keyboard, focus indicator, loading announcement,
and busy or disabled exposure follow
component:ButtonAR2–AR5.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Square surface | Button's surface at the default 1 / 1 aspect ratio, unless a caller width or theme aspect changes it. |
Current source | Prominent | FR3 |
| Icon | The only visible content, sized from the button. | Current source and tests | Prominent | FR3 |
design:reduced-motion governs the press scale IconButton inherits (FR4). No
other design record governs IconButton. IconButton has no theme target of its own;
it renders Button's button target.
Family and system relationships
family:buttonsnames IconButton the explicit icon-only projection of Button; IconButton adopts FR1, FR7, AV2, and AV6 through Button.component:Buttonowns every rendered behavior IconButton shows.spec:AST-085applies through Button; the gap is recorded there.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2 | IconButton.test.tsx label, visible-text, ref, and displayName cases |
At rest | Visible label text, a lost aria-label, or a dropped ref fails. |
audit:IconButton/anatomy |
| FR3 | IconButton.test.tsx icon size cases |
sm, md, lg; explicit Icon size |
A wrong default Icon size or an overridden explicit size fails. | audit:IconButton/layout |
| FR3 (square) | IconButtonAudit.a11y.chromium.spec.ts sensor receipts |
sm, md, lg in Neutral and Butter, light and dark |
A box that is not square, padding at the Neutral theme, an icon off center, or an icon other than 16px (sm, md) or 20px (lg) at the Neutral theme fails a receipt. |
audit:IconButton/layout |
| FR4 | IconButton.test.tsx click, disabled, loading, and elevation cases |
Click; disabled; loading; none and med elevation |
A click that does not reach onClick, a disabled click that does, a busy IconButton without aria-disabled, or identical classes for two elevations fails. |
audit:IconButton/behavior |
| FR4 (variant, size) | IconButton.test.tsx variant and size reflection cases |
every variant; every size | A dropped or wrong data-variant or data-size fails. |
audit:IconButton/behavior |
| FR4 (reduced motion) | Evidence gap: no test asserts the press or loading result under prefers-reduced-motion: reduce. The pressed IconButtonAudit.a11y.chromium.spec.ts receipt records the shipped 0.98 press scale with reduced motion on, which fails this clause, as the shipped Spinner fade does |
Mouse and touch press; pending clickAction or interruptible loading with a fine pointer |
A computed transform other than none or scale(1) during the press, or a Spinner opacity below 1 after loading starts. |
audit:IconButton/behavior |
| AR1, AR4 | Button.a11y.test.tsx and Button.a11y.chromium.spec.ts IconButton states |
IconButton at rest, disabled, loading | A missing name or a wrong focusable, operable, or unavailable state fails. The shared disabled state expects native disabled, matching the component:Button FR10 gap. |
audit:IconButton/accessibility |
| AR2, AR3 | IconButton.test.tsx tooltip-description case and IconButtonAudit.a11y.chromium.spec.ts sensor receipts |
tooltip on keyboard focus; sm at the Neutral theme |
A tooltip that does not show on focus or describe the button, or an sm target under 28 by 28 CSS pixels at the default aspect, fails. |
audit:IconButton/accessibility |
| ORD1 | IconButton.test.tsx caller isIconOnly case |
caller isIconOnly={false} |
Visible label text or a lost aria-label fails. |
audit:IconButton/behavior |
| PR1 | Evidence gap: no test asserts that IconButton adds no work | — | — | audit:IconButton/behavior |
Current-state impact
- Disabled focusability (FR4). A disabled IconButton without a tooltip
renders native
disabled, ascomponent:ButtonFR10 records, againstspec:AST-085FR1 and FR4. Its unit test and the shared button-pattern suite's disabled state both expect nativedisabled. A focused link-mode IconButton that becomes disabled loses focus with or without atooltip, because its anchor is replaced by a<button>, ascomponent:ButtonFR11 records. - Reduced motion (FR4). A standalone IconButton scales to 0.98 on a press,
and the Spinner of a pending
clickActionor an interruptible IconButton fades in, when the person prefers reduced motion, ascomponent:ButtonFR8 and FR15 record, againstdesign:reduced-motionDR1 and DR3. - Self-colored icon while loading (FR4). An icon that paints its own
colors, such as an image or a multicolor SVG, stays visible under the
Spinner, as
component:ButtonFR8 records.
Decision log
No component-local decision. IconButton applies family:buttons and
component:Button.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.