@astryxdesign/core 0.7.6-canary.786c16e → 0.7.6-canary.7958bd2

package/dist/SideNav/SideNavItem.d.ts

@@ -9,8 +9,8 @@
  * provided and fall back to `label` when it is missing or blank. Their label
  * tooltip binds to the interactive control through a callback ref, so hover,
  * keyboard focus, and `aria-describedby` follow the control from the first
- * collapsed render. A disabled control takes neither pointer nor focus, so its
- * row is the tooltip's trigger instead.
+ * collapsed render. A disabled control takes no pointer, so its row listens
+ * for the tooltip instead, while the control keeps focus and the description.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and

package/dist/SideNav/SideNavItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SideNavItem.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAIrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAgB,KAAK,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAkThF,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EACR,OAAO,GACP;QACE,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,CAAC;IACN;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,UAAkB,EAClB,UAAkB,EAClB,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EAAE,eAAe,EAC5B,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,MAAM,EACN,GAAG,IAAI,EACR,EAAE,gBAAgB,sCA2blB;yBA7ce,WAAW"}
+{"version":3,"file":"SideNavItem.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAIrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAgB,KAAK,WAAW,EAAC,MAAM,iCAAiC,CAAC;AA6ThF,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EACR,OAAO,GACP;QACE,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,CAAC;IACN;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,UAAkB,EAClB,UAAkB,EAClB,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EAAE,eAAe,EAC5B,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,MAAM,EACN,GAAG,IAAI,EACR,EAAE,gBAAgB,sCAiclB;yBAnde,WAAW"}

package/dist/SideNav/SideNavItem.js

@@ -13,8 +13,8 @@
  * provided and fall back to `label` when it is missing or blank. Their label
  * tooltip binds to the interactive control through a callback ref, so hover,
  * keyboard focus, and `aria-describedby` follow the control from the first
- * collapsed render. A disabled control takes neither pointer nor focus, so its
- * row is the tooltip's trigger instead.
+ * collapsed render. A disabled control takes no pointer, so its row listens
+ * for the tooltip instead, while the control keeps focus and the description.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and
@@ -52,6 +52,7 @@ import { useSideNavCollapse, SideNavCollapseContext } from "./SideNavCollapseCon
 import { useSideNavRenderMode } from "./SideNavRenderContext.js";
 import { useAppShellMobile } from "../AppShell/AppShellMobileContext.js";
 import { themeProps } from "../utils/themeProps.js";
+import { disabledInteractionProps } from "../utils/disabledInteraction.js";
 import { useTranslator } from "../i18n/index.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 // =============================================================================
