An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Button authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-25 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/Button/Button.test.tsx, packages/core/src/Button/Button.hitArea.test.tsx, packages/core/src/ButtonGroup/ButtonGroup.test.tsx, packages/core/src/Button/tests/Button.a11y.test.tsx, packages/core/src/Button/tests/Button.a11y.chromium.spec.ts, packages/core/src/Button/tests/ButtonTextSize.interaction.browser.spec.ts, packages/core/src/tests/ReducedMotionPress.a11y.chromium.spec.ts, packages/core/src/Layout/tests/edgeCompensation.test.tsx, packages/core/src/utils/pressFeedback.test.ts, ] modules: [] families: [family:buttons, family:navigation-destinations] design_specs: [design:reduced-motion] architecture: [ architecture:component-size-cascade, architecture:component-theming-surface, architecture:interaction-modality, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-005, spec:AST-085, spec:AST-086]
Button component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | None changes. This record states the shipped Button surface: label, variant, size, elevation, content mode, loading and clickAction, isInterruptible, disabled, tooltip, width, form attributes, and link mode. |
| Behavior | A named native <button type="button"> by default. Pending work shows a centered Spinner over content that keeps its space, sets aria-busy, and stays focusable. href renders a link unless the Button is truly disabled. |
| End-user impact | Everyone gets one action control whose size does not move when it loads. Keyboard users keep focus on a busy Button. A disabled Button without a tooltip is still removed from the tab order, so keyboard users cannot find it or hear that it is disabled. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior, except FR15's mouse and pen press (Current-state impact); no API, default, or DOM change. Native disabled on a truly disabled Button conflicts with spec:AST-085 FR1 and FR4, and the Spinner fade under reduced motion conflicts with design:reduced-motion DR3; all are listed under Current-state impact. |
| Review checks | Reject a Button with no accessible name, a pending state that changes outer size or drops focus, a fire-once clickAction that runs twice for one double-click, a disabled link that still navigates, or data-* theme state that disagrees with painted state. |
| Governing rules | family:buttons FR1–FR10; family:navigation-destinations FR1–FR7; spec:AST-085 FR1–FR7; spec:AST-086 FR3–FR4; architecture:component-size-cascade INV3–INV5; architecture:interaction-modality INV1, INV5; design:reduced-motion DR1, DR3. |
This table is a review projection; the body below is authoritative.
Intent
Button is the family's momentary action control. It owns the shared action
surface family:buttons assigns to it: native button semantics, accessible
naming, size, visual variant, press and focus feedback, pending presentation,
link mode, and resting elevation. Consumer usage lives in Button.doc.mjs.
Compatibility and migration
- Released default preserved:
yes;variant="secondary",size="md",elevation="none", andtype="button"are the defaults - Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
- Controlled/uncontrolled behavior: not applicable; Button holds no value.
Pending state comes from
isLoadingor an in-flightclickAction - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The action surface: root element choice, accessible name, content order, size, width and truncation, variant paint, hover, press, and focus feedback.
- Click and
clickActionsequencing, fire-once deduplication, and the interruptible opt-out. - Pending presentation: Spinner overlay, hidden content,
aria-busy, and the loading announcement region. - The touch band under a coarse pointer (
spec:AST-094FR42), carried by the content wrapper's::after; the root's::beforeand::afterstay as FR15 and callers use them. - Busy-only and disabled operability guards.
- Link mode's rendering choice and its disabled fallback.
- Standalone resting elevation and the
buttontheme target. - The ghost variant's edge-compensation marker.
Does not own / non-goals
- Connected-group corners, dividers, inherited disabled state, roving focus,
and shared elevation — owned by
component:ButtonGroupunderfamily:buttonsFR8 and FR12. Button paints what the group context supplies. - InputGroup addon geometry — owned by
component:InputGroup. - Icon-only as a dedicated component — owned by
component:IconButton. - Persistent pressed state — owned by
component:ToggleButton. - Destination acceptance and custom-router handoff — owned by
family:navigation-destinationsandspec:AST-005. - Tooltip appearance, timing, and dismissal — owned by
component:Tooltip. - Spinner, Icon, and Badge rendering — owned by those components.
- The touch press controller and
usePressFeedback— uncontracted shared hooks; Button only composes them.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Variant | primary, secondary, ghost, destructive, plus module-augmented entries |
Visual emphasis of the action. | Every mode. | secondary |
component:Button |
Stable | TypeScript rejects values absent from ButtonVariantMap. An augmented value paints the base surface and reflects data-variant. |
| Size | sm, md, lg |
Control height. | Every mode. | Inherited size, else md |
family:buttons |
Stable | TypeScript rejects other values. |
| Elevation | none, low, med, high |
Resting shadow depth. | Standalone only; inside a ButtonGroup the effective value is none. |
none |
family:buttons |
Stable | TypeScript rejects other values. |
| Content mode | visible label, custom visible content, icon-only | What is visible; the accessible name follows ORD4. | Icon-only drops the visible label and end content. | visible label | family:buttons |
Stable | Icon-only with no icon renders an empty square. |
| Pending | idle, loading, action pending | Work is in flight. | isLoading, or while a clickAction promise is unsettled. |
idle | component:Button |
Stable | Not applicable. |
| Interruptible | off, on | Pending work does not block a new activation. | Only changes pending behavior. | off | component:Button |
Stable | Not applicable. |
| Availability | operable, busy-only, disabled | Whether activation runs, and why not. | Disabled comes from isDisabled or an enclosing ButtonGroup; busy-only from pending. |
operable | component:Button |
Stable | Not applicable. |
| Link mode | off, on | Renders the surface as a navigation link. | On when href is supplied and the Button is not disabled. |
off | component:Button |
Stable | A rejected destination renders inertly under family:navigation-destinations. |
| Width | content-sized, explicit length | Inline size; numbers are pixels, strings pass through. | Every mode; still capped at the container except icon-only. | content-sized | component:Button |
Stable | Not applicable. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Without link mode Button renders one native <button> with type="button" unless type says otherwise; name, value, and form reach that element. |
family:buttons FR2; current source and tests |
| FR2 | Content renders in this order: the leading icon slot, the label text (children when supplied, else label), then endContent. Icon-only renders the icon alone and omits the label text and endContent. endContent inherits the Button's text color. |
family:buttons AV2; current source and tests |
| FR3 | An Astryx Icon in the icon slot without an explicit size renders sm in sm and md Buttons and md in lg Buttons; an explicit Icon size wins. |
family:buttons FR7; current source |
| FR4 | Height comes from the shared element size for the resolved size: an explicit size wins, then the nearest size provider, then md. A labelled button's height is that element size, or one line of its label when the line is taller, so under a set text size (spec:AST-102 FR4) the label stays inside its own button; at the default text size the height is the element size, and a caller's height replaces it. Icon-only is square (--button-icon-only-aspect, default 1 / 1) with no padding and keeps the element size, since its glyph does not grow with the text. |
family:buttons FR7; architecture:component-size-cascade INV3–INV5 |
| FR5 | The label stays on one line. A labelled Button may shrink in a row, never exceeds its container's inline size, and truncates the label with an ellipsis. An explicit width applies in button and link modes and is still capped at the container. Icon-only does not shrink and is not capped. |
Current source and tests |
| FR6 | On activation onClick runs first. If it calls preventDefault(), clickAction does not run. Otherwise clickAction runs, and the Button is pending until its promise settles. |
family:buttons FR5; current source and tests |
| FR7 | A fire-once clickAction runs once per in-flight action: a second activation while it is pending, including a same-tick double-click, does nothing. With isInterruptible, a pending Button stays operable and each activation starts a new clickAction. |
family:buttons FR5; current source and tests |
| FR8 | While pending, Button sets aria-busy="true", hides its content from assistive technology, makes content that takes the Button's text color transparent while it keeps its place in layout, and centers a small Spinner in the inherited foreground color over it. Outer size does not change. On a Button that is not interruptible and has no action pending, explicit isLoading hides the content and shows the Spinner at once. For a pending clickAction, or any pending state on an interruptible Button, the content stays painted and the content hide and the Spinner reveal both wait the medium motion delay, so a fast action never flashes a Spinner or an empty Button. The Spinner fades in over the fast duration. Under reduced motion there is no delay, and with a fine pointer the Spinner MUST appear at once (design:reduced-motion DR3). aria-busy is set at once in every case. Implementation gap: under reduced motion the Spinner still fades in over the fast duration with every pointer. Implementation gap: content that paints its own colors, such as a Badge in endContent, stays visible beside the Spinner. |
family:buttons FR4; current source and tests |
| FR9 | Busy-only (pending, not disabled, not interruptible): Button exposes aria-disabled="true", keeps its tab stop, renders no native disabled, and keeps full opacity. Pointer activation is cancelled and does not reach ancestor click handlers; Enter and Space are suppressed; other keys still reach the caller's onKeyDown. A link-mode Button stays a link while busy-only. |
spec:AST-085 FR1, FR2, FR6; current source and tests |
| FR10 | Disabled (isDisabled, or a disabled enclosing ButtonGroup) MUST stay focusable with aria-disabled="true", keep its tab stop and focus, apply FR9's guards, never run onClick or clickAction, and paint at half opacity. Disabled wins over pending: a disabled, loading Button shows the Spinner and aria-busy but follows this row. Implementation gap: only a disabled Button with a tooltip renders this shape; without a tooltip it renders native disabled, which removes it from the tab order and drops focus when it becomes disabled. |
family:buttons FR3; spec:AST-085; current source and tests |
| FR11 | With href and not disabled, Button renders the link component resolved from as, then LinkProvider, then a native anchor, with target and rel, full button styling, and no text decoration. Destination handling follows family:navigation-destinations. A disabled Button with href renders a <button> that follows FR10 and never navigates. Implementation gap: a focused link Button that becomes disabled is replaced by that new <button>, so focus falls to the page with or without a tooltip; without a tooltip the <button> also carries native disabled (FR10). |
family:navigation-destinations FR1–FR7; current source and tests |
| FR12 | With tooltip, the tooltip attaches to the Button element itself (no wrapper element), opens above it, and its content is added to aria-describedby after any caller value, unless its trimmed text equals the Button's accessible name as its props decide it (the derived or caller aria-label, or label when icon and endContent render nothing or a decorative Icon), as Avatar AR5 does, so a tooltip that repeats the name is not read twice. When the name comes from elsewhere (aria-labelledby, or other content in icon or endContent), the tooltip still describes the Button. IconButton inherits this. |
Current source; real-browser accessibility test |
| FR13 | A standalone Button paints the shadow token for its elevation. Inside a ButtonGroup it paints no shadow and reflects data-elevation="none", whatever elevation says. |
family:buttons FR8–FR10; current source and tests |
| FR14 | The root carries astryx-button and reflects the effective data-variant, data-size, and data-elevation. |
family:buttons FR10; architecture:component-theming-surface; tests |
| FR15 | Hover paints the shared interaction overlay on hover-capable pointers, and a press paints the shared pressed overlay through the press controller: at once under a mouse or a pen (spec:AST-094 FR11's fine-pointer profile) and on FR11's control profile under a finger, fading out on release on the theme's exit motion tokens (--duration-exit, --ease-exit; spec:AST-094 FR5). Under a coarse pointer, while a press is on or fading, Button paints the press on its own ::before; a caller's ::before styles apply on top of that layer and win where they overlap, so a decoration that must stay through a touch press belongs on a child element. Without a reduced-motion preference, a standalone Button also scales to 0.98 on a mouse press, or while the touch press reads on; under reduced motion it MUST NOT scale (design:reduced-motion DR1). All of this paint follows the element's exposed disabled state: a Button that is natively disabled or exposes aria-disabled="true" (busy-only, disabled with a tooltip, or a caller's own aria-disabled) shows no overlay and no press scale, even when it stays operable. Inside a ButtonGroup the press scale does not apply. Button's hover and press transitions are fast, and instant under reduced motion. |
Current source and tests; spec:AST-094 FR11 and DEC-21 for the mouse and pen press |
| FR16 | The ghost variant carries the edge-compensation marker so an enclosing container can align it flush with its edge; other variants do not. | Current source; edge-compensation tests |
| FR17 | ref, className, style, xstyle, and other DOM props reach the root element. A caller's own aria-busy and aria-disabled are kept beside Button's own (either one sets the attribute); a caller aria-disabled changes exposure and paint only and does not make the Button inert. The tooltip trigger shares the caller's ref, which stays attached across rerenders. |
Current source and tests |
Allowed variation
- AV1 — Theme paint. Themes may change variant colors, radius (through the
buttontarget), focus offset (--button-focus-offset), and the icon-only aspect without changing anatomy, naming, or operability. - AV2 — Custom variants. A module-augmented variant may be painted entirely
by the theme through
data-variant; Button supplies only the base surface. - AV3 — Visible content.
childrenandendContentmay be any caller content; Button does not inspect them.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Text, at rest | Native button named from its rendered content (icon-slot text, the label, and end-content text), or by a caller aria-label. |
Variant, size, theme paint. |
| Icon-only | Square; aria-label is label; no visible text or end content. |
Icon content. |
| Custom visible content | Visible children; aria-label is label. |
Content shape. |
| Loading | Spinner centered; text-colored content hidden but in layout, on the Spinner's schedule; aria-busy; focusable; same outer size. |
Delay per FR8. |
| Disabled with tooltip | aria-disabled; focusable; dimmed; inert; described by the tooltip. |
Tooltip text. |
| Disabled, no tooltip | Same as with a tooltip: aria-disabled; focusable; dimmed; inert. Implementation gap: native disabled (FR10). |
— |
| Link mode | Link element with button styling; busy-only stays a link. | Link component from as or LinkProvider. |
| In a ButtonGroup | Group corners and dividers; no press scale; effective elevation none. |
Orientation. |
Transformation and precedence order
- ORD1 — Size. Explicit
size, then the nearest size provider, thenmd. - ORD2 — Availability. Disabled, then busy-only, then operable. Interruptible pending is operable.
- ORD3 — Element. Link mode only when
hrefis supplied and the Button is not disabled; otherwise<button>. - ORD4 — Accessible name. Button sets
aria-labeltolabelwhen it is icon-only with a non-empty label, when it is pending and not icon-only, or whenchildrendiffers fromlabel; that value wins over a calleraria-label. Otherwise a calleraria-label, when given, names the Button, and without one the Button is named from its rendered content: any text in theiconslot, the label text, and any text inendContent. A decorative Astryx Icon adds nothing to that name. - ORD5 — Styling. Variant paint applies over the shared focus outline, so
the destructive focus ring takes the error color; caller
xstyleapplies after Button's own styles, thenclassNameandstylemerge.
Performance and resources
- PR1 — No idle work. A Button that mounts idle schedules nothing for its loading region. Only a Button first rendered pending defers the region's text by one animation frame (AR4).
Accessibility contract
- AR1 — Name. Every Button has an accessible name (ORD4), as
family:buttonsFR1 requires:labelwhen Button setsaria-label, otherwise a calleraria-labelor the rendered content, which includes the label text. An icon-only icon never substitutes for the name. - AR2 — Keyboard. A
<button>activates with Enter and Space; a link activates with Enter. Focus order is the DOM order. - AR3 — Focus indicator. Keyboard focus paints the shared focus outline at
--button-focus-offset; the destructive variant colors it with the error color. Visibility followsarchitecture:interaction-modalityINV1. - AR4 — Loading announcement. Button renders one persistent, visually
hidden
role="status"aria-live="polite"region. It holds the localized loading string while pending and is empty otherwise. A Button first rendered pending mounts the region empty and fills it on the next frame (spec:AST-086FR3). Inside a live container it keeps its role and urgency (spec:AST-086FR4). Spoken output followsspec:AST-009. - AR5 — Busy and disabled exposure. Pending sets
aria-busy. Busy-only and disabled Buttons MUST exposearia-disabled="true"on the focusable element (spec:AST-085FR5). Implementation gap: a disabled Button without a tooltip exposes nativedisabledinstead (FR10). - AR6 — Target size. Every Button is at least 28 CSS pixels tall, unless a
caller's height replaces its size (FR4). With the
default square aspect and no
width, an icon-only Button is at least 28 by 28; a labelled Button can shrink in a crowded row only down to its 24 CSS pixels of inline padding. Both meet the WCAG 2.5.8 24 by 24 minimum. A callerwidthor a theme icon-only aspect that makes a Button narrower than 24 CSS pixels, or a caller height under 24 CSS pixels, leaves its target size to that caller or theme.
Implementation gap: Button's hover and pressed overlays on the dark accent give its label 4.35:1 and 4.02:1, under 4.5:1.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Primary surface | Accent fill with on-accent text. | Current source | Prominent | FR14 |
| Secondary surface | Neutral fill with primary text. | Current source | Supporting | FR14 |
| Ghost surface | Transparent fill with primary text; edge-compensatable. | Current source | Supporting | FR14, FR16 |
| Destructive surface | Error fill with on-error text and an error-colored focus ring. | Current source | Prominent | FR14, AR3 |
| Press | Pressed overlay on a Button not exposed as disabled, plus a 0.98 scale when standalone and motion is not reduced. | Current source; design:reduced-motion DR1 |
Supporting | FR15 |
| Disabled | Half opacity; no hover or press paint. | Current source | Supporting | FR10, FR15 |
| Pending | Spinner over hidden content; full opacity when busy-only. | Current source | Supporting | FR8, FR9 |
design:reduced-motion governs Button's press scale (FR15). No other design
record governs Button; exact paint stays in code and visual evidence.
The root carries the one button target (FR14). Icon, Label, and End content
have no target of their own and take color from button; the Spinner is a
Spinner instance with the inherited shade. The touch band has no target. The
consumer anatomy names no root part, so this record carries no
anatomy-theming map.
Family and system relationships
family:buttonsowns the shared naming, size, pending, callback-order, elevation, and state-agreement rules; Button adopts them and is the surface IconButton and ToggleButton reuse.family:navigation-destinationsandspec:AST-005own link-mode destination handling.spec:AST-085owns disabled focusability; Button meets it for busy-only and tooltip-disabled states and not for other disabled states (FR10).spec:AST-086owns the loading region's live-region rules (AR4).architecture:component-size-cascadeowns size inheritance (ORD1).architecture:component-theming-surfaceowns target anddata-*rules (FR14).architecture:interaction-modalityowns focus-indicator visibility (AR3).
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2, AR1 | Button.test.tsx label, children, icon-only, end-content presence, and type cases; Button.a11y.test.tsx; Button.a11y.chromium.spec.ts |
Text, icon-only, composed label, end content, submit type | A lost name, a wrong default type, or end content in icon-only fails. |
audit:Button/anatomy |
| FR1, FR2 (gaps) | Evidence gap: no test passes name, value, or form, or asserts the order of icon, label, and end content |
— | — | audit:Button/anatomy |
| FR3 | Evidence gap: no Button-level test of the text-mode icon slot default | sm, md, lg with an unsized Icon |
— | audit:Button/anatomy |
| FR4 | ButtonTextSize.interaction.browser.spec.ts (a label larger than the element size grows its button; at the default text size the Neutral and Butter themes' labelled buttons keep their element heights); Button.test.tsx default size geometry (a caller's height and the block padding hold). Evidence gap: no test asserts the explicit size, then nearest provider, then md order |
sm, md, lg; inside a size provider |
— | audit:Button/layout |
| FR5 | Button.test.tsx width and narrow-row suites; InputGroup addon case |
Numeric and string width, link mode, icon-only, grouped | A Button that overflows its row, stops truncating, or squeezes icon-only fails. | audit:Button/layout |
| FR6, FR7 | Button.test.tsx click, double-click, and interruptible suites |
onClick then clickAction; preventDefault; double-click; re-click | Order flips, a prevented click runs the action, or a fire-once action runs twice fails. | audit:Button/behavior |
| FR8, AR4 | Button.test.tsx loading, spinner shade, and live-region suites |
isLoading; pending clickAction; first render loading |
Missing aria-busy, a wrong Spinner shade, or a live region mounted with text fails. |
audit:Button/behavior |
| FR8 (hide and delay) | Evidence gap: no test asserts the hidden content, the reveal delay, or the reduced-motion path; the shipped Spinner fade fails the fine-pointer reduced-motion clause (Current-state impact) | isLoading; pending clickAction; interruptible |
Under reduced motion with a fine pointer, a Spinner opacity below 1 after the loading state starts. | audit:Button/behavior |
| FR8 (outer size) | Evidence gap: no test measures that a pending Button keeps its outer size | Loading text, icon-only, and end-content Buttons | — | audit:Button/layout |
| FR9, FR10, AR5 | Button.test.tsx aria-disabled, busy-only, and native-disabled suites; Button.a11y.chromium.spec.ts |
Busy-only, tooltip-disabled, disabled, disabled and loading | A busy Button loses focus, an inert Button fires, or a click reaches an ancestor fails. Native-disabled assertions match the FR10 gap. | audit:Button/accessibility |
| FR11 | Button.test.tsx link-mode suites |
Link, busy-only link, disabled href |
A disabled link navigates or a busy link turns into a <button> fails. |
audit:Button/behavior |
| FR12 | Button.a11y.chromium.spec.ts described state |
Disabled with tooltip | A tooltip that does not describe the Button fails. | audit:Button/accessibility |
| FR12 (placement and order) | Evidence gap: no test asserts that the tooltip opens above the Button or that its id follows a caller aria-describedby |
Tooltip with and without a caller description | — | audit:Button/accessibility |
| FR13, FR14 | Button.test.tsx theme-target and elevation suites; ButtonGroup.test.tsx "reports flat on a member, since the group owns the surface" for the grouped data-elevation="none" |
secondary target attributes; every elevation tier |
A missing target, or a data-elevation other than the effective tier, fails. |
audit:Button/theming |
| FR13 (painted shadow) | Evidence gap: no test reads the painted shadow, so a grouped Button that paints its own shadow, or swapped tier shadows, would pass | Standalone tiers; grouped member | — | audit:Button/theming |
| FR14 (per variant) | Evidence gap: data-variant is asserted for secondary only |
Other variants | — | audit:Button/theming |
| FR15 | Button.test.tsx touch pressed-state suite |
Touch press on and fading | Losing the touch press arm or its release fade fails. | audit:Button/behavior |
| FR15 (disabled paint) | pressFeedback.test.ts "paints nothing on a disabled surface, and does not light the row around it" for the touch press. Evidence gap: no test of the hover and pressed overlays or the mouse scale on a Button exposed as disabled |
Native disabled; aria-disabled |
A disabled surface that takes the touch press fails. | audit:Button/behavior |
| FR15 (reduced motion) | ReducedMotionPress.a11y.chromium.spec.ts ("a pressed button never scales under reduced motion, with a mouse or a finger (DR1)") |
Mouse press; touch press | A computed transform other than none or scale(1) during the press. |
audit:Button/behavior |
spec:AST-094 FR42 |
Button.hitArea.test.tsx: a standalone and a link Button take the touch band on their content wrapper, and a caller's ::after stays on the button; a disabled, busy-only or grouped Button, or a Button whose tracking group draws its band, takes none |
standalone; link; caller ::after; disabled; busy-only; grouped; tracking group draws the band |
A Button without the band fails. So does a disabled, busy-only or grouped Button with its own, or a Button with its own whose tracking group draws its band. | audit:Button/behavior |
| FR15 (hover and mouse scale) | Evidence gap: no test asserts the hover overlay or the 0.98 mouse-press scale | Hover; mouse press, standalone and grouped | — | audit:Button/behavior |
| FR16 | edgeCompensation.test.tsx Button data-attribute suite |
Ghost and primary | A ghost Button without the marker, or a primary Button with it, fails. | audit:Button/layout |
| FR17 | Button.test.tsx ref suites and the caller aria-disabled/aria-busy case |
Initial render and rerender; caller aria-busy and aria-disabled |
A dropped or detached ref, or a dropped caller aria-busy or aria-disabled, fails. Evidence gap: no test asserts that a caller aria-disabled leaves the Button operable. |
audit:Button/behavior |
| ORD1, ORD5 | Evidence gap: no test asserts size precedence (see FR4) or that caller xstyle, className, and style win over Button's own styles |
— | — | audit:Button/behavior |
| ORD4 | Button.test.tsx icon-only and composed-label cases. Evidence gap: no test asserts the aria-label set while pending or when children differs from label, or the content name with icon-slot or end-content text |
Icon-only; composed label | An icon-only Button without aria-label, or a composed label that gains one, fails. |
audit:Button/accessibility |
| AR2 | Button.a11y.chromium.spec.ts activation and tab-reachability checks. Evidence gap: no test of Enter activation in link mode |
Text and icon-only Buttons | A Button that Enter or Space does not activate, or that Tab skips, fails. | audit:Button/accessibility |
| AR3 | Evidence gap: no test asserts the focus outline or the destructive error-colored ring | Keyboard focus; destructive | — | audit:Button/accessibility |
| AR6, PR1 | Evidence gap: no test measures the target size or asserts that an idle Button schedules nothing | — | — | audit:Button/behavior |
Current-state impact
- FR15's mouse and pen press through the press controller is not implemented:
a mouse press still paints with
:active(spec:AST-094DEC-21). - Disabled focusability (FR10, FR11, AR5). A Button disabled by
isDisabledor a ButtonGroup without a tooltip, including one withhref, renders nativedisabled. It leaves the tab order and drops focus when it becomes disabled, againstspec:AST-085FR1 and FR4 andfamily:buttonsFR3. The shared button-pattern browser states record this state as not focusable. A focused link Button that becomes disabled also loses focus with atooltip, because its anchor is replaced by a<button>. - Consumer docs.
Button.doc.mjsdescribes the Spinner as replacing the icon; it overlays all content (FR8). The ChineseisLoadingtext says loading disables interaction, and itsicontext says an icon without children renders a square button; icon-only depends onisIconOnly(FR2). - End-content doc type (AV3).
Button.doc.mjstypesendContentasReactElement<IconProps> | ReactElement<BadgeProps>, and its Chinese text says it accepts only an Icon or a Badge, whileButtonPropstypes itReactNodeand any caller content renders. - Spinner fade under reduced motion (FR8). With a fine pointer the Spinner
still fades in over the fast duration when the person prefers reduced motion,
against
design:reduced-motionDR3. - Self-colored end content while loading (FR8). A Badge or other content that paints its own colors stays visible beside the Spinner.
Decision log
No component-local decision. Button applies the family and system decisions linked above.
Open questions
None. The content wrapper is a real box, so no display: contents element
stands between the Button and its label for WebKit to drop the name through.
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.