@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/ToggleButton/ToggleButtonGroup.tsx

@@ -23,6 +23,7 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import type {ButtonSize} from '../Button';
+import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {themeProps} from '../utils/themeProps';
@@ -74,7 +75,15 @@ const styles = stylex.create({
 // Props — Discriminated Union
 // =============================================================================
 
-interface ToggleButtonGroupBaseProps {
+/**
+ * Host props reach the group element (`architecture:public-component-api`
+ * INV5): `className`, `style`, `id`, `aria-*`, `data-*` and handlers. The group
+ * keeps its own `role`, `aria-label` and theme target.
+ */
+interface ToggleButtonGroupBaseProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'onChange' | 'defaultValue' | 'role' | 'aria-label'
+> {
   /** Toggle button children. */
   children: ReactNode;
 
@@ -184,7 +193,14 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
     size,
     isDisabled = false,
     xstyle,
+    className,
+    style,
     'data-testid': testId,
+    // Read through `props` below, where the union narrows them by `type`.
+    type: _type,
+    value: _value,
+    onChange: _onChange,
+    ...hostProps
   } = props;
 
   const isMultiple = props.type === 'multiple';
@@ -225,6 +241,7 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
   return (
     <ToggleButtonGroupContext value={contextValue}>
       <div
+        {...hostProps}
         role="group"
         aria-label={label}
         data-testid={testId}
@@ -235,6 +252,8 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
             orientation === 'vertical' && styles.vertical,
             xstyle,
           ),
+          className,
+          style,
         )}>
         {children}
       </div>

package/src/Token/Token.doc.mjs

@@ -88,7 +88,7 @@ export const docs = {
     },
   ],  theming: {
     targets: [
-      {className: 'astryx-token', visualProps: ['color', 'size']},
+      {className: 'astryx-token', visualProps: ['color', 'size'], states: ['disabled']},
     ],
   },
   usage: {
@@ -193,7 +193,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-token', visualProps: ['color', 'size']},
+      {className: 'astryx-token', visualProps: ['color', 'size'], states: ['disabled']},
     ],
   },
   usage: {

package/src/Token/Token.spec.md

@@ -41,7 +41,7 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085]
 | Behavior                | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them.           |
 | End-user impact         | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls.                                                        |
 | Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                  |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Six implementation gaps are listed under Current-state impact.                                                                     |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact.                                                                    |
 | Review checks           | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. |
 | Governing rules         | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`.                        |
 
@@ -66,10 +66,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Current-state impact
 
-- **Disabled link token (FR5, AR5).** A disabled token with `href` and no
-  `onClick` renders a static `span`: it loses its tab stop and exposes no
-  disabled state, where `spec:AST-085` FR1 and FR5 keep a disabled control
-  focusable and announced.
 - **`onClick` with `href` (FR3).** When a token renders as a link, a supplied
   `onClick` is not attached or called, where
   `architecture:public-component-api` INV5 preserves accepted event inputs.
@@ -77,10 +73,6 @@ Consumer migration instructions belong in consumer docs and release notes.
   static, clickable, or link-and-remove token puts `aria-label` on a `span` that
   has no role, where WAI-ARIA 1.2 prohibits naming the generic role. The
   visually hidden label text still reaches assistive technology.
-- **Disabled state not reflected on the target (FR5).** No structure reflects
-  `isDisabled` on the `token` target, so a theme cannot style the disabled state
-  through it, where `architecture:component-theming-surface` INV6 keeps state on
-  the owning target.
 - **Two focus indicators on Remove (AR4).** In clickable and link-and-remove
   tokens, keyboard focus on the Remove button draws the token's outline and the
   button's own, where `architecture:interaction-modality` INV3 allows one
@@ -116,29 +108,29 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept          | Closed values or states                                                                                          | Meaning                                                        | Availability by variant/orientation/state                                       | Default   | Owner             | Stability | Invalid-value behavior                                                                                                                         |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| Structure        | static; clickable; link; link-and-remove                                                                         | Which element owns the token's own action (FR2–FR4).           | Resolved from `href`, `onClick`, `isDisabled`, and an enclosing trigger context | static    | `component:Token` | Stable    | A disabled link token stays a focusable control that exposes its disabled state (FR5); today it resolves to the static structure, the FR5 gap. |
-| Size             | `sm`, `md`, `lg`                                                                                                 | Selects the block size.                                        | All structures                                                                  | `md`      | `component:Token` | Stable    | TypeScript rejects other values.                                                                                                               |
-| Tone (`color`)   | `default`, `red`, `orange`, `yellow`, `green`, `teal`, `cyan`, `blue`, `purple`, `pink`, `gray`; theme additions | Selects fill and text color.                                   | All structures                                                                  | `default` | `component:Token` | Stable    | A theme-added value is reflected on `token` and receives no component fill or color; TypeScript rejects unregistered values.                   |
-| Removable        | present when `onRemove` is supplied; absent                                                                      | Adds the Remove button after the label and end content.        | All structures                                                                  | absent    | `component:Token` | Stable    | —                                                                                                                                              |
-| Label visibility | visible; visually hidden                                                                                         | Hides the label visually while keeping it as the token's name. | All structures                                                                  | visible   | `component:Token` | Stable    | —                                                                                                                                              |
-| Disabled         | enabled; disabled                                                                                                | Blocks every token and remove action.                          | All structures                                                                  | enabled   | `component:Token` | Stable    | —                                                                                                                                              |
+| Concept          | Closed values or states                                                                                          | Meaning                                                        | Availability by variant/orientation/state                                       | Default   | Owner             | Stability | Invalid-value behavior                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Structure        | static; clickable; link; link-and-remove                                                                         | Which element owns the token's own action (FR2–FR4).           | Resolved from `href`, `onClick`, `isDisabled`, and an enclosing trigger context | static    | `component:Token` | Stable    | A disabled link token stays a focusable control that exposes its disabled state (FR5).                                       |
+| Size             | `sm`, `md`, `lg`                                                                                                 | Selects the block size.                                        | All structures                                                                  | `md`      | `component:Token` | Stable    | TypeScript rejects other values.                                                                                             |
+| Tone (`color`)   | `default`, `red`, `orange`, `yellow`, `green`, `teal`, `cyan`, `blue`, `purple`, `pink`, `gray`; theme additions | Selects fill and text color.                                   | All structures                                                                  | `default` | `component:Token` | Stable    | A theme-added value is reflected on `token` and receives no component fill or color; TypeScript rejects unregistered values. |
+| Removable        | present when `onRemove` is supplied; absent                                                                      | Adds the Remove button after the label and end content.        | All structures                                                                  | absent    | `component:Token` | Stable    | —                                                                                                                            |
+| Label visibility | visible; visually hidden                                                                                         | Hides the label visually while keeping it as the token's name. | All structures                                                                  | visible   | `component:Token` | Stable    | —                                                                                                                            |
+| Disabled         | enabled; disabled                                                                                                | Blocks every token and remove action.                          | All structures                                                                  | enabled   | `component:Token` | Stable    | —                                                                                                                            |
 
 ## Behavioral and layout contract
 
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                    |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1  | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and a minimum block size of `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. That size grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap.                                                                                                                                                                                                                                                             | Current source and tests |
-| FR2  | With no `href`, `onClick`, or enclosing trigger context, the token is a static `span` holding its content directly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
-| FR3  | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact).                                                                                                                                                                                                                                                                    | Current source and tests |
-| FR4  | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`. With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation.                                                                                   | Current source and tests |
-| FR5  | A disabled token renders at half opacity with pointer events off and fires neither `onClick` nor `onRemove` from pointer, Enter, or Space; inner and Remove buttons stay focusable with `aria-disabled="true"` and never receive native `disabled`. A disabled control keeps its tab stop and exposes its disabled state (`spec:AST-085` FR1, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: a disabled token with `href` and no `onClick` or trigger context renders as a static `span` with no tab stop and no disabled state, and no structure reflects the disabled state on the `token` target (Current-state impact). | Current source and tests |
-| FR6  | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
-| FR7  | The label never wraps: the root is capped at its container's inline size and clips overflow. In the static and link structures the Label ends in an ellipsis; in the clickable and link-and-remove structures the inner control clips the Label without an ellipsis. `isLabelHidden` keeps the Label in the DOM with a visually hidden clip treatment.                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
-| FR8  | `color` defaults to `default`, painting `--color-neutral` with primary text; every other built-in tone paints its tinted background with its matching colored text. The `token` target reflects the resolved `color` and `size` for every value, including a theme-added color, which receives no component fill or text color until a theme paints it.                                                                                                                                                                                                                                                                                                                                                          | Current source and tests |
-| FR9  | Clickable and link structures paint the shared hover overlay under a hover-capable pointer and the shared pressed overlay for mouse and touch presses; the static structure paints neither.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source           |
-| FR10 | `ref` reaches the root element of every structure. Supported DOM, ARIA, data, and event props reach the root; `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                    |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1  | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and a minimum block size of `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. That size grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap.                                                                                                                                                                                                                      | Current source and tests |
+| FR2  | With no `href`, `onClick`, or enclosing trigger context, the token is a static `span` holding its content directly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
+| FR3  | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact).                                                                                                                                                                                                                             | Current source and tests |
+| FR4  | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`. With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation.                                            | Current source and tests |
+| FR5  | A disabled token renders at half opacity with pointer events off and fires neither `onClick` nor `onRemove` from pointer, Enter, or Space; inner and Remove buttons stay focusable with `aria-disabled="true"` and never receive native `disabled`. A disabled control keeps its tab stop and exposes its disabled state (`spec:AST-085` FR1, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). A disabled token with `href` and no `onClick` or trigger context renders a focusable link with `aria-disabled="true"` and no `href`, and every structure reflects the disabled state on the `token` target. | Current source and tests |
+| FR6  | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it.                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
+| FR7  | The label never wraps: the root is capped at its container's inline size and clips overflow. In the static and link structures the Label ends in an ellipsis; in the clickable and link-and-remove structures the inner control clips the Label without an ellipsis. `isLabelHidden` keeps the Label in the DOM with a visually hidden clip treatment.                                                                                                                                                                                                                                                                                                                    | Current source and tests |
+| FR8  | `color` defaults to `default`, painting `--color-neutral` with primary text; every other built-in tone paints its tinted background with its matching colored text. The `token` target reflects the resolved `color` and `size` for every value, including a theme-added color, which receives no component fill or text color until a theme paints it.                                                                                                                                                                                                                                                                                                                   | Current source and tests |
+| FR9  | Clickable and link structures paint the shared hover overlay under a hover-capable pointer and the shared pressed overlay for mouse and touch presses; the static structure paints neither.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source           |
+| FR10 | `ref` reaches the root element of every structure. Supported DOM, ARIA, data, and event props reach the root, except that in the clickable structure `aria-labelledby` and `aria-describedby` reach the inner button, the element that owns the token's action (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                 | Current source and tests |
 
 ### Allowed variation
 
