@maltjoy/mcp-server 0.4.0 → 0.6.0-beta.0

package/dist/doc/VJoyStep/guideline.md

@@ -0,0 +1,182 @@
+---
+component: VJoyStep
+status: draft
+language: en
+dsds: JoyStep.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Step
+
+Use **`VJoyStep`** as one segment in a multi-step progress indicator — a horizontal bar with an optional text label.
+
+Each step shows fill progress for **completed**, **current**, or **upcoming** states. Compose several `VJoyStep` children inside **`VJoyStepper`**, which drives `completed` and `currentSubStep` from its `step` and `subStep` props. Use `subSteps` on a step when that main step has internal sub-progress.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyStep` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Stepper](https://joy.malt.com/6bf479565/p/83eba5-stepper) |
+| **Storybook** | [VJoyStepper docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoystepper--docs) (includes `VJoyStep` children) |
+| **DSDS (machine)** | [`JoyStep.dsds.json`](./JoyStep.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyStep")` |
+
+---
+
+## When to use this component
+
+Use a step segment when a workflow has **named stages** the user should track — onboarding funnels, multi-page forms, checkout, or any linear process with 2–6 main steps.
+
+Typical pattern: render one `VJoyStep` per stage as children of `VJoyStepper`, put the step name in the default slot, and bind `VJoyStepper` `step` (and optionally `subStep`) to your flow state. Set `subSteps` on a step when that stage itself has substages and you want finer fill animation on the bar.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Managing the full stepper row and current index | `VJoyStepper` (parent of `VJoyStep` children) |
+| A single percentage or completion bar (no named steps) | `VJoyProgressBar` |
+| Full-page guided flow shell (header, footer, scroll) | `VJoyFunnel` + `VJoyStepper` in `#funnel-stepper` |
+| Carousel / page dot indicators | `VJoyIndicators` |
+| Custom progress bars with ad-hoc CSS | Still use `VJoyStep` + Joy tokens — don’t reinvent step chrome |
+
+> **Composition:** `VJoyStep` is a **child** of `VJoyStepper` in almost all product code. Using it standalone is valid for Storybook or tests, but apps should drive state through the stepper.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-step` with size and state modifier classes |
+| Stroke track | Yes | `.joy-step__stroke` — full-width neutral bar (8px height) |
+| Stroke fill | Yes | `.joy-step__stroke--filled` — colored segment; width driven by internal `progress` |
+| Label | No* | Default slot in `.joy-step__label`; animated in/out when `showLabel` is true |
+
+\*Label slot is optional, but each step in a stepper **should** have a short name for clarity. Labels are **hidden below 480px viewport width** via component CSS.
+
+### Default values
+
+- `completed` defaults to **`false`**
+- `currentSubStep` defaults to **`0`** (upcoming — no fill)
+- `subSteps` defaults to **`1`** (no sub-progress granularity)
+- `size` defaults to **`default`** (`small` only reduces label typography — not bar height)
+- `showLabel` defaults to **`true`**
+- `id` defaults to a generated `joy-step-value--{random}` string
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Progress logic
+
+`VJoyStep` computes bar fill from props (exposed as `progress`):
+
+| Condition | Fill |
+| --- | --- |
+| `completed` is `true` | `100%` |
+| `currentSubStep` is `0` | `0%` (upcoming) |
+| Current, `subSteps` ≤ 1 or `currentSubStep` is `1` | `10%` (started) |
+| Current with `subSteps` > 1 | Scales between ~10% and ~90% from `currentSubStep / subSteps` |
+
+`VJoyStepper` sets `completed` on steps before the active index and passes `currentSubStep` only to the active step. When using `VJoyStep` without a stepper, wire these props yourself.
+
+`subSteps` must be **≥ 1**; values ≤ 0 log a console warning and emit `update:subSteps`.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Composition
+
+- **MUST** compose `VJoyStep` children inside `VJoyStepper` for multi-step flows — let the stepper own `step` / `subStep` state.
+- **SHOULD** provide a short default-slot label per step (noun or short phrase).
+- **SHOULD** use `subSteps` only on steps that genuinely have internal substages — keep most steps at the default `1`.
+- **SHOULD** place the stepper in `VJoyFunnel`’s `#funnel-stepper` slot for full-page funnels.
+- **MUST NOT** use `VJoyStep` alone when the UI needs step navigation — that belongs in page logic + `VJoyStepper`.
+
+### Implementation
+
+- **MUST** use only documented props from MCP or `TJoyStep.types.ts`.
+- **MUST** use Joy tokens — no custom `.joy-step` bar or label overrides.
+- **MUST NOT** invent props (`variant`, `color`, `active`, …).
+- **MUST NOT** hardcode bar height or fill colors — they come from CSS variables (`--stepper-border-color`, `--stepper-border-color-filled`, etc.).
+- **SHOULD** treat `size="small"` as a **label density** choice only; bar dimensions stay the same.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyStepper` + one `VJoyStep` per stage | Manual flex row of custom progress divs |
+| Short labels in the default slot | Long descriptions in the step label |
+| `subSteps` on steps with real substages | `subSteps` > 1 on every step by default |
+| `VJoyFunnel` `#funnel-stepper` for funnels | Stepper floating without layout context |
+| `VJoyProgressBar` for a single % | `VJoyStep` for non-stepped progress |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Presentational segments — not interactive controls |
+| Name | Step meaning comes from the visible default-slot label when `showLabel` is true |
+| Mobile | Labels are not shown below 480px — ensure step context is clear from page title or heading |
+| Progress | Bar fill is decorative; don’t rely on color alone — labels (or page headings) name each stage |
+| Grouping | Multiple steps in `VJoyStepper` form one progress indicator; keep DOM order matching visual order |
+| Funnel | `VJoyFunnel` collapses stepper labels on scroll — primary step context should remain in the page heading |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyStepper, VJoyStep } from '@maltjoy/core-vue'
+
+const currentStep = ref(2)
+const currentSubStep = ref(3)
+</script>
+
+<template>
+  <!-- Typical: stepper owns state -->
+  <VJoyStepper :step="currentStep" :sub-step="currentSubStep">
+    <VJoyStep>Introduction</VJoyStep>
+    <VJoyStep :sub-steps="4">Profile</VJoyStep>
+    <VJoyStep>Review</VJoyStep>
+    <VJoyStep>Confirmation</VJoyStep>
+  </VJoyStepper>
+
+  <!-- Standalone (tests / edge cases) — wire props manually -->
+  <VJoyStep completed>Done</VJoyStep>
+  <VJoyStep :current-sub-step="2" :sub-steps="3">In progress</VJoyStep>
+  <VJoyStep>Upcoming</VJoyStep>
+
+  <!-- Smaller label typography -->
+  <VJoyStep size="small" :current-sub-step="1">Compact label</VJoyStep>
+
+  <!-- Hide label (bar only) -->
+  <VJoyStep :show-label="false" :current-sub-step="1" />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyStep` and `VJoyStepper` are already global.
+
+For funnel layouts, see `VJoyFunnel` docs — place `VJoyStepper` in `#funnel-stepper`.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyStepper` | Parent that manages current step, sub-step, and child `VJoyStep` state |
+| `VJoyFunnel` | Full-page multi-step shell with optional stepper slot |
+| `VJoyProgressBar` | Single completion percentage without named steps |
+| `VJoyIndicators` | Dot-style page or carousel indicators |
+| `VJoyFunnelHeader` / `VJoyFunnelFooter` | Navigation chrome inside a funnel |

