@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/ToggleButton/ToggleButtonGroup.spec.md

@@ -1,195 +0,0 @@
----
-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/Token/Token.spec.md

@@ -1,262 +0,0 @@
----
-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. 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`.                        |
-
-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
-
-- **`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.
-- **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).                                       |
-| 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). 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
-
-- **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, 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 →
-  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`.
-- **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, 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.
-- **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 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
-  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`, `size`, and the disabled state.
-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.
-- `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; 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
-
-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.