@astryxdesign/core 0.7.2-canary.22c592a → 0.7.2-canary.25548b9

package/dist/Chat/ChatLayoutScrollButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatLayoutScrollButton.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatLayoutScrollButton.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAa1B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAS5C,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,SAAS,CAAC,cAAc,CAAC,EACzB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qCAAqC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAsED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,GAAG,EACH,SAAS,EACT,KAAK,EACL,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,2BAA2B,qBAuC7B;yBAhDe,sBAAsB"}
+{"version":3,"file":"ChatLayoutScrollButton.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatLayoutScrollButton.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAa1B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAS5C,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,SAAS,CAAC,cAAc,CAAC,EACzB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qCAAqC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAuED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,GAAG,EACH,SAAS,EACT,KAAK,EACL,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,2BAA2B,qBAwC7B;yBAjDe,sBAAsB"}

package/dist/Chat/ChatLayoutScrollButton.js

@@ -89,6 +89,7 @@ export function ChatLayoutScrollButton({
       ...mergeProps(stylex.props(styles.wrapper, xstyle), className, style),
       ...rest,
       children: /*#__PURE__*/_jsx("div", {
+        inert: !isVisible,
         ...mergeProps(themeProps('chat-layout-scroll-button'), {
           0: {
             className: "xawy1a7 xb3r6kr xjspbzw x1prclbq x14hfi27 x1ueg155 xrgg2z9 xlr8y92 x2rcmwa x12w9bfk xg01cxk x47corl xlshs6z x1jys5uj"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.2-canary.22c592a",
+  "version": "0.7.2-canary.25548b9",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,8 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.2-canary.22c592a",
-    "@astryxdesign/cli": "0.7.2-canary.22c592a",
+    "@astryxdesign/a11y-spec": "0.7.2-canary.25548b9",
+    "@astryxdesign/cli": "0.7.2-canary.25548b9",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/Chat/ChatLayoutScrollButton.test.tsx

@@ -70,6 +70,19 @@ describe('ChatLayoutScrollButton', () => {
     ).toHaveFocus();
   });
 
+  it('makes the pill inert whenever the visible state turns off', () => {
+    const {container, rerender} = render(
+      <ChatLayoutScrollButton isVisible onClick={() => {}} />,
+    );
+    const pill = container.querySelector('.astryx-chat-layout-scroll-button');
+
+    expect(pill).not.toHaveAttribute('inert');
+
+    rerender(<ChatLayoutScrollButton isVisible={false} onClick={() => {}} />);
+
+    expect(pill).toHaveAttribute('inert');
+  });
+
   it('is not keyboard reachable while hidden', async () => {
     const user = userEvent.setup();
     render(

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -86,8 +86,9 @@ const styles = stylex.create({
     opacity: 0,
     pointerEvents: 'none',
     // The hidden pill paints nothing, so focus landing on it would have no
-    // visible indicator (WCAG 2.2 SC 2.4.7). `opacity` and `pointer-events`
-    // leave the button in sequential focus navigation; `visibility` removes it.
+    // visible indicator (WCAG 2.2 SC 2.4.7). `visibility` removes it from
+    // sequential navigation after the fade; `inert` immediately prevents new
+    // focus and makes an already-focused descendant relinquish focus.
     visibility: 'hidden',
     maxWidth: sizeVars['--size-element-md'],
   },
@@ -151,6 +152,7 @@ export function ChatLayoutScrollButton({
       {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
       {...rest}>
       <div
+        inert={!isVisible}
         {...mergeProps(
           themeProps('chat-layout-scroll-button'),
           stylex.props(

package/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts

@@ -44,6 +44,7 @@ const STORY_ID = 'core-chatlayout--scroll-affordance-states';
  * a stable handle for it.
  */
 const PILL = '.astryx-chat-layout-scroll-button';
+const AFFORDANCE = `${PILL} button`;
 
 /** One observed tab stop, identified structurally rather than by its text. */
 type FocusStop = {
@@ -126,7 +127,11 @@ test.afterAll(async () => {
 
 async function openStory(
   page: Page,
-  {theme = 'neutral', colorMode = 'light'} = {},
+  {
+    theme = 'neutral',
+    colorMode = 'light',
+    holdMotion = true,
+  }: {theme?: string; colorMode?: string; holdMotion?: boolean} = {},
 ): Promise<Locator> {
   page.on('pageerror', error => pageErrors.push(String(error)));
   browserVersion = page.context().browser()?.version() ?? 'unknown';
@@ -136,7 +141,9 @@ async function openStory(
   );
   const root = page.locator('.astryx-chat-layout');
   await root.waitFor({state: 'visible'});
-  await holdMotionStill(page);
+  if (holdMotion) {
+    await holdMotionStill(page);
+  }
   await page.evaluate(async () => document.fonts.ready);
   return root;
 }
@@ -169,21 +176,25 @@ async function pillVisibility(page: Page): Promise<string> {
 }
 
 /**
- * Can the affordance take focus at all? This is the mechanism under test:
- * `visibility: hidden` removes an element from sequential focus navigation AND
- * refuses programmatic focus, which `opacity: 0` does neither of. A CSS locator
- * is used rather than a role query because a hidden button is not in the
- * accessibility tree and a role query would not resolve it.
+ * Can the affordance take new focus at all? This is one half of the mechanism
+ * under test: `inert` refuses programmatic focus immediately, while delayed
+ * `visibility: hidden` removes the control from sequential navigation after the
+ * fade. A CSS locator is used rather than a role query because a hidden button
+ * is not in the accessibility tree and a role query would not resolve it.
  */
-async function affordanceAcceptsFocus(page: Page): Promise<boolean> {
-  return page
-    .locator('.astryx-chat-layout-scroll-button button')
-    .evaluate(element => {
-      // preventScroll: focusing must not move the scroll position, or the
-      // probe would change the very state the next assertion reads.
-      (element as HTMLElement).focus({preventScroll: true});
-      return document.activeElement === element;
-    });
+async function affordanceAcceptsFocus(
+  page: Page,
+  resetFocus: Locator,
+): Promise<boolean> {
+  // Start outside the affordance so this probe proves a NEW focus transfer;
+  // equality alone would also be true when a button stayed active as it hid.
+  await resetFocus.focus();
+  return page.locator(AFFORDANCE).evaluate(element => {
+    // preventScroll: focusing must not move the scroll position, or the
+    // probe would change the very state the next assertion reads.
+    (element as HTMLElement).focus({preventScroll: true});
+    return document.activeElement === element;
+  });
 }
 
 /**
@@ -340,6 +351,36 @@ async function capture(
   return receipt;
 }
 
+test('the hiding affordance releases focus before its fade finishes', async ({
+  page,
+}) => {
+  const root = await openStory(page, {holdMotion: false});
+  const pill = page.locator(PILL);
+  const affordance = page.locator(AFFORDANCE);
+
+  await scrollToTop(root);
+  await expect(pill).toHaveCSS('visibility', 'visible');
+  await affordance.focus();
+  await expect(affordance).toBeFocused();
+
+  await page.keyboard.press('Enter');
+  await expect
+    .poll(
+      async () =>
+        affordance.evaluate(element => document.activeElement === element),
+      {timeout: 5000},
+    )
+    .toBe(false);
+
+  // `visibility` flips only after the fade. Focus leaving while it is still
+  // visible proves the immediate `inert` state rather than the delayed CSS.
+  await expect(pill).toHaveCSS('visibility', 'visible');
+  await expect
+    .poll(async () => distanceFromBottom(root), {timeout: 5000})
+    .toBeLessThan(2);
+  await expect(pill).toHaveCSS('visibility', 'hidden');
+});
+
 test('the scroll affordance is keyboard reachable exactly while it is visible', async ({
   page,
 }) => {
@@ -367,7 +408,7 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
   expect(await distanceFromBottom(root)).toBeLessThan(2);
   await expect(pill).toHaveCSS('visibility', 'hidden');
   expect(
-    await affordanceAcceptsFocus(page),
+    await affordanceAcceptsFocus(page, before),
     'a control that paints nothing must refuse focus (WCAG 2.2 SC 2.4.7)',
   ).toBe(false);
   const restFrame = await capture(page, 'rest-hidden', {
@@ -384,7 +425,7 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
   await expect(pill).toHaveCSS('visibility', 'visible');
   expect(await distanceFromBottom(root)).toBeGreaterThan(100);
   expect(
-    await affordanceAcceptsFocus(page),
+    await affordanceAcceptsFocus(page, before),
     'the visible affordance must keep its keyboard access',
   ).toBe(true);
   await expect(
@@ -415,8 +456,12 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
     .poll(async () => distanceFromBottom(root), {timeout: 5000})
     .toBeLessThan(2);
   await expect(pill).toHaveCSS('visibility', 'hidden');
+  await expect(
+    page.locator(AFFORDANCE),
+    'the affordance must relinquish focus when it hides',
+  ).not.toBeFocused();
   expect(
-    await affordanceAcceptsFocus(page),
+    await affordanceAcceptsFocus(page, before),
     'after returning to the bottom the affordance must refuse focus again',
   ).toBe(false);
   const returnedFrame = await capture(page, 'returned-hidden', {

package/src/ContextMenu/ContextMenu.test.tsx

@@ -10,7 +10,7 @@
 
 import {useRef, useState} from 'react';
 import {createPortal} from 'react-dom';
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
 import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {readFileSync} from 'node:fs';
@@ -26,6 +26,11 @@ import {
 import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
 import {Divider} from '../Divider';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {warmMenuBottomSheet} from '../DropdownMenu/__tests__/warmMenuBottomSheet';
+
+// The touch sheet is loaded lazily; resolve its modules once up front, so
+// ContextMenu's own lazy sheet renders within the cases' waitFor.
+beforeAll(warmMenuBottomSheet, 20000);
 
 function NestedDismissibleLayer({onDismiss}: {onDismiss: () => void}) {
   const [isOpen, setIsOpen] = useState(true);

package/src/SideNav/SideNav.spec.md

@@ -0,0 +1,227 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:SideNav
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-16
+owners: [cixzhang]
+review_triggers: [layout, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/SideNav/SideNav.test.tsx,
+    apps/storybook/stories/SideNav.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-017/FR3]
+---
+
+# SideNav component contract
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+This record governs how nested SideNavItem rows are drawn: their width, where
+their nesting indent sits, and what the indent area does. It covers SideNav,
+SideNavSection, and SideNavItem only as far as that geometry depends on them.
+SideNavItem's link and destination safety is governed by
+`family:navigation-destinations`; other SideNav behavior remains described by
+its source, tests, and consumer docs until a record claims it.
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None. No prop, value, default, or theme target changes.                                                                                                                                                                                                 |
+| Behavior                | Every SideNavItem row spans the full width of its nav list at any depth. Depth shows as inline-start indent inside the row: one `--spacing-6` step per level, added to the row's own padding.                                                           |
+| End-user impact         | A person scanning a nested nav sees hover, pressed, selected, and focus fills that line up with the top-level rows, and can click a nested row's indent to activate it, as they would its label.                                                        |
+| Builder impact          | No new choice or prop. Icons and labels keep their per-depth position. Content placed directly inside a SideNavItem that is not itself a SideNavItem sits at the nav list edge, because the nested group adds no inset; no supported setting insets it. |
+| Compatibility/readiness | Nonbreaking change of visual direction (`spec:AST-017/FR3`). The collapsed rail and top-level rows are unchanged. Authority is current; implementation may be staged.                                                                                   |
+| Review checks           | Reject a nested row narrower than a top-level row, an indent drawn outside the row, an indent area that shows feedback but does not activate, a clipped focus ring, or an indent in the flyout's top level.                                             |
+| Governing rules         | DD1 and FR3–FR5 below; `family:navigation-destinations` for destinations; `architecture:internationalization` for logical direction.                                                                                                                    |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+SideNav is the vertical navigation region of an app. SideNavItem rows can nest
+to show a hierarchy of destinations. Nesting must read as one list of equal
+rows, so the eye compares labels and states across depths rather than seeing a
+second, narrower kind of row. SideNav owns this because only SideNavItem knows
+a row's depth and its row padding.
+
+## Compatibility and migration
+
+- Released default preserved: `no`; nested rows change from inset to full width.
+  Top-level rows and the collapsed rail are unchanged.
+- Compatibility class: nonbreaking appearance change of visual direction under
+  `spec:AST-017/FR3`; no public API, accepted input, or accessibility semantic
+  changes.
+- Controlled/uncontrolled behavior: unchanged.
+- Migration decision: none; there is no supported way to keep the inset look.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The width of every expanded SideNavItem row, at every depth.
+- Where a nested row's indent sits, its step, and how it adds to the row's
+  padding.
+- What the indent area paints and what a click on it does.
+- Whether the nested group clips its rows.
+
+**Does not own / non-goals**
+
+- Destination acceptance, blocking, and router handoff — owned by
+  `family:navigation-destinations`.
+- The collapsed item's tooltip and how it attaches — outside this record.
+- Exact fill colors, radius, row height, and row padding per size — owned by
+  the shared nav item styles and the `side-nav-item` theme target.
+- Layout of caller content placed directly inside a SideNavItem that is not a
+  SideNavItem — owned by the product callsite.
+- SideNavHeading, SideNavCollapseButton, and the SideNav header, footer, and
+  resize zones.
+
+## Public concepts
+
+| Concept       | Closed values or states                        | Meaning                                                                                                     | Availability by variant/orientation/state | Default | Owner               | Stability | Invalid-value behavior |
+| ------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | ------------------- | --------- | ---------------------- |
+| Nesting depth | `0`, `1`, `2`, … (derived, not a prop)         | The number of SideNavItem ancestors of a row within the same list. A collapsed rail's flyout restarts at 0. | Expanded rail; mobile drawer; flyout      | `0`     | `component:SideNav` | stable    | Not caller-settable    |
+| Row size      | `sm`, `md`, `lg` (existing SideNavItem `size`) | Sets the row's height and base inline padding; the indent adds to that padding.                             | Every row                                 | `md`    | `component:SideNav` | stable    | Rejected by the type   |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                       | Draft review state                           |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------- |
+| FR1 | SideNav renders its navigation children in a scrollable list, which may be grouped by SideNavSection. A SideNavItem with children renders them, after its own row, in a group labelled by the parent's label; unless `collapsible` is `false`, the group expands and collapses and is hidden from assistive technology and inert while collapsed.                                        | Current source, docs, and tests                             | Current behavior                             |
+| FR2 | In a collapsed rail, a SideNavItem without an icon is not rendered; a leaf item renders icon-only, named by a non-blank caller `aria-label` or else its label; an item with children renders an icon-only trigger that opens a flyout listing its children as the flyout's top level.                                                                                                    | Current source, docs, and tests                             | Current behavior                             |
+| FR3 | In an expanded rail, in a flyout, and in the mobile navigation drawer, every SideNavItem row MUST span the full inline size of its list at any depth. A row at depth `n` MUST start its content `n` × `--spacing-6` beyond the row's own inline-start padding for its size, inside the row; the nested group MUST add no inset. A flyout's top level is depth 0.                         | `component:SideNav/DEC-1`                                   | Settled intent; implementation may be staged |
+| FR4 | The indent area MUST be part of the row's target: a click there, including a modified or middle click on a link row, does what the same click on the row's primary element does. When the row also carries an independent expand toggle or `actions`, the indent belongs to the primary link or button, and the toggle and actions keep their own activation at the row's trailing edge. | `component:SideNav/DEC-1`; `family:navigation-destinations` | Settled intent; implementation may be staged |
+| FR5 | An expanded nested group MUST NOT clip its rows once it has finished opening, so a nested row's focus ring paints in full. The group MAY clip while collapsed and while it opens or closes.                                                                                                                                                                                              | `component:SideNav/DEC-1`                                   | Settled intent; implementation may be staged |
+
+### Allowed variation
+
+- **AV1 — Depth and size.** Any depth and any row size may appear; FR3 holds for
+  each row from its own size's padding.
+- **AV2 — Theme tokens.** A theme that changes `--spacing-6` or the row padding
+  tokens changes the step or the base with them.
+- **AV3 — Row implementation.** The element that carries the indent may change
+  while the painted row stays full width and the indent stays clickable.
+
+### Representative states
+
+| State                                 | Required invariant                                                                        | Allowed variation               |
+| ------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------- |
+| Depth 1–3, `md`                       | Row width equals a top-level row's; content starts one step further in per level.         | Labels, icons, selection.       |
+| `sm` and `lg` nested rows             | Indent adds to that size's base padding.                                                  | Row height by size.             |
+| Nested row with own link and children | Full-width row; indent is part of the link; the expand toggle stays at the trailing edge. | Collapsed or expanded children. |
+| Nested row with `actions`             | Full-width row; indent is part of the primary element; actions stay at the trailing edge. | Action content.                 |
+| Keyboard focus on a nested row        | The focus ring paints in full around the row.                                             | Ring style by theme.            |
+| Right-to-left                         | Indent sits at the inline start (right); same widths.                                     | Writing direction.              |
+| Collapsed rail                        | Icon-only items; the flyout's top level has no indent; deeper flyout levels indent.       | Flyout content.                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Row inline-start padding.** The row's size padding, then plus depth ×
+  `--spacing-6`. A caller's `style` on a nested item composes after the indent in the
+  shared order (`architecture:public-component-api`): properties the caller does
+  not set keep the indent, and a caller-set inline-start padding replaces it.
+
+### Performance and resources
+
+- **PR1 — No measurement.** Depth and indent come from composition; no
+  measurement, observer, or extra render pass is added.
+
+## Accessibility contract
+
+- **AR1 — Presentation only.** Width and indent MUST NOT change any row's role,
+  accessible name, state, DOM order, or tab order.
+- **AR2 — Visible focus.** A nested row's focus indicator MUST paint in full at
+  every depth (FR5).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                 | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
+| Navigation items | Nested rows read as equal rows of one list; depth reads as indent. | Owner choice (DD1)       | Prominent      | FR3–FR5            |
+
+### Design decisions
+
+<!-- design-decisions:v1 -->
+
+| ID  | Decision                                                                                                                                                                                                         | Intent or reason                                                                                                                                                                                            | Applies to                                                                                         | Allowed variation                                                                                            |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| DD1 | Every SideNavItem row spans the full width of its nav list at any depth; nesting shows as indent inside the row, ahead of its content. Hover, pressed, selected, and focus paint the whole row, indent included. | Fills line up across depths, so the nav reads as one list of equal rows while labels keep their per-level alignment; the indent belongs to the row's primary target rather than sitting beside it as a gap. | SideNavItem rows at every depth, at rest and through hover, pressed, selected, disabled, and focus | Themes restyle fill, radius, and padding through the `side-nav-item` target; the step follows `--spacing-6`. |
+
+## Family and system relationships
+
+- `family:navigation-destinations` owns the accept/block result for a
+  SideNavItem `href`; the indent area activates the same destination the primary
+  element does (FR4).
+- `architecture:internationalization` owns logical direction; the indent is
+  inline-start and mirrors under right-to-left.
+- `architecture:interaction-modality` owns shared focus-visible behavior; FR5
+  keeps the ring visible at every depth.
+- `architecture:component-theming-surface` owns the `side-nav-item` target;
+  this record adds no target or state.
+- `architecture:public-component-api` owns how caller styling inputs compose;
+  ORD1 places the indent before a caller's `style`.
+- `spec:AST-017/FR3` classifies the change as a nonbreaking change of visual
+  direction.
+- `component:TreeList` DD1–DD3 record the same row geometry for TreeList. They
+  are precedent, not authority here; each component owns its own rows.
+
+## Verification map
+
+| Contract  | Verification                                                                          | Representative states                                                                         | Mutation or failure expectation                                                                                                                                        | Audit section            |
+| --------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1, FR2  | `SideNav.test.tsx` nesting, collapsible, and collapsed-rail suites                    | Nested, collapsible, collapsed rail, flyout                                                   | Removing the labelled group, its collapsed inert state, or the collapsed icon-only and flyout paths fails.                                                             | `audit:SideNav/anatomy`  |
+| FR3, ORD1 | Focused `SideNav.test.tsx` indent coverage, required with implementation              | Depth 1 and 2; `sm` and `md`; split and actions rows; caller `style`; flyout                  | A group inset, a missing or wrong indent, a dropped caller `style`, an indent that overrides a caller-set inline-start padding, or an indented flyout top level fails. | `audit:SideNav/layout`   |
+| FR3, DD1  | Real-browser geometry over the SideNav nested stories                                 | Depths 1–3; `sm`, `md`, `lg`; light and dark; right-to-left; mobile drawer                    | A nested row's box narrower than a top-level row's, or a label moved from its per-depth position, fails.                                                               | `audit:SideNav/layout`   |
+| FR4       | Real-browser click in the indent area of plain, split, and actions rows               | Link and button rows; plain, modified, and middle clicks; nested rows with toggle and actions | A click in the indent that does nothing or differs from the same click on the primary element, or a toggle or action that activates the row, fails.                    | `audit:SideNav/behavior` |
+| FR5, AR2  | `SideNav.test.tsx` group clipping case and real-browser keyboard focus on nested rows | Only-child and last nested rows; after opening; collapsed                                     | A focus ring cut at any edge of an expanded group, or an expanded group that still clips, fails.                                                                       | `audit:SideNav/a11y`     |
+| FR2, FR3  | Real-browser collapsed rail and flyout                                                | Collapsed rail with nested children                                                           | Any change to the collapsed rail, or an indent on the flyout's top level, fails.                                                                                       | `audit:SideNav/layout`   |
+| AR1       | Accessibility-tree comparison of nested rows                                          | Plain, split, and actions rows                                                                | Any change in role, name, state, or order fails.                                                                                                                       | `audit:SideNav/a11y`     |
+
+## Decision log
+
+<!-- Record the boundary or requirement, not how it was reached. A rejected alternative is at most one line here, kept only when it is consequential and likely to recur. -->
+
+### DEC-1 — Nested rows are full width; depth is indent inside the row
+
+**Reference:** `component:SideNav/DEC-1`
+**Decider:** cixzhang, 2026-10-16
+
+A nested row that starts at its indent paints its fills from a different edge
+than the rows above it, so it reads as a different, narrower component. A row that
+spans the full width with its indent inside lines up every fill and keeps each
+label at its per-depth position. The indent is part of the row's primary
+target, so it acts as well as lights up. Full-width rows reach the nested group's
+edges, so an open group must not clip them, or their focus ring is cut off.
+
+Rejected: indenting the nested group from outside the rows, because fills then
+start at a different edge per depth.
+
+## 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/Toolbar/Toolbar.test.tsx

@@ -140,14 +140,6 @@ describe('Toolbar', () => {
     );
   });
 
-  it('sets aria-orientation to vertical', () => {
-    render(<Toolbar label="Actions" orientation="vertical" />);
-    expect(screen.getByRole('toolbar')).toHaveAttribute(
-      'aria-orientation',
-      'vertical',
-    );
-  });
-
   it('reflects the size', () => {
     render(<Toolbar label="Actions" size="sm" />);
     const toolbar = screen.getByRole('toolbar');

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

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Toolbar.a11y.chromium.spec.ts
+ * @input Built toolbar stories and TOOLBAR_PATTERN in real Chromium
+ * @output Browser evidence for every toolbar expectation across Toolbar's representative states, and a paint check that each state's controls sit on the axis and in the direction it declares
+ * @position Chromium lane of the Toolbar binding
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  TOOLBAR_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {
+  TOOLBAR_BINDING_STATES,
+  type ToolbarBindingState,
+} from './Toolbar.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+async function mountState(
+  page: Page,
+  state: ToolbarBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const root = page.locator('#storybook-root');
+  const subject = root.getByRole('toolbar', {name: state.label, exact: true});
+  await expect(subject).toBeVisible();
+  const related: Record<string, Locator> = {
+    before: root.getByRole('button', {
+      name: 'Before the toolbar',
+      exact: true,
+    }),
+    after: root.getByRole('button', {name: 'After the toolbar', exact: true}),
+  };
+  for (const [relation, name] of Object.entries(state.controls)) {
+    related[relation] = subject.getByRole('button', {name, exact: true});
+  }
+  return {subject, related};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: ToolbarBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLBAR_PATTERN,
+    binding: 'Toolbar',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every toolbar expectation is exercised by a Toolbar state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of TOOLBAR_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+/**
+ * The contract reads `orientation` and `direction` as facts the binding
+ * declares. This checks the painted page agrees: the second control sits
+ * below the first in a vertical state, and after it in reading order — to
+ * its right, or its left under right-to-left — in a horizontal one.
+ */
+for (const state of TOOLBAR_BINDING_STATES) {
+  test(`Toolbar [${state.id}] paints its controls on the declared axis and direction`, async ({
+    page,
+  }) => {
+    const {related} = await mountState(page, state);
+    const first = await related['first-control'].boundingBox();
+    const second = await related['second-control'].boundingBox();
+    if (first == null || second == null) {
+      throw new Error(`state "${state.id}" has an unpainted control`);
+    }
+    const firstMiddle = {
+      x: first.x + first.width / 2,
+      y: first.y + first.height / 2,
+    };
+    const secondMiddle = {
+      x: second.x + second.width / 2,
+      y: second.y + second.height / 2,
+    };
+    if (state.facts.orientation === 'vertical') {
+      expect(second.y, 'second control below the first').toBeGreaterThanOrEqual(
+        first.y + first.height,
+      );
+    } else {
+      expect(
+        Math.abs(secondMiddle.y - firstMiddle.y),
+        'controls share a row',
+      ).toBeLessThan(first.height / 2);
+      if (state.facts.direction === 'rtl') {
+        expect(secondMiddle.x, 'second control left of the first').toBeLessThan(
+          firstMiddle.x,
+        );
+      } else {
+        expect(
+          secondMiddle.x,
+          'second control right of the first',
+        ).toBeGreaterThan(firstMiddle.x);
+      }
+    }
+  });
+}
+
+for (const state of TOOLBAR_BINDING_STATES) {
+  test(`Toolbar [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(TOOLBAR_PATTERN, [result]);
+    // Required rows block (AST-020 FR9).
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/Toolbar/__tests__/Toolbar.a11y.renders.tsx

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Toolbar.a11y.renders.tsx
+ * @input One toolbar binding state from Toolbar.a11y.states.ts
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook): a page button before the Toolbar, the Toolbar, and a page button after it
+ * @position Shared fixture for the Toolbar binding
+ */
+
+import type {ReactElement} from 'react';
+import {Button} from '../../Button/Button';
+import {VStack} from '../../VStack/VStack';
+import {Toolbar} from '../Toolbar';
+import type {ToolbarBindingState, ToolbarControl} from './Toolbar.a11y.states';
+
+/**
+ * One slot's controls. A slot lays its children out in a row, so a vertical
+ * toolbar's caller stacks them, as a product toolbar would, to arrange the
+ * controls on the axis the state declares.
+ */
+function controls(
+  list: ReadonlyArray<ToolbarControl>,
+  orientation: ToolbarBindingState['facts']['orientation'],
+): ReactElement | undefined {
+  if (list.length === 0) {
+    return undefined;
+  }
+  const buttons = list.map(control => (
+    <Button
+      key={control.label}
+      label={control.label}
+      variant="ghost"
+      isDisabled={control.isDisabled}
+    />
+  ));
+  return orientation === 'vertical' ? (
+    <VStack gap={1}>{buttons}</VStack>
+  ) : (
+    <>{buttons}</>
+  );
+}
+
+export function renderToolbarState(
+  state: Pick<
+    ToolbarBindingState,
+    'label' | 'startControls' | 'endControls' | 'facts'
+  >,
+): ReactElement {
+  return (
+    <div dir={state.facts.direction} style={{padding: 24, maxWidth: 640}}>
+      <button type="button">Before the toolbar</button>
+      <Toolbar
+        label={state.label}
+        orientation={state.facts.orientation}
+        startContent={controls(state.startControls, state.facts.orientation)}
+        endContent={controls(state.endControls, state.facts.orientation)}
+      />
+      <button type="button">After the toolbar</button>
+    </div>
+  );
+}

package/src/Toolbar/__tests__/Toolbar.a11y.states.ts

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Toolbar.a11y.states.ts
+ * @input Toolbar's representative states and the facts TOOLBAR_PATTERN reads
+ * @output TOOLBAR_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (Toolbar under spec:AST-020 FR15)
+ */
+
+import type {ToolbarStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface ToolbarControl {
+  readonly label: string;
+  readonly isDisabled?: boolean;
+}
+
+export interface ToolbarBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** The Toolbar `label`, which names the toolbar. */
+  readonly label: string;
+  /** Controls in the start slot, in order. */
+  readonly startControls: ReadonlyArray<ToolbarControl>;
+  /** Controls in the end slot, in order. */
+  readonly endControls: ReadonlyArray<ToolbarControl>;
+  /** Relation name → accessible name of the control it designates. */
+  readonly controls: Readonly<
+    Record<'first-control' | 'second-control' | 'last-control', string>
+  >;
+  readonly facts: ToolbarStateFacts;
+}
+
+const story = (id: string) => `a11y-toolbar--${id}`;
+
+const FORMATTING = [
+  {label: 'Bold'},
+  {label: 'Italic'},
+  {label: 'Underline'},
+] as const;
+
+const FORMATTING_CONTROLS = {
+  'first-control': 'Bold',
+  'second-control': 'Italic',
+  'last-control': 'Settings',
+} as const;
+
+const HORIZONTAL_LTR: ToolbarStateFacts = {
+  orientation: 'horizontal',
+  direction: 'ltr',
+  wraps: true,
+  homeEnd: true,
+};
+
+export const TOOLBAR_BINDING_STATES = [
+  {
+    id: 'horizontal',
+    summary:
+      'a named horizontal Toolbar with three formatting buttons in the start slot and Settings in the end slot',
+    storyId: story('horizontal'),
+    label: 'Text formatting',
+    startControls: FORMATTING,
+    endControls: [{label: 'Settings'}],
+    controls: FORMATTING_CONTROLS,
+    facts: HORIZONTAL_LTR,
+  },
+  {
+    id: 'horizontal-rtl',
+    summary:
+      'the same Toolbar inside a right-to-left container, where ArrowLeft moves to the next control',
+    storyId: story('horizontal-rtl'),
+    label: 'Text formatting',
+    startControls: FORMATTING,
+    endControls: [{label: 'Settings'}],
+    controls: FORMATTING_CONTROLS,
+    facts: {...HORIZONTAL_LTR, direction: 'rtl'},
+  },
+  {
+    id: 'vertical',
+    summary:
+      'a vertical Toolbar of drawing tools, moved through with ArrowDown and ArrowUp',
+    storyId: story('vertical'),
+    label: 'Drawing tools',
+    startControls: [{label: 'Select'}, {label: 'Pen'}, {label: 'Eraser'}],
+    endControls: [],
+    controls: {
+      'first-control': 'Select',
+      'second-control': 'Pen',
+      'last-control': 'Eraser',
+    },
+    facts: {...HORIZONTAL_LTR, orientation: 'vertical'},
+  },
+  {
+    id: 'first-control-disabled',
+    summary:
+      'a Toolbar whose first button is disabled, so Tab enters on the first enabled button and the arrows skip the disabled one',
+    storyId: story('first-control-disabled'),
+    label: 'Edit actions',
+    startControls: [
+      {label: 'Undo', isDisabled: true},
+      {label: 'Cut'},
+      {label: 'Copy'},
+    ],
+    endControls: [{label: 'Paste'}],
+    controls: {
+      'first-control': 'Cut',
+      'second-control': 'Copy',
+      'last-control': 'Paste',
+    },
+    facts: HORIZONTAL_LTR,
+  },
+] as const satisfies ReadonlyArray<ToolbarBindingState>;
+
+export const TOOLBAR_EXCLUSIONS = [
+  {
+    id: 'control-semantics',
+    owner:
+      'the button, toggle-button and menu-button patterns and their bindings',
+    reason:
+      'Each control placed in a Toolbar exposes its own role, name, state and activation through its own pattern; this binding renders plain Buttons only so the toolbar container and the movement between controls are what is checked.',
+  },
+  {
+    id: 'caret-guard-and-nested-popovers',
+    owner:
+      'Toolbar.test.tsx (caret-guard, nested popover and onKeyDown composition suites)',
+    reason:
+      'Leaving caret keys to a text field mid-line, leaving keys inside an open MoreMenu to that menu, and composing a caller onKeyDown are binding behaviour the APG leaves to the author, so no state here places a text field or popover in the toolbar.',
+  },
+  {
+    id: 'three-lane-layout',
+    owner:
+      'Toolbar.test.tsx (centerContent and three-slot layout tests) and the repository visual gate',
+    reason:
+      'Center content switches the row to a three-column grid, but the controls stay in DOM order inside the same toolbar element and the same roving tab stop walks them, so the role, name, Tab stop and arrow order this contract reads do not change; the grid itself is layout paint.',
+  },
+  {
+    id: 'outer-chrome',
+    owner: 'component:Section and the repository visual gate',
+    reason:
+      'Variant, dividers, block padding and edge compensation are Section and layout paint around the toolbar row; they change no role, name, Tab stop or arrow movement, so every state uses the default transparent chrome.',
+  },
+] as const;

package/src/Toolbar/__tests__/Toolbar.a11y.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Toolbar.a11y.test.tsx
+ * @input TOOLBAR_PATTERN bound to Toolbar's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for Toolbar (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TOOLBAR_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderToolbarState} from './Toolbar.a11y.renders';
+import {
+  TOOLBAR_BINDING_STATES,
+  TOOLBAR_EXCLUSIONS,
+  type ToolbarBindingState,
+} from './Toolbar.a11y.states';
+
+function toolbarFor(state: ToolbarBindingState): HTMLElement {
+  return screen.getByRole('toolbar', {name: state.label});
+}
+
+function relatedFor(
+  state: ToolbarBindingState,
+): Readonly<Record<string, Element>> {
+  const related: Record<string, Element> = {
+    before: screen.getByRole('button', {name: 'Before the toolbar'}),
+    after: screen.getByRole('button', {name: 'After the toolbar'}),
+  };
+  for (const [relation, name] of Object.entries(state.controls)) {
+    related[relation] = screen.getByRole('button', {name});
+  }
+  return related;
+}
+
+async function checkState(state: ToolbarBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLBAR_PATTERN,
+    binding: 'Toolbar',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderToolbarState(state));
+      return createJsdomHarness({
+        subject: toolbarFor(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('Toolbar — toolbar pattern, jsdom lane', () => {
+  it.each(
+    TOOLBAR_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: TOOLBAR_PATTERN,
+      binding: 'Toolbar',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderToolbarState(state));
+      },
+      subject: () => toolbarFor(state),
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TOOLBAR_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TOOLBAR_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('toolbar binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = TOOLBAR_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps control semantics, editing and popover keys, the three-lane layout, and outer chrome explicit', () => {
+    expect(TOOLBAR_EXCLUSIONS.map(row => row.id)).toEqual([
+      'control-semantics',
+      'caret-guard-and-nested-popovers',
+      'three-lane-layout',
+      'outer-chrome',
+    ]);
+    for (const exclusion of TOOLBAR_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the toolbar and every control relation it names for every state', () => {
+    for (const state of TOOLBAR_BINDING_STATES) {
+      render(renderToolbarState(state));
+      const toolbar = toolbarFor(state);
+      for (const name of Object.values(state.controls)) {
+        expect(
+          toolbar.contains(screen.getByRole('button', {name})),
+          `${state.id}: ${name}`,
+        ).toBe(true);
+      }
+      cleanup();
+    }
+  });
+});