package/dist/doc/VJoyStepper/guideline.md

@@ -0,0 +1,390 @@
+---
+component: VJoyStepper
+status: draft
+language: en
+dsds: JoyStepper.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Stepper
+
+Use **`VJoyStepper`** with **`VJoyStep`** children when the user is moving through a **linear, multi-step process** — onboarding funnels, registration wizards, or guided workflows — and needs a visual sense of where they are and how much remains.
+
+The parent manages which step is current (`step`, 1-based), optional sub-step progress within the active step (`subStep`), and automatically marks earlier steps as completed. Each child renders a progress stroke and an optional text label.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyStepper` + `VJoyStep` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Stepper](https://zeroheight.com/6bf479565/p/2411991-stepper) |
+| **Storybook** | [VJoyStepper docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoystepper--docs) |
+| **DSDS (machine)** | [`JoyStepper.dsds.json`](./JoyStepper.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyStepper")` · `joy_get_component_info("VJoyStep")` |
+
+---
+
+## When to use this component
+
+Use a stepper when progress through a **fixed sequence** matters — the user should see how many stages exist, which ones are done, and where they are now. Typical jobs: signup funnels, project-creation flows, and multi-screen forms inside `VJoyFunnel`.
+
+Place one `VJoyStep` per main stage in the default slot. Drive `step` from your route, wizard state, or page logic when the user moves forward or back. Use `subStep` together with `sub-steps` on the active `VJoyStep` when a single stage has internal milestones (e.g. several screens before advancing to the next main step).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Peer sections on one surface (switch panels, not a sequence) | `VJoyTabs` |
+| Expand/collapse optional blocks on the same page | `VJoyCollapse` |
+| A single percentage or task completion bar | `VJoyProgressBar` |
+| Carousel / dot pagination | `VJoyIndicators` |
+| Primary app or site navigation | App shell patterns (`VJoyMenu`, sidebar, header nav) |
+| Clickable steps that jump to arbitrary stages | Not supported — keep linear navigation via footer CTAs |
+| Custom progress markup / ad-hoc bars | Still use `VJoyStepper` + `VJoyStep` + Joy tokens |
+
+---
+
+## How it works
+
+`VJoyStepper` reads **`VJoyStep`** children from its default slot (including via `v-for`), computes completed vs. current vs. upcoming states, and passes progress into each child.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Stepper container | Yes | Root `.joy-stepper` — horizontal flex row of steps |
+| Step (`VJoyStep`) | Yes (≥1) | One segment per main stage; flexes to share width |
+| Progress stroke | Yes | 8px bar (`joy-step__stroke`); neutral track + secondary fill |
+| Filled portion | Yes | `joy-step__stroke--filled` — width reflects completion / sub-step progress |
+| Step label | No | Text from each `VJoyStep` default slot; can be hidden (see States) |
+
+### Default values
+
+**`VJoyStepper`**
+
+- `step` is **required** — **1-based** index of the active main step
+- `subStep` defaults to **`1`** — position within the active step’s sub-steps
+
+**`VJoyStep`** (set on each child; see `VJoyStep` Storybook for detail)
+
+- `subSteps` defaults to **`1`**
+- `size` defaults to **`default`** (label typography only — does not change bar height)
+- `showLabel` defaults to **`true`** (overridden when inside `VJoyFunnel` on scroll — see States)
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Composition
+
+```vue
+<VJoyStepper :step="currentStep" :sub-step="currentSubStep">
+  <VJoyStep>Introduction</VJoyStep>
+  <VJoyStep :sub-steps="4">Project details</VJoyStep>
+  <VJoyStep>Confirmation</VJoyStep>
+</VJoyStepper>
+```
+
+- **`VJoyStep`** children go in the `VJoyStepper` default slot (static list or `v-for`).
+- Bind **`step`** to your wizard state; increment when the user completes a stage.
+- Set **`sub-steps`** on a child when that stage has multiple internal screens; bind **`sub-step`** on the parent while that stage is active.
+- In funnels, place the stepper in **`VJoyFunnel`**’s `funnel-stepper` slot so label visibility follows scroll behavior.
+
+### Sub-step validation
+
+If `subStep` is **≤ 0** or **greater than** the active step’s `sub-steps`, the component treats the value as invalid and falls back to the maximum sub-step for that step (`invalidSubStepValue` on the exposed instance). **MUST** keep `subStep` within `1 … subSteps` in product code — do not rely on the fallback.
+
+---
+
+## Variants
+
+`VJoyStepper` has **no variant or emphasis prop**. Visual meaning comes from **step state** (completed, ongoing, upcoming) and Joy tokens on each `VJoyStep` stroke and label.
+
+Do not simulate alternate color themes with custom CSS — use the component as shipped.
+
+### Not in the API: clickable steps
+
+The stepper is **presentational**. Users advance via funnel footer CTAs, form submit, or routing — not by clicking step segments. Do not add `@click` handlers or link styling to steps.
+
+---
+
+## Sizes
+
+Bar height is fixed at **8px** via Joy stepper tokens — there is no size prop on `VJoyStepper`.
+
+Label density is controlled per child with **`size`** on `VJoyStep`:
+
+| Size | Use when |
+| --- | --- |
+| `default` | Standard funnel headers and desktop layouts |
+| `small` | Dense funnels or when labels must stay compact (bar height unchanged) |
+
+**Do not hardcode stroke height or label font sizes** in apps — use `size` and `--joy-font-size-primary-*` tokens.
+
+---
+
+## States
+
+| State | What the user sees |
+| --- | --- |
+| Completed | Earlier steps (`index < step - 1`): fill at 100%; muted label color |
+| Ongoing (current) | Active step: secondary fill animates with `subStep` / `sub-steps`; bold label |
+| Upcoming | Later steps: empty track; neutral label |
+| Sub-step progress | On the current step only — fill grows from ~10% at sub-step 1 toward 100% as `subStep` approaches `sub-steps` |
+| Labels visible | Default — each `VJoyStep` shows its slot text below the bar |
+| Labels hidden (mobile) | Viewports **≤ 479px** — labels are hidden in CSS; progress bars remain |
+| Labels hidden (funnel scroll) | Inside `VJoyFunnel`, labels hide when the user scrolls the content (`VJoyStepperShowLabels` inject) — strokes stay visible |
+
+There is **no disabled, error, or loading state** on the stepper itself. Reflect validation or blocking in the funnel footer (`VJoyFunnelFooter` + `VJoyButton`), not on the progress bar.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure / flow
+
+- **MUST** keep the flow **linear** — one active `step` at a time; update `step` when the user legitimately advances or goes back.
+- **SHOULD** limit main steps to **about 3** per design guidance — split very long flows across routes or sessions instead of many equal segments.
+- **SHOULD** limit sub-steps to **≤ 10** per main step when using `sub-steps` / `subStep`.
+- **SHOULD** place the stepper in `VJoyFunnel`’s `funnel-stepper` slot for full-page funnels so sticky header + scroll label behavior applies.
+- **MUST NOT** use the stepper as navigation — no jumping to arbitrary steps by clicking bars.
+
+### Implementation
+
+- **MUST** compose `VJoyStepper` with **`VJoyStep`** children — not hand-rolled divs.
+- **MUST** use only documented props (Joy MCP / Storybook). No `variant`, `disabled`, or `href` props exist.
+- **MUST** treat `step` as **1-based** (first step = `1`, not `0`).
+- **MUST** keep `subStep` within `1 … subSteps` for the active step.
+- **MUST** style with Joy tokens — no custom `.joy-stepper` / `.joy-step__stroke` chrome overrides.
+- **MUST NOT** invent props on `VJoyStepper` or `VJoyStep`.
+- **SHOULD** use `v-for` on `VJoyStep` when steps are data-driven — `VJoyStepper` unwraps a single fragment child.
+
+### Intermediate / untitled steps
+
+Design allows **intermediate** segments that show progress without a title — leave the `VJoyStep` default slot empty when only the bar should communicate position. Prefer titled steps when the user benefits from named stages.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `step` + `sub-step` driven by wizard state | Hardcoded step index with no back-navigation sync |
+| Short noun labels per step | Long sentences or verb-only imperatives in labels |
+| `sub-steps` only on steps that need internal progress | `sub-steps="10"` on every step “just in case” |
+| `VJoyFunnel` + `VJoyFunnelFooter` for funnel CTAs | Clickable step bars as the only navigation |
+| `size="small"` for dense funnels | Custom 4px / 12px bar heights |
+
+---
+
+## Content
+
+Step labels name **stages**, not actions. They appear under the bar on larger viewports and may hide on small screens or when the funnel content scrolls.
+
+### Label formula
+
+**Short noun or noun phrase** naming the stage:
+
+- ✅ Introduction · Project details · Confirmation  
+- ✅ Profile · Billing · Review  
+
+Use **parallel structure** across steps (all nouns, similar length). Per Malt conjugation guidance, prefer **nouns** over infinitives or imperatives in stepper labels.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Keep labels **short** — aim for **≤ 3–4 words**; the bar is the primary progress cue on mobile |
+| **MUST** | Use **sentence case** (or product locale rules) consistently across the set |
+| **MUST** | Make each label **distinct** — no two steps that differ only by punctuation |
+| **MUST NOT** | Use button-style imperatives as labels — ❌ `Continue`, `Submit` (save verbs for footer CTAs) |
+| **MUST NOT** | Repeat the funnel page title in every step — ❌ `Create project — Details` → ✅ `Details` |
+| **SHOULD** | Name the **stage**, not the UI — ✅ `Verification` · ❌ `Step 2` |
+| **SHOULD** | Omit labels only when intermediate nameless segments are intentional |
+| **SHOULD** (FR) | Prefer nouns (`Introduction`, `Description du besoin`) over infinitives; avoid imperative `-ez` in labels |
+
+### Patterns
+
+**Three-step funnel** — `Introduction` → `Details` → `Confirmation`. Default tab: step 1; footer `Next` advances `step`.
+
+**Stage with internal screens** — set `:sub-steps="4"` on the active `VJoyStep` and bump `:sub-step` as the user moves through substeps before incrementing `step`.
+
+**Funnel with scroll** — rely on `VJoyFunnel` to collapse labels while scrolling; ensure stage names are still clear from page headings in the main content.
+
+---
+
+## Accessibility
+
+The stepper is **presentational progress feedback**, not an interactive control.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | No tablist / button semantics — decorative progress segments |
+| Interaction | Users do not activate steps directly; navigation happens via footer CTAs or form actions |
+| Name | Step labels are visible text when shown; on mobile or collapsed funnel scroll, **page title / heading** must convey the current stage |
+| Progress | Completed vs. ongoing vs. upcoming is communicated visually (fill + color); do not rely on color alone for critical status — pair with heading copy |
+| Motion | Fill width animates on the ongoing step — respect `prefers-reduced-motion` at the app level if you add custom wrappers |
+| Focus | No focusable elements inside the stepper — keyboard users tab to footer actions |
+
+Target: **WCAG 2.2 AA** where the product requires it. For audit trails, expose current position in the document (`<h1>`, `aria-current="step"` on the active section) outside the stepper component.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyStepper,
+  VJoyStep,
+  VJoyFunnel,
+  VJoyFunnelFooter,
+  VJoyButton,
+} from '@maltjoy/core-vue'
+
+const currentStep = ref(1)
+const currentSubStep = ref(1)
+
+const stages = [
+  { id: 'intro', label: 'Introduction', subSteps: 1, dense: false },
+  { id: 'details', label: 'Project details', subSteps: 4, dense: true },
+  { id: 'confirm', label: 'Confirmation', subSteps: 1, dense: false },
+]
+
+function next() {
+  if (currentSubStep.value < 4) {
+    currentSubStep.value += 1
+    return
+  }
+  currentSubStep.value = 1
+  currentStep.value += 1
+}
+</script>
+
+<template>
+  <!-- Basic wizard -->
+  <VJoyStepper :step="currentStep">
+    <VJoyStep>Introduction</VJoyStep>
+    <VJoyStep>Details</VJoyStep>
+    <VJoyStep>Confirmation</VJoyStep>
+  </VJoyStepper>
+
+  <!-- Sub-steps on the active stage -->
+  <VJoyStepper :step="2" :sub-step="4">
+    <VJoyStep>Introduction</VJoyStep>
+    <VJoyStep :sub-steps="4">Project details</VJoyStep>
+    <VJoyStep :sub-steps="4">Review</VJoyStep>
+    <VJoyStep>Done</VJoyStep>
+  </VJoyStepper>
+
+  <!-- Data-driven steps -->
+  <VJoyStepper :step="currentStep" :sub-step="currentSubStep">
+    <VJoyStep
+      v-for="stage in stages"
+      :key="stage.id"
+      :sub-steps="stage.subSteps"
+      :size="stage.dense ? 'small' : 'default'"
+    >
+      {{ stage.label }}
+    </VJoyStep>
+  </VJoyStepper>
+
+  <!-- Inside a funnel -->
+  <VJoyFunnel>
+    <template #funnel-stepper>
+      <VJoyStepper :step="currentStep" :sub-step="currentSubStep">
+        <VJoyStep>Profile</VJoyStep>
+        <VJoyStep :sub-steps="4">Project</VJoyStep>
+        <VJoyStep>Confirm</VJoyStep>
+      </VJoyStepper>
+    </template>
+
+    <!-- …main funnel content… -->
+
+    <VJoyFunnelFooter>
+      <template #footer-right>
+        <VJoyButton label="Next" variant="main" size="small" @click="next" />
+      </template>
+    </VJoyFunnelFooter>
+  </VJoyFunnel>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyStepper` and `VJoyStep` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyStep` | Required child — one segment per main stage (label, `sub-steps`, `size`) |
+| `VJoyFunnel` | Full-page funnel layout; provides `funnel-stepper` slot and scroll label behavior |
+| `VJoyFunnelFooter` / `VJoyFunnelHeader` | Sticky funnel chrome and primary navigation CTAs |
+| `VJoyButton` | Next, Back, Skip actions in the funnel footer |
+| `VJoyTabs` | Peer sections on one surface, not a sequential flow |
+| `VJoyProgressBar` | Single continuous completion percentage, not discrete stages |
+| `VJoyTemplate` | Page layout inside funnel content |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyStepper.dsds.json`](./JoyStepper.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Linear multi-step funnel / wizard | `VJoyStepper` + `VJoyStep` children | `VJoyTabs` for sequential onboarding |
+| Peer panels on one page | `VJoyTabs` | `VJoyStepper` |
+| One percentage bar | `VJoyProgressBar` | Multiple `VJoyStep` with fake labels |
+| Accordion FAQ on same page | `VJoyCollapse` | `VJoyStepper` |
+| Full-page guided flow | `VJoyFunnel` + `VJoyStepper` in `funnel-stepper` | Bare stepper floating without funnel layout |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyStepper")` and `joy_get_component_info("VJoyStep")` (or read Storybook) before generating props.
+2. **MUST** always emit **`VJoyStep`** inside **`VJoyStepper`** default slot — one child per main stage.
+3. **MUST** bind **`step`** (required, **1-based**) to wizard state.
+4. **MUST** use **`sub-step`** on `VJoyStepper` and **`sub-steps`** on the active `VJoyStep` together when a stage has internal progress.
+5. **MUST** keep `subStep` in range `1 … subSteps` for the active step.
+6. **MUST NOT** invent `variant`, `disabled`, `clickable`, or navigation props.
+7. **MUST NOT** override `.joy-stepper`, `.joy-step__stroke`, or bar height with custom CSS.
+8. **MUST NOT** make steps clickable or use the stepper as the sole navigation mechanism.
+9. **SHOULD** use ~**3** main steps and ≤ **10** sub-steps per design guidance.
+10. **SHOULD** use `size="small"` on `VJoyStep` only for label density — bar stays 8px.
+
+### Valid enums (from MCP / types)
+
+| Component | Prop | Values |
+| --- | --- | --- |
+| `VJoyStep` | `size` | `default`, `small` |
+
+### Checklist
+
+- [ ] `VJoyStepper` + one `VJoyStep` per main stage (not standalone `VJoyStep` for wizards)
+- [ ] `step` is 1-based and synced with footer / route navigation
+- [ ] `sub-step` / `sub-steps` aligned and in valid range
+- [ ] Props from MCP / Storybook only — no invented enums
+- [ ] No custom stepper chrome CSS
+- [ ] Labels are short nouns; verbs live on footer `VJoyButton`s
+- [ ] Funnel flows use `VJoyFunnel` `funnel-stepper` slot when appropriate
+- [ ] Current stage named in page heading when labels may be hidden (mobile / scroll)
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyStepper.dsds.json`](./JoyStepper.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants / sizes | `variants` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Imports | `imports` in JSON |
+| Stroke / typography tokens | `design-specifications` in JSON (`--stepper-border-color-*`, `--joy-font-size-primary-*`) |