An open source design system that's fully customizable and agent ready
TypeScript
spec: define Button family behaviors (#6055)
Cindy Zhangcb13c1eaa890
diff --git a/docs/families/buttons.md b/docs/families/buttons.mdnew file mode 100644index 0000000000..a01f751094--- /dev/null+++ b/docs/families/buttons.md@@ -0,0 +1,235 @@+---+schema_version: 1+template_version: 1+kind: family+id: family:buttons+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-09-04+owners: [cixzhang]+review_triggers: [behavior, layout, theming, accessibility, public-api]+verified_by:+ [+ packages/core/src/Button/Button.test.tsx,+ packages/core/src/IconButton/IconButton.test.tsx,+ packages/core/src/ButtonGroup/ButtonGroup.test.tsx,+ packages/core/src/ToggleButton/ToggleButton.test.tsx,+ ]+members:+ [+ component:Button,+ component:IconButton,+ component:ToggleButton,+ component:ButtonGroup,+ component:ToggleButtonGroup,+ ]+architecture:+ [architecture:component-theming-surface, architecture:public-component-api]+contributing: []+deciding_specs: [spec:AST-002/DEC-1]+---++# Button family contract++## Intent++People should encounter one coherent button system whether an action is labeled,+icon-only, persistent, standalone, or grouped. Members share the same control+geometry, accessible-name requirement, interaction feedback, asynchronous-action+model, and surface ownership. Each member still owns the semantics specific to a+momentary action, navigation destination, persistent pressed state, or group.++ToggleButton renders Button's elevation state but cannot currently select the+family's resting elevation axis. The family admits that axis for ToggleButton.+Its transparent ghost surface remains a known visual question: elevation may+provide the floating boundary instead of an opaque fill or outline, and this+contract does not require a new background treatment.++## Membership rule++A component belongs when its primary public purpose is to activate a button-like+action, retain a button's pressed action state, or compose those controls into a+button-specific group while preserving their shared surface and interaction+contract.++- **Members:** Button, IconButton, ToggleButton, ButtonGroup, and+ ToggleButtonGroup.+- **Collaborators:** Spinner supplies pending feedback; Tooltip supplies visible+ explanation; LinkProvider supplies Button's navigation renderer; SizeContext+ supplies inherited control size; DropdownMenu may contribute a button trigger+ to ButtonGroup. These collaborators do not become Button-family members.+- **Excluded:** Link's primary purpose is navigation rather than a button surface.+ Switch, CheckboxInput, and RadioList represent settings or form values rather+ than button actions. SegmentedControl and TabList switch views or destinations+ under their own selection/navigation contracts. Components that merely use a+ Button as a trigger or action slot retain their own family membership.++Membership follows public responsibility, not an import of Button or a rendered+`<button>` element.++## Shared owner++- Button owns the common action surface: native button semantics, focus and press+ feedback, size, visual variant, loading presentation, link mode, and resting+ elevation.+- IconButton is the explicit icon-only projection of Button and inherits that+ surface contract without creating another action model.+- ToggleButton reuses the Button surface and adds a persistent controlled pressed+ state, pressed-state visuals, and an interruptible pressed Action.+- ButtonGroup owns connected action-group geometry, roving focus, inherited size+ and disabled state, and one shared connected elevation.+- ToggleButtonGroup owns single- or multiple-selection state and the layout of+ distinct ToggleButton surfaces. It does not become a connected visual surface+ merely because it groups selection.+- Shared primitives retain their own contracts. Spinner, Tooltip, Icon, Link, and+ DropdownMenu behavior does not become Button-specific when composed into a+ member.++## Canonical concepts++| Concept | Values or states | Default semantics | Stability |+| ---------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |+| activation model | momentary action, navigation, persistent press | Button and IconButton activate once; ToggleButton represents retained pressed state | shipped distinction |+| content mode | visible label, custom visible content, icon-only | every control has a required accessible `label`; icon-only hides it visually | shipped family rule |+| size | `sm`, `md`, `lg` | `md`; explicit member size wins over an inherited group size | shipped family axis |+| visual state | rest, hover, focus, active, disabled, loading; pressed where applicable | states preserve control geometry and accessible purpose | shipped family rule |+| async action | absent, fire-once, interruptible persistent action | ordinary actions deduplicate while pending; persistent toggles remain reversible | shipped family distinction |+| elevation | `none`, `low`, `med`, `high` | `none`; the element painting the visible surface owns the shadow | shipped family axis; ToggleButton adoption approved |+| grouping | standalone, spaced set, connected surface | semantics and painted containment decide ownership; grouping alone does not | family rule |++## Cross-component invariants++- **FR1 — Every control has an accessible name.** A Button-family control MUST+ receive a non-empty accessible `label`. A text control renders that label or+ caller-provided visible content. An icon-only control exposes the label through+ `aria-label`; its icon does not substitute for a programmatic name.+- **FR2 — Native action semantics are the default.** A momentary or persistent+ action renders an operable button with keyboard activation, focus-visible+ feedback, and `type="button"` unless the component's documented form mode says+ otherwise. Button's `href` mode is the explicit navigation variation and also+ follows `family:navigation-destinations`.+- **FR3 — Disabled means non-operable.** A disabled member MUST NOT invoke its+ callback or Action. When a disabled reason requires focus, the component MAY use+ focusable `aria-disabled` semantics while still blocking activation. A group+ disabled state overrides member availability.+- **FR4 — Pending feedback preserves purpose and geometry.** Where a member+ exposes loading or an Action, pending work MUST set `aria-busy`, keep the+ control's dimensions stable, and present a Spinner without changing the+ accessible purpose. Explicit disabled styling and pending styling remain+ distinct.+- **FR5 — Callback and Action order is consistent.** Where a member exposes both+ a synchronous callback and an Action, the callback runs first. Preventing that+ event prevents the Action. A fire-once action deduplicates activation while+ pending; an explicitly interruptible persistent action may accept a new+ activation and replace the in-flight intent.+- **FR6 — Persistent state is explicit and reversible.** A ToggleButton MUST+ expose its effective state with `aria-pressed` and request the next controlled+ value on activation. Pending state may be optimistic, but a new activation MUST+ derive from the effective in-flight value rather than a stale committed value.+- **FR7 — Shared size preserves family geometry.** Members using the family size+ axis MUST map `sm`, `md`, and `lg` to the same control-height contract. An+ icon-only member is square at the resolved size. Label weight, pressed state,+ loading, or icon replacement MUST NOT change its outer dimensions.+- **FR8 — Elevation belongs to the painted surface.** A standalone member that+ paints its visible surface owns its resting elevation. A connected group that+ paints one continuous surface owns one shared elevation and its members paint+ effective elevation `none`. A semantic or layout group that paints no shared+ surface MUST NOT acquire elevation solely because it contains buttons.+- **FR9 — Elevation is independent from interaction state.** Pressed, hover,+ focus, active, loading, disabled, and icon states MUST NOT change the owner or+ tier of elevation. They may change the treatment painted on that surface.+- **FR10 — Public, rendered, and theming states agree.** When a member exposes a+ family visual axis, its public prop, effective rendered `data-*` state, and+ documented theme visual prop MUST describe the value it actually paints. A+ wrapper MUST NOT report an ignored child value as effective output.+- **FR11 — A button-specific group has one accessible owner.** ButtonGroup and+ ToggleButtonGroup MUST expose an accessible group label and propagate their+ documented size and disabled defaults without removing a member's accessible+ name. The group owns only the behavior and surface declared by its group mode.+- **FR12 — Connected and spaced groups stay distinct.** ButtonGroup's connected+ presentation removes inter-member gaps, shares outer edges, owns one elevation,+ and uses its documented roving-focus keyboard model. The current+ ToggleButtonGroup keeps distinct child surfaces separated by a gap; each child+ may own its own elevation, and the wrapper owns no shadow. A future connected+ toggle presentation MUST move elevation to the group and make members flat.++## Allowed component variation++- **AV1 — Momentary versus persistent action.** Button and IconButton do not+ retain pressed state. ToggleButton owns `isPressed`, `onPressedChange`,+ `pressedChangeAction`, and pressed-state presentation.+- **AV2 — Visible versus icon-only content.** Button may render a visible label,+ custom visible content, a leading icon, and end content. IconButton always+ renders one required icon with no visible label. ToggleButton may use either+ visible or icon-only content and may replace its icon when pressed.+- **AV3 — Visual emphasis.** Button and IconButton expose the Button variant map.+ ToggleButton owns its selected/depressed treatment instead of inventing a+ momentary-action hierarchy. Themes may vary appearance without changing these+ semantics.+- **AV4 — Navigation.** Button and IconButton may render as links when `href` is+ supplied. ToggleButton remains an action with `aria-pressed`; navigation backed+ by its Action does not turn the control into a destination link.+- **AV5 — Group keyboard model.** ButtonGroup may use roving focus for a connected+ action cluster. ToggleButtonGroup retains the keyboard and selection behavior+ documented for its pressed-button set. Visual similarity alone does not require+ both groups to use the same composite-widget model.+- **AV6 — Tooltip ownership.** A component may require an explicit tooltip or+ provide a documented automatic tooltip for icon-only use. The accessible label+ remains required either way.++## Representative matrix++| Member and state | Shared invariant | Deliberate variation |+| -------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- |+| `component:Button` / ordinary action | named, sized, focusable action surface; fire-once pending behavior | visible content, variants, form type, and optional link mode |+| `component:IconButton` / compact action or FAB | Button behavior, square geometry, family elevation | required icon; label is programmatic rather than visible |+| `component:ToggleButton` / pressed and unpressed | Button geometry, naming, focus, pending, and surface ownership | controlled `aria-pressed`, pressed icon/treatment, interruptible Action |+| `component:ButtonGroup` / horizontal or vertical | labeled group; inherited size/disabled state | connected edges, one shared elevation, roving focus |+| `component:ToggleButtonGroup` / single or multiple | labeled group; inherited size/disabled state | selection owner; spaced child surfaces; no wrapper elevation |+| future connected toggle group | labeled selection group and pressed semantics | one painted group surface owns elevation; members paint none |++## Adoption and exceptions++| Component | Current adoption | Gap or exception |+| ----------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |+| `component:Button` | owns the shared surface, size, state, Action, link, and elevation mechanisms | link mode additionally follows `family:navigation-destinations` |+| `component:IconButton` | inherits Button props and always selects icon-only presentation | tooltip remains explicit consumer guidance |+| `component:ToggleButton` | inherits Button geometry, focus, pending presentation, and rendered elevation state | approved adoption gap: add the existing optional `elevation` prop and matching theme metadata |+| `component:ButtonGroup` | connected surface, inherited size/disabled state, shared elevation, and roving focus | member elevation is intentionally suppressed while connected |+| `component:ToggleButtonGroup` | controlled single/multiple selection, inherited size/disabled state, and spaced layout | wrapper is not a painted surface and therefore exposes no family elevation |++ToggleButton elevation is an approved implementation gap. Adding the existing+optional `Elevation` axis restores family parity without changing no-prop+rendering. Its current transparent surface is accepted without claiming the+transparency question is solved; the shadow may provide the floating boundary,+and any later fill or outline treatment requires separate visual review.++## Verification map++| Contract | Verification | Representative members and states | Mutation or failure expectation |+| --------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |+| FR1–FR3 | role/name, keyboard, callback, disabled, and disabled-reason tests | text Button, IconButton, ToggleButton, link mode, member/group disabled | a member loses its name, keyboard path, or invokes while disabled |+| FR4–FR6 | Action order, pending, optimistic, dedupe, and interruptibility tests | Button fire-once Action; ToggleButton rapid pressed/unpressed Actions | dimensions or purpose change, Action bypasses callback cancellation, or stale state wins |+| FR7 | unit plus real-browser geometry checks | all sizes; text/icon-only; pressed/unpressed; loading | family heights diverge, icon-only stops being square, or state shifts outer size |+| FR8–FR10 | data attribute, theme metadata, and computed-shadow tests | standalone Button/IconButton/ToggleButton; connected and spaced groups; every elevation tier | shadow lands on the wrong box, state changes depth, or public/theme/rendered values disagree |+| FR11–FR12 | group semantics, propagation, DOM, keyboard, and rendered-surface tests | connected ButtonGroup; spaced ToggleButtonGroup; horizontal/vertical; disabled members | group lacks a name, default propagation fails, or spaced/connected ownership is conflated |++## Decision links++- `spec:AST-002/DEC-1` — public API admission is explicit and evidence-backed.+- `family:navigation-destinations` — Button link mode retains the shared+ navigation safety contract.++## Open questions++None.++## Content boundary++This file owns only cross-component Button-family behavior. Component-specific+prop tables, callback payload types, selection algorithms, variants, tooltip+policy, group layouts, implementation mechanisms, current audit results, and+product-specific action hierarchy remain with their component, architecture,+design, audit, or callsite owners.