@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Toast/Toast.spec.md

@@ -1,291 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Toast
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-30
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Layer/LayerProvider.test.tsx,
-    packages/core/src/Toast/ToastViewport.test.tsx,
-    packages/core/src/Toast/ToastViewport.modalHost.test.tsx,
-    packages/core/src/Toast/useToast.test.tsx,
-    apps/storybook/stories/Toast.stories.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:action-groups]
-design_specs: [design:bidirectionality, design:reduced-motion]
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:layer-runtime,
-    architecture:interaction-modality,
-  ]
-contributing: []
-system_specs:
-  [
-    spec:AST-086,
-    spec:AST-003,
-    spec:AST-094,
-    spec:AST-100,
-    spec:AST-059,
-    spec:AST-027,
-  ]
----
-
-# Toast component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `useToast()` returning a show function that takes `{body, type ('info' default, 'error'), isAutoHide (true for info, false for error), autoHideDuration (5000), endContent, renderContent, uniqueID, collisionBehavior ('overwrite' default, 'ignore'), onHide}` and returns a dismiss function; `ToastViewport` with `position` (`bottomEnd`), `maxVisible` (5), `inset`, `layerInset`, and `isTopLayer` (true); `Toast`; target `toast` with `type`. |
-| Behavior                | A stack of non-modal notification cards at one viewport corner. Each toast is announced once, can auto-hide (pausing while hovered, focused, touched, or the window is blurred), and dismisses by its button, a vertical swipe toward its edge, or code. F6 moves focus into the newest toast.                                                                                                                                                         |
-| End-user impact         | Users get brief notices without losing their place; screen-reader users hear each toast once; keyboard users reach toast controls with F6 and land somewhere sensible after dismissing; touch users swipe toasts away.                                                                                                                                                                                                                                 |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Compatibility/readiness | Records shipped behavior; no public change. Nineteen implementation gaps, listed under Current-state impact.                                                                                                                                                                                                                                                                                                                                           |
-| Review checks           | Reject a toast announced more than once per show, a dismissal that drops focus to the body, an auto-hide that runs while the user is reading or interacting, or a swipe as the only way to dismiss.                                                                                                                                                                                                                                                    |
-| Governing rules         | `spec:AST-086` FR1; `spec:AST-003` (modal rehosting); `spec:AST-094`; `spec:AST-100`; `spec:AST-059` FR6; `architecture:layer-runtime`; `design:bidirectionality`; `design:reduced-motion`.                                                                                                                                                                                                                                                            |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Toast shows brief, non-modal notifications. This record covers the toast card
-(`Toast`), the viewport that stacks, hosts, and announces toasts
-(`ToastViewport`, which has no consumer doc of its own), and the behavior the
-`useToast` show function drives. Consumer usage lives in `Toast.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: toasts live in the viewport's state; the
-  show function returns a dismiss function
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Each card is a second live region.** The viewport announces every toast
-  through the shared announcement channel, and each visible card also carries
-  `role="status"` or `role="alert"` with `aria-live`. `spec:AST-086` FR1 requires
-  exactly one announcement owner per message.
-- **The viewport builds its own top layer and exit.** ToastViewport mounts its
-  own top layer and runs its own exit collapse. `architecture:layer-runtime`
-  INV14 has a layer use the runtime's top-layer mounting and shared exit copy
-  rather than building its own.
-- **Announcements go through the body-level channel.** The viewport announces
-  through the shared body-level channel, which a native modal hides, instead
-  of its own persistent containers. `spec:AST-086` FR10 has a modal-hosted
-  owner keep its own channel.
-- **The swipe decides on net travel.** A swipe dismisses on net travel past a
-  distance threshold, or on a fast flick timed by its own average speed, even
-  when the finger moves back before release. `spec:AST-094` FR36–FR37 decide
-  once at release on projected travel and cancel a release moving back, and
-  `spec:AST-100` FR1, FR2, and FR4 take the release velocity from the shared
-  tracker.
-- **A toast raised while the window is blurred runs its timer.** Only a later
-  blur pauses it, so a toast raised while the user is in another window can
-  auto-hide unseen.
-- **A control-free toast cannot take focus.** With no control in the newest
-  toast, F6 leaves focus where it was; dismissing a focused toast beside a
-  control-free one drops focus to the page body.
-- **The swipe ignores a mouse.** Only touch and pen drags are recognized; a
-  mouse drag does nothing. `spec:AST-094` FR43 attaches gestures to every
-  pointer.
-- **A swipe settles at theme timing.** After release the commit or snap-back
-  is a CSS transition at theme timing rather than starting at the release
-  velocity (`spec:AST-094` FR38).
-- **A hidden toast's overwrite is announced unseen.** Overwriting, through
-  `uniqueID`, a toast hidden by the cap announces the new text while it is not
-  shown, and nothing is announced when it surfaces.
-- **Custom content without a control has only the swipe.** A `renderContent`
-  toast that renders no control can be dismissed only by a swipe, and an error
-  toast does not auto-hide. `spec:AST-094` FR39 keeps every drag action
-  reachable without a drag.
-- **Some modals supply no outlet.** A modal Drawer, Lightbox, or MobileNav
-  opens without supplying an outlet, so toasts stay behind it; `spec:AST-003`
-  FR18 rehosts globally hosted layers above every native modal.
-- **A toast collapsing through an outlet move can linger.** A toast that is
-  still collapsing when its viewport moves into or out of any outlet FR12
-  names comes back as an invisible zero-height row that never unmounts: it
-  keeps the notifications landmark exposed and F6 focuses its hidden dismiss
-  button, and it holds one of the `maxVisible` places. With no provider
-  above the caller a dismissal called before the fallback viewport
-  mounts does nothing, so the toast shows and stays unless it
-  auto-hides (FR3, FR5, FR7, FR10, FR11, FR12).
-- **Announcement happens at dispatch, not when shown.** The viewport announces
-  a toast when it is raised rather than when it appears, so a toast shown and
-  dismissed in the same handler is announced although it never appears, and of
-  toasts raised past `maxVisible` in one handler the older, hidden one is
-  announced and nothing is announced when it later appears (FR9).
-- **Announced words can differ from shown words.** The viewport announces the
-  words in the `body` option's text and element children, so words a component
-  renders itself, such as a translated message, are lost, and a
-  `renderContent` card is announced with the `body` words even when it shows
-  others. `spec:AST-086` FR7 has the announced words match the shown words
-  (FR9).
-- **The action row does not track a held pointer.** A press that slides across
-  the row's sibling actions does not act on the action it lifts on;
-  `family:action-groups` has the row use the shared press tracking.
-- **Nested viewports can show two landmarks.** An outer and an inner viewport
-  that each hold a toast expose two notifications landmarks (FR11).
-- **Reduced motion is instant on every pointer.** Under reduced motion the
-  entrance, the row collapse, and the swipe's throw run for 0.01 ms on every
-  pointer; a touch user
-  gets no opacity fade, which `design:reduced-motion` DR2 calls for.
-- **A zero toast inset does not override the provider.** A `toast.inset` edge
-  set to 0 keeps the provider's `layerInset` on that edge; `spec:AST-059` FR6
-  has a set edge replace it. An inset edge opposite the position, such as
-  `top` for a bottom stack, moves the stack to that edge.
-- **The viewport sets a page-level z-index.** The viewport carries
-  `z-index: 500`; `spec:AST-027` FR1 keeps z-index local only, and FR8 orders
-  floating surfaces through the browser top layer.
-
-## Ownership boundary
-
-**Owns**
-
-- The card's layout, auto-hide timing, swipe dismissal, and dismiss button
-  (FR1–FR5).
-- The viewport's placement, stacking, collision handling, announcement, F6
-  entry, focus handoff, landmark, and modal rehosting (FR6–FR12).
-
-**Does not own / non-goals**
-
-- Body, end content, and custom content — owned by the caller.
-- The dismiss Button — owned by `component:Button`.
-- The shared announcement channel — owned by `spec:AST-086`; top-layer hosting —
-  owned by `architecture:layer-runtime` and `spec:AST-003`.
-- The `useToast` hook's module contract — uncontracted; this record covers the
-  behavior it drives.
-
-## Public concepts
-
-| Concept            | Closed values or states                          | Meaning                                                    | Availability by variant/orientation/state | Default     | Owner             | Stability | Invalid-value behavior           |
-| ------------------ | ------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------- | ----------- | ----------------- | --------- | -------------------------------- |
-| Type               | `info`, `error`                                  | Announcement urgency and card treatment.                   | Every toast.                              | `info`      | `component:Toast` | Stable    | TypeScript rejects other values. |
-| Position           | `topEnd`, `topStart`, `bottomEnd`, `bottomStart` | Corner the stack sits in and the edge toasts swipe toward. | Viewport.                                 | `bottomEnd` | `component:Toast` | Stable    | TypeScript rejects other values. |
-| Collision behavior | `overwrite`, `ignore`                            | What a toast with an existing `uniqueID` does.             | Toasts with `uniqueID`.                   | `overwrite` | `component:Toast` | Stable    | TypeScript rejects other values. |
-| Dismiss reason     | `auto`, `manual`                                 | Reported to `onHide`.                                      | Every dismissal.                          | —           | `component:Toast` | Stable    | Not applicable.                  |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                    |
-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1  | A card carries `toast` with `type` and shows `body` and, on its first line, `endContent` then a dismiss Button named by `@astryx.toast.dismiss`; long body text wraps below. `renderContent` replaces that layout, receives `body`, `endContent`, `type`, timing, and a `dismiss` function, and gets no injected dismiss control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
-| FR2  | With auto-hide on (the default for `info`, off for `error`), the card dismisses with reason `auto` after `autoHideDuration` ms. The timer pauses while the pointer is over the card, focus is inside it, a touch or pen gesture is active, or the window is blurred, and resumes with the remaining time (at least 1 s). Each pause condition holds the timer on its own: one ending resumes it only when no other still holds, and focus moving between the card's own controls keeps it held. Implementation gap: a toast raised while the window is already blurred starts its timer (Current-state impact).                                                                                                                                                                                                                           | Current source and tests |
-| FR3  | The dismiss button, a swipe, a `dismiss` call, or the returned dismiss function dismiss with reason `manual`; `onHide` fires at most once, when the toast is dismissed, even when dismissed twice during its exit. Implementation gap: with no provider above the caller, a dismissal called before the fallback viewport mounts does nothing, so the toast shows and stays unless it auto-hides (Current-state impact). A toast replaced through `uniqueID` is not dismissed and reports no `onHide`.                                                                                                                                                                                                                                                                                                                                    | Current source and tests |
-| FR4  | A drag toward the position's block edge, from any pointer (`spec:AST-094` FR43), decides once, at release, per `spec:AST-094` FR36–FR37: projected travel past the commit point dismisses, and a release moving back toward the start cancels. A short drag snaps back; horizontal intent, a second touch, or a gesture starting on an interactive descendant does not dismiss. Native page scrolling continues until touch intent matches the dismiss edge. In the default layout the visible dismiss button stays as a non-gesture alternative; custom content supplies its own. Implementation gaps: the shipped rule dismisses on net travel past a distance threshold or a fast flick timed by its own average speed, even after the finger moves back, and recognizes only touch and pen drags, not a mouse (Current-state impact). | Current source and tests |
-| FR5  | A new card slides in from its edge and fades in; a dismissed card collapses and fades before it unmounts; both slide only along the block axis. A dismissal without a swipe uses theme timing; a swipe's commit and snap-back start at the release velocity (`spec:AST-094` FR38). Under reduced motion the entrance and dismissal are an opacity-only fade of 200 ms or less on a coarse pointer or after a touch release (`design:reduced-motion` DR2) and immediate otherwise (DR3), and the card still unmounts. Implementation gaps: a swipe's settle is a CSS transition at theme timing, and under reduced motion every transition, including the row collapse and the swipe's throw, runs for 0.01 ms on every pointer (Current-state impact).                                                                                    | Current source and tests |
-| FR6  | The viewport stacks toasts at `position`, newest nearest the configured edge, with an 8 px gap and no extra space at the edge beyond the safe-area gutter it keeps; it spans the inline axis within its inset, honoring start and end insets in either direction. Each edge sits at the provider's `layerInset`, and a `toast.inset` edge, when set, replaces it (`spec:AST-059` FR6). Implementation gaps: a `toast.inset` edge set to 0 does not replace the provider's value, and an edge opposite the position, such as `top` for a bottom stack, moves the stack to that edge (Current-state impact).                                                                                                                                                                                                                                | Current source and tests |
-| FR7  | With `maxVisible` of 1 or more, at most that many toasts show; when more are raised, the oldest wait hidden and return as visible toasts leave. `maxVisible={0}` shows every toast.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR8  | A toast whose `uniqueID` matches a toast the viewport holds, whether shown, hidden by the cap, or exiting, replaces it in place under `overwrite` (and is announced again; the card remounts, so focus inside it drops to the page body), and is dropped unshown and unannounced under `ignore`, even when both are raised before the first renders. Implementation gap: overwriting a toast hidden by the cap announces it while it is not shown, and nothing is announced when it surfaces (Current-state impact).                                                                                                                                                                                                                                                                                                                      | Current source and tests |
-| FR9  | Each shown toast has one announcement owner (`spec:AST-086` FR1): the viewport announces it once, when it is shown, `error` assertively and `info` politely, using the toast's text content, through its own persistent polite and assertive containers, which move with it into a modal (`spec:AST-086` FR10). Unrelated renders do not re-announce. Implementation gaps: the viewport announces through the shared body-level channel, which a modal hides, and announces at dispatch rather than when a toast appears (Current-state impact).                                                                                                                                                                                                                                                                                          | `spec:AST-086`; tests    |
-| FR10 | F6 moves focus to the first control in the newest toast. Focus entering the viewport, by F6, Tab or a click, records where it was. Dismissing a toast that holds focus moves focus to a control in a remaining toast, or back to the remembered element when none remain. Implementation gap: with no control in the target toast, F6 leaves focus where it was and the handoff drops focus to the page (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
-| FR11 | While a toast is visible the viewport is a `region` landmark named by `@astryx.toast.viewport`, without `aria-modal`; it exposes no landmark when empty, so an empty nested viewport adds none. Implementation gap: nested viewports that each hold a toast expose two landmarks (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
-| FR12 | A top-layer viewport moves into the latest open Dialog, scrim sheet, or modal flow step, following the top of a stack and handing back to the one beneath when it closes, and returns to its place when none remains, keeping each toast, its timer, and focus inside the viewport. It re-enters the top layer in place when a non-modal sheet opens after it, and stays in place when rendered in place, or when an inline dialog, a sheet without a scrim, or a non-modal flow opens.                                                                                                                                                                                                                                                                                                                                                   | `spec:AST-003`; tests    |
-
-### Allowed variation
-
-- **AV1 — Content.** Body, end content, and custom content vary.
-- **AV2 — Theme styling.** Themes restyle `toast` per type.
-
-### Representative states
-
-| State                   | Required invariant                               | Allowed variation |
-| ----------------------- | ------------------------------------------------ | ----------------- |
-| Info, auto-hide         | Polite announcement once; timer pauses on hover. | Duration.         |
-| Error                   | Assertive announcement once.                     | —                 |
-| Overwrite by uniqueID   | Replaced in place; announced again.              | —                 |
-| Six toasts, default cap | Oldest waits hidden; five visible.               | Cap.              |
-| Over an open Dialog     | Viewport inside the dialog's top layer.          | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Collision.** `ignore` drops a matching toast before announcement;
-  `overwrite` replaces it, then announces.
-
-### Performance and resources
-
-- **PR1 — Cleanup.** Timers, window listeners, and native touch listeners are
-  removed when a toast unmounts.
-
-## Accessibility contract
-
-- **AR1 — One announcement.** FR9 (with the gap under Current-state impact).
-- **AR2 — Keyboard reach.** FR10.
-- **AR3 — Timing.** FR2 pauses auto-hide while the user reads or interacts.
-- **AR4 — Gesture alternative.** In the default layout FR4 keeps a button for
-  every swipe dismissal; custom content supplies its own non-drag dismissal,
-  apart from the control-free custom content gap (Current-state impact).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                       | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ---------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Body             | Message text that wraps.                 | Current source and public docs | Prominent      | FR1                |
-| End content      | Caller controls on the first line.       | Caller content                 | Supporting     | FR1                |
-| Dismiss button   | Small ghost icon button at the line end. | `component:Button`             | Supporting     | FR1, FR3           |
-
-No anatomy-theming map is recorded: the card carries `toast`, but
-`Toast.doc.mjs` names only the card's contents (Body, End content, Dismiss
-button), so no anatomy part can own the `toast` target.
-
-## Family and system relationships
-
-- `spec:AST-086` owns the announcement channel and the one-owner rule.
-- `family:action-groups` covers Toast's action row when it holds two or more
-  sibling actions; the row adopts that family's held-pointer tracking.
-- `spec:AST-003` and `architecture:layer-runtime` own top-layer hosting above
-  native modals.
-- `design:bidirectionality` keeps block-axis swipes and inline insets correct in
-  right-to-left.
-
-## Verification map
-
-| Contract | Verification                                                                                            | Representative states                                                                              | Mutation or failure expectation                                                       | Audit section               |
-| -------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------- |
-| FR1, FR3 | `ToastViewport.test.tsx` layout, custom content, and onHide tests                                       | Default, custom content, double dismiss                                                            | Dropped controls or a repeated `onHide` fails.                                        | `audit:Toast/behavior`      |
-| FR2      | `ToastViewport.test.tsx` blur-pause and pause-source tests                                              | Window blur, new toast during pause, overlapping pointer/focus/window holds, focus moving inside   | A timer running while paused, or resuming while another hold remains, fails.          | `audit:Toast/behavior`      |
-| FR4, FR5 | `ToastViewport.test.tsx` gesture and motion tests                                                       | Pen and touch thresholds, short drag, horizontal intent, second touch, interactive descendant, RTL | A dismissal from a rejected gesture, a lost snap-back, or off-axis drift fails.       | `audit:Toast/behavior`      |
-| FR6–FR8  | `ToastViewport.test.tsx` placement, cap, and uniqueID tests; `Layer/LayerProvider.test.tsx` inset tests | Each position, cap 1 and an explicit cap, overwrite, ignore                                        | Wrong order, cap, or collision fails.                                                 | `audit:Toast/layout`        |
-| FR9–FR11 | `ToastViewport.test.tsx` announcement, F6, focus, landmark tests                                        | Info, error, StrictMode, nested viewports                                                          | A repeated or wrong-urgency announcement, or focus to the body after F6 entry, fails. | `audit:Toast/accessibility` |
-| FR12     | `ToastViewport.modalHost.test.tsx`                                                                      | Dialog, nested dialogs, sheets and sheet stacks, modal flows                                       | A lost toast, timer, or focus, or the wrong outlet, fails.                            | `audit:Toast/layering`      |
-
-Read from source, with no focused test yet:
-
-- FR1: the `toast` target and its `type` state.
-- FR2: pausing while a touch gesture is active, and the 1 s minimum on
-  resume.
-- FR4: a mouse drag dismissing, and a release moving back cancelling; the
-  gesture tests assert today's touch-and-pen-only, net-travel rule.
-- FR5: a swipe's settle starting at the release velocity, and the
-  reduced-motion fade and immediate change; the motion tests assert today's
-  0.01 ms transitions.
-- FR6: a set `toast.inset` edge replacing the provider's value at 0.
-- FR7: the default cap of 5, and `maxVisible={0}` showing every toast.
-- FR9: delivery through the viewport's own polite and assertive containers;
-  the announcement tests read the shared body-level channel.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, the announcement
-channel, or layer-hosting rules. It links to their owners.

package/src/ToggleButton/ToggleButton.spec.md

@@ -1,256 +0,0 @@
----
-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.