From 00a94ee0160b12d2ccf2e3149026ba8f4122f00c Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Fri, 30 Oct 2026 10:33:00 -0700
Subject: [PATCH 1/3] fix(Typeahead): the value token's button is named by the
 field label and the value (WCAG 2.4.6, 4.1.2)

With a value, Typeahead takes its input out of the Tab order, so the
Tab stop is the token's inner button, and that button was named by the
value alone ("Apple, button"), with no field name, description or
status. It is now labelled by the field label and the value and
described like the input. A clickable Token passes aria-labelledby and
aria-describedby to the inner button that owns its action
(public-component-api INV5) instead of the generic root. Fixes #8945.
---
 .changeset/typeahead-token-tab-stop-named.md  |  7 +++
 packages/core/src/Token/Token.test.tsx        | 19 ++++++++
 packages/core/src/Token/Token.tsx             | 14 ++++++
 .../core/src/Typeahead/Typeahead.test.tsx     | 48 ++++++++++++++-----
 packages/core/src/Typeahead/Typeahead.tsx     | 34 +++++++++----
 5 files changed, 103 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/typeahead-token-tab-stop-named.md

diff --git a/.changeset/typeahead-token-tab-stop-named.md b/.changeset/typeahead-token-tab-stop-named.md
new file mode 100644
index 0000000000000..204f03e431a20
--- /dev/null
+++ b/.changeset/typeahead-token-tab-stop-named.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] With a value, a `Typeahead`'s Tab stop is the value's token button, and it is now named by the field label and the value ("Fruit Apple", not just "Apple") and described by the field's description and status, so screen reader users know which field it belongs to. A clickable `Token` now passes `aria-labelledby` and `aria-describedby` to its inner button.
+
+@cixzhang @duytbp
diff --git a/packages/core/src/Token/Token.test.tsx b/packages/core/src/Token/Token.test.tsx
index 4426fc386716c..a923410f3291d 100644
--- a/packages/core/src/Token/Token.test.tsx
+++ b/packages/core/src/Token/Token.test.tsx
@@ -256,6 +256,25 @@ describe('Token accessibility', () => {
     ).toBeInTheDocument();
   });
 
