@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/Stepper/Step.spec.md

@@ -28,15 +28,15 @@ system_specs: [spec:AST-085]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                     |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `Step` with `step`, `label`, `description`, `children`, `status`, `indicator` (`auto`, `number`, `none`, or a node; default `auto`), `isDisabled`, `isOptional`, `endContent`, and `density`.                                                                                |
-| Behavior                | One list item of a Stepper. Its progress (completed, in progress, not started) comes from its `step` index against the Stepper's active step; it is a button that asks to go to that step when the Stepper has `onStepClick`, it is enabled, and the Stepper is not compact. |
-| End-user impact         | Users see each step's progress (number, ring, or check) and its status cue where one applies; screen-reader users hear the current step, a status word, and a "Go to step N" name on clickable steps; keyboard users Tab between enabled clickable steps.                    |
-| Builder impact          | None.                                                                                                                                                                                                                                                                        |
-| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps (see Current-state impact).                                                                                                                                                                            |
-| Review checks           | Reject status conveyed only by color under `indicator="auto"`, an indicator exposed to assistive technology, a disabled step that activates, or `aria-current` on anything but the in-progress step.                                                                         |
-| Governing rules         | `component:Stepper` (targets, connector, label paint, compact layout); `architecture:interaction-modality`.                                                                                                                                                                  |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `Step` with `step`, `label`, `description`, `children`, `status`, `indicator` (`auto`, `number`, `none`, or a node; default `auto`), `isDisabled`, `isOptional`, `endContent`, and `density`.                                                                                                                            |
+| Behavior                | One list item of a Stepper. Its progress (completed, in progress, not started) comes from its `step` index against the Stepper's active step; it is a button that asks to go to that step when the Stepper has `onStepClick` and is not compact; a disabled step keeps its button, `aria-disabled`, and never activates. |
+| End-user impact         | Users see each step's progress (number, ring, or check) and its status cue where one applies; screen-reader users hear the current step, a status word, a "Go to step N" name and the step's description on clickable steps; keyboard users Tab between clickable steps, disabled ones included.                         |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                                                    |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact).                                                                                                                                                                                                                          |
+| Review checks           | Reject status conveyed only by color under `indicator="auto"`, an indicator exposed to assistive technology, a disabled step that activates, or `aria-current` on anything but the in-progress step.                                                                                                                     |
+| Governing rules         | `component:Stepper` (targets, connector, label paint, compact layout); `architecture:interaction-modality`.                                                                                                                                                                                                              |
 
 This table is a review projection; the body below is authoritative.
 
@@ -56,12 +56,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Current-state impact
 
-- **A disabled step leaves the tab order.** In a clickable Stepper outside
-  compact mode a disabled Step renders no button, so keyboard users cannot reach
-  it or learn that it is disabled, and a focused step that becomes disabled
-  loses its button, dropping focus to the page. `spec:AST-085` FR1, FR4, and FR5
-  have a disabled control stay focusable, keep focus, and expose
-  `aria-disabled="true"`.
 - **Other indicator modes show status by color alone, or not at all.** With
   `indicator="number"`, a reached step shows status only through badge color
   and a not-started step shows none. A custom node shows status only through
@@ -70,9 +64,9 @@ Consumer migration instructions belong in consumer docs and release notes.
   its `status`, so in both cases status shows only in the visually hidden word. WCAG 1.4.1 requires information
   not to be conveyed by color alone.
 - **A clickable step's name hides its other text.** The button's name is the
-  step number, label, and status word, and nothing describes it, so the
-  description, the "Optional" cue, and `endContent` never reach assistive
-  technology on a clickable step. WCAG 1.3.1 requires information shown to be
+  step number, label, and status word, and only the description describes it,
+  so the "Optional" cue and `endContent` never reach assistive technology on a
+  clickable step. WCAG 1.3.1 requires information shown to be
   available programmatically.
 
 ## Ownership boundary
