Harden & refine Stepper (lab) — align design with EPS stepper migration

[cixzhang]

Summary

Harden and refine the Stepper component (packages/lab/src/Stepper — Stepper + Step). It has shipped in @astryxdesign/lab with a working API, tests, docs, and stories, but needs a hardening + design-refinement pass before it can graduate toward core.

⚠️ Design must align with the EPS stepper migration

Astryx's Stepper is intentionally different in design from the EPS stepper. We're actively working on the EPS → Astryx migration, so this refinement must align the two designs — decide deliberately where Astryx's stepper converges with EPS's and where it stays distinct, rather than drifting independently. Design decisions here should be made with the migration in mind, not in isolation.

Current state (for reference)

• Location: packages/lab/src/Stepper/ — Stepper.tsx, Step.tsx, StepStatus.ts, StepperContext.ts, colocated Stepper.test.tsx, Stepper.doc.mjs / Step.doc.mjs, Storybook story.
• Stepper: activeStep, orientation (horizontal/vertical), onStepClick (non-linear nav), label, density (compact/balanced/spacious). Renders as <ol>/<li> with aria-current="step".
• Step: step index, label, description, status (accent/success/warning/error — color only), icon, indicator (auto/number/none/ReactNode), isDisabled, isOptional, endContent, density.
• History: originally XDSStepper (XDSStepper #215, feat(Stepper): add XDSStepper and XDSStep components #2206), moved to lab for API rework (refactor(Stepper): move to @xds/lab — API needs rework #2335), earlier hardening pass (Hardening: XDSStepper #2224, closed).

Hardening scope (per the Component Hardening Protocol)

Layer 1 — automated audit: token usage (note STEP_GAP = '2px' hardcoded gap — should this be a spacing token?), themeProps placement across states, prop/type naming, structure, export hygiene, a11y contracts.

Layer 2 — bug & visual fixes: verify every state the props already promise renders correctly — rest / hover / focus / active / disabled / the four status colors / completed vs. current vs. upcoming / optional. Keyboard nav for the clickable (onStepClick) case, aria-current wiring, focus order. Overflow / long-label / many-steps behavior in both orientations.

Layer 3 — design review: proportions, indicator modes, connector treatment, density scales, vertical-stepper content layout — evaluated against the EPS stepper as part of the migration alignment.

Acceptance criteria

• Design reconciled with the EPS stepper as part of the migration (convergence/divergence decisions recorded).
• Layer 1 audit clean (tokens, themeProps, naming, structure, a11y, exports).
• All prop-promised states render correctly across themes + light/dark.
• Keyboard + ARIA verified for linear and non-linear (onStepClick) modes.
• Stories demonstrate every state, both orientations, all density scales, and edge cases (long labels, many steps).
• Findings that exceed hardening scope (new props/variants) routed to spec issues; naming disputes routed to a vibe test.

[ernestt]

We can support an on-track indicator variant — where the indicators sit on the connector line rather than beside it — matching the EPS design. It's implemented behind a new indicatorPosition="on-track" prop in #4214 (separated remains the default). See the screenshots in that PR for horizontal, vertical, and status states.

That said, this look has drawbacks that are intrinsic to the design, not implementation bugs. Flagging them here so we go in eyes-open:

• indicator="none" becomes meaningless. The whole premise is "a node sitting on the track." With no node you get a bare line plus an empty rail column that still offsets the labels — all the layout cost, none of the payoff. (It stays a legitimate minimal style in separated.)
• The track axis can't be padded. Any padding along the line direction breaks the continuous rail into gapped chunks. Density therefore has to be redirected to the cross axis only, and the vertical variant needs a negative-margin "bridge" to keep both padding and a continuous line — inherently more fragile than separated's uniform per-step padding.
• Node size is coupled to track thickness. A thin rail works with every node type; thickening the track makes number badges/rings bulge past the band and filled glyphs visually merge into it. (We tried a thick-track experiment and reverted it for exactly this.)
• Extra coupling: the layout needs the total step count to know when to hide the trailing segment on the last step — the separated variant needs no such cross-step knowledge.
• Vertical alignment is engineered, not free. Top-aligning the node with the label's first line relies on a fixed leading segment + the bridge trick, rather than falling out of normal flow.
• Transparent/outline indicators show the rail through them (the current-step ring, outline status glyphs) — busier, and more so with a thicker track.
• endContent and the content slot align less tidily, since labels are offset from the rail (vertical) or centered under it (horizontal).

Net: separated is the more robust, prop-agnostic layout, so we're keeping it as the default. We're shipping on-track specifically to meet this EPS parity requirement, with the above understood as accepted trade-offs. A truly continuous rail running under the nodes (vs. segments flanking each node) would require restructuring the connector into a single overlay layer with absolutely-positioned nodes — out of scope for #4214.

[ernestt]

Following up on the earlier cons list above: while prototyping the responsive-collapse and auto-advance features for the Stepper, two more intrinsic on-track cons surfaced. Like the others, these are properties of the design, not implementation bugs:

• Responsive collapse isn't supported for on-track. The collapsed narrow-width layout (hide non-active nodes/labels, keep an even progress rail) doesn't reduce cleanly for the segment-based on-track structure — the continuous rail and its nodes break visually. Collapse is therefore scoped to the separated variant.
• Auto-advance (reels-style timed fill) isn't supported for on-track. The element that visually fills/progresses is the connector segment between nodes, not the step's own node — so a timed fill reads as "the gap is progressing," which is misleading. Auto-advance is therefore scoped to the separated variant.

Both reinforce the same conclusion: separated stays the more robust, general-purpose variant, and on-track remains scoped to EPS parity.