@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/ToggleButton/ToggleButtonGroup.spec.md

@@ -0,0 +1,195 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:ToggleButtonGroup
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, 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,
+    packages/core/src/Layer/layerScopedContext.test.tsx,
+  ]
+modules: []
+families: [family:buttons]
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-085, spec:AST-038]
+---
+
+# ToggleButtonGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | None changes. ToggleButtonGroup takes `label`, `type` (`single` or `multiple`), a controlled `value` and `onChange`, `orientation`, `size`, `isDisabled`, `xstyle`, and `data-testid`.     |
+| Behavior                | A labelled `role="group"` of separate ToggleButtons. Valued members show the group's selection and ask the group to toggle; the group reports the next selection through `onChange`.       |
+| End-user impact         | People pick one or several options with plain toggle buttons. Each member is its own Tab stop. A disabled group's members leave the tab order.                                             |
+| Builder impact          | None.                                                                                                                                                                                      |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Disabled members use native `disabled` without a tooltip, against `spec:AST-085` FR1 and FR7; listed under Current-state impact. |
+| Review checks           | Reject a group without a name, a member whose pressed state disagrees with `value`, a member Action started by group activation, a wrapper shadow, or connected surfaces.                  |
+| Governing rules         | `family:buttons` FR8, FR11, FR12, AV5; `spec:AST-085` FR1, FR7.                                                                                                                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ToggleButtonGroup owns single or multiple selection across a set of
+ToggleButtons and lays them out as separate surfaces, as `family:buttons`
+assigns. Consumer usage lives in `ToggleButtonGroup.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; `type="single"`,
+  `orientation="horizontal"`, `isDisabled={false}`
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: controlled only; the group holds no
+  selection of its own
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The group root: role, accessible name, layout, and the
+  `toggle-button-group` target.
+- Selection: which valued members are pressed, and the next selection a member
+  activation requests.
+- The default size and disabled state valued and unvalued members read.
+
+**Does not own / non-goals**
+
+- Each member's surface, `aria-pressed`, paint, and disabled rendering — owned
+  by `component:ToggleButton` and `component:Button`.
+- Connected geometry and a shared elevation — not provided; members are
+  separate surfaces (`family:buttons` FR12).
+- Roving focus — not provided; each member is a Tab stop (`family:buttons`
+  AV5).
+- Requiring a selection in single mode — not provided; the active member
+  deselects.
+
+## Public concepts
+
+| Concept     | Closed values or states      | Meaning                          | Availability by variant/orientation/state | Default       | Owner                         | Stability | Invalid-value behavior                                                   |
+| ----------- | ---------------------------- | -------------------------------- | ----------------------------------------- | ------------- | ----------------------------- | --------- | ------------------------------------------------------------------------ |
+| Type        | `single`, `multiple`         | How many members may be pressed. | Always; fixes the `value` shape.          | `single`      | `component:ToggleButtonGroup` | Stable    | TypeScript rejects a `value` or `onChange` that does not match the type. |
+| Value       | `string \| null`, `string[]` | The selected member values.      | Always; required.                         | required      | `component:ToggleButtonGroup` | Stable    | A value no member carries selects nothing visible.                       |
+| Orientation | `horizontal`, `vertical`     | Row or column layout.            | Always.                                   | `horizontal`  | `component:ToggleButtonGroup` | Stable    | TypeScript rejects other values.                                         |
+| Size        | `sm`, `md`, `lg`             | Default member size.             | Always; a member's own `size` wins.       | members' `md` | `family:buttons`              | Stable    | TypeScript rejects other values.                                         |
+| Disabled    | off, on                      | Every member is disabled.        | Always.                                   | off           | `component:ToggleButtonGroup` | Stable    | Not applicable.                                                          |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| FR1 | The root is one element with `role="group"` and `aria-label` set to `label`, carrying `astryx-toggle-button-group`, `data-testid`, and `xstyle`. It exposes no orientation or disabled attribute of its own.                                                                                                                                                              | `family:buttons` FR11; current source and tests      |
+| FR2 | Members sit in a row (or a column when vertical) separated by the `--spacing-1` gap. The wrapper paints no surface and no shadow; each member keeps its own surface and elevation.                                                                                                                                                                                        | `family:buttons` FR8, FR12; current source and tests |
+| FR3 | A member whose `value` is in the selection renders pressed; every other valued member renders unpressed.                                                                                                                                                                                                                                                                  | `family:buttons` FR11; current tests                 |
+| FR4 | Single mode: activating an unpressed member calls `onChange` with its value; activating the pressed member calls `onChange(null)`.                                                                                                                                                                                                                                        | Current tests                                        |
+| FR5 | Multiple mode: activating an unpressed member calls `onChange` with the current values plus its value appended; activating a pressed member calls it with that value removed.                                                                                                                                                                                             | Current tests                                        |
+| FR6 | Member activation only requests a selection. The pressed state changes when the caller passes the new `value`, never earlier, and no member Action or Action-pending state runs (`component:ToggleButton` FR6).                                                                                                                                                           | `family:buttons` FR11; current tests                 |
+| FR7 | Members read the group's `size` as their default and its disabled state. While disabled, every member MUST be disabled under `component:ToggleButton` FR7: focusable with `aria-disabled` and inert (`spec:AST-085` FR1, FR7); an enabled group does not re-enable a member that disables itself. Implementation gap: members without a tooltip render native `disabled`. | `family:buttons` FR3, FR11; current tests            |
+| FR8 | Each member is its own Tab stop in DOM order; the group adds no arrow-key handling.                                                                                                                                                                                                                                                                                       | `family:buttons` AV5; current source                 |
+| FR9 | The group's selection, size, and disabled context does not reach ToggleButtons rendered inside a layer opened from a member (`spec:AST-038` FR7, FR8).                                                                                                                                                                                                                    | Current source                                       |
+
+### Allowed variation
+
+- **AV1 — Members.** Members are ToggleButtons; a member without `value` reads
+  only the group's size and disabled state and otherwise behaves standalone.
+
+### Representative states
+
+| State                   | Required invariant                                            | Allowed variation       |
+| ----------------------- | ------------------------------------------------------------- | ----------------------- |
+| Single, none selected   | Every member unpressed; activating one requests its value.    | Orientation.            |
+| Single, one selected    | That member pressed; activating it requests `null`.           | —                       |
+| Multiple, some selected | Each selected member pressed; activation adds or removes one. | —                       |
+| Member disabled         | That member inert; others selectable.                         | Tooltip present or not. |
+| Group disabled          | Every member inert (FR7 gap for members without a tooltip).   | —                       |
+
+### Transformation and precedence order
+
+- **ORD1 — Member pressed state.** For a valued member, the group's selection;
+  the member's own `isPressed` is ignored.
+- **ORD2 — Member size.** Member `size`, then group `size`, then `md`.
+- **ORD3 — Member disabled.** Group disabled or member disabled.
+
+### Performance and resources
+
+- **PR1 — Group listeners only for press tracking.** The group adds no
+  observer or measurement, and no event listener beyond the press tracking
+  `family:action-groups` FR5 gives it.
+
+## Accessibility contract
+
+- **AR1 — Group name.** The group exposes `role="group"` with `label` as its
+  name; members keep their own names and `aria-pressed`.
+- **AR2 — Keyboard.** Tab moves through members in order (FR8); each member
+  activates with Enter and Space as a Button does.
+- **AR3 — Disabled.** Members expose disabled per `component:Button` AR5 (FR7
+  gap); the group root carries no disabled state.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                               | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------ | ------------------------ | -------------- | ------------------ |
+| Members          | Separate ToggleButton surfaces with a small gap. | Current source           | Prominent      | FR2                |
+| Group wrapper    | Layout only; no paint or shadow.                 | Current source           | Supporting     | FR2                |
+
+No design record governs ToggleButtonGroup. Its root carries the
+`toggle-button-group` target with no reflected visual props.
+
+## Family and system relationships
+
+- `family:buttons` assigns selection ownership, spaced layout, no wrapper
+  elevation, and the toggle group's own keyboard model (FR11, FR12, AV5);
+  ToggleButtonGroup adopts them.
+- `component:ToggleButton` defers its pressed state and requests to the group
+  for valued members (`component:ToggleButton` FR6).
+- `spec:AST-085` FR7 applies to group disablement; the gap is FR7 here.
+
+## Verification map
+
+| Contract                     | Verification                                                                                                                                                                    | Representative states                                   | Mutation or failure expectation                                                                                                                                                  | Audit section                           |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1, AR1                     | `ToggleButton.test.tsx` group role and label cases                                                                                                                              | Single and multiple                                     | A missing name or role fails. Evidence gap: no test asserts the root target, `data-testid`, or `xstyle`.                                                                         | `audit:ToggleButtonGroup/accessibility` |
+| FR3–FR5, ORD1                | `ToggleButton.test.tsx` single and multiple suites                                                                                                                              | Select, switch, deselect, add, remove                   | A wrong pressed member or a wrong `onChange` payload fails.                                                                                                                      | `audit:ToggleButtonGroup/behavior`      |
+| FR6                          | `ToggleButton.test.tsx` group-ownership cases                                                                                                                                   | Members with standalone handlers and `onClick`          | A member Action runs, or pressed state moves before `value`, fails.                                                                                                              | `audit:ToggleButtonGroup/behavior`      |
+| FR7, ORD3, AR3               | `ToggleButton.test.tsx` disabled suite; `ToggleButton.a11y.test.tsx`                                                                                                            | Member disabled; group disabled; tooltip-bearing member | A disabled member that toggles, or a re-enabled member, fails. The shared disabled states expect native `disabled`, matching the FR7 gap.                                        | `audit:ToggleButtonGroup/accessibility` |
+| FR2                          | `ToggleButton.test.tsx` grouped elevation case                                                                                                                                  | Member with its own elevation                           | A member losing its elevation inside the group fails. Evidence gap: no test asserts the spacing or the unpainted wrapper. Evidence gap: no test reads a member's painted shadow. | `audit:ToggleButtonGroup/layout`        |
+| FR9 (selection)              | `layerScopedContext.test.tsx` "ends ancestor selection and callbacks while honoring explicit toggle props"                                                                      | Member inside a fixed Layer and an inline Dialog        | A member inside a layer that follows the outer group's selection or callbacks fails.                                                                                             | `audit:ToggleButtonGroup/behavior`      |
+| FR8, FR9 (size and disabled) | Evidence gap: no test of member Tab order, or of size and disabled scoping at a layer                                                                                           | —                                                       | —                                                                                                                                                                                | `audit:ToggleButtonGroup/accessibility` |
+| FR7 (size), ORD2, PR1        | Evidence gap: no test asserts the group size default, member size precedence, or that the group adds no listeners beyond the press tracking `family:action-groups` FR5 gives it | —                                                       | —                                                                                                                                                                                | `audit:ToggleButtonGroup/behavior`      |
+| AR2                          | `ToggleButton.a11y.test.tsx` and `ToggleButton.a11y.chromium.spec.ts` operable and focusable facts for the single- and multiple-group states                                    | Group members                                           | A group member that is not operable or that Tab does not reach fails.                                                                                                            | `audit:ToggleButtonGroup/accessibility` |
+
+## Current-state impact
+
+- **Disabled focusability (FR7).** A disabled group renders members without a
+  tooltip with native `disabled`, against `spec:AST-085` FR1 and FR7 and
+  `family:buttons` FR3.
+
+## Decision log
+
+No component-local decision. ToggleButtonGroup applies `family:buttons`.
+
+## Open questions
+
+None.
+
+## 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.

package/src/ToggleButton/__tests__/ToggleButton.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^internal/a11y-spec/src/patterns/toggle-button
 
 /**
  * @file ToggleButton.a11y.chromium.spec.ts

package/src/Token/Token.spec.md

@@ -0,0 +1,271 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Token
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-24
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Token/Token.test.tsx,
+    packages/core/src/Token/__tests__/TokenRemoveTarget.a11y.chromium.spec.ts,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/theme/extensibleAxes.test.ts,
+    apps/storybook/stories/Token.stories.tsx,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-005, spec:AST-009, spec:AST-085]
+---
+
+# Token component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                      |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | An inline chip with a required string `label`, `size`, theme-extensible `color`, optional `icon` and `endContent`, and optional `onClick`, `href`, and `onRemove` interactions.                               |
+| 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.                                                                     |
+| 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`.                        |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Token represents one discrete piece of associated data — a tag, a filter, a
+selected recipient — as a compact inline chip. It owns the chip's geometry and
+tones, the choice of a static, clickable, or link structure, and the remove
+action beside the chip's own action.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: not applicable; Token holds no state
+- Migration decision: none
+
+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.
+- **Hidden-label name on a generic container (AR3).** With `isLabelHidden`, a
+  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
+  indicator per focus move.
+- **Small remove target (AR6).** At `size="sm"` the token's 20px block size and
+  clipped overflow cut the Remove button's hit area to 24 by 20 CSS pixels,
+  below the 24 by 24 of WCAG 2.2 2.5.8.
+
+## Ownership boundary
+
+**Owns**
+
+- The token root, its Icon and End content slots, the Label, and the Remove
+  button.
+- Size geometry, tones, label overflow, and the disabled treatment.
+- Choosing the static, clickable, link, or link-and-remove structure, and the
+  surface-click delegation in the clickable and link-and-remove structures.
+- The Remove button's name, target size, and isolation from the token's own
+  action.
+
+**Does not own / non-goals**
+
+- Navigation-destination safety and router substitution — owned by
+  `family:navigation-destinations` and `spec:AST-005`; Token renders its link
+  through the shared link component.
+- Which enclosing contexts make a token a trigger — owned by the shared
+  interactive-role context; Token only consumes the resolved role.
+- Hover and press overlays and touch press timing — owned by the shared
+  interaction overlay used by every pressable surface.
+- The supplied icon's and end content's own semantics — owned by those nodes.
+- Collections of tokens, token entry, and keyboard deletion — owned by
+  `component:Tokenizer` and other composing components.
+
+## 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    | —                                                                                                                                              |
+
+## 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 |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may change visual properties of `token` per
+  `color` and `size` without changing structure, slot order, or the Remove
+  button's target.
+- **AV2 — Router link.** A `LinkProvider` link component may replace the native
+  anchor in the link structures under `family:navigation-destinations`.
+
+### 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.                  |
+
+### 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` →
+  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`.
+- **ORD3 — Remove click.** Stop propagation → `onRemove`.
+
+### Performance and resources
+
+- **PR1 — Shared press controller.** Every structure installs the shared
+  document-level press controller once per mount through its counted
+  installer; Token adds no per-token listener, observer, or timer. Only the
+  link-and-remove container holds refs for click delegation.
+
+## Accessibility contract
+
+- **AR1 — Separate controls.** The token's own action and the Remove button are
+  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
+  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.
+- **AR3 — Hidden label.** With `isLabelHidden`, the Label text stays in the
+  accessibility tree and names the token, and no element with the generic role
+  carries a name (WAI-ARIA 1.2). The root carries `aria-label` equal to the
+  label. Implementation gap: on the static, clickable, and link-and-remove
+  structures that root is a role-less `span`.
+- **AR4 — One focus indicator per focus move.** Each focus move shows one
+  owning indicator (`architecture:interaction-modality` INV3). The link root
+  draws its own focus-visible outline; clickable and link-and-remove containers
+  draw the outline for the inner control, which draws none of its own; the
+  Remove button draws its own outline. Implementation gap: the containers draw
+  their outline while any descendant has `:focus-visible`, so focusing Remove in
+  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.
+- **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
+  runs the token's own action, in both text directions. Implementation gap: at
+  `size="sm"` the 20px-tall root clips the extension, leaving a 24 by 20 target.
+- **AR7 — Description.** `description` sets `aria-description` on the root.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                           | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
+| Token root       | A compact chip whose tone identifies the data it represents. | Current source           | Prominent      | FR1, FR7, FR8      |
+| Icon             | Optional leading glyph identifying the token type.           | Current source and docs  | Supporting     | FR1                |
+| Label            | The visible text and the default accessible name.            | Current source and docs  | Prominent      | FR7, AR2, AR3      |
+| 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`.
+The Label, End content, and Icon add no targets; the Remove button inherits the
+token's text color.
+
+## Family and system relationships
+
+- `family:navigation-destinations` and `spec:AST-005` own destination checks
+  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.
+- `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
+  extensible `color` axis; FR8 records the unthemed fallback.
+- `architecture:interaction-modality` owns modality and focus-indicator
+  ownership; AR4 records which element draws Token's indicator.
+
+## 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`     |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+None.
+
+## 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.