@@ -105,17 +99,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Basis                           |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
-| FR1 | A Step renders one `<li>`. Its progress is `in-progress` when `step` equals the Stepper's active step, `completed` when it is lower, and `not-started` when higher; only the in-progress step carries `aria-current="step"`. It registers its index and a live disabled check with the Stepper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests        |
-| FR2 | With `onStepClick` on the Stepper, an enabled Step outside compact mode wraps its indicator, label, and description in a `<button>` (the content slot stays outside it) named by `@astryx.step.goToStep` ("Go to step N: label") or `.goToStepWithStatus` when a status word applies; activation (click, Enter, Space) calls `onStepClick(step)`. Completed, in-progress, and upcoming steps are all clickable. Any Step without `onStepClick` renders no button. A disabled Step in a clickable Stepper outside compact mode MUST stay focusable with `aria-disabled="true"` and keep its tab stop (`spec:AST-085` FR1, FR5). Implementation gap: it renders no button, so it leaves the tab order, exposes no disabled state, and drops focus when it becomes disabled while focused (`spec:AST-085` FR4). | Current source and tests        |
-| FR3 | `indicator="auto"` shows the number while not started, the ring while in progress, and a check once completed; `number` always shows the number; `none` shows nothing; a non-string node renders as given; any other string falls back to the ring while not started or in progress and the check once completed, with no number, status glyph, or status color. Indicators are `aria-hidden`.                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests        |
-| FR4 | `status` never recolors the progress bar. Under `indicator="auto"` it recolors a non-current step with `success`, `warning`, or `error` and shows a distinct status glyph (replacing the number on not-started steps); the current step's ring and `accent` keep progress color. Under `number` it recolors reached badges only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests        |
-| FR5 | Each Step exposes a visually hidden status word: `error` or `warning` for those statuses, `completed` when completed or `success`, in every layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and tests        |
-| FR6 | `isDisabled` dims the indicator with fixed paint and no theme state (the label's disabled paint and its `disabled` selector are `component:Stepper` FR10) and blocks activation (FR2's implementation gap). `isOptional` appends the translated `@astryx.step.optional` ("Optional") after the label. `endContent` sits at the end of the label row.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests        |
-| FR7 | `density` sets the Step's padding: block padding in every layout, plus inline padding for spacious separated steps and both axes for vertical on-track steps; it falls back to the Stepper's density.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source                  |
-| FR8 | `children` render below the label and description; in a compact horizontal Stepper they stay mounted, hidden with the expanded details, so local state survives. The label stays on one line and ellipsizes; its full text remains in the accessible name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source, docs, and tests |
-| FR9 | The step button paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source                  |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Basis                           |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1 | A Step renders one `<li>`. Its progress is `in-progress` when `step` equals the Stepper's active step, `completed` when it is lower, and `not-started` when higher; only the in-progress step carries `aria-current="step"`. It registers its index and a live disabled check with the Stepper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests        |
+| FR2 | With `onStepClick` on the Stepper, an enabled Step outside compact mode wraps its indicator, label, and description in a `<button>` (the content slot stays outside it) named by `@astryx.step.goToStep` ("Go to step N: label") or `.goToStepWithStatus` when a status word applies; activation (click, Enter, Space) calls `onStepClick(step)`. Completed, in-progress, and upcoming steps are all clickable. Any Step without `onStepClick` renders no button. A disabled Step in a clickable Stepper outside compact mode keeps its button, focusable with `aria-disabled="true"` and the same name, keeps its tab stop and its focus when it becomes disabled while focused, and does not activate (`spec:AST-085` FR1, FR4). A clickable Step's description describes its button, so a disabled step's reason reaches assistive technology (`spec:AST-085` FR5). | Current source and tests        |
+| FR3 | `indicator="auto"` shows the number while not started, the ring while in progress, and a check once completed; `number` always shows the number; `none` shows nothing; a non-string node renders as given; any other string falls back to the ring while not started or in progress and the check once completed, with no number, status glyph, or status color. Indicators are `aria-hidden`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests        |
+| FR4 | `status` never recolors the progress bar. Under `indicator="auto"` it recolors a non-current step with `success`, `warning`, or `error` and shows a distinct status glyph (replacing the number on not-started steps); the current step's ring and `accent` keep progress color. Under `number` it recolors reached badges only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests        |
+| FR5 | Each Step exposes a visually hidden status word: `error` or `warning` for those statuses, `completed` when completed or `success`, in every layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests        |
+| FR6 | `isDisabled` dims the indicator with fixed paint and no theme state (the label's disabled paint and its `disabled` selector are `component:Stepper` FR10) and blocks activation (FR2). `isOptional` appends the translated `@astryx.step.optional` ("Optional") after the label. `endContent` sits at the end of the label row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests        |
+| FR7 | `density` sets the Step's padding: block padding in every layout, plus inline padding for spacious separated steps and both axes for vertical on-track steps; it falls back to the Stepper's density.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source                  |
+| FR8 | `children` render below the label and description; in a compact horizontal Stepper they stay mounted, hidden with the expanded details, so local state survives. The label stays on one line and ellipsizes; its full text remains in the accessible name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source, docs, and tests |
+| FR9 | The step button paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source                  |
 
 ### Allowed variation
 
@@ -129,7 +123,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | Completed, clickable   | Check indicator; "completed" text; named button.            | Status color.     |
 | In progress            | `aria-current="step"`; ring indicator.                      | —                 |
 | Not started with error | Error glyph replaces the number; "error" text.              | —                 |
-| Disabled               | Dimmed; no activation. Implementation gap: no button (FR2). | —                 |
+| Disabled               | Dimmed; focusable and `aria-disabled`; no activation (FR2). | —                 |
 | Compact horizontal     | No button; content mounted but hidden.                      | —                 |
 
 ### Transformation and precedence order
@@ -152,11 +146,11 @@ Consumer migration instructions belong in consumer docs and release notes.
   hidden word (Current-state
   impact).
 - **AR3 — Clickable name.** FR2's button name includes the step number, label,
-  and status word. Implementation gap: a clickable step's description, optional
-  cue, and `endContent` are not exposed (Current-state impact).
-- **AR4 — Keyboard.** Clickable steps are reached with Tab in document order and
-  activate with Enter or Space; today disabled steps are skipped (FR2's
-  implementation gap).
+  and status word, and the step's description describes it. Implementation gap:
+  a clickable step's optional cue and `endContent` are not exposed
+  (Current-state impact).
+- **AR4 — Keyboard.** Clickable steps, disabled ones included, are reached with
+  Tab in document order; enabled ones activate with Enter or Space.
 
 ## Design relationships
 
@@ -175,13 +169,13 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Verification map
 
-| Contract     | Verification                                                        | Representative states                 | Mutation or failure expectation                                                                                                     | Audit section              |
-| ------------ | ------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1          | `Stepper.test.tsx` list and aria-current tests                      | Each progress                         | Wrong current step fails.                                                                                                           | `audit:Step/accessibility` |
-| FR2, AR3–AR4 | `Stepper.test.tsx` onStepClick, keyboard, and accessible-name tests | Completed, active, upcoming, disabled | A missing button or wrong name fails; the disabled-step and Tab-skip assertions pin FR2's implementation gap (pending conformance). | `audit:Step/behavior`      |
-| FR3, FR4     | `Stepper.test.tsx` step-number, indicator, and status glyph tests   | Each indicator mode and status        | Wrong glyph or recolored bar fails.                                                                                                 | `audit:Step/behavior`      |
-| FR8          | `Stepper.test.tsx` compact content-mount tests                      | Both indicator positions              | Step content that loses its state while hidden in a compact Stepper fails.                                                          | `audit:Step/behavior`      |
-| FR5, AR2     | `Stepper.test.tsx` hidden status text tests                         | Separated and on-track                | Missing status text fails.                                                                                                          | `audit:Step/accessibility` |
+| Contract     | Verification                                                        | Representative states                 | Mutation or failure expectation                                                                                                                                         | Audit section              |
+| ------------ | ------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1          | `Stepper.test.tsx` list and aria-current tests                      | Each progress                         | Wrong current step fails.                                                                                                                                               | `audit:Step/accessibility` |
+| FR2, AR3–AR4 | `Stepper.test.tsx` onStepClick, keyboard, and accessible-name tests | Completed, active, upcoming, disabled | A missing button or wrong name fails, and so does a disabled step that leaves the tab order, loses focus when it becomes disabled, lacks `aria-disabled`, or activates. | `audit:Step/behavior`      |
+| FR3, FR4     | `Stepper.test.tsx` step-number, indicator, and status glyph tests   | Each indicator mode and status        | Wrong glyph or recolored bar fails.                                                                                                                                     | `audit:Step/behavior`      |
+| FR8          | `Stepper.test.tsx` compact content-mount tests                      | Both indicator positions              | Step content that loses its state while hidden in a compact Stepper fails.                                                                                              | `audit:Step/behavior`      |
+| FR5, AR2     | `Stepper.test.tsx` hidden status text tests                         | Separated and on-track                | Missing status text fails.                                                                                                                                              | `audit:Step/accessibility` |
 
 Read from source, with no focused test yet:
 

package/src/Stepper/Step.tsx

@@ -38,7 +38,7 @@
  * - /packages/cli/assets/templates/blocks/components/Step/ (showcase blocks)
  */
 
-import {useLayoutEffect, type ReactNode} from 'react';
+import {useId, useLayoutEffect, type ReactNode} from 'react';
 import {createPortal} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 
@@ -1072,7 +1072,12 @@ export function Step({
   // A compact horizontal stepper moves navigation to the named controls in its
   // summary row. Its track — including the on-track indicators — stays purely
   // presentational so it does not expose a second, denser set of click targets.
-  const isClickable = !isDisabled && onStepClick != null && !isCompact;
+  const hasButton = onStepClick != null && !isCompact;
+  // A disabled step keeps its button, focusable and aria-disabled, so it
+  // keeps its tab stop, is announced as unavailable, and keeps focus when it
+  // becomes disabled while focused (`spec:AST-085` FR1, FR4, FR5); only
+  // activation is withheld.
+  const isClickable = hasButton && !isDisabled;
 
   const handleClick = () => {
     if (isClickable && onStepClick) {
@@ -1349,8 +1354,13 @@ export function Step({
     </div>
   );
 
+  // A clickable step's name is its number, label and status word; the
+  // description describes it, so a disabled step's reason reaches assistive
+  // technology too (spec:AST-085 FR5).
+  const descriptionID = useId();
   const descriptionNode = isRenderable(description) ? (
     <div
+      id={descriptionID}
       {...stylex.props(
         hasIndicator
           ? styles.descriptionRowWithIndicator
@@ -1507,6 +1517,7 @@ export function Step({
 
     const otDescriptionNode = isRenderable(description) ? (
       <span
+        id={descriptionID}
         {...mergeProps(
           descriptionThemeProps,
           stylex.props(styles.description),
@@ -1610,11 +1621,15 @@ export function Step({
           aria-current={isActive ? 'step' : undefined}
           data-testid={dataTestId}
           {...rest}>
-          {isClickable ? (
+          {hasButton ? (
             <button
               type="button"
               onClick={handleClick}
               aria-label={stepAriaLabel}
+              aria-describedby={
+                isRenderable(description) ? descriptionID : undefined
+              }
+              aria-disabled={isDisabled || undefined}
               {...pressable}
               {...stylex.props(
                 styles.otInteractive,
@@ -1702,11 +1717,15 @@ export function Step({
         aria-current={isActive ? 'step' : undefined}
         data-testid={dataTestId}
         {...rest}>
-        {isClickable ? (
+        {hasButton ? (
           <button
             type="button"
             onClick={handleClick}
             aria-label={stepAriaLabel}
+            aria-describedby={
+              isRenderable(description) ? descriptionID : undefined
+            }
+            aria-disabled={isDisabled || undefined}
             {...pressable}
             {...stylex.props(
               styles.otInteractive,
@@ -1762,11 +1781,15 @@ export function Step({
         />
         {/* Body: button wraps only label area, children render outside */}
         <div {...stylex.props(styles.verticalBody)}>
-          {isClickable ? (
+          {hasButton ? (
             <button
               type="button"
               onClick={handleClick}
               aria-label={stepAriaLabel}
+              aria-describedby={
+                isRenderable(description) ? descriptionID : undefined
+              }
+              aria-disabled={isDisabled || undefined}
               {...pressable}
               {...stylex.props(
                 styles.buttonReset,
@@ -1830,11 +1853,15 @@ export function Step({
           under the track instead. */}
       {isCompact ? (
         compactNameNode
-      ) : isClickable ? (
+      ) : hasButton ? (
         <button
           type="button"
           onClick={handleClick}
           aria-label={stepAriaLabel}
+          aria-describedby={
+            isRenderable(description) ? descriptionID : undefined
+          }
+          aria-disabled={isDisabled || undefined}
           {...stylex.props(
             styles.buttonReset,
             interactionOverlayStyles.backgroundColor,

package/src/Stepper/Stepper.doc.mjs

@@ -172,7 +172,7 @@ export const docs = {
           name: 'onStepClick',
           type: '(index: number) => void',
           description:
-            'Called when a step is clicked or a compact summary control is used. Enables non-linear navigation. All non-disabled steps become clickable until a horizontal Stepper collapses, when navigation moves to summary controls that skip disabled steps.',
+            'Called when a step is clicked or a compact summary control is used. Enables non-linear navigation. Every step becomes a button until a horizontal Stepper collapses: enabled steps activate, and disabled steps stay focusable and are announced as unavailable but do not activate. When collapsed, navigation moves to summary controls that skip disabled steps.',
         },
         {
           name: 'label',

package/src/Stepper/Stepper.test.tsx

@@ -185,17 +185,75 @@ describe('Stepper', () => {
     expect(handleClick).toHaveBeenCalledWith(2);
   });
 
-  it('does not render buttons for disabled steps', () => {
+  it('keeps a disabled step focusable and aria-disabled, and never activates it (spec:AST-085 FR1, FR2, FR5)', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
     render(
-      <Stepper activeStep={2} onStepClick={() => {}}>
+      <Stepper activeStep={2} onStepClick={handleClick}>
         <Step step={0} label="Step 1" isDisabled />
         <Step step={1} label="Step 2" />
         <Step step={2} label="Step 3" />
       </Stepper>,
     );
-    expect(
-      screen.queryByRole('button', {name: /Go to step 1: Step 1/}),
-    ).not.toBeInTheDocument();
+    const disabled = screen.getByRole('button', {name: /Go to step 1: Step 1/});
+    expect(disabled).toHaveAttribute('aria-disabled', 'true');
+    expect(disabled).not.toHaveAttribute('disabled');
+    await user.click(disabled);
+    disabled.focus();
+    await user.keyboard('{Enter}');
+    await user.keyboard(' ');
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['separated', {}],
+    ['on-track horizontal', {indicatorPosition: 'on-track'}],
+    [
+      'on-track vertical',
+      {indicatorPosition: 'on-track', orientation: 'vertical'},
+    ],
+  ] as const)(
+    "describes a disabled step with its reason, the step's description, %s (spec:AST-085 FR5)",
+    (_layout, layout) => {
+      render(
+        <Stepper activeStep={1} onStepClick={() => {}} {...layout}>
+          <Step step={0} label="Setup" />
+          <Step
+            step={1}
+            label="Permissions"
+            description="Requires admin role"
+            isDisabled
+          />
+        </Stepper>,
+      );
+      const step = screen.getByRole('button', {
+        name: /Go to step 2: Permissions/,
+      });
+      expect(step).toHaveAccessibleDescription('Requires admin role');
+      expect(
+        screen.getByRole('button', {name: /Go to step 1: Setup/}),
+      ).not.toHaveAttribute('aria-describedby');
+    },
+  );
+
+  it('keeps focus on a step that becomes disabled while focused (spec:AST-085 FR4)', () => {
+    const {rerender} = render(
+      <Stepper activeStep={2} onStepClick={() => {}}>
+        <Step step={0} label="Step 1" />
+        <Step step={1} label="Step 2" />
+      </Stepper>,
+    );
+    const step = screen.getByRole('button', {name: /Go to step 1: Step 1/});
+    step.focus();
+    rerender(
+      <Stepper activeStep={2} onStepClick={() => {}}>
+        <Step step={0} label="Step 1" isDisabled />
+        <Step step={1} label="Step 2" />
+      </Stepper>,
+    );
+    const after = screen.getByRole('button', {name: /Go to step 1: Step 1/});
+    expect(after).toHaveFocus();
+    expect(after).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('does not render buttons when onStepClick is not provided', () => {
@@ -610,7 +668,7 @@ describe('Stepper', () => {
       expect(handleClick).toHaveBeenCalledWith(0);
     });
 
-    it('tabs through steps in document order, skipping disabled ones', async () => {
+    it('tabs through steps in document order, disabled ones included', async () => {
       const user = userEvent.setup();
       render(
         <Stepper activeStep={3} onStepClick={() => {}}>
@@ -623,7 +681,11 @@ describe('Stepper', () => {
       expect(
         screen.getByRole('button', {name: 'Go to step 1: One, completed'}),
       ).toHaveFocus();
-      // The disabled step renders no button, so Tab lands on step 3 next.
+      // The disabled step keeps its tab stop (spec:AST-085 FR1).
+      await user.tab();
+      expect(
+        screen.getByRole('button', {name: 'Go to step 2: Two, completed'}),
+      ).toHaveFocus();
       await user.tab();
       expect(
         screen.getByRole('button', {name: 'Go to step 3: Three, completed'}),

package/src/Switch/Switch.spec.md

@@ -123,7 +123,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR5  | A change calls `onChange(checked, event)`; unless that call prevents default, `changeAction(checked, event)` runs in a transition and the switch shows the proposed state while the Action is pending, and `value` once it settles.                                                                                                                                                                                                                                                                                                    | Current tests                                                                                                                           |
 | FR6  | While `isLoading`, or while the shown state differs from `value`, the input sets `aria-busy`, ignores pointer input, refuses changes, keeps focus, and the switch announces its busy start once per busy period through the shared channel.                                                                                                                                                                                                                                                                                            | `spec:AST-086` FR8; current tests                                                                                                       |
 | FR7  | Disabled: `aria-disabled="true"` on a focusable input, no `name`, detached from its form (so it neither submits nor blocks submission when required), no change, no caller `onClick` on the field, no hover or press paint, and a half-opacity track. With `disabledMessage`, a reason tooltip opens on row hover and keyboard focus and describes the input. Implementation gap: caller DOM handlers other than `onClick`, such as `onKeyDown`, still run on the field root while disabled (`spec:AST-085` FR2).                      | `spec:AST-085` FR1–FR3, FR5; current tests                                                                                              |
-| FR8  | Enabled, the input submits `on` under `htmlName` when on and nothing when off; `isRequired` sets native `required`, while `aria-required` follows the effective required state.                                                                                                                                                                                                                                                                                                                                                        | Current tests                                                                                                                           |
+| FR8  | Enabled, the input submits `on` under `htmlName` when on and nothing when off; `isRequired` sets native `required`, while `aria-required` follows the effective required state; `aria-invalid` follows `status` (`false` on a required switch without an error), so the browser's own invalid state never shows before an error.                                                                                                                                                                                                       | Current tests                                                                                                                           |
 | FR9  | Keyboard focus paints the shared focus outline on the track. Hovering the enabled row tints the track; pressing paints the pressed overlay on both, applying `design:user-states` DR1 and DR2; a touch press fades out from the row. Track color transitions are instant under reduced motion.                                                                                                                                                                                                                                         | `architecture:interaction-modality` INV1; `design:user-states` DR1, DR2 for the pressed overlay; `design:reduced-motion`; current tests |
 | FR10 | The thumb travels toward the inline end when on, mirrored under RTL, and moves without a transition under reduced motion (`design:reduced-motion` DR1). On coarse pointers the input's hit area is at least 24 by 24 CSS pixels (WCAG 2.5.8) and follows the inline direction. Under `spec:AST-094` FR42 a coarse-pointer target MUST reach 44 CSS pixels through an invisible hit area where neighbors allow. Implementation gap: the input's hit area stops at 24 by 24.                                                             | WCAG 2.5.8; current tests; `design:reduced-motion` DR1; `spec:AST-094` FR42                                                             |
 | FR11 | Under forced colors, on and off stay distinguishable (Highlight track when on), and the hover tint does not hide the thumb.                                                                                                                                                                                                                                                                                                                                                                                                            | WCAG 1.4.11; current tests                                                                                                              |

package/src/Switch/Switch.test.tsx

@@ -429,7 +429,9 @@ describe('Switch', () => {
           continue;
         }
         for (const node of record.addedNodes) {
-          if (node.textContent) {written.push(node.textContent);}
+          if (node.textContent) {
+            written.push(node.textContent);
+          }
         }
       }
     });
@@ -563,6 +565,24 @@ describe('Switch', () => {
     expect(screen.getByRole('switch')).toBeRequired();
   });
 
+  it('keeps a required switch valid until status shows an error', () => {
+    const {rerender} = render(
+      <Switch label="Accept" value={false} onChange={() => {}} isRequired />,
+    );
+    // Native required alone makes Chromium report the switch invalid.
+    expect(screen.getByRole('switch')).toHaveAttribute('aria-invalid', 'false');
+    rerender(
+      <Switch
+        label="Accept"
+        value={false}
+        onChange={() => {}}
+        isRequired
+        status={{type: 'error', message: 'Required'}}
+      />,
+    );
+    expect(screen.getByRole('switch')).toHaveAttribute('aria-invalid', 'true');
+  });
+
   describe('disabledMessage', () => {
     const h = {hidden: true} as const;
 
@@ -680,6 +700,51 @@ describe('Switch', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
+    it('does not run caller key handlers while disabled', async () => {
+      const user = userEvent.setup();
+      const onKeyDown = vi.fn();
+      const onKeyUp = vi.fn();
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          onKeyDown={onKeyDown}
+          onKeyUp={onKeyUp}
+          isDisabled
+        />,
+      );
+      await user.tab();
+      expect(screen.getByRole('switch')).toHaveFocus();
+      await user.keyboard('{Enter}');
+      await user.keyboard(' ');
+      expect(onKeyDown).not.toHaveBeenCalled();
+      expect(onKeyUp).not.toHaveBeenCalled();
+    });
+
+    it('still runs caller key handlers on an enabled switch', async () => {
+      const user = userEvent.setup();
+      const onKeyDown = vi.fn();
+      const onKeyUp = vi.fn();
+      render(
+        <Switch
+          label="Enable notifications"
+          value={false}
+          onChange={() => {}}
+          onKeyDown={onKeyDown}
+          onKeyUp={onKeyUp}
+        />,
+      );
+      await user.tab();
+      // Releasing Tab lands a keyup on the newly focused switch; count only
+      // the key pressed after it.
+      onKeyDown.mockClear();
+      onKeyUp.mockClear();
+      await user.keyboard('{Enter}');
+      expect(onKeyDown).toHaveBeenCalledTimes(1);
+      expect(onKeyUp).toHaveBeenCalledTimes(1);
+    });
+
     it('stays focusable via aria-disabled when disabled without a reason', async () => {
       const user = userEvent.setup();
       const onChange = vi.fn();

package/src/Switch/Switch.tsx

@@ -679,7 +679,11 @@ export function Switch({
         // than the field wrapper via `...rest`.
         aria-labelledby={ariaLabelledByProp}
         aria-describedby={ariaDescribedBy}
-        aria-invalid={status?.type === 'error' ? true : undefined}
+        // Chromium reports an unchecked native-required checkbox invalid before
+        // any interaction; the invalid state follows status instead.
+        aria-invalid={
+          status?.type === 'error' ? true : isRequired ? false : undefined
+        }
         aria-busy={isBusy || undefined}
         {...stylex.props(
           styles.input,
@@ -758,8 +762,12 @@ export function Switch({
         style,
       )}
       {...rest}
-      // Native `disabled` suppressed clicks on the switch (spec:AST-085 FR2).
-      onClick={isDisabled ? undefined : rest.onClick}>
+      // Native `disabled` suppressed clicks and key events on the switch; the
+      // switch is no longer natively disabled, so withhold the caller's
+      // handlers while disabled (spec:AST-085 FR2).
+      onClick={isDisabled ? undefined : rest.onClick}
+      onKeyDown={isDisabled ? undefined : rest.onKeyDown}
+      onKeyUp={isDisabled ? undefined : rest.onKeyUp}>
       <div
         ref={el => {
           // Interaction (hover/focus) listeners for the disabled-message

package/src/TabList/TabList.test.tsx

@@ -9,8 +9,9 @@
  * SYNC: When TabList components change, update tests to match new behavior
  */
 
+import {useState} from 'react';
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {act, render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {__resetMenuPressForTest} from '../hooks/useMenuPress';
 import userEvent from '@testing-library/user-event';
 import {
@@ -933,8 +934,10 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
       hidden: true,
     });
 
-    fireEvent.keyDown(menu, {key: 'ArrowDown'});
-    expect(analytics).toHaveFocus();
+    // Opening moves focus to the first item a frame later (APG menu-button
+    // focus-on-open): wait for it, since a key pressed before that frame
+    // starts from no item and one pressed after it starts from the first.
+    await waitFor(() => expect(analytics).toHaveFocus());
 
     fireEvent.keyDown(menu, {key: 'ArrowDown'});
     expect(reports).toHaveFocus();
@@ -963,7 +966,8 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
       hidden: true,
     });
 
-    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus analytics
+    // Focus lands on the first item a frame after opening (see above).
+    await waitFor(() => expect(analytics).toHaveFocus());
     fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus reports
 
     // The tab stop follows focus, so it is still a single stop after moving.
@@ -1237,6 +1241,56 @@ describe('TabList overflow (scroll)', () => {
     expect(scrollBy).not.toHaveBeenCalled();
   });
 
+  it('measures a pressed tab after the press, in the next frame, and still shows it whole', async () => {
+    function Controlled() {
+      const [value, setValue] = useState('a');
+      return (
+        <TabList value={value} onChange={setValue}>
+          <Tab value="a" label="Alpha" />
+          <Tab value="b" label="Beta" />
+          <Tab value="c" label="Gamma" />
+        </TabList>
+      );
+    }
+    const {container} = render(<Controlled />);
+    const strip = container.querySelector<HTMLElement>(STRIP);
+    const tab = container.querySelector<HTMLElement>('[data-tab-value="c"]');
+    if (!strip || !tab) {
+      throw new Error('no tab strip');
+    }
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    const stripRect = vi.fn(
+      () => ({left: 0, right: 300, width: 300}) as DOMRect,
+    );
+    strip.getBoundingClientRect = stripRect;
+    tab.getBoundingClientRect = () =>
+      ({left: 240, right: 320, width: 80}) as DOMRect;
+
+    // Pressing a tab focuses it first, and focusing it reveals it.
+    fireEvent.focus(tab);
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+    expect(scrollBy.mock.calls[0][0].left).toBe(20);
+    const readsBeforePress = stripRect.mock.calls.length;
+
+    // The selection itself reads no geometry inside the press...
+    fireEvent.click(tab);
+    expect(tab).toHaveAttribute('aria-current', 'true');
+    expect(stripRect.mock.calls.length).toBe(readsBeforePress);
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+
+    // ...and the next frame measures the selected tab, now wider, so it still
+    // ends fully inside the strip.
+    tab.getBoundingClientRect = () =>
+      ({left: 220, right: 306, width: 86}) as DOMRect;
+    await act(
+      async () =>
+        new Promise<void>(resolve => requestAnimationFrame(() => resolve())),
+    );
+    expect(scrollBy).toHaveBeenCalledTimes(2);
+    expect(scrollBy.mock.calls[1][0].left).toBe(6);
+  });
+
   it('reveals on a selection change, not on an unrelated overflow change', () => {
     const {strip, rerender} = renderStrip({value: 'c', overflow: 'visible'});
     const scrollBy = vi.fn();