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

package/src/Slider/Slider.tsx

@@ -5,7 +5,7 @@
 /**
  * @file Slider.tsx
  * @input Uses React, useId, useRef, useCallback, useEffect, Field, Tooltip, useTooltip, VisuallyHidden
- * @output Exports Slider and its props; unfilled marks share the track token; modifier-only key presses do not restore the thumb focus ring; a drag belongs to the pointer that started it
+ * @output Exports Slider and its props; unfilled marks share the track token; modifier-only key presses do not restore the thumb focus ring; a drag belongs to the pointer that started it; two coincident range thumbs separate toward the press or the first movement
  * @position Core implementation; consumed by index.ts, tested by Slider.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -58,6 +58,8 @@ import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import {useTranslator} from '../i18n';
 // =============================================================================
 // Types
 // =============================================================================
@@ -512,6 +514,7 @@ export function Slider({ref, ...props}: SliderProps) {
     'aria-describedby': ariaDescribedByProp,
     ...restWithRange
   } = props;
+  const t = useTranslator();
   const {minStepsBetweenThumbs: _minSteps, ...restProps} =
     restWithRange as typeof restWithRange & {minStepsBetweenThumbs?: number};
   const {rest, container} = useFieldInputStyling('Slider', restProps, {
@@ -591,7 +594,9 @@ export function Slider({ref, ...props}: SliderProps) {
   // role="slider" in WAI-ARIA 1.2, so the thumb instead points its
   // aria-describedby at a visually hidden "Required" span — mirroring the
   // Field label's visible indicator (where isOptional takes precedence).
-  const conveysRequired = isRequired && !isOptional;
+  // A surrounding FormLayout's defaultOptionality="required" makes an unmarked
+  // field required too (FormLayout FR5).
+  const conveysRequired = useResolvedRequired({isRequired, isOptional});
 
   // Build aria-describedby
   const describedByParts: string[] = [];
@@ -667,8 +672,24 @@ export function Slider({ref, ...props}: SliderProps) {
     [isRange, values],
   );
 
+  // The pointer's value at a press on two coincident thumbs, while no
+  // movement has said which way the drag goes; the first value off it picks
+  // the thumb that can travel that way (see handlePointerMove).
+  const coincidentDragRef = useRef<number | null>(null);
+  // Whether the drag in progress began on two coincident thumbs: such a drag
+  // can always follow the pointer, so when the dragged thumb is held against
+  // the other one and the pointer passes it, the other thumb takes the drag.
+  const coincidentOriginRef = useRef(false);
+
   const updateValue = useCallback(
-    (thumbIndex: number, newVal: number, snap = true) => {
+    (
+      thumbIndex: number,
+      newVal: number,
+      snap = true,
+      // The other thumb's values to start from, when one event moves both
+      // (a drag handed from one coincident thumb to the other).
+      from: ReadonlyArray<number> = values,
+    ) => {
       if (isDisabled) {
         return;
       }
@@ -682,7 +703,7 @@ export function Slider({ref, ...props}: SliderProps) {
       );
 
       if (isRange) {
-        const currentValues = [...values] as [number, number];
+        const currentValues = [...from] as [number, number];
         currentValues[thumbIndex] = clamped;
 
         // Enforce minStepsBetweenThumbs
@@ -760,6 +781,8 @@ export function Slider({ref, ...props}: SliderProps) {
         detachLostCaptureRef.current = null;
         draggingThumbRef.current = null;
         dragPointerRef.current = null;
+        coincidentDragRef.current = null;
+        coincidentOriginRef.current = false;
         setDraggingThumb(null);
         fireChangeEnd();
       }
@@ -799,13 +822,41 @@ export function Slider({ref, ...props}: SliderProps) {
         pressedThumb == null || thumbs == null
           ? -1
           : Array.from(thumbs).indexOf(pressedThumb);
-      // A direct thumb press owns that thumb even when range values coincide.
-      // Track and mark presses still choose the nearest value.
-      const thumbIndex =
+      // A direct thumb press owns that thumb; track and mark presses choose
+      // the nearest value. Two thumbs on one value are the exception: only
+      // one of them can travel toward where the pointer goes. A track press
+      // beside them picks the thumb on its side. A press on the thumbs
+      // themselves (or on their shared value) moves nothing: the pressed
+      // thumb holds the press until the pointer moves, and the direction of
+      // that first movement from the press picks the thumb.
+      const isCoincident = isRange && values[0] === values[1];
+      let thumbIndex =
         pressedThumbIndex >= 0 ? pressedThumbIndex : getClosestThumb(newVal);
+      const parks =
+        isCoincident && (pressedThumbIndex >= 0 || newVal === values[0]);
+      // Until the first movement, a parked press is held by the upper thumb,
+      // the one drawn over the lower one, wherever it landed: on the thumbs
+      // (which the upper thumb covers) or on their shared value elsewhere,
+      // such as its mark label. So its pressed paint shows, and a press that
+      // never moves leaves focus on the same thumb.
+      if (parks && pressedThumbIndex < 0) {
+        thumbIndex = 1;
+      }
+      // The first movement is measured from the pointer itself, not from a
+      // mark it pressed (a wide label sits away from its mark's value).
+      coincidentDragRef.current = parks
+        ? getValueFromPosition(e.clientX, e.clientY)
+        : null;
+      // Only a drag that began on the shared thumbs, the press that waited for
+      // the first movement, hands itself to the other thumb (FR6); a track
+      // press beside them already picked its thumb.
+      coincidentOriginRef.current = parks;
+      if (isCoincident && !parks) {
+        thumbIndex = newVal > values[0] ? 1 : 0;
+      }
       draggingThumbRef.current = thumbIndex;
       setDraggingThumb(thumbIndex);
-      updateValue(thumbIndex, newVal);
+      updateValue(thumbIndex, parks ? values[thumbIndex] : newVal);
 
       // Focus the thumb that owns this drag.
       thumbs?.[thumbIndex]?.focus();
@@ -834,7 +885,15 @@ export function Slider({ref, ...props}: SliderProps) {
         (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
       }
     },
-    [isDisabled, getValueFromPosition, getClosestThumb, updateValue, endDrag],
+    [
+      isDisabled,
+      isRange,
+      values,
+      getValueFromPosition,
+      getClosestThumb,
+      updateValue,
+      endDrag,
+    ],
   );
 
   const handlePointerMove = useCallback(
@@ -847,6 +906,48 @@ export function Slider({ref, ...props}: SliderProps) {
         return;
       }
       const newVal = getValueFromPosition(e.clientX, e.clientY);
+      // Hands the drag to a thumb, with its focus and pressed paint.
+      const handTo = (thumbIndex: number) => {
+        if (thumbIndex === draggingThumbRef.current) {
+          return;
+        }
+        draggingThumbRef.current = thumbIndex;
+        setDraggingThumb(thumbIndex);
+        const thumbs =
+          trackRef.current?.querySelectorAll<HTMLElement>('[role="slider"]');
+        thumbs?.[thumbIndex]?.focus();
+        setKeyboardFocusThumb(null);
+      };
+      const pressValue = coincidentDragRef.current;
+      if (pressValue !== null) {
+        if (newVal === pressValue) {
+          return;
+        }
+        // The first movement from a press on coincident thumbs hands the
+        // drag to the thumb that can travel that way.
+        coincidentDragRef.current = null;
+        handTo(newVal > pressValue ? 1 : 0);
+      } else if (coincidentOriginRef.current) {
+        // A drag that began on coincident thumbs follows the pointer either
+        // way: once the pointer passes the other thumb, the dragged one stops
+        // against it and the other takes the drag (a first step that drifted
+        // the wrong way never sticks the drag).
+        const current = valuesRef.current;
+        const dragging = draggingThumbRef.current;
+        const other = dragging === 0 ? 1 : 0;
+        if (
+          (dragging === 0 && newVal > current[1]) ||
+          (dragging === 1 && newVal < current[0])
+        ) {
+          // The dragged thumb ends against the other one, as if it had
+          // followed the pointer there, and the other follows the pointer on.
+          const from = [...current];
+          from[dragging] = current[other];
+          handTo(other);
+          updateValue(other, newVal, true, from);
+          return;
+        }
+      }
       updateValue(draggingThumbRef.current, newVal);
     },
     [isDisabled, getValueFromPosition, updateValue],
@@ -980,8 +1081,8 @@ export function Slider({ref, ...props}: SliderProps) {
     // name from the visible label element via aria-labelledby.
     const thumbLabel = isRange
       ? thumbIndex === 0
-        ? 'Minimum value'
-        : 'Maximum value'
+        ? t('@astryx.slider.minimumThumb')
+        : t('@astryx.slider.maximumThumb')
       : undefined;
 
     // ARIA bounds must agree with the movement clamping in updateValue: in
@@ -1065,7 +1166,11 @@ export function Slider({ref, ...props}: SliderProps) {
           placement={tooltipPlacement}
           delay={0}
           focusTrigger="always"
-          isOpen={draggingThumb === thumbIndex ? true : undefined}>
+          // A drag keeps its own thumb's value showing and closes the other
+          // thumb's, which a drag handed over from it may have forced open.
+          isOpen={
+            draggingThumb === null ? undefined : draggingThumb === thumbIndex
+          }>
           {thumbElement}
         </Tooltip>
       );

package/src/Spinner/Spinner.tsx

@@ -21,8 +21,8 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, durationVars, spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Text} from '../Text/Text';
-import {mergeProps} from '../utils';
-import {useTranslator} from '../i18n';
+import {mergeProps} from '../utils/mergeProps';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -334,7 +334,9 @@ const styles = stylex.create({
     // it (a frozen spinner reads as broken), matching ProgressBar's approach.
     // The role="status" + "Loading" label still convey busy state (obs-6).
     animationDuration: {
-      default: durationVars['--duration-slow-min'],
+      // The loop reads the duration before a theme's tempo scales it
+      // (spec:AST-108 FR4).
+      default: `var(--_astryx-pre-tempo-duration-slow-min, ${durationVars['--duration-slow-min']})`,
       '@media (prefers-reduced-motion: reduce)': '3s',
     },
     animationIterationCount: 'infinite',

package/src/Stack/Stack.tsx

@@ -30,7 +30,7 @@ import {
   paddingBlockStartStyles,
   paddingBlockEndStyles,
 } from '../Layout/padding.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const overflowStyles = stylex.create({

package/src/Stack/StackItem.tsx

@@ -19,7 +19,7 @@ import {
   type StackItemCrossAlignSelf,
   type StackItemSize,
 } from './stackItem.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const overflowStyles = stylex.create({

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/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.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