An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Step authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-27 owners: [cixzhang] review_triggers: [public-api, behavior, accessibility] verified_by: [ packages/core/src/Stepper/Stepper.test.tsx, apps/storybook/stories/Stepper.stories.tsx, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [] design_specs: [] architecture: [architecture:interaction-modality, architecture:component-theming-surface] contributing: []
system_specs: [spec:AST-085]
Step component contract
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 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.
Intent
Step is one stage of a Stepper flow. It owns its progress derivation, its
indicator choice, its status cues and text alternatives, its clickable form, its optional cue, and where its content renders. Consumer usage lives in Step.doc.mjs.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: progress follows the Stepper's active step
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- 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 its wrapper's color, on every step.indicator="none"shows no indicator, and underautothe current step's ring and label keep progress color whatever itsstatus, 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 only the description describes it,
so the "Optional" cue and
endContentnever reach assistive technology on a clickable step. WCAG 1.3.1 requires information shown to be available programmatically.
Ownership boundary
Owns
- Progress derivation, indicator selection, status glyphs and text, the clickable button, disabled and optional handling, and density fallback (FR1–FR7).
- Where
childrenrender and how they stay mounted (FR8), and the focus outline (FR9).
Does not own / non-goals
- The
step,step-bar,step-connector,step-indicator,step-label, andstep-descriptiontargets, connector geometry and gap, Label and Description paint, and the compact horizontal presentation — owned bycomponent:StepperFR1–FR16. - The active step, orientation, indicator position, and
onStepClick— owned by the Stepper and its caller. - Custom indicator artwork,
endContent, andchildren— owned by the caller.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Progress | completed, in-progress, not-started |
Derived from step and the Stepper's active step. |
Every step. | — | component:Step |
Stable | Not caller-settable. |
| Status | accent, success, warning, error |
Semantic color and glyph for the indicator. | Every step. | Unset (progress color) | component:Step |
Stable | TypeScript rejects other values. |
| Indicator | auto, number, none, node |
What the indicator shows. | Every step. | auto |
component:Step |
Stable | A non-string node renders as given; another string shows the ring, then the check. |
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 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
- AV1 — Indicator artwork. A custom node may replace the indicator.
- AV2 — Layout. Orientation and indicator position come from the Stepper.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| 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; focusable and aria-disabled; no activation (FR2). |
— |
| Compact horizontal | No button; content mounted but hidden. | — |
Transformation and precedence order
- ORD1 — Status word.
error, thenwarning, thencompleted(completed progress orsuccess). - ORD2 — Density. Step
density, then the Stepper's.
Performance and resources
- No resource rule.
Accessibility contract
- AR1 — Current step. FR1's
aria-current="step". - AR2 — Non-color status. With
indicator="auto", FR4's glyphs and FR5's hidden text carry status beyond color; indicators stay hidden from assistive technology. Implementation gap: innumber, custom-node, andnonemodes, and on theautocurrent step, status shows by color alone or only in the hidden word (Current-state impact). - AR3 — Clickable name. FR2's button name includes the step number, label,
and status word, and the step's description describes it. Implementation gap:
a clickable step's optional cue and
endContentare 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
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Indicator | Number, check, status glyph, ring, or custom node. | Current source and public docs | Prominent | FR3, FR4 |
| Optional cue | "Optional" after the label. | Current source | Supporting | FR6 |
Step.doc.mjs declares no anatomy of its own; Step anatomy and targets are in
component:Stepper's theming map.
Family and system relationships
component:Stepperowns the targets, connector, Label and Description paint, and compact layout this component renders within.
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, 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 |
| RTL relation | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on Stepper / Default horizontal |
Step indicator and label; LTR and RTL | An indicator that is not at the inline start of its label fails D2. | audit:Step/i18n-rtl |
Read from source, with no focused test yet:
- FR3: the number on a not-started step and the check after completion under
auto, the empty indicator undernone, and the string fallback. - FR6: the dimmed disabled paint, the optional cue, and
endContent. - FR7.
- FR8: the one-line label.
- FR9.
Decision log
No component-local decision is recorded.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables, examples, or Stepper layout rules. It links to their owners.