@@ -207,6 +208,8 @@ const EXPANDED_COLLAPSE_STATE = {
 /**
  * Renders `<a>` (via LinkComponent) when `href` is set, otherwise `<button>`.
  * Centralizes the link-vs-button decision used across all SideNavItem paths.
+ * A disabled item is a `<button>` that keeps its tab stop and exposes
+ * `aria-disabled`, but is inert (spec:AST-085 FR1, FR2).
  */
 function NavItemElement({
   href,
@@ -231,8 +234,11 @@ function NavItemElement({
     ref: ref,
     type: "button",
     onClick: onClick,
-    disabled: isDisabled,
     ...rest,
+    ...(isDisabled ? {
+      'aria-disabled': true,
+      ...disabledInteractionProps(rest.onKeyDown)
+    } : null),
     children: children
   });
 }
@@ -335,6 +341,10 @@ export function SideNavItem({
   const isRailLeaf = isCollapsed && !hasChildren;
   const railTooltip = useTooltip({
     placement: 'end',
+    // A disabled leaf's row is the trigger (see the collapsed path). It is not
+    // focusable itself, so `auto` would never hear the focus that bubbles up
+    // from its control.
+    focusTrigger: 'always',
     isEnabled: isRailLeaf,
     isOpen: isRailLeaf ? undefined : false
   });
@@ -477,12 +487,14 @@ export function SideNavItem({
 
     // Items without children: icon-only link or button, its label in a
     // tooltip. The control is the trigger, so the element that takes focus is
-    // the one described. A disabled control takes neither pointer
-    // (`navItemStyles.disabled`) nor focus, so its row is the trigger instead.
+    // the one described. A disabled control takes no pointer
+    // (`navItemStyles.disabled`), so its row listens for the tooltip instead;
+    // the control still takes focus (focusin reaches the row) and stays the
+    // element described (spec:AST-085 FR5).
     const isRowTrigger = isDisabled;
     const collapsedAriaProps = {
       'aria-current': isSelected ? 'page' : undefined,
-      'aria-describedby': isRowTrigger ? rest['aria-describedby'] : joinIds(rest['aria-describedby'], railTooltip.describedBy),
+      'aria-describedby': joinIds(rest['aria-describedby'], railTooltip.describedBy),
       'aria-disabled': isDisabled || undefined,
       'aria-label': collapsedAccessibleLabel,
       'data-testid': testId
@@ -500,7 +512,6 @@ export function SideNavItem({
     });
     return /*#__PURE__*/_jsxs("div", {
       ref: isRowTrigger ? railTooltip.ref : undefined,
-      "aria-describedby": isRowTrigger ? railTooltip.describedBy : undefined,
       ...stylex.props(styles.root, xstyle),
       children: [collapsedElement, railTooltip.renderTooltip(label)]
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.6-canary.786c16e",
+  "version": "0.7.6-canary.7958bd2",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -847,9 +847,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.6-canary.786c16e",
-    "@astryxdesign/cli": "0.7.6-canary.786c16e",
-    "@astryxdesign/interaction-harness": "0.7.6-canary.786c16e",
+    "@astryxdesign/a11y-spec": "0.7.6-canary.7958bd2",
+    "@astryxdesign/cli": "0.7.6-canary.7958bd2",
+    "@astryxdesign/interaction-harness": "0.7.6-canary.7958bd2",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/SideNav/SideNav.test.tsx

@@ -964,10 +964,71 @@ describe('SideNavItem', () => {
     expect(button).not.toHaveAttribute('aria-current');
   });
 
-  it('disables the button when isDisabled', () => {
+  // spec:AST-085 FR1, FR2: a disabled item stays focusable but is inert.
+  it('keeps a disabled item focusable and exposes aria-disabled', () => {
     render(<SideNavItem label="Dashboard" isDisabled />);
-    const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    const button = screen.getByRole('button', {name: 'Dashboard'});
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    button.focus();
+    expect(button).toHaveFocus();
+  });
+
+  it('does not run onClick on a disabled item from a click, Enter or Space', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(<SideNavItem label="Dashboard" onClick={handleClick} isDisabled />);
+    const button = screen.getByRole('button', {name: 'Dashboard'});
+    fireEvent.click(button);
+    button.focus();
+    await user.keyboard('{Enter}');
+    await user.keyboard(' ');
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('renders a disabled item with href as a focusable button that does not navigate', () => {
+    const handleClick = vi.fn();
+    render(
+      <SideNavItem
+        label="Dashboard"
+        href="/dashboard"
+        onClick={handleClick}
+        isDisabled
+      />,
+    );
+    expect(screen.queryByRole('link')).toBeNull();
+    const button = screen.getByRole('button', {name: 'Dashboard'});
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).not.toHaveAttribute('href');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    fireEvent.click(button);
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('exposes aria-disabled on the primary of a disabled split row', () => {
+    render(
+      <SideNavItem label="Settings" href="/settings" collapsible isDisabled>
+        <SideNavItem label="General" href="/settings/general" />
+      </SideNavItem>,
+    );
+    const primary = screen.getByRole('button', {name: 'Settings'});
+    expect(primary).not.toHaveAttribute('disabled');
+    expect(primary).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('keeps focus on an item that becomes disabled while focused', () => {
+    const item = (isDisabled: boolean) => (
+      <SideNavItem
+        label="Dashboard"
+        onClick={() => {}}
+        isDisabled={isDisabled}
+      />
+    );
+    const {rerender} = render(item(false));
+    const button = screen.getByRole('button', {name: 'Dashboard'});
+    button.focus();
+    rerender(item(true));
+    expect(screen.getByRole('button', {name: 'Dashboard'})).toHaveFocus();
   });
 
   it('calls onClick handler', async () => {
@@ -2447,6 +2508,18 @@ describe('SideNavItem — mobile drawer close-on-activate', () => {
     expect(closeMobileNav).not.toHaveBeenCalled();
   });
 
+  it('does not close the mobile nav when a disabled item is activated', async () => {
+    const user = userEvent.setup();
+    const {closeMobileNav} = renderInDrawer(
+      <SideNavItem label="Home" href="/" isDisabled data-testid="item" />,
+    );
+    const item = screen.getByTestId('item');
+    fireEvent.click(item);
+    item.focus();
+    await user.keyboard('{Enter}');
+    expect(closeMobileNav).not.toHaveBeenCalled();
+  });
+
   it('does not close the mobile nav when a row action is clicked', async () => {
     const user = userEvent.setup();
     const onActionClick = vi.fn();
@@ -2495,7 +2568,7 @@ describe('SideNav keyboard operation', () => {
     expect(screen.getByRole('button', {name: 'Settings'})).toHaveFocus();
   });
 
-  it('skips a disabled item in the tab order', async () => {
+  it('keeps a disabled item in the tab order', async () => {
     const user = userEvent.setup();
     render(
       <SideNav>
@@ -2508,6 +2581,8 @@ describe('SideNav keyboard operation', () => {
     await user.tab();
     expect(screen.getByRole('button', {name: 'Dashboard'})).toHaveFocus();
     await user.tab();
+    expect(screen.getByRole('button', {name: 'Archived'})).toHaveFocus();
+    await user.tab();
     expect(screen.getByRole('button', {name: 'Settings'})).toHaveFocus();
   });
 
@@ -4001,6 +4076,51 @@ describe('SideNavItem collapsed-from-mount rail tooltip', () => {
     expect(spy.mock.contexts).toContain(layer);
   });
 
+  it('describes a disabled rail item on the control that takes focus', async () => {
+    // spec:AST-085 FR5: the disabled control keeps its tab stop, so the label
+    // tooltip has to describe it, not the row around it.
+    renderRail(
+      <SideNavItem
+        label="Analytics (Coming Soon)"
+        icon={StubIcon}
+        href="/analytics"
+        isDisabled
+      />,
+    );
+    await act(async () => {});
+    const button = screen.getByRole('button', {
+      name: 'Analytics (Coming Soon)',
+    });
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    expect(railTooltipFor(button)).toHaveTextContent('Analytics (Coming Soon)');
+    expect(button.parentElement).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('shows a disabled rail item its label when Tab focuses it', async () => {
+    // The row listens for the tooltip, but it is not focusable itself, so it
+    // has to hear the focus that bubbles up from the control.
+    const user = userEvent.setup();
+    const spy = vi.spyOn(HTMLElement.prototype, 'showPopover');
+    showPopover = spy;
+    renderRail(
+      <SideNavItem
+        label="Analytics (Coming Soon)"
+        icon={StubIcon}
+        href="/analytics"
+        isDisabled
+      />,
+    );
+    await act(async () => {});
+    const button = screen.getByRole('button', {
+      name: 'Analytics (Coming Soon)',
+    });
+
+    await user.tab();
+    expect(button).toHaveFocus();
+    expect(spy.mock.contexts).toContain(railTooltipFor(button));
+  });
+
   it('describes the link once a disabled item is enabled in the rail', () => {
     const item = (isDisabled: boolean) => (
       <SideNavItem

package/src/SideNav/SideNavItem.spec.md

@@ -39,7 +39,7 @@ system_specs: [spec:AST-085]
 | Behavior                | One SideNav row: a link or button with optional icon and passive end content, optional row-level actions beside it, and optional nested children that can expand and collapse. In a collapsed rail it is icon-only with a tooltip or a flyout.                |
 | End-user impact         | Users see and hear the current page, reach row actions before nested items, expand or collapse groups without navigating, and return to the page after choosing a destination in the mobile drawer.                                                           |
 | Builder impact          | None.                                                                                                                                                                                                                                                         |
-| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact).                                                                                                                                                              |
+| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps (see Current-state impact).                                                                                                                                                             |
 | Review checks           | Reject an interactive control rendered inside the primary element, a link that also toggles collapse, a toggle or action that activates the row, collapsed children that stay reachable, or a drawer activation that leaves the drawer open after navigating. |
 | Governing rules         | `component:SideNav` FR1–FR5, DD1 (nesting and row geometry); `family:navigation-destinations`; `architecture:interaction-modality`; `architecture:public-component-api`.                                                                                      |
 
@@ -68,10 +68,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Current-state impact
 
-- **A disabled item leaves the tab order.** A disabled item renders a
-  `<button>` with the native `disabled` attribute, so it is skipped by Tab and
-  exposes no focusable disabled state. `spec:AST-085` FR1 has a disabled control
-  expose `aria-disabled="true"` and keep its tab stop.
 - **A disabled parent stays operable in a collapsed rail.** In a collapsed rail,
   a disabled item with children renders its flyout trigger with neither
   `disabled` nor `aria-disabled`, so it keeps its tab stop and announces no
@@ -125,7 +121,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 | ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
 | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1  | The primary element is the `as` component, else the `LinkProvider` link, else `<a>`, when `href` is set and the item is enabled; otherwise a `<button type="button">`. A disabled item MUST stay focusable with `aria-disabled="true"` and keep its tab stop (`spec:AST-085` FR1). Implementation gap: a disabled item renders native `disabled` instead, which removes it from the tab order. It shows the icon (`selectedIcon` when selected and given), the label, `endContent`, and, for a whole-row collapsible item, a chevron. `endContent` is passive and renders inside the primary element.                                                                       | Current source and tests |
+| FR1  | The primary element is the `as` component, else the `LinkProvider` link, else `<a>`, when `href` is set and the item is enabled; otherwise a `<button type="button">`. A disabled item stays focusable with `aria-disabled="true"`, keeps its tab stop, and keeps focus when it becomes disabled (`spec:AST-085` FR1, FR4). It shows the icon (`selectedIcon` when selected and given), the label, `endContent`, and, for a whole-row collapsible item, a chevron. `endContent` is passive and renders inside the primary element.                                                                                                                                          | Current source and tests |
 | FR2  | In an expanded rail and on a collapsed leaf, `isSelected` sets `aria-current="page"` on the primary element, never on a row wrapper. A collapsed parent's flyout trigger carries no `aria-current`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
 | FR3  | A disabled item does not fire `onClick` or navigate. Its row actions stay operable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
 | FR4  | `actions` render as siblings of the primary element at the row's trailing edge, after the toggle and before nested children in DOM and focus order, at the row's control size (`sm`) unless a control sets its own (`architecture:component-size-cascade`). Clicking an action neither activates nor toggles the row. A row wrapper exists only when there are actions or an independent toggle; a falsy `actions` adds none.                                                                                                                                                                                                                                               | Current source and tests |
@@ -146,16 +142,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State                      | Required invariant                                                                     | Allowed variation |
-| -------------------------- | -------------------------------------------------------------------------------------- | ----------------- |
-| Link, selected             | `aria-current="page"` on the link; selected icon if given.                             | Fill.             |
-| Disabled button            | `aria-disabled`; focusable; no `onClick`. Implementation gap: native `disabled` (FR1). | Muted styling.    |
-| Collapsible without action | Whole row toggles; chevron turns.                                                      | —                 |
-| Collapsible with `href`    | Link navigates; separate toggle button collapses.                                      | —                 |
-| Actions                    | Actions after toggle, before children; never activate the row.                         | Action content.   |
-| Collapsed rail leaf        | Icon-only; tooltip with label.                                                         | —                 |
-| Collapsed rail parent      | Icon-only trigger; flyout with header and children.                                    | Delay.            |
-| Mobile drawer              | Activation closes the drawer.                                                          | —                 |
+| State                      | Required invariant                                             | Allowed variation |
+| -------------------------- | -------------------------------------------------------------- | ----------------- |
+| Link, selected             | `aria-current="page"` on the link; selected icon if given.     | Fill.             |
+| Disabled button            | `aria-disabled`; focusable; no `onClick`.                      | Muted styling.    |
+| Collapsible without action | Whole row toggles; chevron turns.                              | —                 |
+| Collapsible with `href`    | Link navigates; separate toggle button collapses.              | —                 |
+| Actions                    | Actions after toggle, before children; never activate the row. | Action content.   |
+| Collapsed rail leaf        | Icon-only; tooltip with label.                                 | —                 |
+| Collapsed rail parent      | Icon-only trigger; flyout with header and children.            | Delay.            |
+| Mobile drawer              | Activation closes the drawer.                                  | —                 |
 
 ### Transformation and precedence order
 
@@ -211,16 +207,10 @@ is recorded. Row geometry visual intent is `component:SideNav` DD1.
 | FR11          | `SideNav.test.tsx` focus ring suite                                 | Plain, split, actions rows                                                                                                | Missing shared ring classes fail.                                                 | `audit:SideNavItem/accessibility` |
 | FR3, FR7, FR9 | `SideNav.test.tsx` keyboard operation and focus management suites   | Tab order, Enter/Space toggle, flyout Escape                                                                              | Lost order, a stranded focus, or no focus return fails.                           | `audit:SideNavItem/accessibility` |
 
-Pending conformance: the SideNavItem suite's native-`disabled` assertion and
-the keyboard suite's disabled Tab-skip assertion pin FR1's implementation gap;
-they change when disabled items follow `spec:AST-085`.
-
 Read from source, with no focused test yet:
 
-- FR1 and ORD1–ORD2: a disabled item with `href` rendering a button, the
-  required focusable `aria-disabled` shape (no item renders it yet), the
-  button's `type="button"`, the icon, the selected-icon swap, and the whole-row
-  chevron.
+- FR1 and ORD1–ORD2: the button's `type="button"`, the icon, the
+  selected-icon swap, and the whole-row chevron.
 - FR4: the actions' trailing-edge placement and the wrapper for an independent
   toggle without actions.
 - FR5: the forwarded `ref` and `xstyle` on the outer box.

package/src/SideNav/SideNavItem.tsx

@@ -13,8 +13,8 @@
  * provided and fall back to `label` when it is missing or blank. Their label
  * tooltip binds to the interactive control through a callback ref, so hover,
  * keyboard focus, and `aria-describedby` follow the control from the first
- * collapsed render. A disabled control takes neither pointer nor focus, so its
- * row is the tooltip's trigger instead.
+ * collapsed render. A disabled control takes no pointer, so its row listens
+ * for the tooltip instead, while the control keeps focus and the description.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and
@@ -74,6 +74,7 @@ import {
 import {useSideNavRenderMode} from './SideNavRenderContext';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
+import {disabledInteractionProps} from '../utils/disabledInteraction';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -324,6 +325,8 @@ interface NavItemElementProps {
 /**
  * Renders `<a>` (via LinkComponent) when `href` is set, otherwise `<button>`.
  * Centralizes the link-vs-button decision used across all SideNavItem paths.
+ * A disabled item is a `<button>` that keeps its tab stop and exposes
+ * `aria-disabled`, but is inert (spec:AST-085 FR1, FR2).
  */
 function NavItemElement({
   href,
@@ -351,8 +354,16 @@ function NavItemElement({
       ref={ref as React.Ref<HTMLButtonElement>}
       type="button"
       onClick={onClick}
-      disabled={isDisabled}
-      {...rest}>
+      {...rest}
+      {...(isDisabled
+        ? {
+            'aria-disabled': true,
+            ...disabledInteractionProps(
+              rest.onKeyDown as
+                React.KeyboardEventHandler<HTMLButtonElement> | undefined,
+            ),
+          }
+        : null)}>
       {children}
     </button>
   );
@@ -539,6 +550,10 @@ export function SideNavItem({
   const isRailLeaf = isCollapsed && !hasChildren;
   const railTooltip = useTooltip({
     placement: 'end',
+    // A disabled leaf's row is the trigger (see the collapsed path). It is not
+    // focusable itself, so `auto` would never hear the focus that bubbles up
+    // from its control.
+    focusTrigger: 'always',
     isEnabled: isRailLeaf,
     isOpen: isRailLeaf ? undefined : false,
   });
@@ -702,14 +717,17 @@ export function SideNavItem({
 
     // Items without children: icon-only link or button, its label in a
     // tooltip. The control is the trigger, so the element that takes focus is
-    // the one described. A disabled control takes neither pointer
-    // (`navItemStyles.disabled`) nor focus, so its row is the trigger instead.
+    // the one described. A disabled control takes no pointer
+    // (`navItemStyles.disabled`), so its row listens for the tooltip instead;
+    // the control still takes focus (focusin reaches the row) and stays the
+    // element described (spec:AST-085 FR5).
     const isRowTrigger = isDisabled;
     const collapsedAriaProps = {
       'aria-current': isSelected ? ('page' as const) : undefined,
-      'aria-describedby': isRowTrigger
-        ? rest['aria-describedby']
-        : joinIds(rest['aria-describedby'], railTooltip.describedBy),
+      'aria-describedby': joinIds(
+        rest['aria-describedby'],
+        railTooltip.describedBy,
+      ),
       'aria-disabled': isDisabled || undefined,
       'aria-label': collapsedAccessibleLabel,
       'data-testid': testId,
@@ -732,7 +750,6 @@ export function SideNavItem({
     return (
       <div
         ref={isRowTrigger ? railTooltip.ref : undefined}
-        aria-describedby={isRowTrigger ? railTooltip.describedBy : undefined}
         {...stylex.props(styles.root, xstyle)}>
         {collapsedElement}
         {railTooltip.renderTooltip(label)}