@@ -150,24 +142,24 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State              | Required invariant                                                                    | Allowed variation           |
-| ------------------ | ------------------------------------------------------------------------------------- | --------------------------- |
-| Static             | `span` root; Token adds no focusable element except a Remove button.                  | Tone, size, slots.          |
-| Clickable          | One inner button named by the label; container click calls `onClick`.                 | End content.                |
-| Link               | Root is the link; focus outline on the link itself.                                   | Router link component.      |
-| Link and remove    | Container holds a link and a sibling Remove button; surface click activates the link. | Modified and middle clicks. |
-| Removable          | Remove button named "Remove {label}" with a 24 by 24 CSS pixel target.                | Locale wording.             |
-| Disabled clickable | Buttons focusable with `aria-disabled="true"`; no callback fires; half opacity.       | Tone.                       |
-| Hidden label       | Label text visually hidden; the root's `aria-label` equals the label.                 | Structure.                  |
+| State              | Required invariant                                                                                      | Allowed variation           |
+| ------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------- |
+| Static             | `span` root; Token adds no focusable element except a Remove button.                                    | Tone, size, slots.          |
+| Clickable          | One inner button named by the label, or by a caller `aria-labelledby`; container click calls `onClick`. | End content.                |
+| Link               | Root is the link; focus outline on the link itself.                                                     | Router link component.      |
+| Link and remove    | Container holds a link and a sibling Remove button; surface click activates the link.                   | Modified and middle clicks. |
+| Removable          | Remove button named "Remove {label}" with a 24 by 24 CSS pixel target.                                  | Locale wording.             |
+| Disabled clickable | Buttons focusable with `aria-disabled="true"`; no callback fires; half opacity.                         | Tone.                       |
+| Hidden label       | Label text visually hidden; the root's `aria-label` equals the label.                                   | Structure.                  |
 
 ### Transformation and precedence order
 
 - **ORD1 — Structure.** Enabled `href` → `onClick` → enclosing trigger context →
