An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 3 kind: component id: component:Stepper authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-02 owners: [cixzhang] review_triggers: [public-api, theming, layout] verified_by: [ packages/core/src/Stepper/Stepper.test.tsx, packages/core/src/Stepper/Stepper.public.test.ts, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [] architecture: [architecture:component-theming-surface, architecture:public-component-api] contributing: []
system_specs: [spec:AST-002/DEC-1]
Stepper component contract
Intent
Stepper presents an ordered flow of steps and the progress made through it. This
contract records its narrow-container behavior, anatomy-to-target map, public
semantic custom property --step-connector-gap, and Label and Description
ownership.
Compatibility and migration
- Released default preserved:
yes—horizontalOptions.minimumStepWidthstill defaults to112, andcollapsedVariantdefaults towithLabelAndControls - Compatibility class: breaking API narrowing relative to
0.5.3.minimumStepWidthnow accepts pixel numbers only,registerStepreplaces its disabled boolean with an optional options object, andStepperContextValueno longer names step count, compact state, the summary portal, or threshold measurement details - Semantic delta: CSS-length collapse thresholds → numeric pixel thresholds;
disabled snapshots passed to registration → an optional
getIsDisabledcallback; the context hook's public return → the same state, registration, and transition history without compact-layout implementation fields - Review classification: owner-approved breaking simplification for FR14 and the public context boundary
- Controlled/uncontrolled behavior: not applicable
- Migration decision: convert CSS lengths to their intended pixel number,
replace
registerStep(index, isDisabled)withregisterStep(index, {getIsDisabled})or omit the options, and stop reading the five removed context fields
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The
stepper,stepper-frame,stepper-summary,step,step-bar,step-connector,step-indicator,step-label, andstep-descriptiontargets. - The two paint layers of a connector — the unfilled track (the element's own
background) and the accent fill (an absolutely placed
::before) — and the single clip that holds both off the indicator. - Which pieces an on-track connector is drawn from, and how many.
- Reading
horizontalOptions.minimumStepWidthas a pixel number and deriving compact state from that threshold, the Stepper width, and registered steps. - Label and Description paint and the target ownership defined by FR9–FR11.
Does not own / non-goals
- Indicator artwork supplied through
indicator— owned by the caller. - The step content slot and any
endContent— owned by the caller. - Whether a step is complete: derived from
activeStep, not from a caller-owned per-step lifecycle. - The unpainted clickable inner column.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
--step-connector-gap |
Any CSS <length-percentage> |
How far the track stops short of the indicator, on the side facing it | indicatorPosition="on-track", both orientations and both directions, only on steps that render an indicator |
0px |
component:Stepper |
stable | Clamped, never rejected: values below 0 resolve to 0, values above --spacing-2 cap at --spacing-2 |
horizontalOptions.minimumStepWidth |
number |
Required within horizontalOptions; per-step width in pixels below which a horizontal Stepper uses its compact presentation |
Horizontal orientation | 112 when horizontalOptions is omitted |
Caller | stable | TypeScript rejects non-numeric values; numbers are interpreted as pixels |
useStepperContext return |
StepperContextValue |
Stepper state, transition history, and registration for descendant content; excludes step count, compact state, summary portal, and threshold measurement details | Descendants of Stepper |
Current provider value | Component | stable | Throws outside Stepper; TypeScript and runtime omit unsupported layout-coordination fields |
horizontalOptions.collapsedVariant |
withLabelAndControls | withLabel | hiddenLabel |
Required within horizontalOptions; whether compact mode shows a label with navigation controls, a label alone, or only the bare progress track |
Compact horizontal orientation; controls require withLabelAndControls and onStepClick |
withLabelAndControls when horizontalOptions is omitted |
Caller | stable | TypeScript rejects unknown variants |
Consumer syntax and description remain in Stepper.doc.mjs theming.vars.
Behavioral and layout contract
| ID | Candidate invariant | Basis | Draft review state |
|---|---|---|---|
| FR1 | --step-connector-gap falls back to 0px where each connector consumes it and honors values inherited from an ancestor up to the nearest layer content boundary, or supplied through the stepper theming target. |
Reviewed defect (PR #5495) | Settled |
| FR2 | The gap is applied to the ONE edge each segment faces the indicator from, mirrored per axis, so the pair leaves a hole centred on the node. | Current source and browser probe | Settled |
| FR3 | One declaration covers both connector paint layers. A clip on the segment clips its ::before with it, against one reference box, so the two cannot disagree. |
Current source and browser probe | Settled |
| FR4 | The resolved value is clamped to max(0px, min(value, --spacing-2)) before use. |
Reviewed defect (PR #5495) | Settled |
| FR5 | A step rendering no indicator (indicator="none") applies no clip, leaving its track continuous. |
Current source and browser probe | Settled |
| FR6 | No accepted value changes the Stepper's outer size, in either orientation. A clip cannot affect layout. | Current source and browser probe | Settled |
| FR7 | The horizontal clip mirrors under dir="rtl", so the hole stays at the indicator rather than moving to the join between steps. |
Reviewed defect (PR #5495) | Settled |
| FR8 | The pieces an on-track connector is drawn from are not public: no data-segment, and no bare lead/rail/content class is emitted. |
component:Stepper/DEC-1 |
Settled |
| FR9 | In both indicator positions, each rendered Label and Description carries its own target and reflects progress and status. |
Current source, docs, and tests | Settled |
| FR10 | Label alone reflects disabled, because only Label owns disabled paint. Description and the other targets do not gain the selector for symmetry. |
Current source, docs, and tests | Settled |
| FR11 | Label and Description each declare font-size, line-height, and color. Those declarations outrank values inherited from step, so only direct targets can expose that paint to themes. |
Current source and Chromium probe | Settled |
| FR12 | A compact horizontal summary sits directly beneath its track without an additional frame gap. | Reviewed narrow-layout feedback | Settled |
| FR13 | In compact on-track, indicators remain on the rail and the active indicator is not repeated beside the summary label; compact separated retains the active indicator beside its label. |
Reviewed narrow-layout feedback | Settled |
| FR14 | horizontalOptions.minimumStepWidth accepts a number interpreted as pixels. Compact state compares the registered per-step width directly with that number; no threshold measurement element or observer is rendered. |
Configurable collapse threshold | Settled |
| FR15 | horizontalOptions.collapsedVariant keeps horizontal-only configuration together: withLabelAndControls shows the label and controls, withLabel shows only the label, and hiddenLabel renders only the bare progress track with no compact row. |
Collapsed presentation consolidation | Proposed for owner review |
| FR16 | useStepperContext preserves Stepper state, transition history, and registerStep, while omitting stepCount, isCompact, summarySlot, minimumStepWidth, and minStepWidthMeasureRef from both its TypeScript type and runtime object. registerStep(index, options?) accepts an optional getIsDisabled callback instead of a disabled boolean, and compact navigation reads that callback again when a control activates so a stale render cannot select a newly disabled step. |
Public context boundary | Settled |
status on Label and Description is a selector seam. It does not claim that
Astryx paints either text part by status.
Allowed variation
- AV1 — Segment count. How many elements draw one connector span may change with orientation and with the presence of a content slot, without becoming a regression. It is not public.
- AV2 — Percentage resolution. A percentage resolves against each segment's own box, so the hole may differ slightly between a fixed and a flexible segment. Both layers of any one segment still agree exactly (FR3).
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| vertical, on-track, indicator | FR2, FR3, FR6 | AV1, AV2 |
| horizontal, on-track, indicator | FR2, FR3, FR6, FR7 | AV1, AV2 |
dir="rtl", horizontal |
FR7 | AV1 |
indicator="none" |
FR5 | — |
value below 0 or above the cap |
FR4, FR6 | — |
| both indicator positions; each progress/status; disabled Label | FR9–FR11 | — |
| compact horizontal summary | FR12 | — |
compact on-track and separated indicators |
FR13 | — |
| custom numeric pixel collapse threshold | FR14 | — |
| public context read versus internal layout coordination | FR16 | — |
each collapsedVariant, with and without onStepClick |
FR15 | — |
Transformation and precedence order
- ORD1 — Gap resolution. Read the inherited custom property → clamp to
max(0px, min(value, --spacing-2))→ apply as oneclip-path: inset()on the segment. Both halves of the clamp are load-bearing, and neither for padding's reasons:inset()accepts a negative length rather than clamping it the way padding does, so the floor has to be written; the cap bounds an oversized gap to a short track.
Performance and resources
- Horizontal Stepper instances register their list with the shared
ResizeObserver. Numeric pixel thresholds are compared directly, so no second observer or measurement element is required.
Accessibility contract
Compact layout preserves the ordered-list role and aria-current handling while
moving optional navigation to the summary controls.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Stepper | Lays the flow out on one orientation and indicator placement. | Current source and public docs | Supporting | FR1 |
| Frame | Groups the ordered steps with the optional compact summary. | Current source and public docs | Supporting | — |
| Compact summary | Names and controls the current step when horizontal labels collapse. | Current source and public docs | Prominent | — |
| Step | Carries one step's status. | Current source and public docs | Supporting | — |
| Progress bar | Presents progress as a segmented bar per step. | Current source and public docs | Prominent | — |
| Connector | Presents the track between indicators, and the progress made along it. | Current source and public docs | Prominent | FR2–FR7 |
| Indicator | Presents the step's position or completion. | Current source and public docs | Prominent | FR5 |
| Label | Identifies the step. | Current source and public docs | Prominent | FR9–FR11 |
| Description | Gives supporting context below the Label. | Current source and public docs | Supporting | FR9–FR11 |
Theming anatomy
{
"Stepper": {"target": "stepper"},
"Frame": {"target": "stepper-frame"},
"Compact summary": {"target": "stepper-summary"},
"Step": {"target": "step"},
"Progress bar": {"target": "step-bar"},
"Connector": {"target": "step-connector"},
"Indicator": {"target": "step-indicator"},
"Label": {"target": "step-label"},
"Description": {"target": "step-description"}
}
Connector is one anatomy part with one target, even though the on-track layouts
draw it from up to three elements. Those pieces are layout implementation, not
semantic parts, so they get no targets of their own — see DEC-1, which is also
why the caller-owned gap is a custom property rather than a per-piece vocabulary.
Label and Description are local spans styled by Stepper, not delegated Text
parts. Their own typography and color declarations make inherits: step false;
DEC-2 records why they own direct targets instead.
Family and system relationships
architecture:component-theming-surfaceowns anatomy qualification, the guaranteed-property catalog, and the admission rule for public semantic variables.architecture:public-component-apiowns the API admission bar those variables must also pass.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1 | Stepper.test.tsx fallback and inheritance assertions |
vertical and horizontal on-track | Declaring a default on the list blocks values inherited from its horizontal frame. | audit:Stepper/theming |
| FR2, FR3 | Stepper.test.tsx clip assertions |
vertical and horizontal on-track | Clipping the wrong edge, or per-layer copies of the value, fails the suite. | audit:Stepper/theming |
| FR4, FR6 | Stepper.test.tsx clamp assertion |
values below 0 and above the cap |
Removing the floor lets a negative inset through; removing the cap unbounds the hole. | audit:Stepper/theming |
| FR5 | Stepper.test.tsx no-indicator assertion |
indicator="none" |
Applying the clip unconditionally puts holes in a track with no node in them. | audit:Stepper/theming |
| FR7 | Stepper.test.tsx RTL assertion |
dir="rtl", horizontal |
Dropping the mirror moves the hole to the join between steps; caught by the assertion. | audit:Stepper/theming |
| FR8 | Stepper.test.tsx vocabulary guard |
vertical on-track | Re-adding data-segment or a bare role class fails the guard. |
audit:Stepper/theming |
| FR9, FR10 | Stepper.test.tsx target and generated-theme assertions |
Both indicator positions; progress, status, and disabled | Removing a target or state, or moving it off the painted span, fails focused tests. | audit:Stepper/theming |
| FR11 | Exact-head Chromium probe | Themed step, Label, and Description |
If inheritance reaches the text, the Step target's probe color appears there. | audit:Stepper/theming |
| FR12 | Stepper.test.tsx compact frame gap assertion |
Compact horizontal summary | Restoring frame spacing separates the summary from the track and fails the suite. | audit:Stepper/layout |
| FR13 | Stepper.test.tsx compact indicator assertions |
Compact separated and on-track |
Repeating the on-track active indicator, or dropping the separated one, fails the suite. | audit:Stepper/layout |
| FR14 | Stepper.test.tsx threshold assertions |
Default and custom pixel number | Reintroducing threshold measurement or CSS-length support fails the runtime/type guards. | audit:Stepper/layout |
| FR15 | Stepper.test.tsx collapsed-variant assertions |
Three variants, with and without navigation | A variant shows an unrequested label/control or changes the accessible sequence. | audit:Stepper/layout |
| FR16 | Stepper.public.test.ts type assertions and Stepper.test.tsx runtime key assertion |
Public hook/type and separate public/internal provider values | A named layout-coordination field reaches the public type/runtime object, or transition history/registration disappears. | audit:Stepper/api |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and the nine current targets | A target with no anatomy owner, or a stale/extra part, fails repository validation. | audit:Stepper/theming |
Decision log
DEC-1 — The connector gap is a public custom property, not a theme target per piece
Reference: component:Stepper/DEC-1
Decider: cixzhang, 2026-09-02
The optional Connector anatomy represents the connected, on-track presentation;
its inner gap from the component-owned Indicator is a stable component
responsibility. A theme may want that track to stop short of the indicator rather
than run through it. Two otherwise identical Steppers need different resolved outcomes
and only the theme knows which, so the need is caller-owned
(spec:AST-002/DEC-1 FR1). Astryx cannot derive it: nothing in the component's
state, content, or layout says whether this design wants a broken or a
continuous track.
No guaranteed CSS property on the owning target can express it. A connector
paints in two layers — the element's own background (the unfilled track) and a
::before at inset: 0 (the accent fill) — and a theme target reaches the
element only. Measured in Chromium against a built theme override on
step-connector, three steps, vertical:
paddingBlock: 6pxproduces no hole at all. The element's background paints to its border box, and the fill is a pseudo-element the theme cannot reach, so the only observable effect is the Stepper growing 108px → 120px.paddingBlockEnd: 6pxproduces no hole either, and would in any case address only one of the two edges: the leading segment faces the node with its far edge, the trailing segment with its near one.
Only the component can put one clip on the segment that takes its pseudo-element with it, mirror it per axis and per direction, and clamp the value first.
Rejected: exposing lead / rail / content as a public segment vocabulary
(the earlier form of this change). The words never reached generated docs, they
emitted bare lead / content classes a consumer stylesheet can collide with,
and lead denotes different geometry per orientation, so a theme selecting it
could not know what it would get.
DEC-2 — Label and Description own direct targets
Reference: component:Stepper/DEC-2
Decider: cixzhang, 2026-09-02
FR9–FR11 define the admitted targets, state selectors, and inheritance
evidence. Rejected alternatives: inherits: step fails FR11;
delegatesTo: component:Text describes a composition Stepper does not render;
and step-row would expose an unpainted wrapper for speculative styling.
Candidate DEC-3 — Horizontal behavior uses one options object
Reference: component:Stepper/DEC-3
Status: owner review requested
Two otherwise identical horizontal Steppers can need different collapse points or compact content: one may use short fixed labels while another uses wider localized labels; one surrounding flow may own Back/Continue or a step heading while another relies on the Stepper. The caller owns those distinctions. Existing styling seams cannot select the compact React presentation because collapse changes rendered labels, focus targets, navigation controls, and preserved content rather than paint alone.
horizontalOptions keeps these horizontal-only decisions out of the Stepper's
top-level API. minimumStepWidth names the per-step space the caller is
guaranteeing. It is a pixel number, following other Astryx size props, so the
Stepper compares it directly without a browser-resolved probe or a second
observer. collapsedVariant is one closed choice because its values describe
the complete compact presentation and avoid conflicting boolean combinations.
DEC-4 — Public context excludes compact-layout implementation fields
Reference: component:Stepper/DEC-4
Decider: imdreamrunner, 2026-09-06
useStepperContext preserves the existing Stepper state and transition history.
Its registerStep contract replaces the disabled boolean with an optional
options object whose getIsDisabled callback lets compact navigation read the
Step's current state. Separate public and package-internal contexts make the
runtime boundary match the type boundary: the public provider contains exactly
the supported keys, while the internal provider adds stepCount, isCompact,
and summarySlot for the built-in Step. minimumStepWidth and
minStepWidthMeasureRef disappear entirely with the pixel-only threshold
implementation.
Rejected: returning the package-internal provider value from
useStepperContext() with only a narrower TypeScript return type. JavaScript
could still read the removed fields, making the runtime API contradict the
public contract.
Open questions
- Owner review of FR15 and the
horizontalOptions.collapsedVariantpublic API admission argument.
Content boundary
This file does not duplicate consumer prop tables, examples, implementation steps, or system rules. It links to their owners.