feat(Stepper): on-track indicator position + status iconography (EPS parity)

[ernestt]

Summary

Hardens the lab Stepper toward the EPS migration (facebook/astryx#4181).

• indicatorPosition prop — "separated" (default) | "on-track". On-track slots each indicator between continuous track segments (EPS style) rather than beside a per-step bar. The whole indicator+label is the click target, and the trailing segment is hidden on the last step (stepCount threaded via context).
• Status drives iconography, not track color — track lines always stay the progress accent; success / warning / error swap the indicator glyph (themed status icons, matching Input), and the current-step ring always takes precedence. Completed steps keep the filled circle-check so they stay visually distinct from success. Not-started steps stay neutral regardless of status.
• Density applies around the indicators (not just the label) in on-track, for both orientations.
• Alignment/typography — vertical & on-track descriptions are left-aligned; description line-height fixed to 16px.
• Stories + tests covering on-track layout and status-glyph precedence.

On-track variant: known cons (accepted for EPS parity)

on-track ships because it is a non-negotiable EPS migration requirement (#4181), not because it's the more robust layout. separated remains the default and the recommended general-purpose variant. Reviewers should be aware of the on-track trade-offs baked into this design:

• indicator="none" is meaningless on-track. The node is what "sits on the track"; with no node you get a bare line plus an empty rail column offsetting the labels — all the layout cost, none of the payoff. Legitimate in separated.
• The track axis can't be padded. Any padding along the line direction breaks the continuous rail into gapped chunks. This is why density is redirected to the cross axis and why the vertical variant needs a negative-margin "bridge" to keep both padding and a continuous line — a more fragile layout than separated's uniform per-step padding.
• Node size is coupled to track width. Thin rail (4px) works with all node types; widening the track makes number badges/rings bulge past the band and filled glyphs merge into it. (A thick-track experiment was tried and reverted for this reason.)
• Extra context coupling. Needs stepCount from context to hide the last trailing segment — the separated variant needs none of this.
• Engineered vertical alignment. Top-aligning the node with the label's first line relies on a fixed leading-segment + bridge, rather than falling out of normal flow.
• Transparent/outline indicators show the rail through the gap (ring, outline glyphs) — busier than sitting beside the track.
• endContent / content slot align less tidily, since labels are offset from the rail (vertical) or centered (horizontal).
• 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.

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; that's intentionally out of scope here.

Test plan

• pnpm -F @astryxdesign/lab typecheck
• vitest run packages/lab/src/Stepper/Stepper.test.tsx (24 passing)
• Storybook visual review: lab-stepper — Separated (default), OnTrackVertical, OnTrackHorizontalDescriptions, StatusAllStates, OnTrackStatus
• Confirm status glyphs match Input and current-step ring wins over status
• Confirm not-started steps stay neutral regardless of status

Made with Cursor

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 22, 2026 9:50pm

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.7KB	0B

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}