-  static. `onRemove` with an enabled `href` selects the link-and-remove
-  container. A disabled `href` is skipped, so a disabled link token falls
-  through to `onClick`, a trigger context, or static; the static fall-through is
-  the FR5 gap.
-- **ORD2 — Root attributes.** Component class and `data-color`/`data-size` →
+  disabled `href` → static. `onRemove` with an `href` that wins selects the
+  link-and-remove container. A disabled `href` yields to `onClick` and a
+  trigger context; otherwise it keeps the link structure, rendered disabled
+  (FR5).
+- **ORD2 — Root attributes.** Component class and `data-color`/`data-size`/`data-disabled` →
   component styles → `xstyle` → `className` → `style` → caller props → `data-testid`, hidden-label
   `aria-label`, and `aria-description`. A hidden label's `aria-label` replaces
   a caller `aria-label`.
@@ -186,7 +178,8 @@ Consumer migration instructions belong in consumer docs and release notes.
   separate focusable controls in DOM order; neither is nested in the other, so
   the HTML interactive-content rule holds.
 - **AR2 — Names.** In the clickable and link-and-remove structures the inner
-  button or link takes its name from the Label. In the link structure the link
+  button or link takes its name from the Label, or, in the clickable structure,
+  from a caller `aria-labelledby` (FR10). In the link structure the link
   is the root and takes its name from all of its content, including End content
   (a label "Inbox" with a count reads "Inbox 12"). The
   Remove button is named by the translated "Remove {label}" string.
