@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Toast/ToastViewport.test.tsx

@@ -442,6 +442,143 @@ describe('ToastViewport visible limit', () => {
   });
 });
 
+describe('dismissing a toast that has no mounted row', () => {
+  function ShowAndKeepDismiss({
+    options,
+    label,
+    onShown,
+  }: {
+    options: ToastOptions;
+    label: string;
+    onShown: (dismiss: () => void) => void;
+  }) {
+    const toast = useToast();
+    return (
+      <button type="button" onClick={() => onShown(toast(options))}>
+        {label}
+      </button>
+    );
+  }
+
+  it('reports a hidden toast once when it is dismissed twice before the viewport renders again', () => {
+    const onHideA = vi.fn();
+    let dismissA: (() => void) | null = null;
+    render(
+      <ToastViewport isTopLayer={false} maxVisible={1}>
+        <ShowAndKeepDismiss
+          options={{body: 'Toast A', isAutoHide: false, onHide: onHideA}}
+          label="Show A"
+          onShown={dismiss => {
+            dismissA = dismiss;
+          }}
+        />
+        <ShowToastButton
+          options={{body: 'Toast B', isAutoHide: false}}
+          triggerLabel="Show B"
+        />
+      </ToastViewport>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show A'));
+      fireEvent.click(screen.getByText('Show B'));
+    });
+    expect(screen.queryByText('Toast A')).toBeNull();
+
+    // Both calls land in one batch, before the list renders without A.
+    act(() => {
+      dismissA?.();
+      dismissA?.();
+    });
+    expect(onHideA).toHaveBeenCalledTimes(1);
+  });
+
+  it('frees the slot of a toast dismissed while it was hidden past maxVisible', () => {
+    const onHideA = vi.fn();
+    let dismissA: (() => void) | null = null;
+    render(
+      <ToastViewport isTopLayer={false} maxVisible={2}>
+        <ShowAndKeepDismiss
+          options={{body: 'Toast A', isAutoHide: false, onHide: onHideA}}
+          label="Show A"
+          onShown={dismiss => {
+            dismissA = dismiss;
+          }}
+        />
+        <ShowToastButton
+          options={{body: 'Toast B', isAutoHide: false}}
+          triggerLabel="Show B"
+        />
+        <ShowToastButton
+          options={{body: 'Toast C', isAutoHide: false}}
+          triggerLabel="Show C"
+        />
+      </ToastViewport>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show A'));
+      fireEvent.click(screen.getByText('Show B'));
+      fireEvent.click(screen.getByText('Show C'));
+    });
+    // Only the newest two are shown: A is hidden past the limit.
+    expect(screen.queryByText('Toast A')).toBeNull();
+
+    act(() => {
+      dismissA?.();
+    });
+    expect(onHideA).toHaveBeenCalledTimes(1);
+    expect(onHideA).toHaveBeenCalledWith('manual');
+
+    // C leaves. A was dismissed, so it must not come back to hold the slot
+    // as an empty row: B is the only toast left.
+    const toastC = getToastWrapperByText('Toast C');
+    act(() => {
+      fireEvent.click(
+        within(toastC).getByRole('button', {name: 'Dismiss notification'}),
+      );
+    });
+    act(() => {
+      completeExit(toastC.dataset.toastId ?? '');
+    });
+    expect(document.querySelectorAll('[data-toast-id]')).toHaveLength(1);
+    expect(screen.getByText('Toast B')).toBeInTheDocument();
+
+    // Once B leaves too, nothing is left: no row, no empty landmark.
+    const toastB = getToastWrapperByText('Toast B');
+    act(() => {
+      fireEvent.click(
+        within(toastB).getByRole('button', {name: 'Dismiss notification'}),
+      );
+    });
+    act(() => {
+      completeExit(toastB.dataset.toastId ?? '');
+    });
+    expect(document.querySelectorAll('[data-toast-id]')).toHaveLength(0);
+    expect(screen.queryByRole('region', {name: 'Notifications'})).toBeNull();
+    expect(onHideA).toHaveBeenCalledTimes(1);
+  });
+
+  it('never shows a toast dismissed before it rendered, and reports it once', () => {
+    const onHide = vi.fn();
+    render(
+      <ToastViewport isTopLayer={false}>
+        <ShowAndKeepDismiss
+          options={{body: 'Toast gone', isAutoHide: false, onHide}}
+          label="Show and dismiss"
+          onShown={dismiss => dismiss()}
+        />
+      </ToastViewport>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show and dismiss'));
+    });
+
+    expect(document.querySelectorAll('[data-toast-id]')).toHaveLength(0);
+    expect(screen.queryByRole('region', {name: 'Notifications'})).toBeNull();
+    expect(onHide).toHaveBeenCalledTimes(1);
+    expect(onHide).toHaveBeenCalledWith('manual');
+  });
+});
+
 describe('ToastViewport keyboard reach + focus', () => {
   it('F6 moves focus into the newest toast', () => {
     renderViewport(

package/src/Toast/ToastViewport.tsx

@@ -36,6 +36,7 @@ import {LayerContentBoundary} from '../Layer/layerScopedContext';
 import {
   getActiveModalOutlet,
   subscribeModalOutlets,
+  type ModalOutletChange,
 } from '../Layer/modalOutlet';
 import {ToastSurface} from './Toast';
 import {ToastContext, type ToastContextValue} from './ToastContext';
@@ -348,6 +349,9 @@ export function ToastViewport({
   // Toast ids whose exit has begun — guards onHide from double-firing (see
   // removeToast). Mirrors exitingIds state, readable synchronously.
   const exitingIdsRef = useRef<Set<string>>(new Set());
+  // Toasts dispatched since the last commit, by id: a dismiss() called
+  // before the toast first renders still finds it (and its onHide).
+  const pendingEntriesRef = useRef<Map<string, ToastEntry>>(new Map());
   // The element that was focused before the user jumped into the viewport
   // (via F6). Used to restore focus once all toasts are dismissed so focus
   // never falls to <body>.
@@ -423,6 +427,16 @@ export function ToastViewport({
         // else to the polite region (role="status") — mirrors Toast.tsx.
         announce(text, entry.options.type === 'error' ? 'assertive' : 'polite');
       }
+      const pending = pendingEntriesRef.current;
+      if (uniqueID) {
+        // An overwrite replaces a toast that has not rendered yet too.
+        for (const [pendingId, pendingEntry] of pending) {
+          if (pendingEntry.options.uniqueID === uniqueID) {
+            pending.delete(pendingId);
+          }
+        }
+      }
+      pending.set(entry.id, entry);
       // An overwrite swaps a new entry, with a new id, into the replaced
       // toast's place, so the old row leaves the DOM without ever being
       // dismissed. Its settled id is dropped by the prune below, which covers
@@ -449,11 +463,15 @@ export function ToastViewport({
     if (exitingIdsRef.current.has(id)) {
       return;
     }
-    exitingIdsRef.current.add(id);
-    const entry = toastsRef.current.find(t => t.id === id);
-    if (entry) {
-      entry.options.onHide?.(reason);
+    const entry =
+      toastsRef.current.find(t => t.id === id) ??
+      pendingEntriesRef.current.get(id);
+    if (entry == null) {
+      // Already gone: nothing to hide or report.
+      return;
     }
+    exitingIdsRef.current.add(id);
+    entry.options.onHide?.(reason);
     // If focus currently lives inside the toast being dismissed, remember
     // that its removal must hand focus off to a neighbor (or the element
     // focused before the user entered the viewport) rather than <body>.
@@ -480,6 +498,20 @@ export function ToastViewport({
         pendingFocusRef.current = 'restore';
       }
     }
+    if (dismissedNode == null) {
+      // No row is mounted for it: it is hidden past `maxVisible`, or it has
+      // not rendered yet. Nothing animates out, so it leaves the list now.
+      // Waiting for its row to finish exiting would keep it forever: when it
+      // surfaced, its row would mount already collapsed, with no transition
+      // left to end, and hold a visible slot as an empty row.
+      // It leaves the committed list now too, so a second dismissal before
+      // the next render finds nothing to report.
+      exitingIdsRef.current.delete(id);
+      pendingEntriesRef.current.delete(id);
+      toastsRef.current = toastsRef.current.filter(t => t.id !== id);
+      setToasts(prev => prev.filter(t => t.id !== id));
+      return;
+    }
     setExitingIds(prev => {
       if (prev.has(id)) {
         return prev;
@@ -490,6 +522,7 @@ export function ToastViewport({
 
   const handleExited = useCallback((id: string) => {
     exitingIdsRef.current.delete(id);
+    pendingEntriesRef.current.delete(id);
     setExitingIds(withoutId(id));
     setToasts(prev => prev.filter(t => t.id !== id));
   }, []);
@@ -583,7 +616,7 @@ export function ToastViewport({
     if (!isTopLayer || host == null) {
       return;
     }
-    const place = () => {
+    const place = (change: ModalOutletChange = 'outlet') => {
       const parent = getActiveModalOutlet() ?? rootOutletRef.current;
       if (parent == null) {
         return;
@@ -599,7 +632,9 @@ export function ToastViewport({
       }
       // Leaving the document hid the popover. Showing it again puts it above
       // the modal that just opened, or above everything once the last modal
-      // closed.
+      // closed. A non-modal surface that entered the top layer (`entry`)
+      // moved nothing, so the viewport leaves and re-enters in place to get
+      // above it; focus inside it is kept across the re-entry.
       const el = viewportRef.current;
       if (el == null || typeof el.showPopover !== 'function') {
         return;
@@ -610,6 +645,28 @@ export function ToastViewport({
       } catch {
         /* :popover-open unsupported */
       }
+      if (isShowing && change === 'entry') {
+        const active = document.activeElement;
+        const hadFocus = active instanceof HTMLElement && el.contains(active);
+        try {
+          el.hidePopover();
+          isShowing = false;
+        } catch {
+          /* not a showing popover */
+        }
+        if (isShowing) {
+          return;
+        }
+        try {
+          el.showPopover();
+        } catch {
+          /* already showing */
+        }
+        if (hadFocus) {
+          active.focus({preventScroll: true});
+        }
+        return;
+      }
       if (!isShowing) {
         try {
           el.showPopover();

package/src/ToggleButton/ToggleButton.spec.md

@@ -0,0 +1,256 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:ToggleButton
+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/ToggleButton/ToggleButton.test.tsx,
+    packages/core/src/ToggleButton/__tests__/ToggleButton.a11y.test.tsx,
+    packages/core/src/ToggleButton/__tests__/ToggleButton.a11y.chromium.spec.ts,
+  ]
+modules: []
+families: [family:buttons]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:component-style-authoring,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-085]
+---
+
+# ToggleButton component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. ToggleButton takes `label`, `isPressed`, `onPressedChange`, `pressedChangeAction`, `icon`, `pressedIcon`, `isIconOnly`, `children`, `size`, `elevation`, `isDisabled`, `isLoading`, `tooltip`, and `value`.                                                                                                                                                                            |
+| Behavior                | A ghost Button with `aria-pressed`. Standalone, it requests the next pressed value from the caller and may run an interruptible Action with an optimistic pressed state. As a valued ToggleButtonGroup member, the group owns both.                                                                                                                                                                  |
+| End-user impact         | People see and hear whether a toggle is on. A pending toggle shows its new state at once and can be reversed by clicking again. The label does not shift width when pressed. A disabled toggle without a tooltip leaves the tab order.                                                                                                                                                               |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                                                                |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Native `disabled` without a tooltip conflicts with `spec:AST-085` FR1 and FR4; Button's reduced-motion gaps apply; a pre-prevented click skips the Action; caller pressed attributes override ToggleButton's own; the label renders twice; consumer docs promise a tooltip that does not exist. All are listed under Current-state impact. |
+| Review checks           | Reject a toggle without `aria-pressed`, a caller `onClick` that replaces the toggle request, an Action that runs after a prevented callback, a re-click derived from a stale committed value, or pressed state that shifts outer size.                                                                                                                                                               |
+| Governing rules         | `family:buttons` FR1–FR11, AV1–AV4; `component:Button`; `spec:AST-085` FR1, FR4; `design:reduced-motion` DR1, DR3; `architecture:public-component-api` INV5; `architecture:component-style-authoring` INV7.                                                                                                                                                                                          |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ToggleButton is the family's persistent-press control. It reuses Button's
+surface and adds a controlled pressed state, pressed-state paint, an optional
+pressed icon, and an interruptible pressed Action, as `family:buttons`
+assigns. Consumer usage lives in `ToggleButton.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; unpressed, `size="md"`, `elevation="none"`
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: controlled only. `isPressed` (default
+  `false`) is the committed value; ToggleButton holds no committed state of its
+  own, only an optimistic value while an Action is pending
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The effective pressed state, `aria-pressed`, and the next-state request.
+- Callback, caller `onClick`, and Action ordering for a standalone toggle.
+- The optimistic pressed value while an Action is pending.
+- Pressed paint, the pressed icon swap, the pressed label weight, and a
+  stable outer size while pressed.
+- The `toggle-button` target and its `isPressed` and `elevation` reflection.
+- How a valued member defers to its ToggleButtonGroup.
+
+**Does not own / non-goals**
+
+- The surface, naming rules, size heights, pending presentation, disabled
+  rendering, tooltip, link mode, and feedback — owned by `component:Button`.
+- Group selection state, single or multiple mode, and group layout — owned by
+  `component:ToggleButtonGroup`.
+- On/off settings — owned by `component:Switch`.
+- Inheriting an outer size provider — not provided (OQ1).
+
+## Public concepts
+
+| Concept        | Closed values or states      | Meaning                                         | Availability by variant/orientation/state                         | Default               | Owner                    | Stability | Invalid-value behavior                        |
+| -------------- | ---------------------------- | ----------------------------------------------- | ----------------------------------------------------------------- | --------------------- | ------------------------ | --------- | --------------------------------------------- |
+| Pressed        | pressed, unpressed           | The retained on/off state.                      | Standalone from `isPressed`; valued group members from the group. | unpressed             | `component:ToggleButton` | Stable    | Not applicable.                               |
+| Pressed Action | absent, idle, pending        | Async work run for a standalone toggle.         | Standalone only; ignored for valued group members.                | absent                | `component:ToggleButton` | Stable    | Not applicable.                               |
+| Pressed icon   | caller node                  | The icon shown while pressed.                   | When pressed; falls back to `icon`.                               | `icon`                | `component:ToggleButton` | Stable    | Not applicable.                               |
+| Group value    | string                       | Identifies the member to its ToggleButtonGroup. | Inside a ToggleButtonGroup.                                       | none                  | `component:ToggleButton` | Stable    | Without `value`, a member behaves standalone. |
+| Size           | `sm`, `md`, `lg`             | Control height.                                 | Always.                                                           | Group size, else `md` | `family:buttons`         | Stable    | TypeScript rejects other values.              |
+| Elevation      | `none`, `low`, `med`, `high` | Resting shadow depth.                           | Standalone and inside a ToggleButtonGroup.                        | `none`                | `family:buttons`         | Stable    | TypeScript rejects other values.              |
+
+## Behavioral and layout contract
+
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Basis                                                                                                            |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| FR1  | ToggleButton renders one Button with the `ghost` variant and Button's interruptible pending mode, and sets `aria-pressed` to the effective pressed value. Other supplied props reach Button.                                                                                                                                                                                                                                                                                                                                                                                                                                    | `family:buttons` FR2, FR6, AV3; current source                                                                   |
+| FR2  | The effective pressed value is the group's selection for a valued member inside a ToggleButtonGroup, otherwise `isPressed` (default `false`); while a standalone Action is pending, the optimistic value replaces it.                                                                                                                                                                                                                                                                                                                                                                                                           | `family:buttons` FR6, FR11; current tests                                                                        |
+| FR3  | Standalone activation: a caller `onClick` runs first. If that `onClick` calls `preventDefault()`, nothing else runs. Otherwise `onPressedChange(next, event)` runs synchronously, where `next` is the inverse of the effective value. If it calls `preventDefault()`, the Action does not run. A click already prevented before the caller `onClick` ran still calls `onPressedChange`, and `pressedChangeAction` MUST then run (`family:buttons` FR5). Implementation gap: Button skips its `clickAction` for any click already prevented, so `pressedChangeAction` does not run and an Action-only toggle ignores that click. | `family:buttons` FR5; current tests                                                                              |
+| FR4  | With `pressedChangeAction`, a standalone activation sets the optimistic value to `next` and runs the Action through Button's `clickAction`; the Button is pending until it settles. The Action runs with or without `onPressedChange`. A re-click while pending is accepted and derives `next` from the optimistic value. When it settles, the committed `isPressed` shows.                                                                                                                                                                                                                                                     | `family:buttons` FR4–FR6; current tests                                                                          |
+| FR5  | Without `pressedChangeAction`, activation is synchronous and reports no pending state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `family:buttons` FR5; current tests                                                                              |
+| FR6  | A valued member inside a ToggleButtonGroup asks the group to toggle its value on every enabled activation, after any caller `onClick` and whether or not that `onClick` prevented default. It never calls its own `onPressedChange` or `pressedChangeAction` and never reports Action pending.                                                                                                                                                                                                                                                                                                                                  | `family:buttons` FR11; current tests                                                                             |
+| FR7  | Disabled when its own `isDisabled` or its group's `isDisabled` is true; an enabled group never re-enables a member that disables itself. A disabled toggle never requests a state change and follows `component:Button` FR10, including its implementation gap.                                                                                                                                                                                                                                                                                                                                                                 | `family:buttons` FR3; current tests                                                                              |
+| FR8  | While pressed, the surface paints the pressed overlay color; under forced colors it paints `Highlight` with `HighlightText`. The visible label renders semibold while pressed, and pressing MUST NOT change outer size. Content MUST render once, with no hidden twin to reserve width (`architecture:component-style-authoring` INV7). Implementation gap: a labelled toggle wraps its label in a span beside a hidden semibold copy that reserves the width, so the label renders twice and `children` mount twice. Icon-only toggles render no copy.                                                                         | `family:buttons` FR7, FR9; current source and tests; `architecture:component-style-authoring` INV7               |
+| FR9  | While pressed and `pressedIcon` is supplied, the icon slot shows `pressedIcon`; otherwise it shows `icon`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `family:buttons` AV2; current tests                                                                              |
+| FR10 | Size is the explicit `size`, then the enclosing ToggleButtonGroup's `size`, then `md`; ToggleButton does not read an outer size provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `family:buttons` FR7; current source                                                                             |
+| FR11 | `elevation` paints Button's shadow standalone and inside a ToggleButtonGroup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `family:buttons` FR8, FR12; current tests                                                                        |
+| FR12 | The root carries both `astryx-button` and `astryx-toggle-button`, reflects `data-is-pressed` as `"true"` or `"false"`, and reflects `data-elevation`. A caller `className` is kept alongside them. A caller `data-is-pressed` MUST NOT replace the reflected value. Implementation gap: caller props spread last, so a caller `aria-pressed` or `data-is-pressed` overrides ToggleButton's own.                                                                                                                                                                                                                                 | `family:buttons` FR10; `architecture:component-theming-surface`; tests; `architecture:public-component-api` INV5 |
+| FR13 | Visible content is `children` when supplied, else `label`; icon-only shows no visible text. When `label` is non-empty it is the accessible name, because Button sets it as `aria-label` (`component:Button` ORD4).                                                                                                                                                                                                                                                                                                                                                                                                              | `family:buttons` FR1; current tests                                                                              |
+| FR14 | Pending presentation and press feedback follow `component:Button` FR8 and FR15: ToggleButton is a standalone Button inside or outside a ToggleButtonGroup, so it takes the press scale, which MUST NOT apply under reduced motion (`design:reduced-motion` DR1), and its interruptible Spinner waits the medium delay and MUST appear at once under reduced motion with a fine pointer (DR3). Implementation gap: both the press scale and the Spinner fade still apply under reduced motion, and content that paints its own colors stays visible beside the Spinner.                                                          | `component:Button`; `design:reduced-motion`; current source                                                      |
+
+### Allowed variation
+
+- **AV1 — Pressed paint.** Themes may restyle the pressed state through
+  `toggle-button[data-is-pressed="true"]`; pressed must stay distinguishable
+  from unpressed, including under forced colors.
+- **AV2 — Icons.** Any caller node may fill `icon` and `pressedIcon`.
+
+### Representative states
+
+| State                 | Required invariant                                                                             | Allowed variation |
+| --------------------- | ---------------------------------------------------------------------------------------------- | ----------------- |
+| Unpressed             | `aria-pressed="false"`; ghost surface; regular weight.                                         | Icon.             |
+| Pressed               | `aria-pressed="true"`; pressed paint; semibold label; same outer size.                         | Pressed icon.     |
+| Action pending        | Optimistic pressed value; Spinner and `aria-busy`; still operable.                             | Spinner delay.    |
+| Valued group member   | Pressed from the group; activation calls the group; no Action.                                 | Elevation.        |
+| Disabled with tooltip | `aria-disabled`; focusable; no state request.                                                  | —                 |
+| Disabled, no tooltip  | Focusable with `aria-disabled`; no state request. Implementation gap: native `disabled` (FR7). | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Effective pressed.** Group selection for a valued member, then the
+  pending optimistic value, then `isPressed`, then `false`.
+- **ORD2 — Standalone activation.** Caller `onClick`, then `onPressedChange`,
+  then the Action; a newly prevented event stops the steps after it. A click
+  prevented before the caller `onClick` still reaches `onPressedChange`
+  (FR3 gap for the Action).
+- **ORD3 — Disabled.** Group disabled or own disabled; either is enough.
+
+### Performance and resources
+
+- **PR1 — Width reservation.** A labelled toggle renders three elements where
+  its label text would do: a wrapper, the visible label, and a hidden copy;
+  with `children` the children subtree mounts twice. No measurement runs. This
+  cost is the FR8 gap.
+
+## Accessibility contract
+
+- **AR1 — State.** `aria-pressed` MUST reflect the effective pressed value
+  (FR2), including the optimistic value while pending, and a caller prop MUST
+  NOT replace it (`architecture:public-component-api` INV5). Implementation
+  gap: caller props spread last, so a caller `aria-pressed` overrides it.
+- **AR2 — Name.** A non-empty `label` is the accessible name (FR13); the
+  width-reservation copy (FR8 gap) is hidden from assistive technology.
+- **AR3 — Forced colors.** The pressed state stays visible under forced colors
+  (FR8), as WCAG 1.4.11 requires.
+- **AR4 — Visible hint.** An icon-only toggle shows a tooltip only when the
+  caller sets `tooltip`.
+- **AR5 — Everything else.** Keyboard, focus indicator, loading announcement,
+  busy and disabled exposure, and target size follow `component:Button`
+  AR2–AR6.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                              | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Icon             | Leading icon; replaced by Pressed icon while pressed.                           | Current source and tests | Supporting     | FR9                |
+| Pressed icon     | Alternate icon while pressed.                                                   | Current source and tests | Supporting     | FR9                |
+| Label            | Visible text, semibold while pressed, at a stable width (FR8 gap: hidden copy). | Current source and tests | Prominent      | FR8, FR13          |
+| Spinner          | Button's Spinner over hidden content while an Action runs.                      | Current source           | Supporting     | FR4                |
+| Pressed surface  | Pressed overlay fill; `Highlight` under forced colors.                          | Current source and tests | Prominent      | FR8                |
+
+`design:reduced-motion` governs the inherited press scale and Spinner reveal
+(FR14); no other design record governs ToggleButton. The root carries `toggle-button` (and
+Button's `button`); Icon, Pressed icon, and Label take color from them, and the
+Spinner is a Spinner instance. The consumer anatomy names no root part, so this
+record carries no anatomy-theming map.
+
+## Family and system relationships
+
+- `family:buttons` owns persistent-press semantics, callback and Action order,
+  and group ownership of valued members (FR5, FR6, FR11); ToggleButton adopts
+  them. The family's elevation axis is shipped on ToggleButton (FR11).
+- `component:Button` owns the rendered surface and pending, disabled, and
+  tooltip behavior.
+- `component:ToggleButtonGroup` owns selection for valued members.
+- `spec:AST-085` applies through Button; the gap is FR7 here.
+
+## Verification map
+
+| Contract            | Verification                                                                                                                                                                          | Representative states                                         | Mutation or failure expectation                                                                                                                                                                                                                            | Audit section                      |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1, FR2, ORD1, AR1 | `ToggleButton.test.tsx`; `ToggleButton.a11y.chromium.spec.ts` standalone and group states                                                                                             | Unpressed, pressed, icon-only, composed label                 | Missing or stale `aria-pressed` fails.                                                                                                                                                                                                                     | `audit:ToggleButton/accessibility` |
+| FR3–FR5, ORD2       | `ToggleButton.test.tsx` callback, Action, and caller-`onClick` suites                                                                                                                 | Callback only, Action only, both, prevented, pending re-click | Order flips, a prevented callback still runs the Action, or callback-only reports pending fails. Evidence gap: no test runs `pressedChangeAction` on a click prevented before the toggle's handler.                                                        | `audit:ToggleButton/behavior`      |
+| FR6                 | `ToggleButton.test.tsx` group-ownership cases                                                                                                                                         | Member with standalone handlers; member with `onClick`        | A member that runs its own handler or skips the group toggle fails.                                                                                                                                                                                        | `audit:ToggleButton/behavior`      |
+| FR7, ORD3           | `ToggleButton.test.tsx` disabled suite; `ToggleButton.a11y.test.tsx` and `ToggleButton.a11y.chromium.spec.ts` disabled states                                                         | Member and group disabled; tooltip-bearing disabled           | A disabled toggle that toggles, or an enabled group re-enabling a member, fails. The shared disabled state expects native `disabled`, matching the FR7 gap.                                                                                                | `audit:ToggleButton/accessibility` |
+| FR8, FR9, AR3       | `ToggleButton.test.tsx` width-reservation, pressed-icon, and forced-colors cases                                                                                                      | Labelled and icon-only; pressed and unpressed                 | A wrong icon or no forced-colors pressed paint fails. The width-reservation case asserts the hidden copy, matching the FR8 gap.                                                                                                                            | `audit:ToggleButton/visual`        |
+| FR11, FR12          | `ToggleButton.test.tsx` elevation and className cases                                                                                                                                 | Standalone and grouped elevation; caller className            | A lost elevation, missing target, or dropped caller class fails. Evidence gap: no test reads the painted shadow or passes a caller `aria-pressed` or `data-is-pressed`.                                                                                    | `audit:ToggleButton/theming`       |
+| FR8 (outer size)    | Evidence gap: no test measures that pressing keeps the outer size                                                                                                                     | Labelled toggle pressed and unpressed                         | —                                                                                                                                                                                                                                                          | `audit:ToggleButton/layout`        |
+| FR8, FR12 (gaps)    | Evidence gap: no test asserts the pressed overlay paint, the semibold pressed label, or `data-is-pressed`                                                                             | Pressed and unpressed                                         | —                                                                                                                                                                                                                                                          | `audit:ToggleButton/theming`       |
+| FR14                | Evidence gap: no ToggleButton test presses or loads under `prefers-reduced-motion: reduce`, or loads self-colored content; the shipped scale and fade fail the reduced-motion clauses | Mouse and touch press; pending Action with a fine pointer     | A computed transform other than `none` or `scale(1)` during a press, or a Spinner opacity below 1 after it appears.                                                                                                                                        | `audit:ToggleButton/behavior`      |
+| FR10                | Evidence gap: no test of ToggleButton size precedence                                                                                                                                 | —                                                             | —                                                                                                                                                                                                                                                          | `audit:ToggleButton/layout`        |
+| FR13, AR2           | `ToggleButton.test.tsx` children, icon-only, and width-reservation cases; `ToggleButton.a11y.chromium.spec.ts` state-inventory check for the rendered visible label                   | Labelled; custom children; icon-only                          | A labelled toggle without its visible label, children that do not replace it, an icon-only toggle without `aria-label`, or a width copy not hidden from assistive technology fails. Evidence gap: no jsdom test asserts `aria-label` on a labelled toggle. | `audit:ToggleButton/accessibility` |
+| AR5                 | `ToggleButton.a11y.test.tsx` and `ToggleButton.a11y.chromium.spec.ts` operable and focusable facts                                                                                    | Standalone and grouped                                        | A toggle that is not operable or that Tab does not reach fails. Evidence gap: no test asserts the focus indicator or the target size.                                                                                                                      | `audit:ToggleButton/accessibility` |
+| AR4, PR1            | Evidence gap: no test asserts the absence of an automatic tooltip or the cost of the width copy                                                                                       | —                                                             | —                                                                                                                                                                                                                                                          | `audit:ToggleButton/behavior`      |
+
+## Current-state impact
+
+- **Disabled focusability (FR7).** A disabled ToggleButton without a tooltip
+  renders native `disabled`, as `component:Button` FR10 records, against
+  `spec:AST-085` FR1 and FR4 and `family:buttons` FR3. The shared toggle-pattern browser states expect
+  that native `disabled`.
+- **Duplicated label (FR8, PR1).** A labelled toggle renders a hidden semibold
+  copy of its label to reserve width, so `children` mount twice, against
+  `architecture:component-style-authoring` INV7.
+- **Pre-prevented click (FR3).** A click already prevented before the toggle's
+  handler calls `onPressedChange` but not `pressedChangeAction`, so an
+  Action-only toggle ignores it, against `family:buttons` FR5.
+- **Reduced motion (FR14).** A ToggleButton scales to 0.98 on a press, and its
+  Spinner fades in, when the person prefers reduced motion, against
+  `design:reduced-motion` DR1 and DR3, as `component:Button` FR8 and FR15
+  record.
+- **Self-colored content while pending (FR14).** Content that paints its own
+  colors stays visible beside the Spinner, as `component:Button` FR8 records.
+- **Consumer docs.** `ToggleButton.doc.mjs` says an icon without children makes
+  the toggle icon-only, and that icon-only adds an automatic tooltip from the
+  label; its anatomy rows and the `isIconOnly` JSDoc in `ToggleButton.tsx`
+  promise the same automatic tooltip. Icon-only depends on `isIconOnly` alone,
+  and no tooltip appears without `tooltip` (FR13, AR4).
+- **Caller pressed attributes (FR12, AR1).** A caller `aria-pressed` or
+  `data-is-pressed` replaces ToggleButton's own, against
+  `architecture:public-component-api` INV5.
+- **Family adoption table.** `family:buttons` lists ToggleButton elevation as an
+  adoption gap; the axis is shipped (FR11).
+
+## Decision log
+
+No component-local decision. ToggleButton applies `family:buttons` and
+`component:Button`.
+
+## Open questions
+
+- **OQ1 — Should ToggleButton inherit an outer size provider like Button?**
+  (`human-api`) It reads only its own `size` and its group's (FR10); Button and
+  IconButton also read the nearest size provider.
+
+## 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.