package/src/Token/__tests__/TokenRemoveTarget.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y always
 
 /**
  * @file TokenRemoveTarget.a11y.chromium.spec.ts

package/src/Tokenizer/Tokenizer.props-type.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file Tokenizer.props-type.test.tsx
+ * @input Uses vitest, TokenizerProps and Tokenizer
+ * @output Type-level proof that the exported `TokenizerProps` stays an
+ *   interface callers can extend and `Omit` (its `ref` typed for the combobox
+ *   input as released), that the public component names no `experimental`
+ *   presentation, and that only the internal `TokenizerWithPresentation`
+ *   admits the presentation options and a `ref` that also accepts the sheet
+ *   presentation's trigger button
+ * @position Core type tests; checked by `tsc`, with `@ts-expect-error`
+ *   marking the shapes that must keep failing
+ */
+import {createRef, type ComponentProps} from 'react';
+import {describe, it, expect} from 'vitest';
+import type {SearchableItem} from '../Typeahead/types';
+import {Tokenizer, type TokenizerProps} from './Tokenizer';
+import {TokenizerWithPresentation} from '../internal/tokenizer-presentation';
+
+type Item = SearchableItem;
+const source = {search: () => [], bootstrap: () => []};
+
+// A consumer's props interface extends the exported one, as before.
+interface TagsFieldProps extends TokenizerProps<Item> {
+  helpUrl?: string;
+}
+
+// A wrapper narrows the exported props with Omit and spreads the rest.
+function TagsField({helpUrl, ...rest}: Omit<TagsFieldProps, 'label'>) {
+  void helpUrl;
+  return <Tokenizer label="Tags" {...rest} />;
+}
+
+// The component's declared props resolve to the stable interface, so the
+// same two consumer shapes work through ComponentProps.
+type FromComponent = ComponentProps<typeof Tokenizer>;
+interface FromComponentProps extends FromComponent {
+  helpUrl?: string;
+}
+function FromComponentField({
+  helpUrl,
+  ...rest
+}: Omit<FromComponentProps, 'label'>) {
+  void helpUrl;
+  return <Tokenizer label="Tags" {...rest} />;
+}
+// And it is exactly TokenizerProps, in both directions.
+const same: FromComponent extends TokenizerProps<Item>
+  ? TokenizerProps<Item> extends FromComponent
+    ? true
+    : never
+  : never = true;
+void same;
+
+const inputRef = createRef<HTMLInputElement>();
+const wideRef = createRef<HTMLInputElement | HTMLButtonElement>();
+
+export function compiles() {
+  return (
+    <>
+      <TagsField searchSource={source} value={[]} onChange={() => {}} />
+      <FromComponentField
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        ref={inputRef}
+      />
+      {/* The public props name no presentation. */}
+      <TagsField
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        // @ts-expect-error -- `experimental` is not on TokenizerProps
+        experimental={{presentation: 'adaptive'}}
+      />
+      <Tokenizer
+        label="Tags"
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        // @ts-expect-error -- nor on the public component
+        experimental={{presentation: 'bottom-sheet'}}
+      />
+      {/* The stable shape: ref is the combobox input's. */}
+      <Tokenizer
+        label="Tags"
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        ref={inputRef}
+      />
+      {/* The internal signature admits the presentation and the wider ref. */}
+      <TokenizerWithPresentation
+        label="Tags"
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        ref={wideRef}
+        experimental={{presentation: 'adaptive'}}
+      />
+      {/* An input-typed ref is still fine there. */}
+      <TokenizerWithPresentation
+        label="Tags"
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        ref={inputRef}
+        experimental={{}}
+      />
+      <Tokenizer
+        label="Tags"
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        // @ts-expect-error -- the public ref keeps the released input-only type
+        ref={wideRef}
+      />
+    </>
+  );
+}
+
+describe('Tokenizer props type', () => {
+  it('keeps TokenizerProps an interface that extends and Omit-wraps, with no presentation option on the public component (type-checked above)', () => {
+    expect(typeof compiles).toBe('function');
+  });
+});