Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Stepper): a disabled step stays focusable and aria-disabled in a clickable Stepper (component:Step FR2) (#8867)

Cindy Zhang962dffeebaa1
diff --git a/.changeset/stepper-disabled-step-focusable.md b/.changeset/stepper-disabled-step-focusable.md
new file mode 100644
index 0000000000..29548b6b22
--- /dev/null
+++ b/.changeset/stepper-disabled-step-focusable.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] In a clickable `Stepper`, a disabled `Step` now keeps its button: it stays in the tab order, is announced as unavailable (`aria-disabled`), and keeps focus if it becomes disabled while focused, but still does not activate. Its description (the reason it is unavailable) describes the button (`spec:AST-085` FR1, FR4, FR5). Before, it rendered as plain text, so keyboard and screen-reader users could not find it or tell it was unavailable.
+
+@cixzhang
diff --git a/packages/core/src/Stepper/Step.spec.md b/packages/core/src/Stepper/Step.spec.md
index 02ca8e1526..12fef86337 100644
--- a/packages/core/src/Stepper/Step.spec.md
+++ b/packages/core/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:
diff --git a/packages/core/src/Stepper/Step.tsx b/packages/core/src/Stepper/Step.tsx
index 30a239d56c..304cc10c7d 100644
--- a/packages/core/src/Stepper/Step.tsx
+++ b/packages/core/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,
diff --git a/packages/core/src/Stepper/Stepper.doc.mjs b/packages/core/src/Stepper/Stepper.doc.mjs
index d83147dac5..137ed603b0 100644
--- a/packages/core/src/Stepper/Stepper.doc.mjs
+++ b/packages/core/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',
diff --git a/packages/core/src/Stepper/Stepper.test.tsx b/packages/core/src/Stepper/Stepper.test.tsx
index b93291b9c3..9498d1918f 100644
--- a/packages/core/src/Stepper/Stepper.test.tsx
+++ b/packages/core/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'}),