Skip to content

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

TypeScript

feat(Stepper): Visual overhaul — segmented bar, indicator modes, density (#2308)

Ernest9433d7f3d4a9
diff --git a/apps/storybook/stories/Stepper.stories.tsx b/apps/storybook/stories/Stepper.stories.tsx
index 63e0174bac..ef8a590ab9 100644
--- a/apps/storybook/stories/Stepper.stories.tsx
+++ b/apps/storybook/stories/Stepper.stories.tsx
@@ -6,230 +6,679 @@ import {XDSStepper, XDSStep} from '@xds/lab/Stepper';
import {XDSTextInput} from '@xds/core/TextInput';
import {XDSButton} from '@xds/core/Button';
import {XDSText} from '@xds/core/Text';
+import {XDSIcon} from '@xds/core/Icon';
const meta: Meta<typeof XDSStepper> = {
title: 'Lab/Stepper',
component: XDSStepper,
tags: ['autodocs'],
argTypes: {
- activeStep: {
- control: {type: 'number', min: 0, max: 4},
- description: 'Zero-based index of the active step',
- },
- orientation: {
- control: 'select',
- options: ['horizontal', 'vertical'],
- description: 'Layout direction',
- },
+ activeStep: {control: {type: 'number', min: 0, max: 5}},
+ orientation: {control: 'select', options: ['horizontal', 'vertical']},
+ density: {control: 'select', options: ['compact', 'balanced', 'spacious']},
},
};
export default meta;
type Story = StoryObj<typeof XDSStepper>;
+// ============================================================
+// DEFAULT (auto indicator)
+// ============================================================
+
export const Default: Story = {
- args: {activeStep: 1},
- render: args => (
- <XDSStepper activeStep={args.activeStep} orientation={args.orientation}>
- <XDSStep step={0} label="Account" />
- <XDSStep step={1} label="Profile" />
- <XDSStep step={2} label="Review" />
- </XDSStepper>
- ),
-};
-
-export const AllCompleted: Story = {
- render: () => (
- <XDSStepper activeStep={3}>
- <XDSStep step={0} label="Account" />
- <XDSStep step={1} label="Profile" />
- <XDSStep step={2} label="Review" />
- </XDSStepper>
- ),
-};
-
-export const FirstStep: Story = {
- render: () => (
- <XDSStepper activeStep={0}>
- <XDSStep step={0} label="Account" />
- <XDSStep step={1} label="Profile" />
- <XDSStep step={2} label="Review" />
- </XDSStepper>
- ),
-};
-
-export const WithDescriptions: Story = {
- render: () => (
- <XDSStepper activeStep={1}>
- <XDSStep step={0} label="Account" description="Create your account" />
- <XDSStep step={1} label="Profile" description="Set up your profile" />
- <XDSStep step={2} label="Review" description="Review and confirm" />
- </XDSStepper>
- ),
-};
-
-export const Vertical: Story = {
- render: () => (
- <div style={{maxWidth: 400}}>
- <XDSStepper activeStep={1} orientation="vertical">
- <XDSStep step={0} label="Account" description="Create your account" />
- <XDSStep step={1} label="Profile" description="Set up your profile" />
- <XDSStep step={2} label="Review" description="Review and confirm" />
- </XDSStepper>
- </div>
- ),
+ name: 'Default',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep
+ step={0}
+ label="Create workspace"
+ description="Name and configure your workspace"
+ />
+ <XDSStep
+ step={1}
+ label="Invite team members"
+ description="Add collaborators by email"
+ />
+ <XDSStep
+ step={2}
+ label="Set up integrations"
+ description="Connect Slack, GitHub, Jira"
+ />
+ <XDSStep
+ step={3}
+ label="Import data"
+ description="Bring in existing projects"
+ />
+ <XDSStep
+ step={4}
+ label="Launch"
+ description="Go live with your team"
+ />
+ </XDSStepper>
+ </div>
+ );
+ },
};
-export const NonLinear: Story = {
- name: 'Non-Linear (Clickable)',
+export const DefaultHorizontal: Story = {
+ name: 'Default — Horizontal',
render: () => {
- const [activeStep, setActiveStep] = useState(1);
+ const [active, setActive] = useState(1);
return (
- <XDSStepper activeStep={activeStep} onStepClick={setActiveStep}>
- <XDSStep step={0} label="Account" />
- <XDSStep step={1} label="Profile" />
- <XDSStep step={2} label="Review" />
- </XDSStepper>
+ <div style={{maxWidth: 700}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="horizontal"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Workspace" />
+ <XDSStep step={1} label="Team" />
+ <XDSStep step={2} label="Integrations" />
+ <XDSStep step={3} label="Import" />
+ <XDSStep step={4} label="Launch" />
+ </XDSStepper>
+ </div>
);
},
};
-export const WithError: Story = {
- render: () => (
- <XDSStepper activeStep={1}>
- <XDSStep step={0} label="Account" />
- <XDSStep step={1} label="Profile" hasError />
- <XDSStep step={2} label="Review" />
- </XDSStepper>
- ),
+// ============================================================
+// NUMBERED (always number — procedural flows)
+// ============================================================
+
+export const NumberedVertical: Story = {
+ name: 'Numbered — Deploy Pipeline',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep
+ step={0}
+ label="Push to main"
+ description="Merge your pull request"
+ indicator="number"
+ />
+ <XDSStep
+ step={1}
+ label="Run CI checks"
+ description="Lint, type-check, test"
+ indicator="number"
+ />
+ <XDSStep
+ step={2}
+ label="Build container"
+ description="Docker image to registry"
+ indicator="number"
+ />
+ <XDSStep
+ step={3}
+ label="Deploy to staging"
+ description="Verify in staging environment"
+ indicator="number"
+ />
+ <XDSStep
+ step={4}
+ label="Promote to production"
+ description="Canary → full rollout"
+ indicator="number"
+ />
+ </XDSStepper>
+ </div>
+ );
+ },
};
-export const WithDisabled: Story = {
- render: () => (
- <XDSStepper activeStep={1}>
- <XDSStep step={0} label="Account" />
- <XDSStep step={1} label="Profile" />
- <XDSStep step={2} label="Review" isDisabled />
- </XDSStepper>
- ),
+export const NumberedHorizontal: Story = {
+ name: 'Numbered — Horizontal Checkout',
+ render: () => {
+ const [active, setActive] = useState(1);
+ return (
+ <div style={{maxWidth: 600}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="horizontal"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Cart" indicator="number" />
+ <XDSStep step={1} label="Shipping" indicator="number" />
+ <XDSStep step={2} label="Payment" indicator="number" />
+ <XDSStep step={3} label="Confirm" indicator="number" />
+ </XDSStepper>
+ </div>
+ );
+ },
};
-export const FiveSteps: Story = {
- render: () => (
- <XDSStepper activeStep={2}>
- <XDSStep step={0} label="Cart" />
- <XDSStep step={1} label="Shipping" />
- <XDSStep step={2} label="Payment" />
- <XDSStep step={3} label="Review" />
- <XDSStep step={4} label="Confirm" />
- </XDSStepper>
- ),
+// ============================================================
+// STATUS (semantic color + generic icons — validation flows)
+//
+// `status` controls color only (accent/success/warning/error). The
+// indicator accepts any icon, so validation flows pass an explicit
+// <XDSIcon /> rather than relying on a fixed status-driven icon set.
+// ============================================================
+
+export const StatusVertical: Story = {
+ name: 'Status — Account Verification',
+ render: () => {
+ const [active, setActive] = useState(3);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep
+ step={0}
+ label="Email verified"
+ description="[email protected]"
+ status="success"
+ icon={<XDSIcon icon="check" size="sm" />}
+ />
+ <XDSStep
+ step={1}
+ label="Phone verified"
+ description="+1 (555) 012-3456"
+ status="success"
+ icon={<XDSIcon icon="check" size="sm" />}
+ />
+ <XDSStep
+ step={2}
+ label="Identity document"
+ description="Passport upload failed"
+ status="error"
+ icon={<XDSIcon icon="warning" size="sm" />}
+ />
+ <XDSStep
+ step={3}
+ label="Address verification"
+ description="Pending review"
+ status="accent"
+ />
+ <XDSStep
+ step={4}
+ label="Background check"
+ isOptional
+ description="Skipped"
+ />
+ <XDSStep step={5} label="Account activated" />
+ </XDSStepper>
+ </div>
+ );
+ },
};
-export const VerticalNonLinear: Story = {
- name: 'Vertical Non-Linear',
+export const StatusAllStates: Story = {
+ name: 'Status — Semantic Colors Reference',
render: () => {
- const [activeStep, setActiveStep] = useState(2);
+ const [active, setActive] = useState(1);
return (
<div style={{maxWidth: 400}}>
<XDSStepper
- activeStep={activeStep}
+ activeStep={active}
orientation="vertical"
- onStepClick={setActiveStep}>
- <XDSStep step={0} label="Account" description="Create your account" />
- <XDSStep step={1} label="Profile" description="Set up your profile" />
- <XDSStep step={2} label="Review" description="Review and confirm" />
- <XDSStep step={3} label="Done" description="All finished!" />
+ onStepClick={setActive}>
+ <XDSStep
+ step={0}
+ label="Accent"
+ description="--color-accent"
+ status="accent"
+ />
+ <XDSStep
+ step={1}
+ label="Success"
+ description="--color-success"
+ status="success"
+ icon={<XDSIcon icon="check" size="sm" />}
+ />
+ <XDSStep
+ step={2}
+ label="Warning"
+ description="--color-warning"
+ status="warning"
+ icon={<XDSIcon icon="warning" size="sm" />}
+ />
+ <XDSStep
+ step={3}
+ label="Error"
+ description="--color-error"
+ status="error"
+ icon={<XDSIcon icon="warning" size="sm" />}
+ />
+ <XDSStep
+ step={4}
+ label="Default (no status)"
+ description="progress-derived color"
+ />
+ </XDSStepper>
+ </div>
+ );
+ },
+};
+
+// ============================================================
+// MINIMAL (no indicator — content-focused)
+// ============================================================
+
+export const MinimalVertical: Story = {
+ name: 'Minimal — Interview Process',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep
+ step={0}
+ label="Phone screen"
+ description="30 min with recruiter"
+ indicator="none"
+ />
+ <XDSStep
+ step={1}
+ label="Technical interview"
+ description="1 hour coding session"
+ indicator="none"
+ />
+ <XDSStep
+ step={2}
+ label="System design"
+ description="45 min whiteboard"
+ indicator="none"
+ />
+ <XDSStep
+ step={3}
+ label="Team match"
+ description="Meet potential teammates"
+ indicator="none"
+ />
+ <XDSStep step={4} label="Offer" indicator="none" />
+ </XDSStepper>
+ </div>
+ );
+ },
+};
+
+export const MinimalHorizontal: Story = {
+ name: 'Minimal — Video Upload',
+ render: () => {
+ const [active, setActive] = useState(1);
+ return (
+ <div style={{maxWidth: 500}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="horizontal"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Upload" indicator="none" />
+ <XDSStep step={1} label="Details" indicator="none" />
+ <XDSStep step={2} label="Audience" indicator="none" />
+ <XDSStep step={3} label="Publish" indicator="none" />
</XDSStepper>
</div>
);
},
};
-export const VerticalWithContent: Story = {
- name: 'Vertical with Content',
+// ============================================================
+// INDICATOR COMPARISON
+// ============================================================
+
+export const IndicatorComparison: Story = {
+ name: 'Indicator Modes — Side by Side',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{display: 'flex', gap: 48}}>
+ <div style={{maxWidth: 280}}>
+ <XDSText type="label">Auto (default)</XDSText>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Account" />
+ <XDSStep step={1} label="Profile" />
+ <XDSStep step={2} label="Settings" />
+ <XDSStep step={3} label="Review" />
+ <XDSStep step={4} label="Done" />
+ </XDSStepper>
+ </div>
+ <div style={{maxWidth: 280}}>
+ <XDSText type="label">Number</XDSText>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Account" indicator="number" />
+ <XDSStep step={1} label="Profile" indicator="number" />
+ <XDSStep step={2} label="Settings" indicator="number" />
+ <XDSStep step={3} label="Review" indicator="number" />
+ <XDSStep step={4} label="Done" indicator="number" />
+ </XDSStepper>
+ </div>
+ <div style={{maxWidth: 280}}>
+ <XDSText type="label">Custom icon</XDSText>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep
+ step={0}
+ label="Account"
+ icon={<XDSIcon icon="info" size="sm" />}
+ />
+ <XDSStep
+ step={1}
+ label="Profile"
+ icon={<XDSIcon icon="search" size="sm" />}
+ />
+ <XDSStep
+ step={2}
+ label="Settings"
+ icon={<XDSIcon icon="wrench" size="sm" />}
+ />
+ <XDSStep
+ step={3}
+ label="Review"
+ icon={<XDSIcon icon="clock" size="sm" />}
+ />
+ <XDSStep
+ step={4}
+ label="Done"
+ icon={<XDSIcon icon="check" size="sm" />}
+ />
+ </XDSStepper>
+ </div>
+ <div style={{maxWidth: 280}}>
+ <XDSText type="label">None</XDSText>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Account" indicator="none" />
+ <XDSStep step={1} label="Profile" indicator="none" />
+ <XDSStep step={2} label="Settings" indicator="none" />
+ <XDSStep step={3} label="Review" indicator="none" />
+ <XDSStep step={4} label="Done" indicator="none" />
+ </XDSStepper>
+ </div>
+ </div>
+ );
+ },
+};
+
+// ============================================================
+// WITH CONTENT SLOT
+// ============================================================
+
+export const WithContentSlot: Story = {
+ name: 'With Content — Multi-Step Form',
render: () => {
- const [activeStep, setActiveStep] = useState(1);
+ const [active, setActive] = useState(0);
return (
<div style={{maxWidth: 480}}>
- <XDSStepper activeStep={activeStep} orientation="vertical">
- <XDSStep step={0} label="Account" description="Create your account">
- {activeStep === 0 && (
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Project details" indicator="number">
+ {active === 0 && (
<div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
<XDSTextInput
- label="Email"
- placeholder="[email protected]"
+ label="Project name"
+ placeholder="My awesome project"
value=""
/>
<XDSTextInput
- label="Password"
- placeholder="••••••••"
+ label="Repository URL"
+ placeholder="https://github.com/..."
value=""
/>
<div>
<XDSButton
label="Continue"
variant="primary"
- onClick={() => setActiveStep(1)}
+ onClick={() => setActive(1)}
/>
</div>
</div>
)}
</XDSStep>
- <XDSStep
- step={1}
- label="Profile"
- description="Tell us about yourself">
- {activeStep === 1 && (
+ <XDSStep step={1} label="Environment" indicator="number">
+ {active === 1 && (
<div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <XDSTextInput label="Node version" placeholder="20" value="" />
<XDSTextInput
- label="Full name"
- placeholder="Jane Doe"
+ label="Build command"
+ placeholder="npm run build"
value=""
/>
- <XDSTextInput
- label="Company"
- placeholder="Acme Inc."
- value=""
- />
- <XDSTextInput label="Role" placeholder="Engineer" value="" />
<div style={{display: 'flex', gap: 8}}>
<XDSButton
label="Back"
variant="secondary"
- onClick={() => setActiveStep(0)}
+ onClick={() => setActive(0)}
/>
<XDSButton
label="Continue"
variant="primary"
- onClick={() => setActiveStep(2)}
+ onClick={() => setActive(2)}
/>
</div>
</div>
)}
</XDSStep>
- <XDSStep step={2} label="Review" description="Confirm your details">
- {activeStep === 2 && (
+ <XDSStep step={2} label="Deploy" indicator="number">
+ {active === 2 && (
<div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
<XDSText type="body">
- Review your account details and click Finish to complete
- setup.
+ Ready to deploy. This will create a production build and push
+ to your configured hosting.
</XDSText>
<div style={{display: 'flex', gap: 8}}>
<XDSButton
label="Back"
variant="secondary"
- onClick={() => setActiveStep(1)}
+ onClick={() => setActive(1)}
/>
<XDSButton
- label="Finish"
+ label="Deploy now"
variant="primary"
- onClick={() => setActiveStep(3)}
+ onClick={() => setActive(3)}
/>
</div>
</div>
)}
</XDSStep>
+ <XDSStep step={3} label="Done" indicator="number" />
+ </XDSStepper>
+ </div>
+ );
+ },
+};
+
+// ============================================================
+// DENSITY
+// ============================================================
+
+export const DensityComparison: Story = {
+ name: 'Density — Compact / Balanced / Spacious',
+ render: () => {
+ const [active, setActive] = useState(1);
+ return (
+ <div style={{display: 'flex', gap: 48}}>
+ <div style={{maxWidth: 250}}>
+ <XDSText type="label">Compact</XDSText>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}
+ density="compact">
+ <XDSStep step={0} label="Account" indicator="number" />
+ <XDSStep step={1} label="Profile" indicator="number" />
+ <XDSStep step={2} label="Payment" indicator="number" />
+ <XDSStep step={3} label="Review" indicator="number" />
+ </XDSStepper>
+ </div>
+ <div style={{maxWidth: 250}}>
+ <XDSText type="label">Balanced</XDSText>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}
+ density="balanced">
+ <XDSStep step={0} label="Account" indicator="number" />
+ <XDSStep step={1} label="Profile" indicator="number" />
+ <XDSStep step={2} label="Payment" indicator="number" />
+ <XDSStep step={3} label="Review" indicator="number" />
+ </XDSStepper>
+ </div>
+ <div style={{maxWidth: 250}}>
+ <XDSText type="label">Spacious</XDSText>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}
+ density="spacious">
+ <XDSStep step={0} label="Account" indicator="number" />
+ <XDSStep step={1} label="Profile" indicator="number" />
+ <XDSStep step={2} label="Payment" indicator="number" />
+ <XDSStep step={3} label="Review" indicator="number" />
+ </XDSStepper>
+ </div>
+ </div>
+ );
+ },
+};
+
+// ============================================================
+// EDGE CASES
+// ============================================================
+
+export const TwoSteps: Story = {
+ name: 'Edge — Two Steps',
+ render: () => {
+ const [active, setActive] = useState(0);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="horizontal"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Before" />
+ <XDSStep step={1} label="After" />
+ </XDSStepper>
+ </div>
+ );
+ },
+};
+
+export const ManySteps: Story = {
+ name: 'Edge — Seven Steps (Horizontal)',
+ render: () => {
+ const [active, setActive] = useState(3);
+ return (
+ <XDSStepper
+ activeStep={active}
+ orientation="horizontal"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Idea" indicator="number" />
+ <XDSStep step={1} label="Design" indicator="number" />
+ <XDSStep step={2} label="Build" indicator="number" />
+ <XDSStep step={3} label="Test" indicator="number" />
+ <XDSStep step={4} label="Review" indicator="number" />
+ <XDSStep step={5} label="Deploy" indicator="number" />
+ <XDSStep step={6} label="Monitor" indicator="number" />
+ </XDSStepper>
+ );
+ },
+};
+
+export const DisabledSteps: Story = {
+ name: 'Edge — Disabled Steps',
+ render: () => {
+ const [active, setActive] = useState(1);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Basic info" />
+ <XDSStep step={1} label="Permissions" />
+ <XDSStep
+ step={2}
+ label="Admin settings"
+ description="Requires admin role"
+ isDisabled
+ />
+ <XDSStep step={3} label="Confirm" />
+ </XDSStepper>
+ </div>
+ );
+ },
+};
+
+export const OptionalSteps: Story = {
+ name: 'Edge — Optional + Skipped',
+ render: () => {
+ const [active, setActive] = useState(3);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep step={0} label="Basic profile" />
+ <XDSStep
+ step={1}
+ label="Profile photo"
+ isOptional
+ description="Skipped"
+ />
+ <XDSStep step={2} label="Connect socials" isOptional />
+ <XDSStep step={3} label="Preferences" />
+ <XDSStep step={4} label="All done" />
+ </XDSStepper>
+ </div>
+ );
+ },
+};
+
+export const LongLabels: Story = {
+ name: 'Edge — Long Labels & Descriptions',
+ render: () => {
+ const [active, setActive] = useState(1);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSStepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <XDSStep
+ step={0}
+ label="Configure your development environment"
+ description="Install dependencies, set up local database, configure environment variables"
+ />
+ <XDSStep
+ step={1}
+ label="Create initial data migration"
+ description="Define schema, seed data, and run migrations against staging"
+ />
+ <XDSStep
+ step={2}
+ label="Submit for code review"
+ description="Open pull request and address reviewer feedback"
+ />
</XDSStepper>
</div>
);
diff --git a/packages/lab/src/Stepper/Stepper.doc.mjs b/packages/lab/src/Stepper/Stepper.doc.mjs
index a1408acf7f..cb4bd1d1d6 100644
--- a/packages/lab/src/Stepper/Stepper.doc.mjs
+++ b/packages/lab/src/Stepper/Stepper.doc.mjs
@@ -1,6 +1,6 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
export const docs = {
name: 'Stepper',
@@ -10,17 +10,18 @@ export const docs = {
keywords: ['stepper', 'steps', 'wizard', 'workflow', 'progress', 'multi-step', 'form wizard', 'onboarding'],
usage: {
description:
- 'Steppers display progress through a sequence of logical and numbered steps. Use them for multi-step workflows like forms, onboarding flows, or checkout processes where users need to see their position and the steps ahead.',
+ 'Steppers display progress through a sequence of logical and numbered steps. Use them for multi-step workflows like forms, onboarding flows, or checkout processes where users need to see their position and the steps ahead. Rendered as an ordered list (not a navigation landmark).',
bestPractices: [
{guidance: true, description: 'Keep step labels short and descriptive: "Payment" not "Enter your payment information".'},
{guidance: true, description: 'Use the vertical orientation for narrow containers or when steps have longer descriptions.'},
{guidance: true, description: 'Provide onStepClick for non-linear workflows where users may need to revisit earlier steps.'},
+ {guidance: true, description: 'Use status only to apply a semantic color (accent/success/warning/error); pass a custom icon for richer indicators.'},
{guidance: false, description: 'Use a stepper for fewer than 3 steps; a simple heading or progress bar works better.'},
{guidance: false, description: 'Use more than 7 steps; consider grouping related steps or using a different pattern.'},
],
anatomy: [
- {name: 'Step indicator', required: true, description: 'A numbered circle showing the step position. Shows a checkmark when completed.'},
- {name: 'Connector', required: true, description: 'A line between step indicators. Filled when the preceding step is completed.'},
+ {name: 'Progress bar', required: true, description: 'A 4px segmented bar per step. Filled for completed and active steps.'},
+ {name: 'Indicator', required: false, description: 'A numbered badge, a check, or any custom icon. Controlled via the indicator and icon props.'},
{name: 'Label', required: true, description: 'Text identifying the step.'},
{name: 'Description', required: false, description: 'Supporting text below the label with additional context.'},
],
@@ -28,9 +29,8 @@ export const docs = {
theming: {
targets: [
{className: 'xds-stepper', visualProps: ['orientation']},
- {className: 'xds-step', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
- {className: 'xds-step-indicator', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
- {className: 'xds-step-connector'},
+ {className: 'xds-step', visualProps: ['progress', 'status']},
+ {className: 'xds-step-bar'},
],
},
components: [
@@ -38,7 +38,7 @@ export const docs = {
name: 'XDSStepper',
displayName: 'Stepper',
description:
- 'Container component that manages step state and renders steps in horizontal or vertical orientation.',
+ 'Container component that manages step state and renders steps in horizontal or vertical orientation as an ordered list.',
props: [
{
name: 'activeStep',
@@ -61,14 +61,20 @@ export const docs = {
{
name: 'onStepClick',
type: '(index: number) => void',
- description: 'Called when a step indicator is clicked. Enables non-linear navigation. Completed and active steps become clickable.',
+ description: 'Called when a step is clicked. Enables non-linear navigation. All non-disabled steps become clickable, including not-started steps.',
},
{
name: 'label',
type: 'string',
- description: 'Accessible label for the stepper navigation landmark.',
+ description: 'Accessible label describing the set of steps (applied to the ordered list).',
default: "'Progress'",
},
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Controls the padding of all steps.',
+ default: "'balanced'",
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -80,18 +86,18 @@ export const docs = {
name: 'XDSStep',
displayName: 'Step',
description:
- 'Individual step within a stepper. Renders a numbered indicator, connector line, and label with optional description.',
+ 'Individual step within a stepper. Renders a progress-bar segment, an indicator, and a label with optional description.',
props: [
{
name: 'step',
type: 'number',
- description: 'Zero-based index of this step. Used to determine active/completed state relative to the parent activeStep.',
+ description: 'Zero-based index of this step. Used to derive progress (completed/active/not-started) relative to the parent activeStep.',
required: true,
},
{
name: 'label',
type: 'string',
- description: 'Step label text displayed below (horizontal) or beside (vertical) the indicator.',
+ description: 'Step label text.',
required: true,
},
{
@@ -107,13 +113,19 @@ export const docs = {
{
name: 'icon',
type: 'ReactNode',
- description: 'Custom icon to replace the step number or checkmark indicator.',
+ description: 'Custom icon rendered inside the indicator. Accepts any node (e.g. an XDSIcon). Takes precedence over the built-in number/check.',
slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
- name: 'isCompleted',
- type: 'boolean',
- description: 'Override the auto-computed completed state. By default, steps before activeStep are completed.',
+ name: 'status',
+ type: "'accent' | 'success' | 'warning' | 'error'",
+ description: 'Semantic color for the step. Controls color only and maps to the global XDS semantic tokens. Leave unset for the progress-derived default coloring.',
+ },
+ {
+ name: 'indicator',
+ type: "'auto' | 'number' | 'none' | ReactNode",
+ description: "What to show as the step indicator. 'auto' shows a number until completed then a check, 'number' always shows a numbered badge, 'none' hides it, or pass any ReactNode for a custom indicator.",
+ default: "'auto'",
},
{
name: 'isDisabled',
@@ -122,11 +134,21 @@ export const docs = {
default: 'false',
},
{
- name: 'hasError',
+ name: 'isOptional',
type: 'boolean',
- description: 'Shows an error state on the step indicator and label.',
+ description: 'Marks the step as optional, appending an "Optional" affordance after the label.',
default: 'false',
},
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Trailing content rendered at the end of the label row.',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Controls vertical padding of the step. Falls back to the stepper-level density when unset.',
+ },
],
},
],
@@ -137,7 +159,7 @@ export const docs = {
},
};
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('../../core/src/docs-types').TranslationDoc} */
export const docsDense = {
description: 'numbered step sequence for multi-step workflows',
usage: {
@@ -159,28 +181,32 @@ export const docsDense = {
children: 'XDSStep elements',
orientation: 'horizontal or vertical layout',
onStepClick: 'enables non-linear navigation',
- label: 'nav landmark aria-label',
+ label: 'ordered-list aria-label',
+ density: 'padding of all steps',
xstyle: 'StyleX layout customization',
},
},
{
name: 'XDSStep',
displayName: 'Step',
- description: 'individual step w/ indicator, connector, label',
+ description: 'individual step w/ progress bar, indicator, label',
propDescriptions: {
step: 'zero-based step index',
label: 'step label text',
description: 'supporting text below label',
- icon: 'custom icon replacing number/check',
- isCompleted: 'override auto-completed state',
+ icon: 'custom icon for the indicator',
+ status: 'semantic color: accent/success/warning/error (color only)',
+ indicator: "'auto' | 'number' | 'none' | custom node",
isDisabled: 'disable interaction',
- hasError: 'error state on indicator and label',
+ isOptional: 'append Optional affordance',
+ endContent: 'trailing content in label row',
+ density: 'per-step padding override',
},
},
],
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
export const docsZh = {
name: 'Stepper',
displayName: 'Stepper',
@@ -199,9 +225,8 @@ export const docsZh = {
theming: {
targets: [
{className: 'xds-stepper', visualProps: ['orientation']},
- {className: 'xds-step', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
- {className: 'xds-step-indicator', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},
- {className: 'xds-step-connector'},
+ {className: 'xds-step', visualProps: ['progress', 'status']},
+ {className: 'xds-step-bar'},
],
},
components: [
@@ -213,23 +238,27 @@ export const docsZh = {
{name: 'activeStep', type: 'number', description: '当前活动步骤的从零开始的索引。', required: true},
{name: 'children', type: 'ReactNode', description: '要在步骤器中渲染的 XDSStep 元素。', required: true},
{name: 'orientation', type: "'horizontal' | 'vertical'", description: '步骤器的布局方向。', default: "'horizontal'"},
- {name: 'onStepClick', type: '(index: number) => void', description: '点击步骤指示器时调用。启用非线性导航。'},
- {name: 'label', type: 'string', description: '步骤器导航地标的无障碍标签。', default: "'Progress'"},
+ {name: 'onStepClick', type: '(index: number) => void', description: '点击步骤时调用。启用非线性导航。'},
+ {name: 'label', type: 'string', description: '有序列表的无障碍标签。', default: "'Progress'"},
+ {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: '控制所有步骤的内边距。', default: "'balanced'"},
{name: 'xstyle', type: 'StyleXStyles', description: '用于布局自定义的 StyleX 样式。'},
],
},
{
name: 'XDSStep',
displayName: 'Step',
- description: '步骤器中的单个步骤。渲染编号指示器、连接线和带可选描述的标签。',
+ description: '步骤器中的单个步骤。渲染进度条、指示器和带可选描述的标签。',
props: [
{name: 'step', type: 'number', description: '此步骤的从零开始的索引。', required: true},
{name: 'label', type: 'string', description: '步骤标签文本。', required: true},
{name: 'description', type: 'string', description: '标签下方的可选描述。'},
- {name: 'icon', type: 'ReactNode', description: '替换步骤编号或勾选指示器的自定义图标。'},
- {name: 'isCompleted', type: 'boolean', description: '覆盖自动计算的完成状态。'},
+ {name: 'icon', type: 'ReactNode', description: '指示器中的自定义图标。'},
+ {name: 'status', type: "'accent' | 'success' | 'warning' | 'error'", description: '步骤的语义颜色,仅控制颜色。'},
+ {name: 'indicator', type: "'auto' | 'number' | 'none' | ReactNode", description: '指示器显示内容。', default: "'auto'"},
{name: 'isDisabled', type: 'boolean', description: '禁用交互并使步骤指示器和标签变暗。', default: 'false'},
- {name: 'hasError', type: 'boolean', description: '在步骤指示器和标签上显示错误状态。', default: 'false'},
+ {name: 'isOptional', type: 'boolean', description: '标记步骤为可选。', default: 'false'},
+ {name: 'endContent', type: 'ReactNode', description: '标签行末尾的尾随内容。'},
+ {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: '步骤的内边距覆盖。'},
],
},
],
diff --git a/packages/lab/src/Stepper/XDSStep.tsx b/packages/lab/src/Stepper/XDSStep.tsx
index 3e6e4670a4..15f99d7e1e 100644
--- a/packages/lab/src/Stepper/XDSStep.tsx
+++ b/packages/lab/src/Stepper/XDSStep.tsx
@@ -9,14 +9,14 @@
* @position Individual step item; used inside XDSStepper
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Stepper/Stepper.doc.mjs
- * - /packages/core/src/Stepper/XDSStepper.test.tsx
- * - /packages/core/src/Stepper/index.ts
+ * - /packages/lab/src/Stepper/Stepper.doc.mjs
+ * - /packages/lab/src/Stepper/XDSStepper.test.tsx
+ * - /packages/lab/src/Stepper/index.ts
* - /apps/storybook/stories/Stepper.stories.tsx
* - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)
*/
-import type {ReactNode} from 'react';
+import {type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
@@ -29,17 +29,28 @@ import {
easeVars,
} from '@xds/core/theme/tokens.stylex';
import {mergeProps} from '@xds/core/utils';
-import {XDSIcon} from '@xds/core/Icon';
import type {XDSBaseProps} from '@xds/core';
import {useXDSStepperContext} from './XDSStepperContext';
import {xdsThemeProps} from '../../../core/src/utils/xdsThemeProps';
+import type {XDSStepStatus} from './XDSStepStatus';
-export interface XDSStepProps extends XDSBaseProps<HTMLDivElement> {
+/**
+ * Built-in indicator presets. Anything other than these strings passed to
+ * `indicator` is treated as a custom ReactNode (e.g. an `<XDSIcon />`).
+ * - 'auto': numbered badge for not-yet-reached steps, a check once completed
+ * (default)
+ * - 'number': always a numbered badge
+ * - 'none': no indicator — just the progress bar and label
+ */
+export type XDSStepIndicatorPreset = 'auto' | 'number' | 'none';
+export type XDSStepDensity = 'compact' | 'balanced' | 'spacious';
+
+export interface XDSStepProps extends XDSBaseProps<HTMLLIElement> {
/** Ref forwarded to the root element */
- ref?: React.Ref<HTMLDivElement>;
+ ref?: React.Ref<HTMLLIElement>;
/**
- * Zero-based index of this step. Used to determine active/completed state
- * relative to the parent's activeStep.
+ * Zero-based index of this step. Used to derive progress (completed /
+ * active / not-started) relative to the parent's `activeStep`.
*/
step: number;
/**
@@ -56,249 +67,372 @@ export interface XDSStepProps extends XDSBaseProps<HTMLDivElement> {
*/
children?: ReactNode;
/**
- * Custom icon to replace the step number/check indicator.
+ * Custom icon rendered inside the indicator. Accepts any ReactNode (for
+ * example an `<XDSIcon />`). Equivalent to passing the node directly to
+ * `indicator`; takes precedence over the built-in number/check.
*/
icon?: ReactNode;
/**
- * Override the auto-computed completed state.
- * By default, steps before activeStep are completed.
+ * Semantic color for the step. Controls **color only** and maps to the
+ * global XDS semantic tokens (`accent`, `success`, `warning`, `error`).
+ * Leave unset to use the progress-derived default coloring.
*/
- isCompleted?: boolean;
+ status?: XDSStepStatus;
/**
* Disable interaction for this step.
* @default false
*/
isDisabled?: boolean;
/**
- * Optional error state for this step.
+ * Marks the step as optional, appending an "Optional" affordance after the
+ * label.
* @default false
*/
- hasError?: boolean;
+ isOptional?: boolean;
+ /**
+ * Trailing content rendered at the end of the label row (e.g. a timestamp
+ * or status chip).
+ */
+ endContent?: ReactNode;
+ /**
+ * What to show as the step indicator. Accepts a preset string or any
+ * ReactNode:
+ * - 'auto': numbered badge until completed, then a check (default)
+ * - 'number': always a numbered badge
+ * - 'none': no indicator, just the bar + label
+ * - ReactNode: any custom icon or element to render as the indicator
+ * @default 'auto'
+ */
+ indicator?: XDSStepIndicatorPreset | ReactNode;
+ /**
+ * Controls vertical padding of the step. Falls back to the stepper-level
+ * density when unset.
+ * - 'compact': minimal padding (4px block)
+ * - 'balanced': default (8px block)
+ * - 'spacious': generous (12px block, 12px inline)
+ */
+ density?: XDSStepDensity;
+}
+
+// --- Default progress icons (16px) ---
+
+/** Filled check — shown for completed steps 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"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
}
+/** Filled dot in a ring — shown for the active step in 'auto' mode. */
+function CurrentIcon() {
+ return (
+ <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+ <circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="2" />
+ <circle cx="8" cy="8" r="4" fill="currentColor" />
+ </svg>
+ );
+}
+
+// --- Styles ---
+
+const BAR_WIDTH = '4px';
+const ICON_SIZE = spacingVars['--spacing-4'];
+const NUMBER_SIZE = spacingVars['--spacing-5'];
+
const styles = stylex.create({
- // Horizontal layout
- horizontalRoot: {
+ // ===================== VERTICAL LAYOUT =====================
+ verticalRoot: {
display: 'flex',
flexDirection: 'row',
- alignItems: 'flex-start',
- flex: {
- default: 1,
- ':last-child': 'none',
- },
- '--_show-connector': {
- default: 'flex',
- ':last-child': 'none',
- },
+ alignItems: 'stretch',
position: 'relative',
+ gap: spacingVars['--spacing-0-5'],
+ },
+
+ // 4px progress bar segment
+ verticalBar: {
+ width: BAR_WIDTH,
+ borderRadius: radiusVars['--radius-full'],
+ flexShrink: 0,
+ alignSelf: 'stretch',
+ },
+ barCompleted: {
+ backgroundColor: colorVars['--color-accent'],
+ },
+ barIncomplete: {
+ backgroundColor: colorVars['--color-border'],
+ },
+ // Semantic status overrides for the bar — color only.
+ barAccent: {
+ backgroundColor: colorVars['--color-accent'],
},
- horizontalContent: {
+ barSuccess: {
+ backgroundColor: colorVars['--color-success'],
+ },
+ barWarning: {
+ backgroundColor: colorVars['--color-warning'],
+ },
+ barError: {
+ backgroundColor: colorVars['--color-error'],
+ },
+
+ // Step body — the selectable area
+ verticalBody: {
display: 'flex',
flexDirection: 'column',
- alignItems: 'center',
- position: 'relative',
- zIndex: 1,
+ flex: 1,
},
- horizontalConnector: {
+
+ // ===================== HORIZONTAL LAYOUT =====================
+ horizontalStep: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'flex-start',
flex: 1,
- display: 'var(--_show-connector)',
- alignItems: 'center',
- paddingInline: spacingVars['--spacing-2'],
- minWidth: spacingVars['--spacing-6'],
- height: spacingVars['--spacing-7'],
+ // density padding applied via density styles below
},
- horizontalConnectorLine: {
- height: spacingVars['--spacing-0-5'],
+
+ // Full-width progress bar segment sitting above each horizontal step.
+ // Each step owns its own segment (filled from its derived progress) so the
+ // parent never has to introspect children to build the bar.
+ horizontalBar: {
width: '100%',
+ height: BAR_WIDTH,
borderRadius: radiusVars['--radius-full'],
- transitionProperty: 'background-color',
- transitionDuration: durationVars['--duration-fast'],
- transitionTimingFunction: easeVars['--ease-standard'],
+ flexShrink: 0,
+ marginBlockEnd: spacingVars['--spacing-0-5'],
},
- // Vertical layout
- verticalRoot: {
+ // ===================== SHARED =====================
+
+ // Icon + Label in one row
+ iconLabelRow: {
display: 'flex',
flexDirection: 'row',
- alignItems: 'stretch',
- position: 'relative',
- minHeight: spacingVars['--spacing-12'],
- '--_show-connector': {
- default: 'flex',
- ':last-child': 'none',
- },
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
},
- verticalIndicatorColumn: {
+
+ // Indicator icon container
+ icon: {
display: 'flex',
- flexDirection: 'column',
alignItems: 'center',
- width: spacingVars['--spacing-7'],
+ justifyContent: 'center',
+ width: ICON_SIZE,
+ height: ICON_SIZE,
flexShrink: 0,
},
- verticalConnector: {
- flex: 1,
- display: 'var(--_show-connector)',
- justifyContent: 'center',
- paddingBlock: spacingVars['--spacing-1'],
+ iconCompleted: {
+ color: colorVars['--color-accent'],
},
- verticalConnectorLine: {
- width: spacingVars['--spacing-0-5'],
- height: '100%',
- borderRadius: radiusVars['--radius-full'],
- transitionProperty: 'background-color',
- transitionDuration: durationVars['--duration-fast'],
- transitionTimingFunction: easeVars['--ease-standard'],
+ iconInProgress: {
+ color: colorVars['--color-accent'],
},
- verticalContent: {
- display: 'flex',
- flexDirection: 'column',
- paddingInlineStart: spacingVars['--spacing-3'],
- paddingBlockEnd: spacingVars['--spacing-6'],
- flex: 1,
+ iconNotStarted: {
+ color: colorVars['--color-icon-secondary'],
+ },
+ iconDisabled: {
+ color: colorVars['--color-icon-disabled'],
+ opacity: 0.5,
+ },
+ // Semantic status overrides for the icon — color only.
+ iconAccent: {
+ color: colorVars['--color-accent'],
},
- verticalLastContent: {
- paddingBlockEnd: spacingVars['--spacing-0'],
+ iconSuccess: {
+ color: colorVars['--color-success'],
+ },
+ iconWarning: {
+ color: colorVars['--color-warning'],
+ },
+ iconError: {
+ color: colorVars['--color-error'],
},
- // Indicator circle
- indicator: {
- display: 'flex',
- alignItems: 'center',
- justifyContent: 'center',
- width: spacingVars['--spacing-7'],
- height: spacingVars['--spacing-7'],
+ // Number badge
+ numberBadge: {
+ display: 'grid',
+ placeItems: 'center',
+ width: NUMBER_SIZE,
+ height: NUMBER_SIZE,
borderRadius: radiusVars['--radius-full'],
- fontSize: typeScaleVars['--text-supporting-size'],
+ // 10px is below the smallest type token (--text-supporting-size, 12px);
+ // intentional micro-type for the compact 20px numeric badge.
+ fontSize: '10px',
+ paddingBlockEnd: '1px',
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: typeScaleVars['--text-supporting-leading'],
- transitionProperty: 'background-color, color, border-color',
- transitionDuration: durationVars['--duration-fast'],
- transitionTimingFunction: easeVars['--ease-standard'],
+ lineHeight: 1,
flexShrink: 0,
- userSelect: 'none',
- borderWidth: spacingVars['--spacing-0-5'],
- borderStyle: 'solid',
- position: 'relative',
+ textAlign: 'center',
},
- indicatorActive: {
+ numberCompleted: {
backgroundColor: colorVars['--color-accent'],
- borderColor: colorVars['--color-accent'],
- color: colorVars['--color-on-accent'],
+ color: colorVars['--color-background-surface'],
},
- indicatorCompleted: {
+ numberInProgress: {
backgroundColor: colorVars['--color-accent'],
- borderColor: colorVars['--color-accent'],
- color: colorVars['--color-on-accent'],
+ color: colorVars['--color-background-surface'],
},
- indicatorUpcoming: {
- backgroundColor: 'transparent',
- borderColor: colorVars['--color-border-emphasized'],
+ numberNotStarted: {
+ backgroundColor: colorVars['--color-background-muted'],
color: colorVars['--color-text-secondary'],
},
- indicatorDisabled: {
- backgroundColor: 'transparent',
- borderColor: colorVars['--color-border'],
+ numberDisabled: {
+ backgroundColor: colorVars['--color-background-muted'],
color: colorVars['--color-text-disabled'],
+ opacity: 0.5,
},
- indicatorError: {
- backgroundColor: colorVars['--color-error'],
- borderColor: colorVars['--color-error'],
- color: colorVars['--color-on-error'],
- },
- indicatorClickable: {
- cursor: 'pointer',
- ':hover': {
- '@media (hover: hover)': {
- opacity: 0.85,
- },
- },
- },
-
- // Connector line colors
- connectorCompleted: {
+ // Semantic status overrides for the number badge — color only.
+ numberAccent: {
backgroundColor: colorVars['--color-accent'],
+ color: colorVars['--color-on-accent'],
},
- connectorIncomplete: {
- backgroundColor: colorVars['--color-border-emphasized'],
+ numberSuccess: {
+ backgroundColor: colorVars['--color-success'],
+ color: colorVars['--color-on-success'],
},
-
- // Label and description
- labelRow: {
- display: 'flex',
- flexDirection: 'column',
- alignItems: 'center',
- paddingBlockStart: spacingVars['--spacing-1'],
- // No spacing token at 120px — nearest are --spacing-12 (48px) and --spacing-14 (56px)
- maxWidth: '120px',
+ numberWarning: {
+ backgroundColor: colorVars['--color-warning'],
+ color: colorVars['--color-on-warning'],
},
- labelRowVertical: {
- alignItems: 'flex-start',
- maxWidth: 'none',
- paddingBlockStart: spacingVars['--spacing-0-5'],
+ numberError: {
+ backgroundColor: colorVars['--color-error'],
+ color: colorVars['--color-on-error'],
},
+
+ // Label
label: {
fontSize: typeScaleVars['--text-body-size'],
lineHeight: typeScaleVars['--text-body-leading'],
- fontWeight: fontWeightVars['--font-weight-medium'],
- textAlign: 'center',
- },
- labelVertical: {
- textAlign: 'start',
- },
- labelActive: {
+ fontWeight: fontWeightVars['--font-weight-normal'],
color: colorVars['--color-text-primary'],
- fontWeight: fontWeightVars['--font-weight-semibold'],
},
- labelCompleted: {
- color: colorVars['--color-text-primary'],
+ labelInProgress: {
+ fontWeight: fontWeightVars['--font-weight-semibold'],
},
- labelUpcoming: {
+ labelNotStarted: {
color: colorVars['--color-text-secondary'],
},
labelDisabled: {
color: colorVars['--color-text-disabled'],
},
- labelError: {
- color: colorVars['--color-error'],
+
+ // Optional tag
+ optionalDot: {
+ fontSize: typeScaleVars['--text-body-size'],
+ color: colorVars['--color-text-secondary'],
+ },
+ optionalText: {
+ fontSize: typeScaleVars['--text-body-size'],
+ color: colorVars['--color-text-secondary'],
+ },
+
+ // Description
+ descriptionRow: {
+ paddingInlineStart: spacingVars['--spacing-0'],
+ },
+ descriptionRowWithIndicator: {
+ // Align with label: icon (16px) + gap (8px) = 24px
+ paddingInlineStart: spacingVars['--spacing-6'],
+ },
+ descriptionRowWithNumber: {
+ // Align with label: number badge (20px) + gap (8px) = 28px
+ paddingInlineStart: spacingVars['--spacing-7'],
},
description: {
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
color: colorVars['--color-text-secondary'],
- textAlign: 'center',
},
- descriptionVertical: {
- textAlign: 'start',
+
+ // Step content (children / flex slot)
+ stepContent: {
+ paddingBlockStart: spacingVars['--spacing-2'],
},
- descriptionError: {
- color: colorVars['--color-error'],
+ stepContentWithIndicator: {
+ paddingInlineStart: spacingVars['--spacing-6'],
+ },
+ stepContentWithNumber: {
+ paddingInlineStart: spacingVars['--spacing-7'],
},
- // Button reset for clickable indicators
+ // Density
+ densityCompact: {
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ },
+ densityBalanced: {
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-2'],
+ },
+ densitySpacious: {
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-3'],
+ },
+
+ // Button reset for clickable steps
buttonReset: {
- background: 'none',
- border: 'none',
- padding: 0,
- margin: 0,
- font: 'inherit',
+ all: 'unset',
+ textAlign: 'start',
+ alignItems: 'stretch',
+ display: 'flex',
+ flexDirection: 'column',
+ width: '100%',
+ 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'],
+ },
},
- // Step content (children)
- stepContent: {
- paddingBlockStart: spacingVars['--spacing-3'],
+ focusRing: {
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':focus-visible': '2px',
+ },
},
});
/**
- * An individual step within an XDSStepper. Renders a numbered indicator
- * circle, a connector line to the next step, and a label with optional
- * description. Step state (active, completed, upcoming) is derived from
- * the parent's activeStep and this step's `step` prop.
+ * An individual step within an XDSStepper. Renders a 4px progress-bar segment,
+ * an indicator (numbered badge, check, or any custom icon), a label with
+ * optional description, and an optional content slot.
+ *
+ * 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.
*
* @example
* ```
* <XDSStep step={0} label="Account details" description="Enter your email" />
* ```
+ *
+ * @example
+ * ```
+ * // Generic icon + semantic color
+ * <XDSStep step={1} label="Payment" status="error" icon={<XDSIcon icon="warning" />} />
+ * ```
*/
export function XDSStep({
step,
@@ -306,9 +440,12 @@ export function XDSStep({
description,
children,
icon,
- isCompleted: isCompletedProp,
+ status,
isDisabled = false,
- hasError = false,
+ isOptional = false,
+ endContent,
+ indicator: indicatorProp,
+ density: densityProp,
xstyle,
className,
style,
@@ -317,13 +454,31 @@ export function XDSStep({
...rest
}: XDSStepProps) {
const ctx = useXDSStepperContext();
- const {activeStep, orientation, isNonLinear, onStepClick} = ctx;
+ const {activeStep, orientation, onStepClick, density: ctxDensity} = ctx;
- const isActive = step === activeStep;
- const isCompleted = isCompletedProp ?? step < activeStep;
- const isVertical = orientation === 'vertical';
+ const density = densityProp ?? ctxDensity;
+
+ // Resolve indicator prop — may be a preset string or a custom ReactNode.
+ const isCustomIndicator =
+ indicatorProp != null && typeof indicatorProp !== 'string';
+ const indicator: XDSStepIndicatorPreset = isCustomIndicator
+ ? 'auto'
+ : ((indicatorProp as XDSStepIndicatorPreset | undefined) ?? 'auto');
- const isClickable = isNonLinear && !isDisabled && (isCompleted || isActive);
+ // Internal progress, derived from the parent's activeStep. This is NOT the
+ // public `status` prop — `status` controls semantic color only.
+ const progress: 'completed' | 'in-progress' | 'not-started' =
+ step === activeStep
+ ? 'in-progress'
+ : step < activeStep
+ ? 'completed'
+ : 'not-started';
+
+ const isVertical = orientation === 'vertical';
+ const isActive = progress === 'in-progress';
+ // Any non-disabled step is navigable when an onStepClick handler is provided,
+ // including not-started steps (free navigation across the flow).
+ const isClickable = !isDisabled && onStepClick != null;
const handleClick = () => {
if (isClickable && onStepClick) {
@@ -331,166 +486,270 @@ export function XDSStep({
}
};
- const indicatorContent = hasError ? (
- <XDSIcon icon="warning" size="sm" color="inherit" />
- ) : icon != null ? (
- icon
- ) : isCompleted ? (
- <XDSIcon icon="check" size="sm" color="inherit" />
- ) : (
- <span>{step + 1}</span>
- );
+ // Bar fill is purely progress-based; `status` recolors it when set.
+ 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;
- const indicatorVariantStyle = hasError
- ? styles.indicatorError
- : isDisabled
- ? styles.indicatorDisabled
- : isActive
- ? styles.indicatorActive
- : isCompleted
- ? styles.indicatorCompleted
- : styles.indicatorUpcoming;
-
- const stepState = hasError
- ? 'error'
- : isDisabled
- ? 'disabled'
+ // --- Build indicator node ---
+ // 'auto': number for not-started, check/dot icon once reached
+ // 'number': always number badge
+ // 'none': nothing
+ // custom ReactNode (or `icon` prop): render as-is
+ let indicatorNode: ReactNode = null;
+
+ const customIcon = isCustomIndicator ? indicatorProp : (icon ?? null);
+
+ if (indicator !== 'none') {
+ const showNumber =
+ customIcon == null &&
+ (indicator === 'number' ||
+ (indicator === 'auto' && progress === 'not-started'));
+
+ if (showNumber) {
+ const numberColorStyle = isDisabled
+ ? styles.numberDisabled
+ : status === 'accent'
+ ? styles.numberAccent
+ : status === 'success'
+ ? styles.numberSuccess
+ : status === 'warning'
+ ? styles.numberWarning
+ : status === 'error'
+ ? styles.numberError
+ : progress === 'completed'
+ ? styles.numberCompleted
+ : progress === 'in-progress'
+ ? styles.numberInProgress
+ : styles.numberNotStarted;
+
+ indicatorNode = (
+ <div
+ aria-hidden="true"
+ {...stylex.props(styles.numberBadge, numberColorStyle)}>
+ {step + 1}
+ </div>
+ );
+ } else {
+ // Custom icon takes priority, otherwise the progress-derived default.
+ const iconContent =
+ customIcon != null ? (
+ customIcon
+ ) : progress === 'completed' ? (
+ <CheckCircleIcon />
+ ) : (
+ <CurrentIcon />
+ );
+
+ const iconColorStyle = isDisabled
+ ? styles.iconDisabled
+ : 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;
+
+ indicatorNode = (
+ <div aria-hidden="true" {...stylex.props(styles.icon, iconColorStyle)}>
+ {iconContent}
+ </div>
+ );
+ }
+ }
+
+ const hasIndicator = indicator !== 'none';
+ const isNumber =
+ hasIndicator &&
+ customIcon == null &&
+ (indicator === 'number' ||
+ (indicator === 'auto' && progress === 'not-started'));
+
+ const labelColorStyle = isDisabled
+ ? styles.labelDisabled
+ : progress === 'not-started'
+ ? styles.labelNotStarted
: isActive
- ? 'active'
- : isCompleted
- ? 'completed'
- : 'upcoming';
-
- const indicator = isClickable ? (
- <button
- type="button"
- onClick={handleClick}
- aria-label={`Go to step ${step + 1}: ${label}`}
- {...mergeProps(
- xdsThemeProps('step-indicator', {state: stepState}),
- stylex.props(
- styles.buttonReset,
- styles.indicator,
- indicatorVariantStyle,
- styles.indicatorClickable,
- ),
- )}>
- {indicatorContent}
- </button>
- ) : (
- <div
- aria-hidden="true"
- {...mergeProps(
- xdsThemeProps('step-indicator', {state: stepState}),
- stylex.props(styles.indicator, indicatorVariantStyle),
- )}>
- {indicatorContent}
+ ? styles.labelInProgress
+ : undefined;
+
+ // Indicator + Label row
+ const iconLabelNode = (
+ <div {...stylex.props(styles.iconLabelRow)}>
+ {indicatorNode}
+ <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 labelNode = (
- <div
- {...stylex.props(styles.labelRow, isVertical && styles.labelRowVertical)}>
- <span
+ const descriptionNode =
+ description != null ? (
+ <div
{...stylex.props(
- styles.label,
- isVertical && styles.labelVertical,
- hasError
- ? styles.labelError
- : isDisabled
- ? styles.labelDisabled
- : isActive
- ? styles.labelActive
- : isCompleted
- ? styles.labelCompleted
- : styles.labelUpcoming,
+ hasIndicator
+ ? isNumber
+ ? styles.descriptionRowWithNumber
+ : styles.descriptionRowWithIndicator
+ : styles.descriptionRow,
)}>
- {label}
- </span>
- {description != null && (
- <span
- {...stylex.props(
- styles.description,
- isVertical && styles.descriptionVertical,
- hasError && styles.descriptionError,
- )}>
- {description}
- </span>
- )}
- </div>
- );
+ <span {...stylex.props(styles.description)}>{description}</span>
+ </div>
+ ) : null;
+
+ const contentNode =
+ children != null ? (
+ <div
+ {...stylex.props(
+ styles.stepContent,
+ hasIndicator &&
+ (isNumber
+ ? styles.stepContentWithNumber
+ : styles.stepContentWithIndicator),
+ )}>
+ {children}
+ </div>
+ ) : null;
+
+ // Theme data attributes reflect progress + optional semantic status.
+ const themeProps = xdsThemeProps('step', {
+ progress,
+ status: status ?? undefined,
+ });
+ // ======= VERTICAL =======
if (isVertical) {
return (
- <div
+ <li
ref={ref}
{...mergeProps(
- xdsThemeProps('step', {state: stepState}),
+ themeProps,
stylex.props(styles.verticalRoot, xstyle),
className,
style,
)}
aria-current={isActive ? 'step' : undefined}
data-testid={dataTestId}
- role="listitem"
{...rest}>
- <div {...stylex.props(styles.verticalIndicatorColumn)}>
- {indicator}
- <div {...stylex.props(styles.verticalConnector)}>
+ {/* 4px progress bar */}
+ <div
+ {...mergeProps(
+ xdsThemeProps('step-bar'),
+ stylex.props(
+ styles.verticalBar,
+ statusBarStyle ??
+ (isBarFilled ? styles.barCompleted : styles.barIncomplete),
+ ),
+ )}
+ aria-hidden="true"
+ />
+ {/* Body: button wraps only label area, children render outside */}
+ <div {...stylex.props(styles.verticalBody)}>
+ {isClickable ? (
+ <button
+ type="button"
+ onClick={handleClick}
+ aria-label={`Go to step ${step + 1}: ${label}`}
+ {...stylex.props(
+ styles.buttonReset,
+ styles.focusRing,
+ density === 'compact' && styles.densityCompact,
+ density === 'balanced' && styles.densityBalanced,
+ density === 'spacious' && styles.densitySpacious,
+ )}>
+ {iconLabelNode}
+ {descriptionNode}
+ </button>
+ ) : (
<div
- {...mergeProps(
- xdsThemeProps('step-connector'),
- stylex.props(
- styles.verticalConnectorLine,
- isCompleted
- ? styles.connectorCompleted
- : styles.connectorIncomplete,
- ),
- )}
- />
- </div>
- </div>
- <div {...stylex.props(styles.verticalContent)}>
- {labelNode}
- {children != null && (
- <div {...stylex.props(styles.stepContent)}>{children}</div>
+ {...stylex.props(
+ density === 'compact' && styles.densityCompact,
+ density === 'balanced' && styles.densityBalanced,
+ density === 'spacious' && styles.densitySpacious,
+ )}>
+ {iconLabelNode}
+ {descriptionNode}
+ </div>
)}
+ {contentNode}
</div>
- </div>
+ </li>
);
}
+ // ======= HORIZONTAL =======
return (
- <div
+ <li
ref={ref}
{...mergeProps(
- xdsThemeProps('step', {state: stepState}),
- stylex.props(styles.horizontalRoot, xstyle),
+ themeProps,
+ stylex.props(styles.horizontalStep, xstyle),
className,
style,
)}
aria-current={isActive ? 'step' : undefined}
data-testid={dataTestId}
- role="listitem"
{...rest}>
- <div {...stylex.props(styles.horizontalContent)}>
- {indicator}
- {labelNode}
- </div>
- <div {...stylex.props(styles.horizontalConnector)}>
+ {/* 4px progress bar segment for this step */}
+ <div
+ {...mergeProps(
+ xdsThemeProps('step-bar'),
+ stylex.props(
+ styles.horizontalBar,
+ statusBarStyle ??
+ (isBarFilled ? styles.barCompleted : styles.barIncomplete),
+ ),
+ )}
+ aria-hidden="true"
+ />
+ {isClickable ? (
+ <button
+ type="button"
+ onClick={handleClick}
+ aria-label={`Go to step ${step + 1}: ${label}`}
+ {...stylex.props(
+ styles.buttonReset,
+ styles.focusRing,
+ density === 'compact' && styles.densityCompact,
+ density === 'balanced' && styles.densityBalanced,
+ density === 'spacious' && styles.densitySpacious,
+ )}>
+ {iconLabelNode}
+ {descriptionNode}
+ </button>
+ ) : (
<div
- {...mergeProps(
- xdsThemeProps('step-connector'),
- stylex.props(
- styles.horizontalConnectorLine,
- isCompleted
- ? styles.connectorCompleted
- : styles.connectorIncomplete,
- ),
- )}
- />
- </div>
- </div>
+ {...stylex.props(
+ density === 'compact' && styles.densityCompact,
+ density === 'balanced' && styles.densityBalanced,
+ density === 'spacious' && styles.densitySpacious,
+ )}>
+ {iconLabelNode}
+ {descriptionNode}
+ </div>
+ )}
+ {contentNode}
+ </li>
);
}
diff --git a/packages/lab/src/Stepper/XDSStepStatus.ts b/packages/lab/src/Stepper/XDSStepStatus.ts
new file mode 100644
index 0000000000..9046033402
--- /dev/null
+++ b/packages/lab/src/Stepper/XDSStepStatus.ts
@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file XDSStepStatus.ts
+ * @input None
+ * @output Exports XDSStepStatus type
+ * @position Shared type used by XDSStep and the stepper docs
+ */
+
+/**
+ * Semantic color status for a step. Controls **color only** — it maps directly
+ * onto the XDS global semantic color tokens and does not change layout,
+ * iconography, or behavior.
+ *
+ * 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)
+ *
+ * `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"`.
+ */
+export type XDSStepStatus = 'accent' | 'success' | 'warning' | 'error';
diff --git a/packages/lab/src/Stepper/XDSStepper.test.tsx b/packages/lab/src/Stepper/XDSStepper.test.tsx
index ffc2a9e8a9..34459760f0 100644
--- a/packages/lab/src/Stepper/XDSStepper.test.tsx
+++ b/packages/lab/src/Stepper/XDSStepper.test.tsx
@@ -7,7 +7,7 @@ import {XDSStepper} from './XDSStepper';
import {XDSStep} from './XDSStep';
describe('XDSStepper', () => {
- it('renders a navigation landmark with steps', () => {
+ it('renders an ordered list of steps (not a nav landmark)', () => {
render(
<XDSStepper activeStep={0}>
<XDSStep step={0} label="Step 1" />
@@ -15,9 +15,10 @@ describe('XDSStepper', () => {
<XDSStep step={2} label="Step 3" />
</XDSStepper>,
);
- expect(
- screen.getByRole('navigation', {name: 'Progress'}),
- ).toBeInTheDocument();
+ // A stepper is a sequence/progress list, not a navigation landmark.
+ expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
+ const list = screen.getByRole('list', {name: 'Progress'});
+ expect(list.tagName).toBe('OL');
expect(screen.getByText('Step 1')).toBeInTheDocument();
expect(screen.getByText('Step 2')).toBeInTheDocument();
expect(screen.getByText('Step 3')).toBeInTheDocument();
@@ -26,8 +27,8 @@ describe('XDSStepper', () => {
it('renders step numbers', () => {
render(
<XDSStepper activeStep={0}>
- <XDSStep step={0} label="First" />
- <XDSStep step={1} label="Second" />
+ <XDSStep step={0} label="First" indicator="number" />
+ <XDSStep step={1} label="Second" indicator="number" />
</XDSStepper>,
);
expect(screen.getByText('1')).toBeInTheDocument();
@@ -68,7 +69,7 @@ describe('XDSStepper', () => {
</XDSStepper>,
);
expect(
- screen.getByRole('navigation', {name: 'Checkout progress'}),
+ screen.getByRole('list', {name: 'Checkout progress'}),
).toBeInTheDocument();
});
@@ -79,8 +80,8 @@ describe('XDSStepper', () => {
<XDSStep step={1} label="Step 2" />
</XDSStepper>,
);
- const nav = screen.getByRole('navigation');
- expect(nav).toBeInTheDocument();
+ const list = screen.getByRole('list');
+ expect(list).toHaveAttribute('data-orientation', 'vertical');
});
it('calls onStepClick when a completed step is clicked', async () => {
@@ -115,7 +116,7 @@ describe('XDSStepper', () => {
expect(handleClick).toHaveBeenCalledWith(1);
});
- it('does not render buttons for upcoming steps in non-linear mode', () => {
+ it('renders buttons for upcoming steps in non-linear mode', () => {
render(
<XDSStepper activeStep={0} onStepClick={() => {}}>
<XDSStep step={0} label="Step 1" />
@@ -126,8 +127,24 @@ describe('XDSStepper', () => {
screen.getByRole('button', {name: 'Go to step 1: Step 1'}),
).toBeInTheDocument();
expect(
- screen.queryByRole('button', {name: 'Go to step 2: Step 2'}),
- ).not.toBeInTheDocument();
+ screen.getByRole('button', {name: 'Go to step 2: Step 2'}),
+ ).toBeInTheDocument();
+ });
+
+ it('calls onStepClick when an upcoming step is clicked', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <XDSStepper activeStep={0} onStepClick={handleClick}>
+ <XDSStep step={0} label="Step 1" />
+ <XDSStep step={1} label="Step 2" />
+ <XDSStep step={2} label="Step 3" />
+ </XDSStepper>,
+ );
+ await user.click(
+ screen.getByRole('button', {name: 'Go to step 3: Step 3'}),
+ );
+ expect(handleClick).toHaveBeenCalledWith(2);
});
it('does not render buttons for disabled steps', () => {
@@ -154,15 +171,58 @@ describe('XDSStepper', () => {
expect(screen.queryAllByRole('button')).toHaveLength(0);
});
- it('supports isCompleted override', () => {
+ it('applies a semantic color status (color only) via data attribute', () => {
+ render(
+ <XDSStepper activeStep={1}>
+ <XDSStep step={0} label="Step 1" data-testid="step-0" />
+ <XDSStep step={1} label="Step 2" status="error" data-testid="step-1" />
+ </XDSStepper>,
+ );
+ expect(screen.getByTestId('step-1')).toHaveAttribute(
+ 'data-status',
+ 'error',
+ );
+ // status is color-only — it must not change progress semantics.
+ expect(screen.getByTestId('step-1')).toHaveAttribute(
+ 'aria-current',
+ 'step',
+ );
+ });
+
+ it('reflects each global semantic status on the data attribute', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep step={0} label="A" status="accent" data-testid="s-accent" />
+ <XDSStep step={1} label="B" status="success" data-testid="s-success" />
+ <XDSStep step={2} label="C" status="warning" data-testid="s-warning" />
+ <XDSStep step={3} label="D" status="error" data-testid="s-error" />
+ </XDSStepper>,
+ );
+ expect(screen.getByTestId('s-accent')).toHaveAttribute(
+ 'data-status',
+ 'accent',
+ );
+ expect(screen.getByTestId('s-success')).toHaveAttribute(
+ 'data-status',
+ 'success',
+ );
+ expect(screen.getByTestId('s-warning')).toHaveAttribute(
+ 'data-status',
+ 'warning',
+ );
+ expect(screen.getByTestId('s-error')).toHaveAttribute(
+ 'data-status',
+ 'error',
+ );
+ });
+
+ it('does not set a status data attribute when status is unset', () => {
render(
<XDSStepper activeStep={0}>
<XDSStep step={0} label="Step 1" data-testid="step-0" />
- <XDSStep step={1} label="Step 2" isCompleted data-testid="step-1" />
</XDSStepper>,
);
- const step1 = screen.getByTestId('step-1');
- expect(step1).toBeInTheDocument();
+ expect(screen.getByTestId('step-0')).not.toHaveAttribute('data-status');
});
it('handles zero active step correctly', () => {
@@ -179,7 +239,7 @@ describe('XDSStepper', () => {
expect(screen.getByTestId('step-1')).not.toHaveAttribute('aria-current');
});
- it('renders listitem roles for each step', () => {
+ it('renders each step as a list item', () => {
render(
<XDSStepper activeStep={0}>
<XDSStep step={0} label="Step 1" />
@@ -187,6 +247,35 @@ describe('XDSStepper', () => {
<XDSStep step={2} label="Step 3" />
</XDSStepper>,
);
- expect(screen.getAllByRole('listitem')).toHaveLength(3);
+ const items = screen.getAllByRole('listitem');
+ expect(items).toHaveLength(3);
+ expect(items[0].tagName).toBe('LI');
+ });
+
+ it('accepts a custom ReactNode as indicator', () => {
+ render(
+ <XDSStepper activeStep={0}>
+ <XDSStep
+ step={0}
+ label="Step 1"
+ indicator={<span data-testid="custom-icon">★</span>}
+ />
+ </XDSStepper>,
+ );
+ expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+ expect(screen.getByText('★')).toBeInTheDocument();
+ });
+
+ it('accepts a generic icon via the icon prop', () => {
+ render(
+ <XDSStepper activeStep={1}>
+ <XDSStep
+ step={1}
+ label="Payment"
+ icon={<span data-testid="pay-icon">$</span>}
+ />
+ </XDSStepper>,
+ );
+ expect(screen.getByTestId('pay-icon')).toBeInTheDocument();
});
});
diff --git a/packages/lab/src/Stepper/XDSStepper.tsx b/packages/lab/src/Stepper/XDSStepper.tsx
index 451430a679..7485e74893 100644
--- a/packages/lab/src/Stepper/XDSStepper.tsx
+++ b/packages/lab/src/Stepper/XDSStepper.tsx
@@ -9,9 +9,9 @@
* @position Core container component; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
- * - /packages/core/src/Stepper/XDSStepper.test.tsx (tests for new/changed behavior)
- * - /packages/core/src/Stepper/index.ts (exports if types change)
+ * - /packages/lab/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
+ * - /packages/lab/src/Stepper/XDSStepper.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/Stepper/index.ts (exports if types change)
* - /apps/storybook/stories/Stepper.stories.tsx (storybook stories)
* - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)
*/
@@ -28,9 +28,9 @@ import {
type XDSStepperContextValue,
} from './XDSStepperContext';
-export interface XDSStepperProps extends XDSBaseProps<HTMLDivElement> {
+export interface XDSStepperProps extends XDSBaseProps<HTMLOListElement> {
/** Ref forwarded to the root element */
- ref?: React.Ref<HTMLDivElement>;
+ ref?: React.Ref<HTMLOListElement>;
/**
* Zero-based index of the active step.
*/
@@ -50,12 +50,19 @@ export interface XDSStepperProps extends XDSBaseProps<HTMLDivElement> {
*/
onStepClick?: (index: number) => void;
/**
- * Accessible label for the stepper navigation landmark.
+ * Accessible label describing the set of steps.
* @default 'Progress'
*/
label?: string;
+ /**
+ * Controls density (padding) of all steps.
+ * @default 'balanced'
+ */
+ density?: 'compact' | 'balanced' | 'spacious';
}
+const STEP_GAP = '2px';
+
const styles = stylex.create({
root: {
display: 'flex',
@@ -67,9 +74,11 @@ const styles = stylex.create({
horizontal: {
flexDirection: 'row',
alignItems: 'flex-start',
+ gap: STEP_GAP,
},
vertical: {
flexDirection: 'column',
+ gap: STEP_GAP,
},
});
@@ -81,6 +90,13 @@ const styles = stylex.create({
* can derive its state from the parent's activeStep. CSS :last-child
* handles connector hiding — no child introspection needed.
*
+ * Rendered as an ordered list (`<ol>`/`<li>`) rather than a `nav`
+ * landmark: a stepper communicates *progress through a sequence*, not a
+ * set of site navigation links. The active step is marked with
+ * `aria-current="step"` (handled per-step) and the list carries an
+ * accessible `label`. This follows the WAI-ARIA pattern for steppers /
+ * progress sequences and avoids polluting the page's landmark map.
+ *
* @example
* ```
* <XDSStepper activeStep={1}>
@@ -96,6 +112,7 @@ export function XDSStepper({
orientation = 'horizontal',
onStepClick,
label = 'Progress',
+ density = 'balanced',
xstyle,
className,
style,
@@ -108,29 +125,31 @@ export function XDSStepper({
orientation,
isNonLinear: onStepClick != null,
onStepClick: onStepClick ?? null,
+ density,
}),
- [activeStep, orientation, onStepClick],
+ [activeStep, orientation, onStepClick, density],
);
return (
<XDSStepperContext value={ctxValue}>
- <nav ref={ref} aria-label={label} {...rest}>
- <ol
- {...mergeProps(
- xdsThemeProps('stepper', {orientation}),
- stylex.props(
- styles.root,
- orientation === 'horizontal'
- ? styles.horizontal
- : styles.vertical,
- xstyle,
- ),
- className,
- style,
- )}>
- {children}
- </ol>
- </nav>
+ <ol
+ ref={ref}
+ aria-label={label}
+ {...rest}
+ {...mergeProps(
+ xdsThemeProps('stepper', {orientation}),
+ stylex.props(
+ styles.root,
+ orientation === 'horizontal' ? styles.horizontal : styles.vertical,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {/* Each step renders its own progress bar segment; no child
+ introspection needed — steps derive state from context. */}
+ {children}
+ </ol>
</XDSStepperContext>
);
}
diff --git a/packages/lab/src/Stepper/XDSStepperContext.ts b/packages/lab/src/Stepper/XDSStepperContext.ts
index 6bee59eb59..3ec0e4a3e2 100644
--- a/packages/lab/src/Stepper/XDSStepperContext.ts
+++ b/packages/lab/src/Stepper/XDSStepperContext.ts
@@ -9,19 +9,21 @@
* @position Context for XDSStepper <-> XDSStep communication
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Stepper/Stepper.doc.mjs
- * - /packages/core/src/Stepper/index.ts
+ * - /packages/lab/src/Stepper/Stepper.doc.mjs
+ * - /packages/lab/src/Stepper/index.ts
*/
import {createContext, use} from 'react';
export type XDSStepperOrientation = 'horizontal' | 'vertical';
+export type XDSStepperDensity = 'compact' | 'balanced' | 'spacious';
export interface XDSStepperContextValue {
activeStep: number;
orientation: XDSStepperOrientation;
isNonLinear: boolean;
onStepClick: ((index: number) => void) | null;
+ density: XDSStepperDensity;
}
export const XDSStepperContext = createContext<XDSStepperContextValue | null>(
diff --git a/packages/lab/src/Stepper/index.ts b/packages/lab/src/Stepper/index.ts
index dd40cc2300..548ba9a613 100644
--- a/packages/lab/src/Stepper/index.ts
+++ b/packages/lab/src/Stepper/index.ts
@@ -2,20 +2,13 @@
'use client';
-/**
- * @file index.ts
- * @input Imports from Stepper component files
- * @output Exports XDSStepper, XDSStep and their types
- * @position Component entry point; re-exported by /packages/core/src/index.ts
- *
- * SYNC: When modified, update this header and /packages/core/src/Stepper/Stepper.doc.mjs
- */
-
export {XDSStepper} from './XDSStepper';
export type {XDSStepperProps} from './XDSStepper';
export {XDSStep} from './XDSStep';
-export type {XDSStepProps} from './XDSStep';
+export type {XDSStepProps, XDSStepIndicatorPreset} from './XDSStep';
+
+export type {XDSStepStatus} from './XDSStepStatus';
export {useXDSStepperContext} from './XDSStepperContext';
export type {XDSStepperOrientation} from './XDSStepperContext';