+  it("passes aria-labelledby and aria-describedby to a clickable token's button (public-component-api INV5)", () => {
+    render(
+      <>
+        <span id="field-label">Fruit</span>
+        <span id="field-hint">Pick one</span>
+        <Token
+          label="Apple"
+          onClick={() => {}}
+          aria-labelledby="field-label"
+          aria-describedby="field-hint"
+          data-testid="token"
+        />
+      </>,
+    );
+    const button = screen.getByRole('button', {name: 'Fruit'});
+    expect(button).toHaveAccessibleDescription('Pick one');
+    expect(screen.getByTestId('token')).not.toHaveAttribute('aria-labelledby');
+  });
+
   it('keeps both buttons focusable and inert when isDisabled is true', async () => {
     const user = userEvent.setup();
     const handleClick = vi.fn();
diff --git a/packages/core/src/Token/Token.tsx b/packages/core/src/Token/Token.tsx
index 57c5b3d6f351c..f7f24ea6cb189 100644
--- a/packages/core/src/Token/Token.tsx
+++ b/packages/core/src/Token/Token.tsx
@@ -299,6 +299,8 @@ export function Token({
   className,
   style,
   'data-testid': testId,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
   ref,
   ...rest
 }: TokenProps) {
@@ -342,6 +344,14 @@ export function Token({
     </>
   );
 
+  // Naming inputs reach the element that owns the token's action: the inner
+  // button of a clickable token, otherwise the root
+  // (architecture:public-component-api INV5).
+  const labellingProps = {
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+  };
+
   const sharedProps = {
     'data-testid': testId,
     ...(isLabelHidden ? {'aria-label': label} : {}),
@@ -370,6 +380,7 @@ export function Token({
             style,
           )}
           {...rest}
+          {...labellingProps}
           {...(isDisabled ? {'aria-disabled': true} : {})}
           {...sharedProps}>
           {content}
@@ -419,6 +430,7 @@ export function Token({
           style,
         )}
         {...rest}
+        {...labellingProps}
         {...sharedProps}
       />
     );
@@ -458,6 +470,7 @@ export function Token({
         <button
           type="button"
           onClick={effectiveOnClick}
+          {...labellingProps}
           aria-disabled={isDisabled || undefined}
           {...(isDisabled ? disabledInteractionProps() : null)}
           {...stylex.props(styles.invisibleButton)}>
@@ -491,6 +504,7 @@ export function Token({
         style,
       )}
       {...rest}
+      {...labellingProps}
       {...sharedProps}>
       {content}
     </span>
diff --git a/packages/core/src/Typeahead/Typeahead.test.tsx b/packages/core/src/Typeahead/Typeahead.test.tsx
index b39d5afea8e18..a8472e954a6e6 100644
--- a/packages/core/src/Typeahead/Typeahead.test.tsx
+++ b/packages/core/src/Typeahead/Typeahead.test.tsx
@@ -93,6 +93,9 @@ const fruits: SearchableItem[] = [
   {id: '5', label: 'Elderberry'},
 ];
 
+// The token's value also sits in a hidden span its button is labelled by.
+const VISIBLE = {selector: ':not([hidden])'};
+
 const fruitSource: SearchSource = {
   search: (query: string) =>
     fruits.filter(f => f.label.toLowerCase().includes(query.toLowerCase())),
@@ -693,6 +696,25 @@ describe('Typeahead', () => {
     expect(screen.getByText(/Required/)).toBeInTheDocument();
   });
 
+  it('names the token button, the Tab stop while a value shows, by the field label and the value', async () => {
+    const user = userEvent.setup();
+    render(
+      <Typeahead
+        label="Fruit"
+        description="Pick your favorite fruit"
+        status={{type: 'error', message: 'Pick a ripe one'}}
+        searchSource={fruitSource}
+        value={{id: 'apple', label: 'Apple'}}
+        onChange={() => {}}
+      />,
+    );
+    await user.tab();
+    const tabStop = document.activeElement as HTMLElement;
+    expect(tabStop).toHaveAccessibleName('Fruit Apple');
+    expect(tabStop).toHaveAccessibleDescription(/Pick your favorite fruit/);
+    expect(tabStop).toHaveAccessibleDescription(/Pick a ripe one/);
+  });
+
   it('renders error status message', () => {
     render(
       <Typeahead
@@ -715,7 +737,7 @@ describe('Typeahead', () => {
         onChange={() => {}}
       />,
     );
-    expect(screen.getByText(fruits[0].label)).toBeInTheDocument();
+    expect(screen.getByText(fruits[0].label, VISIBLE)).toBeInTheDocument();
   });
 
   it('shows clear button when hasClear and value is selected', () => {
@@ -1616,10 +1638,10 @@ describe('Typeahead edit mode', () => {
   // iOS raises the software keyboard only for a focus made while the browser
   // still dispatches the person's tap, so the focus must not wait for a frame.
   it.each([
-    ['the token', () => screen.getByText(fruits[0].label)],
+    ['the token', () => screen.getByText(fruits[0].label, VISIBLE)],
     [
       'the field around it',
-      () => screen.getByText(fruits[0].label).closest('div')!,
+      () => screen.getByText(fruits[0].label, VISIBLE).closest('div')!,
     ],
   ])(
     'focuses the input with the label selected inside the tap on %s',
@@ -1679,7 +1701,7 @@ describe('Typeahead edit mode', () => {
     );
     const input = screen.getByRole<HTMLInputElement>('combobox');
 
-    fireEvent.click(screen.getByText(fruits[3].label));
+    fireEvent.click(screen.getByText(fruits[3].label, VISIBLE));
 
     expect(input).toHaveFocus();
     expect(input.value).toBe(fruits[3].label);
@@ -1706,7 +1728,7 @@ describe('Typeahead edit mode', () => {
     screen.getByRole('combobox');
 
     // Click the token text to enter edit mode
-    const tokenText = screen.getByText(fruits[0].label);
+    const tokenText = screen.getByText(fruits[0].label, VISIBLE);
     const tokenContainer = tokenText.closest('div')!;
     fireEvent.click(tokenContainer);
 
@@ -1733,7 +1755,7 @@ describe('Typeahead edit mode', () => {
     const input = screen.getByRole<HTMLInputElement>('combobox');
 
     // Enter edit mode: the token gives way to the label as editable text
-    fireEvent.click(screen.getByText(fruits[0].label).closest('div')!);
+    fireEvent.click(screen.getByText(fruits[0].label, VISIBLE).closest('div')!);
     await waitFor(() => expect(input.value).toBe(fruits[0].label));
 
     fireEvent.click(screen.getByRole('button', {name: 'Clear selection'}));
@@ -1772,7 +1794,9 @@ describe('Typeahead edit mode', () => {
       render(<Controlled />);
       const input = screen.getByRole<HTMLInputElement>('combobox');
 
-      fireEvent.click(screen.getByText(fruits[0].label).closest('div')!);
+      fireEvent.click(
+        screen.getByText(fruits[0].label, VISIBLE).closest('div')!,
+      );
       await waitFor(() => expect(input.value).toBe(fruits[0].label));
 
       leaveEditMode(input);
@@ -1816,7 +1840,7 @@ describe('Typeahead edit mode', () => {
     const input = screen.getByRole('combobox');
 
     // Enter edit mode
-    const tokenText = screen.getByText(fruits[0].label);
+    const tokenText = screen.getByText(fruits[0].label, VISIBLE);
     fireEvent.click(tokenText.closest('div')!);
 
     // Blur without selecting anything
@@ -1839,7 +1863,7 @@ describe('Typeahead edit mode', () => {
 
     // Enter edit mode by clicking the token; the input uncollapses and
     // rejoins the Tab order (tabindex is cleared).
-    const tokenText = screen.getByText(fruits[0].label);
+    const tokenText = screen.getByText(fruits[0].label, VISIBLE);
     fireEvent.click(tokenText.closest('div')!);
     await act(async () => {
       await new Promise(r => requestAnimationFrame(r));
@@ -1890,7 +1914,9 @@ describe('Typeahead collapsed input tab order', () => {
     );
     // Focus the token's internal button, then Tab away — focus must not land
     // on the visually hidden combobox input.
-    const tokenButton = screen.getByRole('button', {name: fruits[0].label});
+    const tokenButton = screen.getByRole('button', {
+      name: new RegExp(`${fruits[0].label}$`),
+    });
     tokenButton.focus();
     await user.tab();
     expect(screen.getByRole('combobox')).not.toHaveFocus();
@@ -1918,7 +1944,7 @@ describe('Typeahead collapsed input tab order', () => {
       />,
     );
     // Entering edit mode removes the token and uncollapses the input
-    const tokenText = screen.getByText(fruits[0].label);
+    const tokenText = screen.getByText(fruits[0].label, VISIBLE);
     fireEvent.click(tokenText.closest('div')!);
     expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
   });
diff --git a/packages/core/src/Typeahead/Typeahead.tsx b/packages/core/src/Typeahead/Typeahead.tsx
index d582f885f7ce8..1f697086e9f86 100644
--- a/packages/core/src/Typeahead/Typeahead.tsx
+++ b/packages/core/src/Typeahead/Typeahead.tsx
@@ -428,6 +428,8 @@ export function Typeahead<T extends SearchableItem>({
   const generatedInputId = useId();
   const inputId = idProp ?? generatedInputId;
   const inputLabelId = useId();
+  const fieldLabelId = useId();
+  const tokenValueId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
   const inputGroup = useInputGroup();
@@ -653,14 +655,29 @@ export function Typeahead<T extends SearchableItem>({
         <BusyIndicatorLaneProvider value={busyLane}>
           <div {...stylex.props(styles.contentLane)}>
             {showToken && (
-              <Token
-                ref={tokenRef}
-                label={value.label}
-                size={size}
-                onClick={handleEnterEditMode}
-                isDisabled={isDisabled}
-                xstyle={styles.tokenOverlay}
-              />
+              <>
+                {/* The token's button is the field's Tab stop while a value
+                    shows, so it is named by the field label and the value and
+                    described like the input (input-fields FR10; WCAG 2.4.6,
+                    4.1.2). */}
+                <span id={tokenValueId} hidden>
+                  {value.label}
+                </span>
+                <Token
+                  ref={tokenRef}
+                  label={value.label}
+                  size={size}
+                  onClick={handleEnterEditMode}
+                  isDisabled={isDisabled}
+                  aria-labelledby={`${inputGroup ? inputLabelId : fieldLabelId} ${tokenValueId}`}
+                  aria-describedby={
+                    [ariaDescribedByProp, ariaDescribedBy]
+                      .filter(Boolean)
+                      .join(' ') || undefined
+                  }
+                  xstyle={styles.tokenOverlay}
+                />
+              </>
             )}
             <TrailingKeyDownContext value={onKeyDown}>
               <BaseTypeahead
@@ -735,6 +752,7 @@ export function Typeahead<T extends SearchableItem>({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputId}
+      labelID={fieldLabelId}
       descriptionID={description ? descriptionId : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

From a32f38c7a908e17e1d46cfc60153848e5a09297a Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sat, 31 Oct 2026 06:03:19 -0700
Subject: [PATCH 2/3] fix(Token): a disabled link token keeps caller naming;
 Token FR10 and AR2 say where clickable naming goes; changeset names old
 behavior and WCAG

Review follow-up: aria-labelledby and aria-describedby left rest, and the
disabled link branch spread only rest, so a disabled link token dropped
them; it now spreads labellingProps on its root, with a test. Token FR10
and AR2 record that a clickable token's naming inputs reach its inner
button (public-component-api INV5), and the FR10 verification row checks
it. The changeset names Token's old routing and WCAG 2.4.6 and 4.1.2.
---
 .changeset/typeahead-token-tab-stop-named.md |  4 ++-
 packages/core/src/Token/Token.spec.md        | 29 ++++++++++----------
 packages/core/src/Token/Token.test.tsx       | 18 ++++++++++++
 packages/core/src/Token/Token.tsx            |  1 +
 4 files changed, 37 insertions(+), 15 deletions(-)

diff --git a/.changeset/typeahead-token-tab-stop-named.md b/.changeset/typeahead-token-tab-stop-named.md
index 204f03e431a20..e1f26221d41b8 100644
--- a/.changeset/typeahead-token-tab-stop-named.md
+++ b/.changeset/typeahead-token-tab-stop-named.md
@@ -2,6 +2,8 @@
 '@astryxdesign/core': patch
 ---
 
-[fix] With a value, a `Typeahead`'s Tab stop is the value's token button, and it is now named by the field label and the value ("Fruit Apple", not just "Apple") and described by the field's description and status, so screen reader users know which field it belongs to. A clickable `Token` now passes `aria-labelledby` and `aria-describedby` to its inner button.
+[fix] With a value, a `Typeahead`'s Tab stop is the value's token button (WCAG 2.2 SC 2.4.6 and 4.1.2). It was named by the value alone ("Apple"), so screen reader users could not tell which field it belonged to. It is now named by the field label and the value ("Fruit Apple"), and described by the field's description and status.
+
+A clickable `Token` passed `aria-labelledby` and `aria-describedby` to its root, a generic element where they named nothing. It now passes them to its inner button, the element that owns its action. Every other structure keeps them on its root.
 
 @cixzhang @duytbp
diff --git a/packages/core/src/Token/Token.spec.md b/packages/core/src/Token/Token.spec.md
index 5ef81f6532096..9910267d11b74 100644
--- a/packages/core/src/Token/Token.spec.md
+++ b/packages/core/src/Token/Token.spec.md
@@ -130,7 +130,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | 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 |
+| 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
 
@@ -178,7 +178,8 @@ Consumer migration instructions belong in consumer docs and release notes.
   separate focusable controls in DOM order; neither is nested in the other, so
   the HTML interactive-content rule holds.
 - **AR2 — Names.** In the clickable and link-and-remove structures the inner
-  button or link takes its name from the Label. In the link structure the link
+  button or link takes its name from the Label, or, in the clickable structure,
+  from a caller `aria-labelledby` (FR10). In the link structure the link
   is the root and takes its name from all of its content, including End content
   (a label "Inbox" with a count reads "Inbox 12"). The
   Remove button is named by the translated "Remove {label}" string.
@@ -234,18 +235,18 @@ token's text color.
 
 ## Verification map
 
-| Contract           | Verification                                                                           | Representative states                                                                  | Mutation or failure expectation                                                                                                                                                                    | Audit section          |
-| ------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| FR2, FR10          | `Token.test.tsx` render, ref, and pass-through suites                                  | Static, clickable, and link roots; caller props                                        | A wrong root element, a detached ref, or a dropped caller prop fails DOM assertions. Gap: no test covers the ref on the link-and-remove container.                                                 | `audit:Token/behavior` |
-| FR1, FR7           | `Token.stories.tsx` size, icon, and end-content fixtures in a browser                  | Sizes, icon and end content                                                            | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout`   |
-| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites                          | Link, clickable, link and remove, modified and middle clicks                           | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`.                                            | `audit:Token/behavior` |
-| FR5, AR5           | `Token.test.tsx` disabled tests                                                        | Disabled clickable with remove; 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`     |
+| 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
 
diff --git a/packages/core/src/Token/Token.test.tsx b/packages/core/src/Token/Token.test.tsx
index d139f126265c6..81422e4dcad6b 100644
--- a/packages/core/src/Token/Token.test.tsx
+++ b/packages/core/src/Token/Token.test.tsx
@@ -256,6 +256,24 @@ describe('Token accessibility', () => {
     ).toBeInTheDocument();
   });
 
+  it('keeps aria-labelledby and aria-describedby on a disabled link token', () => {
+    render(
+      <>
+        <span id="dl-label">Docs section</span>
+        <span id="dl-hint">Unavailable offline</span>
+        <Token
+          label="Docs"
+          href="/docs"
+          isDisabled
+          aria-labelledby="dl-label"
+          aria-describedby="dl-hint"
+        />
+      </>,
+    );
+    const link = screen.getByRole('link', {name: 'Docs section'});
+    expect(link).toHaveAccessibleDescription('Unavailable offline');
+  });
+
   it("passes aria-labelledby and aria-describedby to a clickable token's button (public-component-api INV5)", () => {
     render(
       <>
diff --git a/packages/core/src/Token/Token.tsx b/packages/core/src/Token/Token.tsx
index 0d8a3e3381c9e..d89c1e318836e 100644
--- a/packages/core/src/Token/Token.tsx
+++ b/packages/core/src/Token/Token.tsx
@@ -390,6 +390,7 @@ export function Token({
           style,
         )}
         {...rest}
+        {...labellingProps}
         {...disabledInteractionProps(rest.onKeyDown)}
         {...sharedProps}>
         {content}

From 2c48ffb527b8c3dbc2c7de6a66c9b0c6ccdea2f8 Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sat, 31 Oct 2026 06:29:26 -0700
Subject: [PATCH 3/3] docs(Token): the Clickable representative state matches
 AR2 (label, or a caller aria-labelledby)

---
 packages/core/src/Token/Token.spec.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/core/src/Token/Token.spec.md b/packages/core/src/Token/Token.spec.md
index 9910267d11b74..8a3bc535b7797 100644
--- a/packages/core/src/Token/Token.spec.md
+++ b/packages/core/src/Token/Token.spec.md
@@ -142,15 +142,15 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State              | Required invariant                                                                    | Allowed variation           |
-| ------------------ | ------------------------------------------------------------------------------------- | --------------------------- |
-| Static             | `span` root; Token adds no focusable element except a Remove button.                  | Tone, size, slots.          |
-| Clickable          | One inner button named by the label; container click calls `onClick`.                 | End content.                |
-| Link               | Root is the link; focus outline on the link itself.                                   | Router link component.      |
-| Link and remove    | Container holds a link and a sibling Remove button; surface click activates the link. | Modified and middle clicks. |
-| Removable          | Remove button named "Remove {label}" with a 24 by 24 CSS pixel target.                | Locale wording.             |
-| Disabled clickable | Buttons focusable with `aria-disabled="true"`; no callback fires; half opacity.       | Tone.                       |
-| Hidden label       | Label text visually hidden; the root's `aria-label` equals the label.                 | Structure.                  |
+| State              | Required invariant                                                                                      | Allowed variation           |
+| ------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------- |
+| Static             | `span` root; Token adds no focusable element except a Remove button.                                    | Tone, size, slots.          |
+| Clickable          | One inner button named by the label, or by a caller `aria-labelledby`; container click calls `onClick`. | End content.                |
+| Link               | Root is the link; focus outline on the link itself.                                                     | Router link component.      |
+| Link and remove    | Container holds a link and a sibling Remove button; surface click activates the link.                   | Modified and middle clicks. |
+| Removable          | Remove button named "Remove {label}" with a 24 by 24 CSS pixel target.                                  | Locale wording.             |
+| Disabled clickable | Buttons focusable with `aria-disabled="true"`; no callback fires; half opacity.                         | Tone.                       |
+| Hidden label       | Label text visually hidden; the root's `aria-label` equals the label.                                   | Structure.                  |
 
 ### Transformation and precedence order