@@ -204,9 +197,7 @@ Consumer migration instructions belong in consumer docs and release notes.
   those structures shows the container outline and the button's own.
 - **AR5 — Disabled.** A disabled token's controls stay focusable, expose
   `aria-disabled="true"`, and ignore pointer, Enter, and Space (`spec:AST-085`
-  FR1, FR2, FR5); the inner and Remove buttons do. Implementation gap: a
-  disabled link token renders as a static `span` with no tab stop and no
-  disabled state.
+  FR1, FR2, FR5), the disabled link included.
 - **AR6 — Remove target size.** The Remove button's glyph box is 16 by 16 CSS
   pixels and its hit area extends 4 pixels on every side to 24 by 24 at `md`
   and `lg`, meeting WCAG 2.2 2.5.8, while a press on the adjacent label still
@@ -224,7 +215,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | End content      | Optional trailing content such as a count or status dot.     | Current source and docs  | Supporting     | FR1                |
 | Remove button    | A trailing close control that dismisses the token.           | Current source and docs  | Supporting     | FR6, AR1, AR2, AR6 |
 
-Theming: the root is the single `token` target and reflects `color` and `size`.
+Theming: the root is the single `token` target and reflects `color`, `size`, and the disabled state.
 The Label, End content, and Icon add no targets; the Remove button inherits the
 token's text color.
 
@@ -234,7 +225,7 @@ token's text color.
   for both link structures, including delegated surface clicks; Token adopts
   them through the shared link component and clickable-container delegation.
 - `spec:AST-085` owns focusable disabled controls; FR5 and AR5 record Token's
-  conformance and its one gap.
+  conformance.
 - `architecture:public-component-api` owns ref, passthrough, and styling-input
   rules; FR3 records one gap against INV5.
 - `architecture:component-theming-surface` owns the `token` target and the
@@ -244,18 +235,18 @@ token's text color.
 
 ## Verification map
 
