diff --git a/aef6db-stepper/ComponentListing/a5cbb429-b363-4b8b-b07a-a2b1026120b0.json b/aef6db-stepper/ComponentListing/a5cbb429-b363-4b8b-b07a-a2b1026120b0.json
new file mode 100644
index 00000000..5ce2901a
--- /dev/null
+++ b/aef6db-stepper/ComponentListing/a5cbb429-b363-4b8b-b07a-a2b1026120b0.json
@@ -0,0 +1,83 @@
+{
+  "data": {
+    "meta": {
+      "adoptsFrom": {
+        "name": "ComponentListing",
+        "module": "@cardstack/catalog/catalog-app/listing/listing"
+      }
+    },
+    "type": "card",
+    "attributes": {
+      "name": "Stepper UI",
+      "summary": "The Stepper component provides a multi-step flow shell for first-run wizards, onboarding journeys, and setup checklists — a guideline book that walks the user through what to fill in, in what order, before they start using an app. It renders a vertical step rail (numbered dots, checkmark done states, active ring, connector lines) beside the active step's content pane, closed out by a Back / Skip / Next action bar built from boxel-ui Button. The host supplies step definitions and per-step content through named blocks while the component owns the step state machine: gating Next on per-step isComplete wired to host state, MUI-style optional steps that surface a Skip button, onStepChange enter hooks for lazy loading, and optional rail click-to-jump. It supports an inline bordered-card mode and a modal mode (scrim plus centered card) for first-run experiences, a header with kicker, title, and an outlined-circle close button, and a fully replaceable actions block. Theming is driven by the linked theme: every color, font, and radius resolves --stepper-* override knob, then theme semantic token (the --primary / --primary-foreground pair drives the accent fills, their on-fill content, and the Next button), then neutral Boxel-token defaults — link a Theme card or Brand Guide and the whole stepper restyles with no stepper-specific work.",
+      "cardInfo": {
+        "name": "Stepper UI",
+        "notes": null,
+        "summary": null,
+        "cardThumbnailURL": null
+      }
+    },
+    "relationships": {
+      "skills": {
+        "links": {
+          "self": null
+        }
+      },
+      "tags.0": {
+        "links": {
+          "self": "../../Tag/card"
+        }
+      },
+      "license": {
+        "links": {
+          "self": null
+        }
+      },
+      "specs.0": {
+        "links": {
+          "self": "../Spec/stepper"
+        }
+      },
+      "specs.1": {
+        "links": {
+          "self": "../Spec/stepper-playground-example"
+        }
+      },
+      "specs.2": {
+        "links": {
+          "self": "../../Spec/code-snippet"
+        }
+      },
+      "images.0": {
+        "links": {
+          "self": "../Screenshots/c76678a0-a2ee-4142-a3d7-a9f537df7c52-d5ab6927.png"
+        }
+      },
+      "publisher": {
+        "links": {
+          "self": null
+        }
+      },
+      "examples.0": {
+        "links": {
+          "self": "../example/StepperPlayground/c76678a0-a2ee-4142-a3d7-a9f537df7c52"
+        }
+      },
+      "categories.0": {
+        "links": {
+          "self": "../../Category/ui-components-design"
+        }
+      },
+      "cardInfo.theme": {
+        "links": {
+          "self": null
+        }
+      },
+      "cardInfo.cardThumbnail": {
+        "links": {
+          "self": "../Screenshots/c76678a0-a2ee-4142-a3d7-a9f537df7c52-d5ab6927.png"
+        }
+      }
+    }
+  }
+}
diff --git a/aef6db-stepper/Screenshots/c76678a0-a2ee-4142-a3d7-a9f537df7c52-d5ab6927.png b/aef6db-stepper/Screenshots/c76678a0-a2ee-4142-a3d7-a9f537df7c52-d5ab6927.png
new file mode 100644
index 00000000..00d4267f
Binary files /dev/null and b/aef6db-stepper/Screenshots/c76678a0-a2ee-4142-a3d7-a9f537df7c52-d5ab6927.png differ
diff --git a/aef6db-stepper/Spec/stepper-playground-example.json b/aef6db-stepper/Spec/stepper-playground-example.json
new file mode 100644
index 00000000..91947b3e
--- /dev/null
+++ b/aef6db-stepper/Spec/stepper-playground-example.json
@@ -0,0 +1,45 @@
+{
+  "data": {
+    "meta": {
+      "adoptsFrom": {
+        "name": "Spec",
+        "module": "@cardstack/base/spec"
+      }
+    },
+    "type": "card",
+    "attributes": {
+      "ref": {
+        "name": "StepperPlayground",
+        "module": "../example/stepper-playground-example"
+      },
+      "readMe": "## Stepper Playground\n\nA config explorer for `<Stepper>`. Live preview on top, knobs for `@modal` (inline vs scrim + centered card) and `@allowStepJump` below it, then the generated invocation and the full API reference. Colors, fonts, and radius come from the linked theme (cardInfo.theme) via the semantic tokens (`--primary` / `--primary-foreground`, `--foreground`, `--muted`, `--card`, `--border`, `--radius`, `--font-sans`) — link a different Theme card and the whole stepper restyles with no stepper-specific work.\n\nThe live 4-step demo's completion gating is REAL: step 1 completes when you type a name, step 2 when you pick a workspace — exactly how a product wires `isComplete` to its own state. Step 3 sets `optional: true` so a Skip button appears (MUI-style); the steps before it are linear. The last step shows the `@finishLabel` / `@onFinish` primary button, and an event line above the stage prints every `onStepChange` / `onClose` / `onFinish` as it fires.\n\nThis is the **teaching example** for the Stepper API — the generated-code panel prints the exact invocation for the current knob combination.",
+      "cardInfo": {
+        "name": null,
+        "notes": null,
+        "summary": null,
+        "cardThumbnailURL": null
+      },
+      "specType": "card",
+      "cardTitle": "Stepper Playground",
+      "cardDescription": "A live config explorer for <Stepper> — modal and step-jump knobs over a real gated 4-step demo that follows the linked theme, with the generated invocation printed alongside. The teaching example for the Stepper API.",
+      "containedExamples": []
+    },
+    "relationships": {
+      "cardInfo.theme": {
+        "links": {
+          "self": null
+        }
+      },
+      "linkedExamples.0": {
+        "links": {
+          "self": "../example/StepperPlayground/c76678a0-a2ee-4142-a3d7-a9f537df7c52"
+        }
+      },
+      "cardInfo.cardThumbnail": {
+        "links": {
+          "self": null
+        }
+      }
+    }
+  }
+}
diff --git a/aef6db-stepper/Spec/stepper.json b/aef6db-stepper/Spec/stepper.json
new file mode 100644
index 00000000..2014bc9b
--- /dev/null
+++ b/aef6db-stepper/Spec/stepper.json
@@ -0,0 +1,45 @@
+{
+  "data": {
+    "meta": {
+      "adoptsFrom": {
+        "name": "Spec",
+        "module": "@cardstack/base/spec"
+      }
+    },
+    "type": "card",
+    "attributes": {
+      "ref": {
+        "name": "default",
+        "module": "../stepper"
+      },
+      "readMe": "## Stepper\n\nA general multi-step flow shell — the \"guideline book\" that walks a user through a journey (a first-run wizard, an onboarding flow, a setup checklist) *before* they start using an app. Two-pane layout: a vertical step rail on the left (numbered dots, ✓ done state, active ring, connector lines) and the active step's content on the right, closed out by a Back / Skip / Next action bar built from boxel-ui `<Button>`.\n\nThe first consumer is the Table Seating Planner's setup wizard; the component carries no wedding-specific anything — every product supplies its own steps, content, and brand.\n\n### Ownership split\n\nThe **host** owns the step definitions (labels, completion state) and each step's content, supplied through the `<:step>` named block. The **Stepper** owns the step state machine, the rail's done/active painting, gating Next on `isComplete`, and the shell chrome (header, action bar, optional modal scrim). The component never closes itself — visibility stays with the host, exactly like Popover's `@open`.\n\n### Steps — `StepperStep[]`\n\n```ts\ninterface StepperStep {\n  id: string;            // dispatch key for the <:step> block\n  label: string;         // rail label ('Your event')\n  summary?: string;      // rail sub-line while pending; swaps to 'Completed' when done\n  title?: string;        // content-pane heading (defaults to label)\n  description?: string;  // content-pane sub-line\n  icon?: ComponentLike;  // lead icon circle above the title\n  isComplete?: boolean;  // gates Next + paints the rail ✓; omit = never gates\n  optional?: boolean;    // shows a Skip button on this step (MUI-style)\n}\n```\n\n- **Completion gating is host-wired**: point `isComplete` at your own state (`this.name.length > 0`, `this.guests.length > 0`) and Next unlocks/locks live.\n- **Skip is per-step opt-in** (`optional: true`), following the MUI Stepper convention — linear steps get no Skip button. `api.skip` remains available for custom action bars.\n\n### Args\n\n| Arg | Purpose |\n| --- | --- |\n| `@steps` | the `StepperStep[]` above |\n| `@modal` | wrap in a scrim + centered card (`position: absolute; inset: 0` — fills the nearest positioned ancestor). Default inline bordered card |\n| `@kicker` / `@title` | header eyebrow + brand name; header renders only when one of these (or the close button) is present |\n| `@onClose` / `@showClose` | ✕ close — an outlined 30px circle, no fill (same treatment as the seating planner's popover close). `@showClose` defaults to true whenever `@onClose` is set |\n| `@finishLabel` / `@onFinish` | the last step swaps Skip/Next for a single primary button labeled `finishLabel` (default 'Done') |\n| `@onStepChange` | fires `(step, index)` on every step entry — use for enter hooks (e.g. lazy-load data when the user reaches a step) |\n| `@initialStep` | start on a later step (resume) |\n| `@allowStepJump` | click rail items to jump between steps. Off by default so wizards stay linear |\n\n### Blocks\n\n- `<:step as |step api|>` — the active step's content; dispatch on `step.id`. The `api` bundle exposes `next` / `back` / `skip` / `goTo` plus `index` / `isFirst` / `isLast` / `canProceed` for hosts that want custom controls inside the content.\n- `<:actions as |api|>` — replaces the default action bar entirely.\n- `<:decoration>` — renders inside the card for brand art (the seating planner puts its gold corner mandala here).\n\n### Accent & contrast\n\nFills (done dots, connectors, the lead icon circle) paint with the accent; the content ON those fills (✓ glyph, icon) uses a separate foreground so it always reads:\n\n- The fills follow the linked theme's `--primary` with `--primary-foreground` as the on-fill content — themes author this pair as a contrast pairing. With no theme, the fallback is `--boxel-highlight` (bright green) with a dark on-fill color — correct WCAG pairing.\n- For a one-off brand override, set the `--stepper-accent` / `--stepper-accent-fg` pair on a host class (the seating planner sets gold + white).\n- Text on the light rail (active label, kicker) stays ink/muted — accent is for fills only, never light-background text.\n\n### Theming — the theme system drives it\n\nEvery visual value resolves through three scopes, strongest first:\n\n1. **Stepper-only knobs** — `--stepper-*` custom properties set on a host class restyle ONLY the stepper: `--stepper-accent` · `--stepper-accent-fg` · `--stepper-ink` · `--stepper-muted` · `--stepper-surface` (rail bg) · `--stepper-card-bg` · `--stepper-border` · `--stepper-connector` · `--stepper-primary-bg` / `--stepper-primary-fg` (Next button) · `--stepper-kicker-color` · `--stepper-heading-font` · `--stepper-body-font` · `--stepper-radius` · `--stepper-scrim-bg` · `--stepper-shadow`\n2. **Theme semantic tokens** — link a Theme card / Brand Guide and the stepper follows automatically: `--primary` / `--primary-foreground` drive the accent fills, their on-fill content, and the Next button; `--foreground`, `--muted`, `--muted-foreground`, `--card`, `--border`, `--radius`, and `--font-sans` drive text, surfaces, hairlines, corners, and type.\n3. **Built-in neutral defaults** (Boxel tokens) — used with no theme at all.\n\nThe seating planner's Parisian look (navy/gold, Cormorant + Jost) is a scope-1 override — see `wz-theme` in its setup-wizard for the full block.\n\n## Usage\n\nThe **Stepper Playground** example is the canonical reference — knobs for `@modal` and `@allowStepJump` over a live 4-step demo whose gating is real, with a generated-invocation panel; its colors follow the linked theme. The minimal shape:\n\n```gts\nimport Stepper from '../stepper';\nimport type { StepperStep } from '../stepper';\n\nget steps(): StepperStep[] {\n  return [\n    { id: 'event', label: 'Your event', summary: 'Event details',\n      description: 'Tell us about it.', icon: CalendarIcon,\n      isComplete: !!this.title, optional: true },\n    { id: 'template', label: 'Template', summary: 'Choose a layout' },\n  ];\n}\n\n<template>\n  <Stepper\n    @modal={{true}}\n    @steps={{this.steps}}\n    @kicker='Getting started'\n    @title='My Product'\n    @finishLabel='Start blank'\n    @onClose={{this.dismiss}}\n    @onFinish={{this.dismiss}}\n    @onStepChange={{this.stepEntered}}\n  >\n    <:step as |step|>\n      {{#if (eq step.id 'event')}} …event form… {{else}} …template list… {{/if}}\n    </:step>\n  </Stepper>\n</template>\n```\n\nCross-realm import: `@cardstack/catalog/aef6db-stepper/stepper`.",
+      "cardInfo": {
+        "name": null,
+        "notes": null,
+        "summary": null,
+        "cardThumbnailURL": null
+      },
+      "specType": "component",
+      "cardTitle": "Stepper",
+      "cardDescription": "A multi-step flow shell for first-run wizards and onboarding journeys: vertical step rail, per-step completion gating, MUI-style optional steps, boxel-ui buttons, and theme-driven styling (--primary/--primary-foreground pair) with --stepper-* override knobs.",
+      "containedExamples": []
+    },
+    "relationships": {
+      "cardInfo.theme": {
+        "links": {
+          "self": null
+        }
+      },
+      "linkedExamples": {
+        "links": {
+          "self": null
+        }
+      },
+      "cardInfo.cardThumbnail": {
+        "links": {
+          "self": null
+        }
+      }
+    }
+  }
+}
diff --git a/aef6db-stepper/example/StepperPlayground/c76678a0-a2ee-4142-a3d7-a9f537df7c52.json b/aef6db-stepper/example/StepperPlayground/c76678a0-a2ee-4142-a3d7-a9f537df7c52.json
new file mode 100644
index 00000000..a6d75bb1
--- /dev/null
+++ b/aef6db-stepper/example/StepperPlayground/c76678a0-a2ee-4142-a3d7-a9f537df7c52.json
@@ -0,0 +1,32 @@
+{
+  "data": {
+    "meta": {
+      "adoptsFrom": {
+        "name": "StepperPlayground",
+        "module": "@cardstack/catalog/aef6db-stepper/example/stepper-playground-example"
+      }
+    },
+    "type": "card",
+    "attributes": {
+      "title": "Stepper Playground Example",
+      "cardInfo": {
+        "name": "Stepper Playground Example",
+        "notes": null,
+        "summary": null,
+        "cardThumbnailURL": null
+      }
+    },
+    "relationships": {
+      "cardInfo.theme": {
+        "links": {
+          "self": null
+        }
+      },
+      "cardInfo.cardThumbnail": {
+        "links": {
+          "self": null
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/aef6db-stepper/example/stepper-playground-example.gts b/aef6db-stepper/example/stepper-playground-example.gts
new file mode 100644
index 00000000..4dc68375
--- /dev/null
+++ b/aef6db-stepper/example/stepper-playground-example.gts
@@ -0,0 +1,544 @@
+import {
+  CardDef,
+  field,
+  contains,
+  Component,
+} from 'https://cardstack.com/base/card-api';
+import StringField from 'https://cardstack.com/base/string';
+import { tracked } from '@glimmer/tracking';
+
+import { on } from '@ember/modifier';
+import { eq } from '@cardstack/boxel-ui/helpers';
+import { BoxelSelect } from '@cardstack/boxel-ui/components';
+import UserIcon from '@cardstack/boxel-icons/user';
+import SettingsIcon from '@cardstack/boxel-icons/settings';
+import UsersIcon from '@cardstack/boxel-icons/users';
+import RocketIcon from '@cardstack/boxel-icons/rocket';
+
+import Stepper from '../stepper';
+import type { StepperStep } from '../stepper';
+import CodeSnippet from '../../components/code-snippet';
+
+/**
+ * A config explorer for `<Stepper>` — the multi-step "guideline book"
+ * shell that walks a user through a journey (a first-run wizard, an
+ * onboarding flow) before they start using an app. The playground runs a
+ * live 4-step demo whose completion gating is REAL: step 1 completes
+ * when you type a name, step 2 when you pick a workspace — exactly how a
+ * product wires `isComplete` to its own state. Knobs toggle modal mode
+ * and rail jumping; colors, fonts, and radius come from the linked theme
+ * (cardInfo.theme) via the semantic tokens — link a different Theme card
+ * and the whole stepper restyles.
+ */
+class StepperPlaygroundIsolated extends Component<typeof StepperPlayground> {
+  // ── knobs ──
+  modalOptions = ['inline', 'modal'];
+  jumpOptions = ['off', 'on'];
+
+  @tracked modalOn = false;
+  @tracked jumpOn = false;
+
+  setModal = (value: string): void => {
+    this.modalOn = value === 'modal';
+    // Re-open the demo when switching into modal so there is something
+    // to see behind the knob.
+    if (this.modalOn) this.dismissed = false;
+  };
+  setJump = (value: string): void => {
+    this.jumpOn = value === 'on';
+  };
+
+  get modalChoice(): string {
+    return this.modalOn ? 'modal' : 'inline';
+  }
+  get jumpChoice(): string {
+    return this.jumpOn ? 'on' : 'off';
+  }
+
+  // ── demo state the steps gate on (host-owned, like a real product) ──
+  @tracked name = '';
+  @tracked workspace: string | undefined = undefined;
+  @tracked invited = 0;
+  @tracked dismissed = false;
+  @tracked lastEvent = '—';
+
+  workspaceOptions = ['Personal', 'Team', 'Enterprise'];
+
+  setName = (event: Event): void => {
+    this.name = (event.target as HTMLInputElement).value;
+  };
+  setWorkspace = (value: string): void => {
+    this.workspace = value;
+  };
+  invite = (): void => {
+    this.invited += 1;
+  };
+
+  /** The playground's step definitions — `isComplete` is wired to live
+   *  demo state, so Next unlocks the moment the step's input is filled. */
+  get steps(): StepperStep[] {
+    return [
+      {
+        id: 'details',
+        label: 'Your details',
+        summary: 'Name yourself',
+        title: 'Your details',
+        description: 'Type a name below — Next unlocks when it is non-empty.',
+        icon: UserIcon,
+        isComplete: this.name.trim().length > 0,
+      },
+      {
+        id: 'workspace',
+        label: 'Workspace',
+        summary: 'Pick a plan',
+        title: 'Workspace',
+        description: 'Pick a workspace type to complete this step.',
+        icon: SettingsIcon,
+        isComplete: this.workspace !== undefined,
+      },
+      {
+        id: 'team',
+        label: 'Invite team',
+        summary: 'Optional',
+        title: 'Invite team',
+        description:
+          'This step sets optional: true, so a Skip button appears (MUI-style optional step). The two steps before it are linear — no Skip. It also has no isComplete, so Next never gates.',
+        icon: UsersIcon,
+        optional: true,
+      },
+      {
+        id: 'launch',
+        label: 'Launch',
+        summary: 'Ready to go',
+        title: 'Ready to launch',
+        description:
+          'The last step swaps Skip/Next for a single finish button (@finishLabel / @onFinish).',
+        icon: RocketIcon,
+      },
+    ];
+  }
+
+  stepEntered = (step: StepperStep, index: number): void => {
+    this.lastEvent = `onStepChange → '${step.id}' (index ${index})`;
+  };
+  handleClose = (): void => {
+    this.lastEvent = 'onClose fired';
+    this.dismissed = true;
+  };
+  handleFinish = (): void => {
+    this.lastEvent = 'onFinish fired';
+    this.dismissed = true;
+  };
+  reopen = (): void => {
+    this.dismissed = false;
+  };
+
+  /** Generated invocation reflecting every current selection. */
+  get previewCode(): string {
+    const lines = [`<Stepper`];
+    if (this.modalOn) lines.push(`  @modal={{true}}`);
+    lines.push(
+      `  @steps={{this.steps}}`,
+      `  @kicker='Getting started'`,
+      `  @title='Stepper Playground'`,
+      `  @finishLabel='Launch app'`,
+      `  @onClose={{this.handleClose}}`,
+      `  @onFinish={{this.handleFinish}}`,
+      `  @onStepChange={{this.stepEntered}}`,
+    );
+    if (this.jumpOn) lines.push(`  @allowStepJump={{true}}`);
+    lines.push(
+      `>`,
+      `  <:step as |step api|>`,
+      `    {{#if (eq step.id 'details')}} …details form… {{/if}}`,
+      `  </:step>`,
+      `</Stepper>`,
+    );
+    return lines.join('\n');
+  }
+
+  <template>
+    <div class='sp'>
+      <div class='sp-section'>Live preview
+        <span class='sp-event'>last event: {{this.lastEvent}}</span></div>
+      <div class='sp-stage'>
+        {{#if this.dismissed}}
+          <button
+            type='button'
+            class='sp-reopen'
+            {{on 'click' this.reopen}}
+          >Wizard closed — click to reopen</button>
+        {{else}}
+          <Stepper
+            @modal={{this.modalOn}}
+            @steps={{this.steps}}
+            @kicker='Getting started'
+            @title='Stepper Playground'
+            @finishLabel='Launch app'
+            @onClose={{this.handleClose}}
+            @onFinish={{this.handleFinish}}
+            @onStepChange={{this.stepEntered}}
+            @allowStepJump={{this.jumpOn}}
+          >
+            <:step as |step|>
+              {{#if (eq step.id 'details')}}
+                <label class='sp-field'>Name
+                  <input
+                    type='text'
+                    value={{this.name}}
+                    placeholder='e.g. Ada Lovelace'
+                    {{on 'input' this.setName}}
+                  />
+                </label>
+              {{else if (eq step.id 'workspace')}}
+                <div class='sp-pick'>
+                  <BoxelSelect
+                    @options={{this.workspaceOptions}}
+                    @selected={{this.workspace}}
+                    @onChange={{this.setWorkspace}}
+                    @placeholder='Pick a workspace…'
+                    as |item|
+                  >
+                    {{item}}
+                  </BoxelSelect>
+                </div>
+              {{else if (eq step.id 'team')}}
+                <div class='sp-invite'>
+                  <span>{{this.invited}} teammate(s) invited</span>
+                  <button
+                    type='button'
+                    class='sp-invite-btn'
+                    {{on 'click' this.invite}}
+                  >+ Invite</button>
+                </div>
+              {{else}}
+                <p class='sp-done'>Everything's set{{if this.name ', '}}
+                  {{this.name}}. Hit
+                  <strong>Launch app</strong>
+                  to fire
+                  <code>@onFinish</code>.</p>
+              {{/if}}
+            </:step>
+          </Stepper>
+        {{/if}}
+      </div>
+
+      <div class='sp-section'>Configuration</div>
+      <div class='sp-axes'>
+        <div class='sp-axis'>
+          <span class='sp-label'>@modal</span>
+          <BoxelSelect
+            @options={{this.modalOptions}}
+            @selected={{this.modalChoice}}
+            @onChange={{this.setModal}}
+            @placeholder='Choose…'
+            as |item|
+          >
+            {{item}}
+          </BoxelSelect>
+          <span class='sp-desc'><code>inline</code>
+            renders the shell as a plain bordered card;
+            <code>modal</code>
+            wraps it in a scrim + centered card — the first-run-wizard mode.</span>
+        </div>
+        <div class='sp-axis'>
+          <span class='sp-label'>@allowStepJump</span>
+          <BoxelSelect
+            @options={{this.jumpOptions}}
+            @selected={{this.jumpChoice}}
+            @onChange={{this.setJump}}
+            @placeholder='Choose…'
+            as |item|
+          >
+            {{item}}
+          </BoxelSelect>
+          <span class='sp-desc'>When
+            <code>on</code>, clicking a rail item jumps straight to that step.
+            Off by default so a wizard stays linear.</span>
+        </div>
+      </div>
+
+      <div class='sp-section'>Generated code</div>
+      <CodeSnippet @code={{this.previewCode}} />
+
+      <div class='sp-section'>Reference — the full API</div>
+      <div class='sp-args'>
+        <div class='sp-arg'>
+          <code>@steps</code>
+          <span>Array of
+            <code>StepperStep</code>:
+            <code>id</code>,
+            <code>label</code>
+            (rail),
+            <code>summary</code>
+            (rail sub-line, swaps to “Completed” when done),
+            <code>title</code>/<code>description</code>
+            (content-pane heading),
+            <code>icon</code>
+            (lead circle), and
+            <code>isComplete</code>
+            — wire it to your own state; while false it disables Next and once
+            true it paints the rail ✓. Omit it for steps that never gate. Add
+            <code>optional: true</code>
+            to show a Skip button on that step (like MUI's optional steps) —
+            linear steps get no Skip.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>&lt;:step as |step api|&gt;</code>
+          <span>The content pane for the active step — dispatch on
+            <code>step.id</code>. The
+            <code>api</code>
+            bundle exposes
+            <code>next</code>/<code>back</code>/<code>skip</code>/<code
+            >goTo</code>
+            plus
+            <code>index</code>/<code>isFirst</code>/<code>isLast</code>/<code
+            >canProceed</code>
+            for hosts that want custom controls inside the content.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>&lt;:actions&gt;</code>
+          /
+          <code>&lt;:decoration&gt;</code>
+          <span><code>:actions</code>
+            replaces the default Back/Skip/Next bar entirely (receives the same
+            api);
+            <code>:decoration</code>
+            renders inside the card for brand art — the seating planner puts its
+            gold corner mandala there.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>@modal</code>
+          <span>Wraps the shell in a scrim + centered card. The scrim is
+            <code>position: absolute; inset: 0</code>
+            so it fills the nearest positioned ancestor — your card's isolated
+            view.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>@kicker</code>
+          /
+          <code>@title</code>
+          <span>Header chrome. The header only renders when one of these (or
+            <code>@onClose</code>) is present, so a bare stepper stays
+            chrome-free. The close button is an outlined circle ✕ — same
+            treatment as the seating planner's popover close.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>@onClose</code>
+          /
+          <code>@onFinish</code>
+          /
+          <code>@finishLabel</code>
+          <span><code>onClose</code>
+            backs the header ✕ (hide it by passing false to
+            <code>@showClose</code>) and the
+            <code>api.skip</code>
+            fallback on the last step;
+            <code>onFinish</code>
+            backs the last-step primary button labeled
+            <code>finishLabel</code>
+            (default “Done”). The component never closes itself — the host owns
+            visibility, exactly like Popover's
+            <code>@open</code>.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>@onStepChange</code>
+          <span>Fires on every step entry (Next / Skip / goTo) with
+            <code>(step, index)</code>. Use it for enter hooks — the seating
+            planner lazy-loads its templates when the user reaches the template
+            step.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>@initialStep</code>
+          /
+          <code>@allowStepJump</code>
+          <span>Start on a later step (resume), and let users click rail items
+            to jump.</span>
+        </div>
+        <div class='sp-arg'>
+          <code>Theming</code>
+          <span>The stepper follows the linked theme automatically: every visual
+            value resolves
+            <code>--stepper-*</code>
+            knob → theme semantic token → neutral default. The accent fills and
+            their on-fill content pair come from
+            <code>--primary</code>
+            /
+            <code>--primary-foreground</code>; text, surfaces, borders, radius,
+            and fonts come from
+            <code>--foreground</code>,
+            <code>--muted</code>,
+            <code>--muted-foreground</code>,
+            <code>--card</code>,
+            <code>--border</code>,
+            <code>--radius</code>, and
+            <code>--font-sans</code>. Link a Theme card (cardInfo.theme) or
+            Brand Guide and the whole stepper restyles with no stepper-specific
+            work. For a one-off brand override, set the
+            <code>--stepper-accent</code>
+            /
+            <code>--stepper-accent-fg</code>
+            pair on a host class.</span>
+        </div>
+      </div>
+    </div>
+
+    <style scoped>
+      .sp {
+        display: grid;
+        gap: 16px;
+        padding: 24px;
+        max-width: 900px;
+        font:
+          14px/1.4 system-ui,
+          sans-serif;
+      }
+      .sp-section {
+        display: flex;
+        align-items: baseline;
+        gap: 12px;
+        font-size: 11px;
+        font-weight: 700;
+        text-transform: uppercase;
+        letter-spacing: 0.06em;
+        color: #6b7280;
+      }
+      .sp-event {
+        font-weight: 500;
+        text-transform: none;
+        letter-spacing: normal;
+        font-family: ui-monospace, monospace;
+        font-size: 11px;
+        color: #4338ca;
+      }
+      .sp-axes {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+        gap: 12px;
+      }
+      .sp-axis {
+        display: grid;
+        gap: 6px;
+        align-content: start;
+      }
+      .sp-label {
+        font-size: 11px;
+        font-weight: 600;
+        color: #4338ca;
+      }
+      .sp-desc {
+        font-size: 11px;
+        line-height: 1.5;
+        color: #6b7280;
+      }
+      .sp-desc code,
+      .sp-arg code {
+        font-family: ui-monospace, monospace;
+        font-size: 10px;
+        color: #4338ca;
+        background: #eef2ff;
+        padding: 1px 4px;
+        border-radius: 3px;
+      }
+      .sp-stage {
+        position: relative;
+        height: 480px;
+        width: 100%;
+        background: #e5e7eb;
+        border-radius: 10px;
+        overflow: hidden;
+        contain: layout size;
+        display: grid;
+        place-items: center;
+        padding: 16px;
+      }
+      .sp-reopen {
+        padding: 10px 20px;
+        border: 1.5px dashed #9ca3af;
+        border-radius: 8px;
+        background: #fff;
+        cursor: pointer;
+        font: inherit;
+        font-size: 13px;
+        color: #374151;
+      }
+      /* demo step content */
+      .sp-field {
+        display: flex;
+        flex-direction: column;
+        gap: 4px;
+        margin-top: 20px;
+        max-width: 380px;
+        font-size: 12px;
+        color: rgba(0, 0, 0, 0.65);
+      }
+      .sp-field input {
+        padding: 10px 12px;
+        border: 1px solid rgba(0, 0, 0, 0.18);
+        border-radius: 10px;
+        font: inherit;
+        font-size: 14px;
+      }
+      .sp-pick {
+        margin-top: 20px;
+        max-width: 380px;
+      }
+      .sp-invite {
+        margin-top: 20px;
+        padding: 16px;
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        max-width: 380px;
+        border: 1.5px dashed rgba(0, 0, 0, 0.2);
+        border-radius: 16px;
+        font-size: 14px;
+        color: rgba(0, 0, 0, 0.7);
+      }
+      .sp-invite-btn {
+        padding: 8px 16px;
+        border: 1px solid rgba(0, 0, 0, 0.25);
+        border-radius: 999px;
+        background: transparent;
+        cursor: pointer;
+        font: inherit;
+        font-size: 13px;
+      }
+      .sp-done {
+        margin: 20px 0 0;
+        font-size: 14px;
+        color: rgba(0, 0, 0, 0.7);
+        max-width: 48ch;
+      }
+      .sp-args {
+        margin: 0;
+        display: grid;
+        gap: 8px;
+      }
+      .sp-arg {
+        display: grid;
+        grid-template-columns: 220px 1fr;
+        gap: 12px;
+        align-items: baseline;
+        font-size: 12px;
+      }
+      .sp-arg span {
+        color: #4b5563;
+      }
+      @media (max-width: 520px) {
+        .sp-arg {
+          grid-template-columns: 1fr;
+          gap: 2px;
+        }
+      }
+    </style>
+  </template>
+}
+
+export class StepperPlayground extends CardDef {
+  static displayName = 'Stepper Playground';
+
+  @field title = contains(StringField);
+
+  static isolated = StepperPlaygroundIsolated;
+}
diff --git a/aef6db-stepper/stepper.gts b/aef6db-stepper/stepper.gts
new file mode 100644
index 00000000..0867da87
--- /dev/null
+++ b/aef6db-stepper/stepper.gts
@@ -0,0 +1,689 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { Button } from '@cardstack/boxel-ui/components';
+import { eq, not } from '@cardstack/boxel-ui/helpers';
+import type { ComponentLike } from '@glint/template';
+
+/**
+ * `<Stepper>` — a general multi-step flow shell: a vertical step rail on
+ * the left, the active step's content on the right, and a Back / Skip /
+ * Next action bar. Optionally renders as a modal (scrim + centered card)
+ * for first-run wizards.
+ *
+ * **What the host owns.** The step definitions (labels, completion
+ * state) and each step's content, supplied through the `<:step>` block,
+ * which receives the active step plus a navigation API. The Stepper owns
+ * the step state machine, the rail's done/active states, gating Next on
+ * `isComplete`, and the shell chrome (header, action bar, modal scrim).
+ *
+ * **Theming.** Every visual value resolves through three scopes,
+ * strongest first — so a linked Theme card / Brand Guide restyles the
+ * stepper with no stepper-specific work:
+ *
+ *   1. `--stepper-*` knobs — set on a host class to restyle ONLY the
+ *      stepper.
+ *   2. Theme semantic tokens — `--primary` / `--primary-foreground`
+ *      (accent fills + on-fill content, also the Next button),
+ *      `--foreground`, `--muted`, `--muted-foreground`, `--card`,
+ *      `--border`, `--radius`, `--font-sans`. Author a normal theme and
+ *      the stepper follows automatically.
+ *   3. Built-in neutral defaults (Boxel tokens), used with no theme at
+ *      all.
+ *
+ * The `--stepper-*` knob catalog:
+ *
+ *   --stepper-accent        done/active fills (dots, connectors, lead circle)
+ *   --stepper-accent-fg     content ON accent fills (✓ glyph, lead icon)
+ *   --stepper-ink           body text color
+ *   --stepper-muted         secondary text color
+ *   --stepper-surface       rail background
+ *   --stepper-card-bg       card background (modal card / shell)
+ *   --stepper-border        rail/card hairlines
+ *   --stepper-connector     pending rail connectors + dot rings
+ *   --stepper-primary-bg    primary button background
+ *   --stepper-primary-fg    primary button text
+ *   --stepper-kicker-color  header eyebrow text (defaults to muted)
+ *   --stepper-heading-font  step titles + rail labels
+ *   --stepper-body-font     everything else
+ *   --stepper-radius        card corner radius
+ *   --stepper-scrim-bg      modal backdrop
+ *   --stepper-shadow        modal card shadow
+ */
+
+export interface StepperStep {
+  id: string;
+  /** Rail label (e.g. 'Your event'). */
+  label: string;
+  /** Rail sub-line while the step is pending (e.g. 'Event details'). */
+  summary?: string;
+  /** Content-pane heading; defaults to `label`. */
+  title?: string;
+  /** Content-pane sub-line under the heading. */
+  description?: string;
+  /** Optional lead icon rendered in a circle above the title. */
+  icon?: ComponentLike<{ Element: Element }>;
+  /** Gates Next and paints the rail ✓; `undefined` = always proceedable. */
+  isComplete?: boolean;
+  /** Marks the step skippable — a Skip button appears beside Next
+   *  (MUI-style optional step). Linear steps omit this. */
+  optional?: boolean;
+}
+
+export interface StepperApi {
+  index: number;
+  isFirst: boolean;
+  isLast: boolean;
+  canProceed: boolean;
+  next: () => void;
+  back: () => void;
+  /** Advance without gating; on the last step calls `onClose`. */
+  skip: () => void;
+  goTo: (index: number) => void;
+}
+
+interface StepperSignature {
+  Element: HTMLDivElement;
+  Args: {
+    steps: StepperStep[];
+    /** Wrap the shell in a scrim + centered card. Default false. */
+    modal?: boolean;
+    /** Header brand name; header renders when this or `onClose` is set. */
+    title?: string;
+    /** Header eyebrow above the brand name (e.g. 'Getting started'). */
+    kicker?: string;
+    /** Last-step primary button label. Default 'Done'. */
+    finishLabel?: string;
+    /** Starting step index. Default 0. */
+    initialStep?: number;
+    /** Header ✕ and last-step Skip. Close button renders only if set. */
+    onClose?: () => void;
+    /** Show the header ✕. Default: true whenever `onClose` is set. */
+    showClose?: boolean;
+    /** Last-step primary button; the button renders only if set. */
+    onFinish?: () => void;
+    /** Fired whenever a step is entered (Next / Skip / goTo). */
+    onStepChange?: (step: StepperStep, index: number) => void;
+    /** Allow clicking rail items to jump between steps. Default false. */
+    allowStepJump?: boolean;
+  };
+  Blocks: {
+    step: [StepperStep, StepperApi];
+    actions?: [StepperApi];
+    decoration?: [];
+  };
+}
+
+export default class Stepper extends Component<StepperSignature> {
+  @tracked index = this.args.initialStep ?? 0;
+
+  get steps(): StepperStep[] {
+    return this.args.steps ?? [];
+  }
+  get current(): StepperStep | undefined {
+    return this.steps[this.index];
+  }
+  get isFirst(): boolean {
+    return this.index === 0;
+  }
+  get isLast(): boolean {
+    return this.index >= this.steps.length - 1;
+  }
+  get canProceed(): boolean {
+    return this.current?.isComplete ?? true;
+  }
+  get finishLabel(): string {
+    return this.args.finishLabel ?? 'Done';
+  }
+  get showHeader(): boolean {
+    return Boolean(this.args.title || this.args.kicker || this.showClose);
+  }
+  get showClose(): boolean {
+    return this.args.showClose ?? Boolean(this.args.onClose);
+  }
+  get currentOptional(): boolean {
+    return this.current?.optional ?? false;
+  }
+  get api(): StepperApi {
+    return {
+      index: this.index,
+      isFirst: this.isFirst,
+      isLast: this.isLast,
+      canProceed: this.canProceed,
+      next: this.next,
+      back: this.back,
+      skip: this.skip,
+      goTo: this.goTo,
+    };
+  }
+
+  private enter = (index: number) => {
+    if (index < 0 || index >= this.steps.length) return;
+    this.index = index;
+    let step = this.steps[index];
+    if (step) this.args.onStepChange?.(step, index);
+  };
+  next = () => {
+    if (!this.isLast) this.enter(this.index + 1);
+  };
+  back = () => {
+    if (!this.isFirst) this.index -= 1;
+  };
+  skip = () => {
+    if (!this.isLast) this.enter(this.index + 1);
+    else this.args.onClose?.();
+  };
+  goTo = (index: number) => {
+    this.enter(index);
+  };
+  railJump = (index: number) => {
+    if (this.args.allowStepJump) this.enter(index);
+  };
+
+  stepNumber = (index: number): string => {
+    return String(index + 1).padStart(2, '0');
+  };
+
+  <template>
+    <div class='stepper-shell {{if @modal "stepper-scrim"}}' ...attributes>
+      <div class='stepper-card {{unless @modal "stepper-inline"}}'>
+        {{yield to='decoration'}}
+        {{#if this.showHeader}}
+          <div class='stepper-top'>
+            <div class='stepper-brand'>
+              {{#if @kicker}}<span
+                  class='stepper-kicker'
+                >{{@kicker}}</span>{{/if}}
+              {{#if @title}}<span
+                  class='stepper-brand-name'
+                >{{@title}}</span>{{/if}}
+            </div>
+            {{#if this.showClose}}
+              {{#if @onClose}}
+                <button
+                  type='button'
+                  class='stepper-close'
+                  aria-label='Close'
+                  {{on 'click' @onClose}}
+                >✕</button>
+              {{/if}}
+            {{/if}}
+          </div>
+        {{/if}}
+        <div class='stepper-body'>
+          <ol class='stepper-rail'>
+            {{#each this.steps as |step i|}}
+              <li
+                class='stepper-step
+                  {{if step.isComplete "is-done"}}
+                  {{if (eq this.index i) "is-active"}}
+                  {{if @allowStepJump "is-jumpable"}}'
+                {{on 'click' (fn this.railJump i)}}
+              >
+                <span class='stepper-dot'>{{if
+                    step.isComplete
+                    '✓'
+                    (this.stepNumber i)
+                  }}</span>
+                <span class='stepper-step-txt'>
+                  <span class='stepper-step-k'>Step {{this.stepNumber i}}</span>
+                  <span class='stepper-step-l'>{{step.label}}</span>
+                  {{#if step.summary}}
+                    <span class='stepper-step-s'>{{if
+                        step.isComplete
+                        'Completed'
+                        step.summary
+                      }}</span>
+                  {{/if}}
+                </span>
+              </li>
+            {{/each}}
+          </ol>
+          <div class='stepper-main'>
+            <div class='stepper-content'>
+              {{#if this.current}}
+                {{#if this.current.icon}}
+                  <div class='stepper-lead'><this.current.icon
+                      width='26'
+                      height='26'
+                    /></div>
+                {{/if}}
+                {{#if this.current.title}}
+                  <h1 class='stepper-title'>{{this.current.title}}</h1>
+                {{else}}
+                  <h1 class='stepper-title'>{{this.current.label}}</h1>
+                {{/if}}
+                {{#if this.current.description}}
+                  <p class='stepper-sub'>{{this.current.description}}</p>
+                {{/if}}
+                {{yield this.current this.api to='step'}}
+              {{/if}}
+            </div>
+            {{#if (has-block 'actions')}}
+              {{yield this.api to='actions'}}
+            {{else}}
+              <div class='stepper-actions'>
+                {{#unless this.isFirst}}
+                  <Button
+                    @kind='text-only'
+                    class='stepper-ghost stepper-back'
+                    {{on 'click' this.back}}
+                  >Back</Button>
+                {{/unless}}
+                {{#if this.isLast}}
+                  {{#if @onFinish}}
+                    <Button
+                      @kind='primary'
+                      class='stepper-primary'
+                      {{on 'click' @onFinish}}
+                    >{{this.finishLabel}}</Button>
+                  {{/if}}
+                {{else}}
+                  {{#if this.currentOptional}}
+                    <Button
+                      @kind='text-only'
+                      class='stepper-ghost'
+                      {{on 'click' this.skip}}
+                    >Skip</Button>
+                  {{/if}}
+                  <Button
+                    @kind='primary'
+                    @disabled={{not this.canProceed}}
+                    class='stepper-primary'
+                    {{on 'click' this.next}}
+                  >Next</Button>
+                {{/if}}
+              </div>
+            {{/if}}
+          </div>
+        </div>
+      </div>
+    </div>
+    <style scoped>
+      .stepper-shell {
+        box-sizing: border-box;
+        width: 100%;
+        height: 100%;
+        container-type: inline-size;
+        container-name: stepper;
+      }
+      .stepper-scrim {
+        position: absolute;
+        inset: 0;
+        z-index: 200;
+        display: grid;
+        place-items: center;
+        padding: var(--boxel-sp, 16px);
+        background: var(--stepper-scrim-bg, rgba(0, 0, 0, 0.3));
+        backdrop-filter: blur(2px);
+      }
+      .stepper-card {
+        box-sizing: border-box;
+        position: relative;
+        display: flex;
+        flex-direction: column;
+        width: 100%;
+        height: 100%;
+        padding: 26px 30px;
+        overflow: hidden;
+        background: var(
+          --stepper-card-bg,
+          var(--card, var(--boxel-light, #ffffff))
+        );
+        border-radius: var(
+          --stepper-radius,
+          var(--radius, var(--boxel-border-radius-xl, 18px))
+        );
+        box-shadow: var(--stepper-shadow, 0 20px 60px rgba(0, 0, 0, 0.25));
+        font-family: var(
+          --stepper-body-font,
+          var(--font-sans, var(--boxel-font-family, system-ui, sans-serif))
+        );
+        color: var(
+          --stepper-ink,
+          var(--foreground, var(--boxel-dark, #222222))
+        );
+      }
+      .stepper-inline {
+        box-shadow: none;
+        border: 1px solid
+          var(--stepper-border, var(--border, rgba(0, 0, 0, 0.1)));
+      }
+      .stepper-top {
+        display: flex;
+        align-items: flex-start;
+        justify-content: space-between;
+      }
+      .stepper-brand {
+        display: flex;
+        flex-direction: column;
+        gap: 2px;
+      }
+      .stepper-kicker {
+        font-size: 10px;
+        letter-spacing: 0.24em;
+        text-transform: uppercase;
+        color: var(
+          --stepper-kicker-color,
+          var(--stepper-muted, var(--muted-foreground, rgba(0, 0, 0, 0.6)))
+        );
+      }
+      .stepper-brand-name {
+        font-family: var(--stepper-heading-font, inherit);
+        font-size: 21px;
+        font-weight: 600;
+      }
+      /* Outlined circle ✕, no fill — same treatment as the seating
+         planner's popover close button. */
+      .stepper-close {
+        flex: none;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: 30px;
+        height: 30px;
+        border-radius: 50%;
+        border: 1px solid
+          var(--stepper-border, var(--border, rgba(0, 0, 0, 0.15)));
+        background: transparent;
+        color: var(
+          --stepper-muted,
+          var(--muted-foreground, rgba(0, 0, 0, 0.55))
+        );
+        font-size: 12px;
+        line-height: 1;
+        cursor: pointer;
+        transition: 0.15s;
+      }
+      .stepper-close:hover {
+        border-color: var(
+          --stepper-ink,
+          var(--foreground, var(--boxel-dark, #222222))
+        );
+        color: var(
+          --stepper-ink,
+          var(--foreground, var(--boxel-dark, #222222))
+        );
+      }
+      .stepper-body {
+        flex: 1;
+        min-height: 0;
+        display: flex;
+        gap: 32px;
+        margin-top: 18px;
+      }
+      .stepper-rail {
+        flex: none;
+        width: 232px;
+        margin: 0;
+        padding: 22px 18px;
+        list-style: none;
+        display: flex;
+        flex-direction: column;
+        gap: 24px;
+        overflow-y: auto;
+        border: 1px solid
+          var(--stepper-border, var(--border, rgba(0, 0, 0, 0.1)));
+        border-radius: 16px;
+        background: var(
+          --stepper-surface,
+          var(--muted, var(--boxel-100, #f8f8f8))
+        );
+      }
+      .stepper-step {
+        position: relative;
+        display: flex;
+        gap: 14px;
+      }
+      .stepper-step.is-jumpable {
+        cursor: pointer;
+      }
+      .stepper-step:not(:last-child)::before {
+        content: '';
+        position: absolute;
+        left: 15px;
+        top: 34px;
+        bottom: -24px;
+        width: 2px;
+        background: var(
+          --stepper-connector,
+          var(--border, rgba(0, 0, 0, 0.12))
+        );
+      }
+      .stepper-step.is-done:not(:last-child)::before {
+        background: var(
+          --stepper-accent,
+          var(--primary, var(--boxel-highlight, #00ac3d))
+        );
+      }
+      .stepper-dot {
+        flex: none;
+        width: 32px;
+        height: 32px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        border-radius: 50%;
+        border: 2px solid
+          var(--stepper-connector, var(--border, rgba(0, 0, 0, 0.18)));
+        background: var(--stepper-card-bg, var(--card, #ffffff));
+        color: var(
+          --stepper-muted,
+          var(--muted-foreground, rgba(0, 0, 0, 0.5))
+        );
+        font-size: 12px;
+        font-weight: 600;
+        z-index: 1;
+      }
+      /* Accent fill + contrasting on-fill content, sourced from the
+         theme's --primary / --primary-foreground pair; boxel-highlight
+         is bright, so the themeless on-accent fallback is dark. */
+      .stepper-step.is-done .stepper-dot {
+        background: var(
+          --stepper-accent,
+          var(--primary, var(--boxel-highlight, #00ac3d))
+        );
+        border-color: var(
+          --stepper-accent,
+          var(--primary, var(--boxel-highlight, #00ac3d))
+        );
+        color: var(
+          --stepper-accent-fg,
+          var(--primary-foreground, var(--boxel-dark, #000000))
+        );
+      }
+      .stepper-step.is-active .stepper-dot {
+        border-color: var(
+          --stepper-accent,
+          var(--primary, var(--boxel-highlight, #00ac3d))
+        );
+        color: var(
+          --stepper-ink,
+          var(--foreground, var(--boxel-dark, #222222))
+        );
+        box-shadow: 0 0 0 4px
+          color-mix(
+            in srgb,
+            var(
+                --stepper-accent,
+                var(--primary, var(--boxel-highlight, #00ac3d))
+              )
+              16%,
+            transparent
+          );
+      }
+      .stepper-step-txt {
+        display: flex;
+        flex-direction: column;
+        gap: 2px;
+        padding-top: 2px;
+      }
+      .stepper-step-k {
+        font-size: 10px;
+        letter-spacing: 0.18em;
+        text-transform: uppercase;
+        color: var(
+          --stepper-muted,
+          var(--muted-foreground, rgba(0, 0, 0, 0.45))
+        );
+      }
+      .stepper-step-l {
+        font-family: var(--stepper-heading-font, inherit);
+        font-size: 18px;
+        font-weight: 600;
+      }
+      /* Active/done rail TEXT stays ink/muted — accent is for fills
+         only; accent-colored text on the light rail fails contrast. */
+      .stepper-step.is-active .stepper-step-l {
+        color: var(
+          --stepper-ink,
+          var(--foreground, var(--boxel-dark, #222222))
+        );
+      }
+      .stepper-step-s {
+        font-size: 11px;
+        color: var(
+          --stepper-muted,
+          var(--muted-foreground, rgba(0, 0, 0, 0.45))
+        );
+      }
+      .stepper-main {
+        flex: 1;
+        min-width: 0;
+        min-height: 0;
+        display: flex;
+        flex-direction: column;
+      }
+      /* Scroll container for the step's content so tall steps scroll
+         instead of pushing the action bar out of the clipped card. */
+      .stepper-content {
+        flex: 1;
+        min-height: 0;
+        overflow-y: auto;
+        display: flex;
+        flex-direction: column;
+      }
+      .stepper-lead {
+        flex: none;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: 52px;
+        height: 52px;
+        border-radius: 50%;
+        background: var(
+          --stepper-accent,
+          var(--primary, var(--boxel-highlight, #00ac3d))
+        );
+        color: var(
+          --stepper-accent-fg,
+          var(--primary-foreground, var(--boxel-dark, #000000))
+        );
+      }
+      .stepper-title {
+        margin: 12px 0 0;
+        font-family: var(--stepper-heading-font, inherit);
+        font-size: 32px;
+        font-weight: 600;
+      }
+      .stepper-sub {
+        margin: 6px 0 0;
+        font-size: 14px;
+        color: var(
+          --stepper-muted,
+          var(--muted-foreground, rgba(0, 0, 0, 0.65))
+        );
+        max-width: 54ch;
+      }
+      .stepper-actions {
+        display: flex;
+        align-items: center;
+        justify-content: flex-end;
+        gap: 10px;
+        margin-top: auto;
+        padding-top: 16px;
+        border-top: 1px solid
+          var(--stepper-border, var(--border, rgba(0, 0, 0, 0.08)));
+      }
+      .stepper-back {
+        margin-right: auto;
+      }
+      /* Boxel <Button> re-skins: route its CSS API through --stepper-* */
+      .stepper-ghost {
+        --boxel-button-font: 500 13px
+          var(
+            --stepper-body-font,
+            var(--font-sans, var(--boxel-font-family, sans-serif))
+          );
+        color: inherit;
+        opacity: 0.65;
+      }
+      .stepper-ghost:hover {
+        opacity: 1;
+      }
+      /* Anchor the primary button to the theme's --primary /
+         --primary-foreground PAIR (authored together as a contrast
+         pairing) rather than the --boxel-button-primary-* tokens, whose
+         bg and fg can come from different sources and clash. */
+      .stepper-primary,
+      .stepper-primary:not(:disabled):hover,
+      .stepper-primary:not(:disabled):active {
+        --boxel-button-color: var(
+          --stepper-primary-bg,
+          var(--primary, var(--boxel-dark, #222222))
+        );
+        --boxel-button-text-color: var(
+          --stepper-primary-fg,
+          var(--primary-foreground, #ffffff)
+        );
+        --boxel-button-font: 500 13px
+          var(
+            --stepper-body-font,
+            var(--font-sans, var(--boxel-font-family, sans-serif))
+          );
+        --boxel-button-letter-spacing: 0.04em;
+        --boxel-button-padding: 11px 22px;
+        --boxel-button-border-radius: 999px;
+      }
+      .stepper-primary:not(:disabled):hover {
+        filter: brightness(0.92);
+      }
+      .stepper-primary:disabled {
+        opacity: 0.45;
+      }
+      /* Narrow containers: stack the panes — the rail becomes a
+         horizontal scroll strip above the content. */
+      @container stepper (max-width: 560px) {
+        .stepper-card {
+          padding: 18px;
+        }
+        .stepper-body {
+          flex-direction: column;
+          gap: 14px;
+        }
+        .stepper-rail {
+          flex: none;
+          width: 100%;
+          flex-direction: row;
+          gap: 18px;
+          padding: 12px 14px;
+          overflow-x: auto;
+          overflow-y: hidden;
+        }
+        .stepper-step {
+          flex: none;
+        }
+        .stepper-step:not(:last-child)::before {
+          display: none;
+        }
+        .stepper-step-s {
+          display: none;
+        }
+        .stepper-title {
+          font-size: 24px;
+        }
+      }
+    </style>
+  </template>
+}