diff --git a/.changeset/stepper-component.md b/.changeset/stepper-component.md
new file mode 100644
index 000000000..ad4fa18ae
--- /dev/null
+++ b/.changeset/stepper-component.md
@@ -0,0 +1,17 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add `Stepper` for showing progress through a fixed sequence of steps: the steps of a wizard form, the stages of an approval flow, the quality gates of a project. Each step has a `status` (`complete`, `current`, `upcoming` or `skipped`), an optional `badge` beside its label and an optional `description` under it, and the line between steps fills up to the furthest step reached. It lays out horizontally or vertically; a horizontal Stepper scrolls sideways when its steps don't fit and, below 400px of container width, shows only its markers with "Step 2 of 4" and the current step's label, and each marker names its step in a tooltip. `onStepClick` makes completed steps clickable, and step ids are typed so `onStepClick` receives your own id union.
+
+```tsx
+
+```
diff --git a/docs-manifest.json b/docs-manifest.json
index e61f12412..6f5823664 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -824,10 +824,10 @@
"symbols": [],
"hashes": {
"typeSurface": null,
- "outline": "fbc09ef9994494cb",
+ "outline": "6f44fa0ce14bc031",
"snapshot": null,
- "outputMd": "851afb4672da6673",
- "examples": "157ff03dc999d3d3"
+ "outputMd": "e86dd12f9aaa196f",
+ "examples": "f0c771090062761d"
}
},
"global-header-layout": {
@@ -1374,6 +1374,23 @@
"examples": "2782e1f9f3822dfe"
}
},
+ "stepper": {
+ "slug": "stepper",
+ "kind": "code-backed",
+ "outline": "docs-src/components/stepper.docs.outline.md",
+ "output": "docs/components/stepper.md",
+ "examples": "docs-src/components/stepper.docs.examples.tsx",
+ "sources": ["packages/core/src/components/stepper/**"],
+ "claims": [],
+ "symbols": ["Stepper", "StepperProps", "StepperStep"],
+ "hashes": {
+ "typeSurface": "03575b3ae95ff031",
+ "outline": "620afc4168680aa7",
+ "snapshot": "62a67309416ceed7",
+ "outputMd": "dfd07cfec2f84d5b",
+ "examples": "9a0f9bf7c9b8fb95"
+ }
+ },
"styling-theming": {
"slug": "styling-theming",
"kind": "prose",
@@ -1863,6 +1880,7 @@
"packages/core/skills/app-shell-patterns/references/components/sidebar-layout.md": "af971809e42dfdb8",
"packages/core/skills/app-shell-patterns/references/components/sidebar-section.md": "281cfa2dcbff14be",
"packages/core/skills/app-shell-patterns/references/components/spinner.md": "eec440408611a233",
+ "packages/core/skills/app-shell-patterns/references/components/stepper.md": "dfd07cfec2f84d5b",
"packages/core/skills/app-shell-patterns/references/components/table.md": "c5933b640a78c3bf",
"packages/core/skills/app-shell-patterns/references/components/tabs.md": "a94b016f0c9709b7",
"packages/core/skills/app-shell-patterns/references/components/text.md": "e5311b1891f3ff7b",
@@ -1902,14 +1920,14 @@
"packages/core/skills/app-shell-patterns/references/patterns/form-modal.md": "a0d3c952b0b10351",
"packages/core/skills/app-shell-patterns/references/patterns/form-sectioned.md": "d31cd3ae6ad0790c",
"packages/core/skills/app-shell-patterns/references/patterns/form-single-page.md": "10a0f4d91a120752",
- "packages/core/skills/app-shell-patterns/references/patterns/form-wizard.md": "851afb4672da6673",
+ "packages/core/skills/app-shell-patterns/references/patterns/form-wizard.md": "e86dd12f9aaa196f",
"packages/core/skills/app-shell-patterns/references/patterns/i18n-labels.md": "d9f0851d9c98ecfe",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-confirm.md": "2db70f423c6fdf97",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-multi-select.md": "253fcea1c4e5a42c",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-toast.md": "f68bdab855730f48",
"packages/core/skills/app-shell-patterns/references/pages/document-collection.md": "e79d9120d86db198",
"packages/core/skills/app-shell-patterns/references/pages/document-detail.md": "e07c7fee2478a21d",
- "packages/core/skills/app-shell-patterns/SKILL.md": "18efee79280174e7",
+ "packages/core/skills/app-shell-patterns/SKILL.md": "1594f44402a51278",
"packages/core/skills/app-shell-upgrade/references/migrations.md": "9bd2735c34fd35e3",
"packages/core/skills/app-shell-upgrade/SKILL.md": "f9be942f3e596c00"
}
diff --git a/docs-src/components/stepper.docs.examples.tsx b/docs-src/components/stepper.docs.examples.tsx
new file mode 100644
index 000000000..b01f137c8
--- /dev/null
+++ b/docs-src/components/stepper.docs.examples.tsx
@@ -0,0 +1,51 @@
+import { Badge, Stepper } from "@tailor-platform/app-shell";
+
+export function BasicUsage() {
+ return (
+
+ );
+}
+
+export function StageProgress() {
+ return (
+ Next,
+ description: "Plan 18 Nov",
+ },
+ { id: "qg5", label: "QG5", status: "upcoming", description: "Plan 9 Dec" },
+ ]}
+ />
+ );
+}
+
+export function Vertical() {
+ return (
+
+ );
+}
diff --git a/docs-src/components/stepper.docs.outline.md b/docs-src/components/stepper.docs.outline.md
new file mode 100644
index 000000000..cdc518e73
--- /dev/null
+++ b/docs-src/components/stepper.docs.outline.md
@@ -0,0 +1,89 @@
+---
+kind: code-backed
+group: stepper
+title: Stepper
+description: Shows progress through a fixed sequence of steps — wizard steps, approval stages, quality gates
+sources:
+ - packages/core/src/components/stepper/**
+---
+
+# Stepper
+
+`Stepper` shows how far something has progressed through a fixed sequence of steps: the steps of a [wizard form](../patterns/form-wizard.md), the stages of an approval flow, the quality gates of a project. Each step has a status, and the line between steps is filled up to the furthest step reached.
+
+It only displays progress. The page decides each step's status and what happens when a step is clicked.
+
+## Import
+
+```tsx
+import { Stepper } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ---------------------------- | -------------- | ---------------------------------------------------------------------------------- |
+| `steps` | `StepperStep[]` | - | The steps, in order |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | A row of steps, or a column for beside a form |
+| `onStepClick` | `(id: Id) => void` | - | Makes completed steps clickable — for example to go back to an earlier wizard step |
+| `aria-label` | `string` | "Progress" | Accessible name for the list of steps (the default is translated) |
+| `className` | `string` | - | Additional CSS classes |
+| `style` | `CSSProperties` | - | Inline styles |
+
+### `StepperStep`
+
+| Field | Type | Description |
+| ------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `id` | `Id extends string` | Stable id, passed to `onStepClick` |
+| `label` | `ReactNode` | Step name |
+| `status` | `"complete" \| "current" \| "upcoming" \| "skipped"` | Where the step stands (below) |
+| `badge` | `ReactNode` | Shown beside the label — for example a "Next" or "Overdue" `Badge` |
+| `description` | `ReactNode` | Shown under the label — a short hint, or a few lines of values such as plan and actual dates |
+
+## Status
+
+| `status` | Marker | Use for |
+| ------------ | ------------------------------ | -------------------------------------------- |
+| `"complete"` | Filled, with a check | Steps that are done |
+| `"current"` | Outlined in the primary colour | The step the user is on, or the next one due |
+| `"upcoming"` | Outlined, muted | Steps not started |
+| `"skipped"` | Dashed outline, muted | Steps that don't apply to this record |
+
+Mark at most one step `current`. It gets `aria-current="step"`, and screen readers hear the status of the others ("Completed", "Skipped", "Not started").
+
+The line is filled up to the furthest step reached — the last step that is `complete` or `current`. A skipped step before it is filled through; one after it isn't.
+
+Step ids are typed: give `steps` a union of ids and `onStepClick` receives that union.
+
+```tsx
+type StepId = "supplier" | "lines" | "review";
+const steps: StepperStep[] = [
+ /* … */
+];
+
+ goTo(id)} />; // id: StepId
+```
+
+## Stage progress
+
+Badges and descriptions turn the Stepper into a stage tracker on a detail page:
+
+
+
+## Vertical
+
+A vertical Stepper suits a column beside a form, such as a wizard on a page:
+
+
+
+## Narrow containers
+
+A horizontal Stepper adapts to the width of its container, not the viewport:
+
+- When the steps don't fit side by side, the row scrolls sideways rather than squeezing the labels.
+- Below 400px it shows only the markers and lines, with "Step 2 of 4" and the current step's label underneath. This is what a wizard needs in a dialog on a phone.
+- Each marker then names its step in a tooltip on hover, and the marker of a completed step becomes the button that goes back to it, so keyboard users still have one visible place to focus.
diff --git a/docs-src/patterns/form-wizard.docs.examples.tsx b/docs-src/patterns/form-wizard.docs.examples.tsx
index 7235a9096..57e8431eb 100644
--- a/docs-src/patterns/form-wizard.docs.examples.tsx
+++ b/docs-src/patterns/form-wizard.docs.examples.tsx
@@ -1,6 +1,5 @@
import { useState } from "react";
import {
- Badge,
Button,
Card,
Field,
@@ -8,6 +7,7 @@ import {
Form,
Layout,
Select,
+ Stepper,
} from "@tailor-platform/app-shell";
const OWNERS = ["Tanaka", "Sato", "Suzuki", "Yamada"];
@@ -60,20 +60,16 @@ export function FormWizard() {
-
-
-