-| Contract           | Verification                                                                           | Representative states                                        | Mutation or failure expectation                                                                                                                                                                    | Audit section          |
-| ------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| FR2, FR10          | `Token.test.tsx` render, ref, and pass-through suites                                  | Static, clickable, and link roots; caller props              | A wrong root element, a detached ref, or a dropped caller prop fails DOM assertions. Gap: no test covers the ref on the link-and-remove container.                                                 | `audit:Token/behavior` |
-| FR1, FR7           | `Token.stories.tsx` size, icon, and end-content fixtures in a browser                  | Sizes, icon and end content                                  | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout`   |
-| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites                          | Link, clickable, link and remove, modified and middle clicks | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`.                                            | `audit:Token/behavior` |
-| FR5, AR5           | `Token.test.tsx` disabled tests                                                        | Disabled clickable with remove                               | A native `disabled`, a lost tab stop on a button, or a fired callback fails. Gap: no test covers a disabled link token.                                                                            | `audit:Token/a11y`     |
-| AR2, AR3, AR7      | `Token.test.tsx` accessibility suite                                                   | Remove name, hidden label, description                       | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name.                                                            | `audit:Token/a11y`     |
-| AR6                | `TokenRemoveTarget.a11y.chromium.spec.ts`                                              | Pre-set filter tokens (default size), LTR and RTL            | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered.                                                                    | `audit:Token/a11y`     |
-| FR8                | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring                                | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`.                                                        | `audit:Token/theming`  |
-| FR9, AR4           | `Token.stories.tsx` clickable and link fixtures in a browser                           | Hover, press, keyboard focus on the token                    | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture.                               | `audit:Token/design`   |
-| PR1                | Source review                                                                          | Every structure                                              | Gap: no automated check fails if Token adds a per-token listener, observer, or timer.                                                                                                              | `audit:Token/behavior` |
-| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3)                                       | Every structure; hidden label; description; disabled         | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only.                              | `audit:Token/a11y`     |
+| Contract           | Verification                                                                           | Representative states                                                                                   | Mutation or failure expectation                                                                                                                                                                            | Audit section          |
+| ------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR2, FR10          | `Token.test.tsx` render, ref, and pass-through suites                                  | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` |
+| FR1, FR7           | `Token.stories.tsx` size, icon, and end-content fixtures in a browser                  | Sizes, icon and end content                                                                             | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check.         | `audit:Token/layout`   |
+| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites                          | Link, clickable, link and remove, modified and middle clicks                                            | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`.                                                    | `audit:Token/behavior` |
+| FR5, AR5           | `Token.test.tsx` disabled tests                                                        | Disabled clickable with remove; disabled static; disabled link with and without remove                  | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails.                                                                        | `audit:Token/a11y`     |
+| AR2, AR3, AR7      | `Token.test.tsx` accessibility suite                                                   | Remove name, hidden label, description                                                                  | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name.                                                                    | `audit:Token/a11y`     |
+| AR6                | `TokenRemoveTarget.a11y.chromium.spec.ts`                                              | Pre-set filter tokens (default size), LTR and RTL                                                       | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered.                                                                            | `audit:Token/a11y`     |
+| FR8                | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring                                                                           | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`.                                                                | `audit:Token/theming`  |
+| FR9, AR4           | `Token.stories.tsx` clickable and link fixtures in a browser                           | Hover, press, keyboard focus on the token                                                               | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture.                                       | `audit:Token/design`   |
+| PR1                | Source review                                                                          | Every structure                                                                                         | Gap: no automated check fails if Token adds a per-token listener, observer, or timer.                                                                                                                      | `audit:Token/behavior` |
+| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3)                                       | Every structure; hidden label; description; disabled                                                    | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only.                                      | `audit:Token/a11y`     |
 
 ## Decision log
 

package/src/Token/Token.tsx

