Skip to content

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

TypeScript

feat(Stepper): add on-track indicator position + status iconography for EPS parity (#4214)

Ernest4a7ce02d92ab
diff --git a/apps/storybook/stories/Stepper.stories.tsx b/apps/storybook/stories/Stepper.stories.tsx
index 9166376cd0..a736436de7 100644
--- a/apps/storybook/stories/Stepper.stories.tsx
+++ b/apps/storybook/stories/Stepper.stories.tsx
@@ -16,6 +16,10 @@ const meta: Meta<typeof Stepper> = {
activeStep: {control: {type: 'number', min: 0, max: 5}},
orientation: {control: 'select', options: ['horizontal', 'vertical']},
density: {control: 'select', options: ['compact', 'balanced', 'spacious']},
+ indicatorPosition: {
+ control: 'select',
+ options: ['separated', 'on-track'],
+ },
},
};
@@ -56,11 +60,7 @@ export const Default: Story = {
label="Import data"
description="Bring in existing projects"
/>
- <Step
- step={4}
- label="Launch"
- description="Go live with your team"
- />
+ <Step step={4} label="Launch" description="Go live with your team" />
</Stepper>
</div>
);
@@ -159,11 +159,13 @@ export const NumberedHorizontal: Story = {
};
// ============================================================
-// STATUS (semantic color + generic icons — validation flows)
+// STATUS (semantic status — validation flows)
//
-// `status` controls color only (accent/success/warning/error). The
-// indicator accepts any icon, so validation flows pass an explicit
-// <Icon /> rather than relying on a fixed status-driven icon set.
+// In the default `auto` mode, `status` sets both the indicator color and a
+// matching glyph: success → green check-circle, warning/error → the shared
+// Input status icons. `accent` is color-only. The current (in-progress) step
+// always keeps its current-step ring, so status glyphs show on the other
+// steps. `status` never recolors the connector/track.
// ============================================================
export const StatusVertical: Story = {
@@ -181,21 +183,18 @@ export const StatusVertical: Story = {
label="Email verified"
description="[email protected]"
status="success"
- icon={<Icon icon="check" size="sm" />}
/>
<Step
step={1}
label="Phone verified"
description="+1 (555) 012-3456"
status="success"
- icon={<Icon icon="check" size="sm" />}
/>
<Step
step={2}
label="Identity document"
description="Passport upload failed"
status="error"
- icon={<Icon icon="warning" size="sm" />}
/>
<Step
step={3}
@@ -219,7 +218,9 @@ export const StatusVertical: Story = {
export const StatusAllStates: Story = {
name: 'Status — Semantic Colors Reference',
render: () => {
- const [active, setActive] = useState(1);
+ // Start past all steps so each status glyph is visible (the current step
+ // always shows the ring, which would otherwise mask one status).
+ const [active, setActive] = useState(5);
return (
<div style={{maxWidth: 400}}>
<Stepper
@@ -237,21 +238,18 @@ export const StatusAllStates: Story = {
label="Success"
description="--color-success"
status="success"
- icon={<Icon icon="check" size="sm" />}
/>
<Step
step={2}
label="Warning"
description="--color-warning"
status="warning"
- icon={<Icon icon="warning" size="sm" />}
/>
<Step
step={3}
label="Error"
description="--color-error"
status="error"
- icon={<Icon icon="warning" size="sm" />}
/>
<Step
step={4}
@@ -684,3 +682,238 @@ export const LongLabels: Story = {
);
},
};
+
+// ============================================================
+// ON-TRACK (EPS-aligned) — indicator slotted into the connector line
+// ============================================================
+
+export const OnTrackVertical: Story = {
+ name: 'On-Track — Vertical',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 400}}>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step step={0} label="Create workspace" />
+ <Step step={1} label="Invite team members" />
+ <Step step={2} label="Set up integrations" />
+ <Step step={3} label="Import data" />
+ <Step step={4} label="Launch" />
+ </Stepper>
+ </div>
+ );
+ },
+};
+
+export const OnTrackHorizontal: Story = {
+ name: 'On-Track — Horizontal',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 700}}>
+ <Stepper
+ activeStep={active}
+ orientation="horizontal"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step step={0} label="Cart" indicator="number" />
+ <Step step={1} label="Shipping" indicator="number" />
+ <Step step={2} label="Payment" indicator="number" />
+ <Step step={3} label="Review" indicator="number" />
+ <Step step={4} label="Confirm" indicator="number" />
+ </Stepper>
+ </div>
+ );
+ },
+};
+
+export const OnTrackVerticalDescriptions: Story = {
+ name: 'On-Track — Vertical (with description)',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 400}}>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step
+ step={0}
+ label="Create workspace"
+ description="Name and configure your workspace"
+ />
+ <Step
+ step={1}
+ label="Invite team members"
+ description="Add collaborators by email"
+ />
+ <Step
+ step={2}
+ label="Set up integrations"
+ description="Connect Slack, GitHub, Jira"
+ />
+ <Step
+ step={3}
+ label="Import data"
+ description="Bring in existing projects"
+ />
+ <Step step={4} label="Launch" description="Go live with your team" />
+ </Stepper>
+ </div>
+ );
+ },
+};
+
+export const OnTrackHorizontalDescriptions: Story = {
+ name: 'On-Track — Horizontal (with description)',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 760}}>
+ <Stepper
+ activeStep={active}
+ orientation="horizontal"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step
+ step={0}
+ label="Cart"
+ indicator="number"
+ description="Review your items"
+ />
+ <Step
+ step={1}
+ label="Shipping"
+ indicator="number"
+ description="Where to deliver"
+ />
+ <Step
+ step={2}
+ label="Payment"
+ indicator="number"
+ description="Card or PayPal"
+ />
+ <Step
+ step={3}
+ label="Review"
+ indicator="number"
+ description="Confirm details"
+ />
+ <Step
+ step={4}
+ label="Confirm"
+ indicator="number"
+ description="Place your order"
+ />
+ </Stepper>
+ </div>
+ );
+ },
+};
+
+export const OnTrackComparison: Story = {
+ name: 'On-Track — vs Separated',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{display: 'flex', gap: 64}}>
+ <div style={{maxWidth: 280}}>
+ <Text type="label">separated (current)</Text>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ indicatorPosition="separated"
+ onStepClick={setActive}>
+ <Step step={0} label="Account" description="Basic details" />
+ <Step step={1} label="Profile" description="About you" />
+ <Step step={2} label="Settings" description="Preferences" />
+ <Step step={3} label="Review" description="Confirm details" />
+ </Stepper>
+ </div>
+ <div style={{maxWidth: 280}}>
+ <Text type="label">on-track (EPS-aligned)</Text>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step step={0} label="Account" description="Basic details" />
+ <Step step={1} label="Profile" description="About you" />
+ <Step step={2} label="Settings" description="Preferences" />
+ <Step step={3} label="Review" description="Confirm details" />
+ </Stepper>
+ </div>
+ </div>
+ );
+ },
+};
+
+export const OnTrackStatus: Story = {
+ name: 'On-Track — Status Colors',
+ render: () => {
+ const [active, setActive] = useState(3);
+ return (
+ <div style={{maxWidth: 400}}>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step
+ step={0}
+ label="Email verified"
+ description="[email protected]"
+ status="success"
+ />
+ <Step
+ step={1}
+ label="Phone verified"
+ description="+1 (555) 012-3456"
+ status="success"
+ />
+ <Step
+ step={2}
+ label="Identity document"
+ description="Passport upload failed"
+ status="error"
+ />
+ <Step
+ step={3}
+ label="Address verification"
+ description="Pending review"
+ status="accent"
+ />
+ <Step step={4} label="Background check" isOptional />
+ <Step step={5} label="Account activated" />
+ </Stepper>
+ </div>
+ );
+ },
+};
+
+export const OnTrackHorizontalManySteps: Story = {
+ name: 'On-Track — Horizontal, Many Steps',
+ render: () => {
+ const [active, setActive] = useState(3);
+ return (
+ <Stepper
+ activeStep={active}
+ orientation="horizontal"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step step={0} label="Idea" indicator="number" />
+ <Step step={1} label="Design" indicator="number" />
+ <Step step={2} label="Build" indicator="number" />
+ <Step step={3} label="Test" indicator="number" />
+ <Step step={4} label="Review" indicator="number" />
+ <Step step={5} label="Deploy" indicator="number" />
+ <Step step={6} label="Monitor" indicator="number" />
+ </Stepper>
+ );
+ },
+};
diff --git a/packages/lab/src/Stepper/Step.tsx b/packages/lab/src/Stepper/Step.tsx
index e0f18379a7..747dba3626 100644
--- a/packages/lab/src/Stepper/Step.tsx
+++ b/packages/lab/src/Stepper/Step.tsx
@@ -30,6 +30,7 @@ import {
} from '@astryxdesign/core/theme/tokens.stylex';
import {mergeProps} from '@astryxdesign/core/utils';
import type {BaseProps} from '@astryxdesign/core';
+import {Icon} from '@astryxdesign/core/Icon';
import {useStepperContext} from './StepperContext';
import {themeProps} from '@astryxdesign/core/utils';
import type {StepStatus} from './StepStatus';
@@ -73,9 +74,13 @@ export interface StepProps extends BaseProps<HTMLLIElement> {
*/
icon?: ReactNode;
/**
- * Semantic color for the step. Controls **color only** and maps to the
- * global Astryx semantic tokens (`accent`, `success`, `warning`, `error`).
- * Leave unset to use the progress-derived default coloring.
+ * Semantic status for the step, mapped to the global Astryx semantic tokens
+ * (`accent`, `success`, `warning`, `error`). In the default `auto` indicator
+ * mode it sets both the indicator color and a matching glyph: `success` shows
+ * a green check-circle, `warning`/`error` show the shared Input status icons.
+ * `accent` is color-only. The current (in-progress) step always keeps its
+ * current-step indicator regardless of `status`. Never recolors the
+ * connector/track.
*/
status?: StepStatus;
/**
@@ -115,16 +120,22 @@ export interface StepProps extends BaseProps<HTMLLIElement> {
}
// --- Default progress icons (16px) ---
+//
+// The `completed` progress state and the current-step ring are drawn as local
+// glyphs: `completed` is a filled circle-check (a distinct "progress done"
+// mark), deliberately different from the semantic `success` status — which
+// defers to the themed Icon registry (an outline check). `warning` / `error`
+// statuses also defer to the themed registry so they share one visual language.
-/** Filled check — shown for completed steps in 'auto' mode. */
+/** Filled circle with a check — shown for a completed step in 'auto' mode. */
function CheckCircleIcon() {
return (
<svg width="16" height="16" viewBox="0 0 16 16" fill="none">
<circle cx="8" cy="8" r="8" fill="currentColor" />
<path
- d="M5 8.5l2 2 4-4"
- stroke="white"
- strokeWidth="1.5"
+ d="M4.75 8.25 7 10.5l4.25-4.5"
+ stroke={colorVars['--color-background-surface']}
+ strokeWidth="1.75"
strokeLinecap="round"
strokeLinejoin="round"
/>
@@ -171,19 +182,6 @@ const styles = stylex.create({
barIncomplete: {
backgroundColor: colorVars['--color-border'],
},
- // Semantic status overrides for the bar — color only.
- barAccent: {
- backgroundColor: colorVars['--color-accent'],
- },
- barSuccess: {
- backgroundColor: colorVars['--color-success'],
- },
- barWarning: {
- backgroundColor: colorVars['--color-warning'],
- },
- barError: {
- backgroundColor: colorVars['--color-error'],
- },
// Step body — the selectable area
verticalBody: {
@@ -350,7 +348,10 @@ const styles = stylex.create({
},
description: {
fontSize: typeScaleVars['--text-supporting-size'],
- lineHeight: typeScaleVars['--text-supporting-leading'],
+ // The supporting-leading token (1.667 → 20px at 12px) reads too loose for
+ // a caption sitting under its label; a fixed 16px line box (1.33) is
+ // tighter without collapsing the text the way capsize trim did.
+ lineHeight: '16px',
color: colorVars['--color-text-secondary'],
},
@@ -411,6 +412,181 @@ const styles = stylex.create({
':focus-visible': '2px',
},
},
+
+ // ===================== ON-TRACK LAYOUT =====================
+ // Indicator is slotted into the connector line as a node on the track.
+ // Each step draws the connector segments that flank its own indicator; the
+ // segment *before* the indicator is hidden on the first step (step === 0) so
+ // the track starts at the first node. Segments abut the indicator directly,
+ // so no child introspection or total-count is needed.
+
+ otVerticalRoot: {
+ display: 'flex',
+ flexDirection: 'column',
+ position: 'relative',
+ },
+ otHorizontalRoot: {
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minWidth: 0,
+ },
+
+ // Interactive wrapper (indicator + label act as one click target).
+ otInteractive: {
+ all: 'unset',
+ boxSizing: 'border-box',
+ // `all: unset` leaves the <button> UA default of centered text; force
+ // start so vertical labels/descriptions read left-aligned. Horizontal
+ // labels re-center via otLabelWrapH (a deeper element).
+ textAlign: 'start',
+ cursor: 'pointer',
+ borderRadius: radiusVars['--radius-element'],
+ transitionProperty: 'background-color',
+ transitionDuration: durationVars['--duration-fast-min'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ backgroundColor: {
+ default: 'transparent',
+ ':hover': {
+ '@media (hover: hover)': colorVars['--color-overlay-hover'],
+ },
+ ':active': colorVars['--color-overlay-pressed'],
+ },
+ },
+
+ otRowWrap: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'stretch',
+ gap: spacingVars['--spacing-2'],
+ width: '100%',
+ },
+ otColWrap: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'stretch',
+ width: '100%',
+ },
+
+ // Vertical indicator column: [segment] [indicator] [segment] stacked.
+ otIndicatorColV: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ width: NUMBER_SIZE,
+ flexShrink: 0,
+ alignSelf: 'stretch',
+ },
+ // Shared segment base: square ends so stacked segments read as one
+ // continuous line (no radius).
+ otSegBaseV: {
+ width: BAR_WIDTH,
+ flexShrink: 0,
+ borderRadius: 0,
+ },
+ // Flexible segment (below the node) — grows to fill the step height and
+ // meets the next node's leading segment.
+ otSegFlexV: {
+ flex: 1,
+ minHeight: spacingVars['--spacing-2'],
+ },
+ // Fixed leading segment (above the node) — its height offsets the node down
+ // so it aligns with the label's first line instead of the step's center.
+ otSegLeadV: (value: string) => ({
+ height: value,
+ }),
+
+ // Horizontal track row: [segment] [indicator] [segment] in a line.
+ otTrackRowH: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'center',
+ width: '100%',
+ },
+ otSegH: {
+ height: BAR_WIDTH,
+ flex: 1,
+ minWidth: spacingVars['--spacing-2'],
+ borderRadius: 0,
+ },
+
+ otSegHidden: {
+ visibility: 'hidden',
+ },
+
+ // Connector fill colors (progress-derived; status recolors when set).
+ lineFilled: {
+ backgroundColor: colorVars['--color-accent'],
+ },
+ lineUnfilled: {
+ backgroundColor: colorVars['--color-border'],
+ },
+
+ otBodyV: {
+ display: 'flex',
+ flexDirection: 'column',
+ justifyContent: 'flex-start',
+ flex: 1,
+ gap: spacingVars['--spacing-0-5'],
+ minWidth: 0,
+ },
+ otLabelWrapH: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-0-5'],
+ textAlign: 'center',
+ },
+ otLabelRowStart: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ },
+ otLabelRowCenter: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'center',
+ justifyContent: 'center',
+ flexWrap: 'wrap',
+ gap: spacingVars['--spacing-1'],
+ },
+
+ otContentV: {
+ paddingInlineStart: spacingVars['--spacing-7'],
+ paddingBlockStart: spacingVars['--spacing-2'],
+ },
+ otContentH: {
+ paddingBlockStart: spacingVars['--spacing-2'],
+ },
+
+ // Density-driven spacing. The connector runs along the "track axis"
+ // (vertical = block, horizontal = inline), so density is only ever applied
+ // to the *cross* axis — padding the track axis would break the line into
+ // gapped segments.
+ //
+ // Vertical: pad the whole step row (indicator rail + label) so density adds
+ // breathing room *around the indicators*, not just the text. Applied to the
+ // hover target itself.
+ otRowPadV: (value: string) => ({
+ paddingBlock: value,
+ paddingInline: value,
+ }),
+ // The rail draws the connector, so it must span the row's full block extent
+ // to keep the line continuous. A negative block margin cancels the wrapper's
+ // block padding, letting the line bridge step-to-step while the label still
+ // sits inside the padding.
+ otRailBridgeV: (value: string) => ({
+ marginBlock: `calc(-1 * ${value})`,
+ }),
+ // Horizontal: block padding around the track+label column (inside the hover
+ // target) adds vertical breathing room while the inline track stays flush.
+ otPadBlock: (value: string) => ({
+ paddingBlock: value,
+ }),
+ otMarginTop: (value: string) => ({
+ marginBlockStart: value,
+ }),
});
/**
@@ -420,8 +596,10 @@ const styles = stylex.create({
*
* Progress (completed / active / not-started) is derived from the parent's
* `activeStep` and this step's `step` prop. The optional `status` prop layers a
- * semantic color (`accent` / `success` / `warning` / `error`) on top — color
- * only; it does not change layout or iconography.
+ * semantic meaning on top: in the default `auto` indicator mode it recolors the
+ * indicator and swaps in a matching glyph (`success` → green check-circle,
+ * `warning`/`error` → the shared Input status icons). The current step always
+ * keeps its current-step ring. `status` never recolors the connector/track.
*
* @example
* ```
@@ -430,7 +608,7 @@ const styles = stylex.create({
*
* @example
* ```
- * <Step step={1} label="Payment" status="error" icon={<Icon icon="warning" />} />
+ * <Step step={1} label="Payment" status="error" />
* ```
*/
export function Step({
@@ -453,7 +631,14 @@ export function Step({
...rest
}: StepProps) {
const ctx = useStepperContext();
- const {activeStep, orientation, onStepClick, density: ctxDensity} = ctx;
+ const {
+ activeStep,
+ orientation,
+ onStepClick,
+ density: ctxDensity,
+ indicatorPosition,
+ stepCount,
+ } = ctx;
const density = densityProp ?? ctxDensity;
@@ -485,18 +670,9 @@ export function Step({
}
};
- // Bar fill is purely progress-based; `status` recolors it when set.
+ // Bar fill is purely progress-based. `status` never recolors the bar — it
+ // only recolors the indicator (icon / number badge) below.
const isBarFilled = progress === 'completed' || progress === 'in-progress';
- const statusBarStyle =
- status === 'accent'
- ? styles.barAccent
- : status === 'success'
- ? styles.barSuccess
- : status === 'warning'
- ? styles.barWarning
- : status === 'error'
- ? styles.barError
- : undefined;
// --- Build indicator node ---
// 'auto': number for not-started, check/dot icon once reached
@@ -507,22 +683,46 @@ export function Step({
const customIcon = isCustomIndicator ? indicatorProp : (icon ?? null);
+ // Semantic `status` drives a distinct indicator glyph (default 'auto' mode,
+ // no custom icon), all sourced from the themed Icon registry so a step reads
+ // the same as the rest of the system:
+ // - success → the themed `success` glyph (same check-circle as a completed
+ // step), tinted success — i.e. a green check
+ // - warning → the themed `warning` glyph
+ // - error → the themed `error` glyph
+ // The current (in-progress) step always shows the current-step ring — its
+ // indicator "replaces" any status glyph. `accent` has no distinct glyph and
+ // falls through to the progress-derived default.
+ const statusGlyph: 'success' | 'warning' | 'error' | null =
+ indicator === 'auto' &&
+ customIcon == null &&
+ !isActive &&
+ (status === 'success' || status === 'warning' || status === 'error')
+ ? status
+ : null;
+
if (indicator !== 'none') {
const showNumber =
customIcon == null &&
+ statusGlyph == null &&
(indicator === 'number' ||
(indicator === 'auto' && progress === 'not-started'));
if (showNumber) {
+ // Status only fills the badge once the step is reached. A not-started
+ // step stays neutral — otherwise `accent` (which has no glyph to swap in)
+ // would paint an inverted accent badge on an upcoming step, making it
+ // read as active/completed.
+ const isReached = progress === 'completed' || progress === 'in-progress';
const numberColorStyle = isDisabled
? styles.numberDisabled
- : status === 'accent'
+ : isReached && status === 'accent'
? styles.numberAccent
- : status === 'success'
+ : isReached && status === 'success'
? styles.numberSuccess
- : status === 'warning'
+ : isReached && status === 'warning'
? styles.numberWarning
- : status === 'error'
+ : isReached && status === 'error'
? styles.numberError
: progress === 'completed'
? styles.numberCompleted
@@ -538,25 +738,59 @@ export function Step({
</div>
);
} else {
- // Custom icon takes priority, otherwise the progress-derived default.
- const iconContent =
+ // Priority: explicit custom icon → status glyph (non-current steps) →
+ // progress-derived default (check when completed, ring when current).
+ const iconContent: ReactNode =
customIcon != null ? (
customIcon
+ ) : statusGlyph === 'success' ? (
+ <Icon
+ icon="success"
+ size="sm"
+ color={isDisabled ? 'disabled' : 'success'}
+ />
+ ) : statusGlyph === 'warning' ? (
+ <Icon
+ icon="warning"
+ size="sm"
+ color={isDisabled ? 'disabled' : 'warning'}
+ />
+ ) : statusGlyph === 'error' ? (
+ <Icon
+ icon="error"
+ size="sm"
+ color={isDisabled ? 'disabled' : 'error'}
+ />
) : progress === 'completed' ? (
<CheckCircleIcon />
) : (
<CurrentIcon />
);
+ // Wrapper tint drives the currentColor glyphs (check-circle / ring /
+ // custom icon). The <Icon> status glyphs set their own color, but we tint
+ // the wrapper to match so the indicator's color reflects `status` too.
const iconColorStyle = isDisabled
? styles.iconDisabled
- : status === 'accent'
- ? styles.iconAccent
- : status === 'success'
+ : customIcon != null
+ ? status === 'accent'
+ ? styles.iconAccent
+ : status === 'success'
+ ? styles.iconSuccess
+ : status === 'warning'
+ ? styles.iconWarning
+ : status === 'error'
+ ? styles.iconError
+ : progress === 'completed'
+ ? styles.iconCompleted
+ : progress === 'in-progress'
+ ? styles.iconInProgress
+ : styles.iconNotStarted
+ : statusGlyph === 'success'
? styles.iconSuccess
- : status === 'warning'
+ : statusGlyph === 'warning'
? styles.iconWarning
- : status === 'error'
+ : statusGlyph === 'error'
? styles.iconError
: progress === 'completed'
? styles.iconCompleted
@@ -576,6 +810,7 @@ export function Step({
const isNumber =
hasIndicator &&
customIcon == null &&
+ statusGlyph == null &&
(indicator === 'number' ||
(indicator === 'auto' && progress === 'not-started'));
@@ -636,6 +871,216 @@ export function Step({
status: status ?? undefined,
});
+ // ======= ON-TRACK (EPS-aligned): indicator is a node on the connector =======
+ if (indicatorPosition === 'on-track') {
+ // Connector fill is purely progress-based (matches the separated bar):
+ // the segment before the indicator is "reached" once we're at/past this
+ // step; the segment after is filled only once this step is completed.
+ // `status` never recolors the connector — only the indicator.
+ const beforeFilled = step <= activeStep;
+ const afterFilled = step < activeStep;
+ const beforeSegStyle = beforeFilled
+ ? styles.lineFilled
+ : styles.lineUnfilled;
+ const afterSegStyle = afterFilled ? styles.lineFilled : styles.lineUnfilled;
+ const isFirst = step === 0;
+ // The last step has no next node, so its trailing segment is hidden.
+ const isLast = step === stepCount - 1;
+
+ const densitySpace =
+ density === 'compact'
+ ? spacingVars['--spacing-1']
+ : density === 'spacious'
+ ? spacingVars['--spacing-3']
+ : spacingVars['--spacing-2'];
+
+ const labelLineNode = (
+ <div
+ {...stylex.props(
+ isVertical ? styles.otLabelRowStart : styles.otLabelRowCenter,
+ )}>
+ <span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>
+ {isOptional && (
+ <>
+ <span {...stylex.props(styles.optionalDot)}>•</span>
+ <span {...stylex.props(styles.optionalText)}>Optional</span>
+ </>
+ )}
+ {endContent}
+ </div>
+ );
+
+ const otDescriptionNode =
+ description != null ? (
+ <span {...stylex.props(styles.description)}>{description}</span>
+ ) : null;
+
+ const otContentNode =
+ children != null ? (
+ <div
+ {...stylex.props(isVertical ? styles.otContentV : styles.otContentH)}>
+ {children}
+ </div>
+ ) : null;
+
+ if (isVertical) {
+ const inner = (
+ <>
+ <div
+ {...stylex.props(
+ styles.otIndicatorColV,
+ styles.otRailBridgeV(densitySpace),
+ )}>
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('step-connector'),
+ stylex.props(
+ styles.otSegBaseV,
+ styles.otSegLeadV(densitySpace),
+ beforeSegStyle,
+ isFirst && styles.otSegHidden,
+ ),
+ )}
+ />
+ {indicatorNode}
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('step-connector'),
+ stylex.props(
+ styles.otSegBaseV,
+ styles.otSegFlexV,
+ afterSegStyle,
+ isLast && styles.otSegHidden,
+ ),
+ )}
+ />
+ </div>
+ <div {...stylex.props(styles.otBodyV)}>
+ {labelLineNode}
+ {otDescriptionNode}
+ </div>
+ </>
+ );
+
+ return (
+ <li
+ ref={ref}
+ {...mergeProps(
+ stepThemeProps,
+ stylex.props(styles.otVerticalRoot, xstyle),
+ className,
+ style,
+ )}
+ aria-current={isActive ? 'step' : undefined}
+ data-testid={dataTestId}
+ {...rest}>
+ {isClickable ? (
+ <button
+ type="button"
+ onClick={handleClick}
+ aria-label={`Go to step ${step + 1}: ${label}`}
+ {...stylex.props(
+ styles.otInteractive,
+ styles.otRowWrap,
+ styles.otRowPadV(densitySpace),
+ styles.focusRing,
+ )}>
+ {inner}
+ </button>
+ ) : (
+ <div
+ {...stylex.props(
+ styles.otRowWrap,
+ styles.otRowPadV(densitySpace),
+ )}>
+ {inner}
+ </div>
+ )}
+ {otContentNode}
+ </li>
+ );
+ }
+
+ // Horizontal on-track
+ const innerH = (
+ <>
+ <div {...stylex.props(styles.otTrackRowH)}>
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('step-connector'),
+ stylex.props(
+ styles.otSegH,
+ beforeSegStyle,
+ isFirst && styles.otSegHidden,
+ ),
+ )}
+ />
+ {indicatorNode}
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('step-connector'),
+ stylex.props(
+ styles.otSegH,
+ afterSegStyle,
+ isLast && styles.otSegHidden,
+ ),
+ )}
+ />
+ </div>
+ <div
+ {...stylex.props(
+ styles.otLabelWrapH,
+ styles.otMarginTop(densitySpace),
+ )}>
+ {labelLineNode}
+ {otDescriptionNode}
+ </div>
+ </>
+ );
+
+ return (
+ <li
+ ref={ref}
+ {...mergeProps(
+ stepThemeProps,
+ stylex.props(styles.otHorizontalRoot, xstyle),
+ className,
+ style,
+ )}
+ aria-current={isActive ? 'step' : undefined}
+ data-testid={dataTestId}
+ {...rest}>
+ {isClickable ? (
+ <button
+ type="button"
+ onClick={handleClick}
+ aria-label={`Go to step ${step + 1}: ${label}`}
+ {...stylex.props(
+ styles.otInteractive,
+ styles.otColWrap,
+ styles.otPadBlock(densitySpace),
+ styles.focusRing,
+ )}>
+ {innerH}
+ </button>
+ ) : (
+ <div
+ {...stylex.props(
+ styles.otColWrap,
+ styles.otPadBlock(densitySpace),
+ )}>
+ {innerH}
+ </div>
+ )}
+ {otContentNode}
+ </li>
+ );
+ }
+
// ======= VERTICAL =======
if (isVertical) {
return (
@@ -656,8 +1101,7 @@ export function Step({
themeProps('step-bar'),
stylex.props(
styles.verticalBar,
- statusBarStyle ??
- (isBarFilled ? styles.barCompleted : styles.barIncomplete),
+ isBarFilled ? styles.barCompleted : styles.barIncomplete,
),
)}
aria-hidden="true"
@@ -715,8 +1159,7 @@ export function Step({
themeProps('step-bar'),
stylex.props(
styles.horizontalBar,
- statusBarStyle ??
- (isBarFilled ? styles.barCompleted : styles.barIncomplete),
+ isBarFilled ? styles.barCompleted : styles.barIncomplete,
),
)}
aria-hidden="true"
diff --git a/packages/lab/src/Stepper/StepStatus.ts b/packages/lab/src/Stepper/StepStatus.ts
index b188009453..14f4b7a721 100644
--- a/packages/lab/src/Stepper/StepStatus.ts
+++ b/packages/lab/src/Stepper/StepStatus.ts
@@ -8,19 +8,19 @@
*/
/**
- * Semantic color status for a step. Controls **color only** — it maps directly
- * onto the Astryx global semantic color tokens and does not change layout,
- * iconography, or behavior.
+ * Semantic status for a step, mapped directly onto the Astryx global semantic
+ * tokens. In the default `auto` indicator mode it sets both the indicator color
+ * and a matching glyph (see below); it never recolors the connector/track.
*
* Plain string values aligned with the global token semantics:
- * - 'accent' → `--color-accent` (default emphasis / in-progress)
- * - 'success' → `--color-success` (a positively-resolved step)
- * - 'warning' → `--color-warning` (needs attention)
- * - 'error' → `--color-error` (must be resolved)
+ * - 'accent' → `--color-accent` (default emphasis / in-progress; color only)
+ * - 'success' → `--color-success` (green check-circle glyph)
+ * - 'warning' → `--color-warning` (shared Input `warning` glyph)
+ * - 'error' → `--color-error` (shared Input `error` glyph)
*
* `status` is intentionally NOT a lifecycle enum (completed/active/etc.) — the
- * step's progress is derived from the parent's `activeStep`. Use `status` only
- * when you want to tint a step with a specific semantic color, e.g.
- * `status="error"`.
+ * step's progress is derived from the parent's `activeStep`. The current
+ * (in-progress) step always keeps its current-step indicator regardless of
+ * `status`.
*/
export type StepStatus = 'accent' | 'success' | 'warning' | 'error';
diff --git a/packages/lab/src/Stepper/Stepper.test.tsx b/packages/lab/src/Stepper/Stepper.test.tsx
index 3fa6bb6e6a..1320f96de1 100644
--- a/packages/lab/src/Stepper/Stepper.test.tsx
+++ b/packages/lab/src/Stepper/Stepper.test.tsx
@@ -216,6 +216,66 @@ describe('Stepper', () => {
);
});
+ it('keeps the progress bar progress-colored regardless of status, recoloring only the indicator', () => {
+ // Baseline: a completed step with no status.
+ const baseline = render(
+ <Stepper activeStep={1}>
+ <Step step={0} label="A" data-testid="base" />
+ </Stepper>,
+ );
+ const baseStep = baseline.getByTestId('base');
+ const baseBar = baseStep.querySelector('.astryx-step-bar') as HTMLElement;
+ const baseIndicator = baseStep.querySelector('svg')
+ ?.parentElement as HTMLElement;
+
+ // Same completed step, now with a semantic status.
+ const themed = render(
+ <Stepper activeStep={1}>
+ <Step step={0} label="A" status="error" data-testid="themed" />
+ </Stepper>,
+ );
+ const themedStep = themed.getByTestId('themed');
+ const themedBar = themedStep.querySelector(
+ '.astryx-step-bar',
+ ) as HTMLElement;
+ const themedIndicator = themedStep.querySelector('svg')
+ ?.parentElement as HTMLElement;
+
+ // Bar coloring must be identical — status must NOT recolor the bar
+ // (always --color-accent when filled / --color-border when incomplete).
+ expect(themedBar.className).toBe(baseBar.className);
+
+ // The indicator, however, must pick up the status color.
+ expect(themedIndicator.className).not.toBe(baseIndicator.className);
+ });
+
+ it('keeps an incomplete step bar border-colored regardless of status', () => {
+ // Baseline: a not-started step with no status.
+ const baseline = render(
+ <Stepper activeStep={0}>
+ <Step step={0} label="A" data-testid="base-active" />
+ <Step step={1} label="B" data-testid="base" />
+ </Stepper>,
+ );
+ const baseBar = baseline
+ .getByTestId('base')
+ .querySelector('.astryx-step-bar') as HTMLElement;
+
+ // Same not-started step, now with a semantic status.
+ const themed = render(
+ <Stepper activeStep={0}>
+ <Step step={0} label="A" data-testid="themed-active" />
+ <Step step={1} label="B" status="warning" data-testid="themed" />
+ </Stepper>,
+ );
+ const themedBar = themed
+ .getByTestId('themed')
+ .querySelector('.astryx-step-bar') as HTMLElement;
+
+ // Incomplete bar stays border-colored — status must not recolor it.
+ expect(themedBar.className).toBe(baseBar.className);
+ });
+
it('does not set a status data attribute when status is unset', () => {
render(
<Stepper activeStep={0}>
@@ -278,4 +338,78 @@ describe('Stepper', () => {
);
expect(screen.getByTestId('pay-icon')).toBeInTheDocument();
});
+
+ it('renders a distinct indicator glyph per status on non-current steps', () => {
+ // All steps completed (activeStep past them) so none is the current step.
+ render(
+ <Stepper activeStep={4}>
+ <Step step={0} label="A" status="success" data-testid="s-success" />
+ <Step step={1} label="B" status="warning" data-testid="s-warning" />
+ <Step step={2} label="C" status="error" data-testid="s-error" />
+ <Step step={3} label="D" data-testid="s-plain" />
+ </Stepper>,
+ );
+
+ const indicatorClass = (testid: string) =>
+ (
+ screen.getByTestId(testid).querySelector('svg')
+ ?.parentElement as HTMLElement
+ ).className;
+
+ // Each status renders an svg indicator (no number badge)...
+ expect(screen.getByTestId('s-success').querySelector('svg')).toBeTruthy();
+ expect(screen.getByTestId('s-warning').querySelector('svg')).toBeTruthy();
+ expect(screen.getByTestId('s-error').querySelector('svg')).toBeTruthy();
+
+ // ...and each status tints the indicator differently from the others and
+ // from the plain completed (accent) step.
+ const classes = new Set([
+ indicatorClass('s-success'),
+ indicatorClass('s-warning'),
+ indicatorClass('s-error'),
+ indicatorClass('s-plain'),
+ ]);
+ expect(classes.size).toBe(4);
+ });
+
+ it('lets the current step keep its ring indicator regardless of status', () => {
+ // A current step with no status.
+ const plain = render(
+ <Stepper activeStep={0}>
+ <Step step={0} label="A" data-testid="plain" />
+ </Stepper>,
+ );
+ const plainIndicator = (
+ plain.getByTestId('plain').querySelector('svg')
+ ?.parentElement as HTMLElement
+ ).className;
+
+ // The same current step, now with status="success": the indicator must be
+ // unchanged (the current-step ring replaces any status glyph).
+ const themed = render(
+ <Stepper activeStep={0}>
+ <Step step={0} label="A" status="success" data-testid="themed" />
+ </Stepper>,
+ );
+ const themedIndicator = (
+ themed.getByTestId('themed').querySelector('svg')
+ ?.parentElement as HTMLElement
+ ).className;
+
+ expect(themedIndicator).toBe(plainIndicator);
+ });
+
+ it('replaces the number badge with a status glyph on not-started steps', () => {
+ render(
+ <Stepper activeStep={0}>
+ <Step step={0} label="A" data-testid="current" />
+ <Step step={1} label="B" status="error" data-testid="future" />
+ </Stepper>,
+ );
+ const future = screen.getByTestId('future');
+ // The not-started step would normally show its number ("2"); with a status
+ // glyph it shows an icon instead.
+ expect(future.textContent).not.toContain('2');
+ expect(future.querySelector('svg')).toBeTruthy();
+ });
});
diff --git a/packages/lab/src/Stepper/Stepper.tsx b/packages/lab/src/Stepper/Stepper.tsx
index cf3c3b6f66..cc1ea6e5cf 100644
--- a/packages/lab/src/Stepper/Stepper.tsx
+++ b/packages/lab/src/Stepper/Stepper.tsx
@@ -16,15 +16,17 @@
* - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)
*/
-import {useMemo, type ReactNode} from 'react';
+import {Children, useMemo, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
+import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
import {mergeProps} from '@astryxdesign/core/utils';
import type {BaseProps} from '@astryxdesign/core';
import {themeProps} from '@astryxdesign/core/utils';
import {
StepperContext,
type StepperOrientation,
+ type StepperIndicatorPosition,
type StepperContextValue,
} from './StepperContext';
@@ -59,10 +61,17 @@ export interface StepperProps extends BaseProps<HTMLOListElement> {
* @default 'balanced'
*/
density?: 'compact' | 'balanced' | 'spacious';
+ /**
+ * Controls where each step's indicator sits relative to the connector track.
+ * - 'separated': indicator lives in the label row, distinct from the progress
+ * bar (the original Astryx layout).
+ * - 'on-track': indicator is slotted into the connector line as a node on the
+ * track (EPS-aligned design).
+ * @default 'separated'
+ */
+ indicatorPosition?: StepperIndicatorPosition;
}
-const STEP_GAP = '2px';
-
const styles = stylex.create({
root: {
display: 'flex',
@@ -74,11 +83,22 @@ const styles = stylex.create({
horizontal: {
flexDirection: 'row',
alignItems: 'flex-start',
- gap: STEP_GAP,
+ gap: spacingVars['--spacing-0-5'],
},
vertical: {
flexDirection: 'column',
- gap: STEP_GAP,
+ gap: spacingVars['--spacing-0-5'],
+ },
+ // On-track: steps must abut so their connector segments form one continuous
+ // line, so the inter-step gap collapses to zero.
+ horizontalOnTrack: {
+ flexDirection: 'row',
+ alignItems: 'flex-start',
+ gap: 0,
+ },
+ verticalOnTrack: {
+ flexDirection: 'column',
+ gap: 0,
},
});
@@ -87,8 +107,9 @@ const styles = stylex.create({
* with visual indicators for completed, active, and upcoming states.
*
* Each Step child must provide a `step` prop (zero-based index) so it
- * can derive its state from the parent's activeStep. CSS :last-child
- * handles connector hiding — no child introspection needed.
+ * can derive its state from the parent's activeStep. The parent supplies
+ * the total `stepCount` via context so the on-track layout can hide the
+ * trailing connector on the final step.
*
* Rendered as an ordered list (`<ol>`/`<li>`) rather than a `nav`
* landmark: a stepper communicates *progress through a sequence*, not a
@@ -113,12 +134,14 @@ export function Stepper({
onStepClick,
label = 'Progress',
density = 'balanced',
+ indicatorPosition = 'separated',
xstyle,
className,
style,
ref,
...rest
}: StepperProps) {
+ const stepCount = Children.count(children);
const ctxValue = useMemo<StepperContextValue>(
() => ({
activeStep,
@@ -126,10 +149,29 @@ export function Stepper({
isNonLinear: onStepClick != null,
onStepClick: onStepClick ?? null,
density,
+ indicatorPosition,
+ stepCount,
}),
- [activeStep, orientation, onStepClick, density],
+ [
+ activeStep,
+ orientation,
+ onStepClick,
+ density,
+ indicatorPosition,
+ stepCount,
+ ],
);
+ const isOnTrack = indicatorPosition === 'on-track';
+ const orientationStyle =
+ orientation === 'horizontal'
+ ? isOnTrack
+ ? styles.horizontalOnTrack
+ : styles.horizontal
+ : isOnTrack
+ ? styles.verticalOnTrack
+ : styles.vertical;
+
return (
<StepperContext value={ctxValue}>
<ol
@@ -137,12 +179,8 @@ export function Stepper({
aria-label={label}
{...rest}
{...mergeProps(
- themeProps('stepper', {orientation}),
- stylex.props(
- styles.root,
- orientation === 'horizontal' ? styles.horizontal : styles.vertical,
- xstyle,
- ),
+ themeProps('stepper', {orientation, indicatorPosition}),
+ stylex.props(styles.root, orientationStyle, xstyle),
className,
style,
)}>
diff --git a/packages/lab/src/Stepper/StepperContext.ts b/packages/lab/src/Stepper/StepperContext.ts
index 418440e8ff..0f5ddc274b 100644
--- a/packages/lab/src/Stepper/StepperContext.ts
+++ b/packages/lab/src/Stepper/StepperContext.ts
@@ -18,17 +18,32 @@ import {createContext, use} from 'react';
export type StepperOrientation = 'horizontal' | 'vertical';
export type StepperDensity = 'compact' | 'balanced' | 'spacious';
+/**
+ * Controls where each step's indicator sits relative to the connector track.
+ * - 'separated': indicator lives in the label row, distinct from the progress
+ * bar (Astryx's original layout).
+ * - 'on-track': indicator is slotted *into* the connector line as a node on the
+ * track, with the label beside (vertical) or below (horizontal). Aligns with
+ * the EPS stepper design.
+ */
+export type StepperIndicatorPosition = 'separated' | 'on-track';
+
export interface StepperContextValue {
activeStep: number;
orientation: StepperOrientation;
isNonLinear: boolean;
onStepClick: ((index: number) => void) | null;
density: StepperDensity;
+ /**
+ * Total number of Step children. Used by the on-track layout to hide the
+ * trailing connector segment on the last step (which otherwise has no next
+ * node to reach toward).
+ */
+ stepCount: number;
+ indicatorPosition: StepperIndicatorPosition;
}
-export const StepperContext = createContext<StepperContextValue | null>(
- null,
-);
+export const StepperContext = createContext<StepperContextValue | null>(null);
StepperContext.displayName = 'StepperContext';
export function useStepperContext(): StepperContextValue {
diff --git a/packages/lab/src/Stepper/index.ts b/packages/lab/src/Stepper/index.ts
index f71cc98979..80cf57b4c7 100644
--- a/packages/lab/src/Stepper/index.ts
+++ b/packages/lab/src/Stepper/index.ts
@@ -11,4 +11,7 @@ export type {StepProps, StepIndicatorPreset} from './Step';
export type {StepStatus} from './StepStatus';
export {useStepperContext} from './StepperContext';
-export type {StepperOrientation} from './StepperContext';
+export type {
+ StepperOrientation,
+ StepperIndicatorPosition,
+} from './StepperContext';