@@ -299,6 +299,8 @@ export function Token({
   className,
   style,
   'data-testid': testId,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
   ref,
   ...rest
 }: TokenProps) {
@@ -342,13 +344,61 @@ export function Token({
     </>
   );
 
+  // Naming inputs reach the element that owns the token's action: the inner
+  // button of a clickable token, otherwise the root
+  // (architecture:public-component-api INV5).
+  const labellingProps = {
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+  };
+
   const sharedProps = {
     'data-testid': testId,
     ...(isLabelHidden ? {'aria-label': label} : {}),
     ...(description != null ? {'aria-description': description} : {}),
   };
 
-  if (role === 'link') {
+  // A disabled link keeps a focusable link with aria-disabled and no
+  // destination, as a disabled Link does (spec:AST-085 FR1, FR5;
+  // component:Link FR5). useInteractiveRole reports no link role once
+  // disabled, so the structure is chosen here.
+  const isDisabledLink = isDisabled && href != null && effectiveOnClick == null;
+
+  if (isDisabledLink && onRemove == null) {
+    // A disabled link is an <a> with no href, as Link renders one: nothing can
+    // navigate, it keeps a Tab stop and the link role (spec:AST-085 FR1, FR5).
+    // The router LinkComponent is skipped, since a custom router link may
+    // require a live href.
+    const DisabledAnchor = 'a';
+    return (
+      <DisabledAnchor
+        ref={ref as React.Ref<HTMLAnchorElement>}
+        role="link"
+        aria-disabled={true}
+        tabIndex={0}
+        {...mergeProps(
+          themeProps('token', {color, size, disabled: 'disabled'}),
+          focusOutlineProps.focusVisible(
+            styles.base,
+            sizeStyles[size],
+            colorStyles[color],
+            styles.interactive,
+            styles.disabled,
+            xstyle,
+          ),
+          className,
+          style,
+        )}
+        {...rest}
+        {...labellingProps}
+        {...disabledInteractionProps(rest.onKeyDown)}
+        {...sharedProps}>
+        {content}
+      </DisabledAnchor>
+    );
+  }
+
+  if (role === 'link' || isDisabledLink) {
     if (onRemove == null) {
       return (
         <LinkComponent
@@ -356,7 +406,11 @@ export function Token({
           href={href as string}
           {...pressable}
           {...mergeProps(
-            themeProps('token', {color, size}),
+            themeProps('token', {
+              color,
+              size,
+              disabled: isDisabled ? 'disabled' : null,
+            }),
             focusOutlineProps.focusVisible(
               styles.base,
               sizeStyles[size],
@@ -370,6 +424,7 @@ export function Token({
             style,
           )}
           {...rest}
+          {...labellingProps}
           {...(isDisabled ? {'aria-disabled': true} : {})}
           {...sharedProps}>
           {content}
@@ -405,7 +460,11 @@ export function Token({
           </span>
         }
         {...mergeProps(
-          themeProps('token', {color, size}),
+          themeProps('token', {
+            color,
+            size,
+            disabled: isDisabled ? 'disabled' : null,
+          }),
           focusOutlineProps.focusWithin(
             styles.base,
             sizeStyles[size],
@@ -419,6 +478,7 @@ export function Token({
           style,
         )}
         {...rest}
+        {...labellingProps}
         {...sharedProps}
       />
     );
@@ -439,7 +499,11 @@ export function Token({
         onClick={isDisabled ? undefined : handleContainerClick}
         {...pressable}
         {...mergeProps(
-          themeProps('token', {color, size}),
+          themeProps('token', {
+            color,
+            size,
+            disabled: isDisabled ? 'disabled' : null,
+          }),
           focusOutlineProps.focusWithin(
             styles.base,
             sizeStyles[size],
@@ -458,6 +522,7 @@ export function Token({
         <button
           type="button"
           onClick={effectiveOnClick}
+          {...labellingProps}
           aria-disabled={isDisabled || undefined}
           {...(isDisabled ? disabledInteractionProps() : null)}
           {...stylex.props(styles.invisibleButton)}>
@@ -479,7 +544,11 @@ export function Token({
     <span
       ref={ref}
       {...mergeProps(
-        themeProps('token', {color, size}),
+        themeProps('token', {
+          color,
+          size,
+          disabled: isDisabled ? 'disabled' : null,
+        }),
         stylex.props(
           styles.base,
           sizeStyles[size],
@@ -491,6 +560,7 @@ export function Token({
         style,
       )}
       {...rest}
+      {...labellingProps}
       {...sharedProps}>
       {content}
     </span>

package/src/Token/TokenLink.tsx

@@ -32,6 +32,7 @@ import type {LinkComponentType} from '../Link/types';
 import {composeEventHandlers} from '../utils';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {disabledInteractionProps} from '../utils/disabledInteraction';
 export interface TokenLinkProps extends HTMLAttributes<HTMLElement> {
   /** Ref forwarded to the container element. */
   ref?: Ref<HTMLElement>;
@@ -100,13 +101,26 @@ export function TokenLink({
           : composeEventHandlers(onMouseUpProp, onMouseUp)
       }>
       {icon}
-      <LinkComponent
-        ref={linkRef as Ref<HTMLAnchorElement>}
-        href={href}
-        aria-disabled={isDisabled || undefined}
-        {...linkStyleProps}>
-        {labelContent}
-      </LinkComponent>
+      {isDisabled ? (
+        // A disabled link stays a focusable link with no destination, as a
+        // disabled Link does (spec:AST-085 FR1, FR5; component:Link FR5).
+        <a
+          ref={linkRef as Ref<HTMLAnchorElement>}
+          role="link"
+          aria-disabled={true}
+          tabIndex={0}
+          {...linkStyleProps}
+          {...disabledInteractionProps()}>
+          {labelContent}
+        </a>
+      ) : (
+        <LinkComponent
+          ref={linkRef as Ref<HTMLAnchorElement>}
+          href={href}
+          {...linkStyleProps}>
+          {labelContent}
+        </LinkComponent>
+      )}
       {endContent}
       {removeButton}
     </span>

package/src/Tokenizer/Tokenizer.spec.md

@@ -16,6 +16,7 @@ verified_by:
     packages/core/src/Tokenizer/Tokenizer.ssr.test.tsx,
     packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx,
     packages/core/src/Tokenizer/Tokenizer.props-type.test.tsx,
+    packages/core/src/PowerSearch/PowerSearch.test.tsx,
     packages/core/src/internal/tokenizer-presentation.test.ts,
     packages/core/src/Typeahead/Typeahead.test.tsx,
     packages/core/src/Layer/useLayer.test.tsx,
@@ -325,7 +326,7 @@ presentation, which has no inline combobox, suggestion menu, or end lane.
 
 ## Accessibility contract
 
-AR1–AR5 describe the `popover` presentation; AR6 describes the sheet
+AR1–AR5 and AR7 describe the `popover` presentation; AR6 describes the sheet
 presentation.
 
 - **AR1 — Modality equivalence.** The same input or token/control produces the
@@ -371,15 +372,27 @@ presentation.
   once the confirmation has closed, since a message sent while the
   confirmation covers the sheet is not heard — `spec:AST-086/FR14`), the
   search's busy start, and how each search
-  ended — the result count for a non-empty query, or the empty state's text
-  when it shows — are announced once per occasion from inside the sheet
-  through `useAnnounce`, which `spec:AST-086/FR14` routes into the persistent
+  ended — the result count for a non-empty query, or the empty state's text when
+  it shows, both from the search's own `useAnnounce({hasReplace: true})`
+  instance (`spec:AST-086/FR9`, FR13), so a newer one replaces one not yet
+  spoken — are announced once per occasion from inside the sheet through
+  `useAnnounce`, which `spec:AST-086/FR14` routes into the persistent
   polite container of the sheet's own dialog while it is open, because the
   shared page-body channel is not exposed behind a native modal; the
   container follows FR3, FR5, and FR6 of that record (WCAG 2.2 SC 4.1.3
   through `spec:AST-020/FR1`). After the sheet closes focus returns to the
   trigger and the field's announcements follow the same FR14 route from
   wherever the field renders.
+- **AR7 — Clear all is announced.** In the `popover` presentation, the field's
+  Clear all, which empties every token at once and moves focus to the input,
+  announces "All items removed" (`@astryx.tokenizer.allRemoved`, the words of
+  the sheet's Clear all in AR6) the same way the field announces a token added
+  or removed: politely, through the shared channel (`spec:AST-086/FR2`, FR5).
+  It is announced once per Clear all (`spec:AST-086/FR6`); a Clear all
+  confirmed in the sheet is announced by the sheet alone (AR6), and the field
+  stays silent for it (WCAG 2.2 SC 4.1.3 through `spec:AST-020/FR9`). A
+  component that composes Tokenizer and words its own Clear all announces its
+  own words instead (`component:PowerSearch`).
 
 ## Design relationships
 
@@ -460,6 +473,7 @@ become Tokenizer policy.
 | FR13–FR15, AR5      | Focused Tokenizer/BaseTypeahead tests and exact-head Chromium interaction evidence                                                               | pointer/keyboard commit, first/middle/last choice, rejected/deferred control, loading, disabled, max, exhaustion, Escape, Tab, outside focus                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Selected values remain available, order changes, focus leaves the combobox, active descendant names no option, stale work reopens, or a terminal state stays interactive. | `audit:Tokenizer/multi-select`   |
 | PR1–PR5             | Instrumented reads, pending-frame cleanup tests, and first-frame Chromium capture                                                                | open, close before frame, reopen opposite side, resize while open                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Render-time/repeated reads, observer/pointer tracking, uncancelled frame, or first-frame jump occurs.                                                                     | `audit:Tokenizer/performance`    |
 | AR1–AR5             | Existing interaction suites plus focused pointer/keyboard/browser checks; native-disabled assertions pending conformance (`spec:AST-085`)        | add/edit, focus/refocus, overflow, disabled, dismissal, retained bootstrap selection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Modality changes placement, semantics/focus regress, active descendant becomes invalid, or visible placement is wrong before fallback.                                    | `audit:Tokenizer/accessibility`  |
+| AR7                 | Focused Tokenizer tests, inline and sheet, and the PowerSearch test                                                                              | inline Clear all; a localized catalog; a Clear all confirmed in the sheet counted across every live region; PowerSearch's own words                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | The inline Clear all is silent, speaks words other than its catalog message, a sheet Clear all is announced twice, or PowerSearch speaks Tokenizer's words.               | `audit:Tokenizer/accessibility`  |
 | FR16–FR24, AR6, PR6 | Focused Tokenizer sheet tests with the compact-touch query stubbed both ways, a server-render-then-hydrate test, plus real-engine touch evidence | default popover, forced sheet, adaptive both ways, `adaptive` server-rendered as the combobox and hydrated without a recoverable error, then the trigger on a coarse-pointer client with the body still active, with `hasAutoFocus` the autofocused input's focus on the trigger after the swap and no `onBlur`/`onFocus` reported, the trigger's box against the hydrating field's at 390 and 414px, base props and ref on the trigger, the trigger's description in the inline input's order — a disabled trigger with `disabledMessage`, `description` and a status exposing the caller's ids, the description, the status message and the reason before the count and the tokens —, inert-prop warning, pending search, in-sheet announcements of toggles, busy start, result count and the rendered empty outcome, the confirmed Clear all announced once the confirmation has closed, a below-threshold query, a rejecting source, focus on the panel at open, the query cleared by a swipe, scrim, or Escape close, focus after a presentation change with the sheet closed, focus after the create row, focus after a confirmed Clear all, a spent Clear all focusable with `aria-disabled` and no action, focus after a settled search removes the focused row, no busy feedback or busy-start announcement on open with an instant source, only the search field — no list, no message, no announcement — for an empty query with nothing to list (a search-only source, nothing selected), and the list once a query finds items, element counts under a fine and a coarse pointer at rest and open (Chromium, Experimental stories: adaptive 154/120 at rest — the closed trigger in place of the inline field, a different element that stays under the fine count — and 157/165 open at the query "e" with no footer, the coarse total reconciled as rest − the re-hosted surfaces host + the dialog of 47 by part, forced sheet 114/114 and 165/165; the two owner exceptions DEC-3 records beyond the FR60 allowance, with before and after counts), no confirmation dialog in the DOM while none is pending, the query kept across a disabled-forced close, `aria-setsize`/`aria-posinset` on each row's `listitem` and the next batch on focus reaching the last rendered row, open/toggle/reopen order, create, batches, limit, Clear all, disabled while open, focus return | A field without `experimental` changes, a toggle moves a row, Clear all skips confirmation, the limit disables checked rows, or the popover bundle carries the sheet.     | `audit:Tokenizer/sheet`          |
 | Record structure    | `scripts/check-knowledge.mjs`                                                                                                                    | Template-v3 current record and current-only frontmatter links                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Invalid metadata, authority, or relationship references fail repository validation.                                                                                       | `audit:Tokenizer/knowledge`      |