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

package/dist/doc/VJoyWalkthrough/guideline.md

@@ -0,0 +1,351 @@
+---
+component: VJoyWalkthrough
+status: draft
+language: en
+dsds: JoyWalkthrough.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Walkthrough
+
+Use **`VJoyWalkthrough`** when you need a **persistent, collapsible onboarding panel** — for example a “Get started” checklist, profile-completion guidance, or multi-step help that stays available while the user explores the page.
+
+It teleports to `body`, anchors to the bottom-right on desktop (full viewport on narrow screens), collapses to a floating trigger pill when closed, and exposes slots for illustration, titles, progress, and body content. Optional footer copy supports permanent dismiss (“don’t show again”).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyWalkthrough` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Walkthrough](https://zeroheight.com/6bf479565/p/6305853-walkthrough) |
+| **Storybook** | [VJoyWalkthrough docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoywalkthrough--docs) |
+| **DSDS (machine)** | [`JoyWalkthrough.dsds.json`](./JoyWalkthrough.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyWalkthrough")` |
+
+---
+
+## When to use this component
+
+Use a walkthrough when onboarding or contextual help should remain **available without blocking the whole page** — the user can collapse the panel, keep working, and reopen it from the trigger.
+
+Typical jobs: checklist-style onboarding, profile completion nudges, feature discovery with expandable steps, or resume flows where progress is shown in the trigger subtitle and/or a `walkthrough-progress` slot (often `VJoyProgressBar`).
+
+Pair `triggerTitle` / `triggerSubtitle` / `triggerIcon` with slot content so both the collapsed pill and the expanded panel tell a coherent story.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Spotlight tour anchored to specific page elements | `VJoyProductTour` |
+| Blocking confirmation or focused decision | `VJoyDialog` |
+| Slide-in panel for filters, details, or long forms | `VJoyDrawer` |
+| Brief transient feedback after an action | `pushVJoySnackbar` |
+| Short hover/focus hint on a single control | `VJoyTooltip` |
+| Full-page multi-step funnel | `VJoyFunnel` |
+| Only the collapsed pill, no modal shell | `VJoyWalkthroughTrigger` (uncommon — see its guideline) |
+| Custom fixed corner card with ad-hoc CSS | Still use `VJoyWalkthrough` + Joy tokens |
+
+> **Docs only:** `disableTeleport` exists for Storybook previews. **Do not** set it in production — the component should teleport to `body` for correct z-index stacking (`--joy-core-z-index-walkthrough`).
+
+---
+
+## How it works
+
+### Open / collapse lifecycle
+
+1. **Collapsed (default)** — `open` is `false`; `VJoyWalkthroughTrigger` is shown (bottom-right on desktop, bottom-left fixed on mobile). Clicking the trigger opens the modal.
+2. **Open** — modal panel replaces the trigger. Header click runs a fade-out (~200 ms), then collapses and emits `hide` + `hide:header`.
+3. **Footer dismiss** — when `footer` is set, clicking the footer link collapses the panel and emits `hide` + `hide:footer` (use this path to persist “don’t show again”).
+4. **Controlled `open`** — bind `:open` and listen to `hide` / `hide:header` / `hide:footer` to sync app state (for example localStorage). Internal `isOpen` also syncs when `open` changes.
+
+Fallthrough attributes (`id`, `data-*`, `aria-*`) on `VJoyWalkthrough` are applied to **`.joy-walkthrough-modal`** while the panel is open. Use **`triggerAttrs`** for attributes on the collapsed trigger button.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Teleport host | Yes | Renders at `body` unless `disableTeleport` (docs only) |
+| Root container | Yes | `.joy-walkthrough` — fixed positioning, z-index walkthrough token |
+| Modal panel | Yes* | `.joy-walkthrough-modal` — white card, elevation-4, fade-in animation |
+| Header | Yes* | Dark bar (`neutral-60`); shows `triggerIcon`, `triggerTitle`, chevron; click collapses |
+| Illustration slot | No | `walkthrough-illustration` — leading visual (often `VJoyIcon`) |
+| Title slot | No* | `walkthrough-title` — primary heading in content area |
+| Subtitle slot | No | `walkthrough-subtitle` — supporting line under title |
+| Progress slot | No | `walkthrough-progress` — e.g. `VJoyProgressBar` with label |
+| Content slot | No | `walkthrough-content` — steps, lists, collapsible sections |
+| Footer | No | Text link (`footer` prop) — permanent dismiss CTA |
+| Trigger | Yes* | `VJoyWalkthroughTrigger` when collapsed |
+
+\*Modal and header exist only while open; trigger exists only while collapsed. At least one of title slots or trigger copy should explain the panel’s purpose.
+
+### Default values
+
+- `open` defaults to **`false`**
+- `triggerTitle`, `triggerSubtitle`, `triggerIcon`, `footer`, and `triggerAttrs` are **optional**
+- `disableTeleport` is **unset** (teleport enabled)
+
+Props, events, slots, and exposed `isOpen`: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Layout and tokens
+
+- **Desktop** — fixed `bottom: 20px; right: 20px`; modal width `--walkthrough-width` (420px), max content height `--walkthrough-max-height` (420px), scrollable body.
+- **Mobile / short viewport** — full width and height when `max-width: 500px` or `max-height: 600px`; trigger compacts (title hidden on narrow viewports — plan copy accordingly).
+- **Do not** hardcode `420px` or z-index in apps — sizing and stacking come from Joy tokens inside `JoyWalkthrough.scss`.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Collapsed (default) | Floating trigger pill with icon, title, optional subtitle, chevron-up; page remains fully usable |
+| Opening | Trigger click sets `isOpen` true; modal fades in (~150 ms) |
+| Open | Expanded panel over page; header shows chevron-down; content slots visible |
+| Hiding | Header or footer click adds `joy-walkthrough-modal--hiding`; after ~200 ms panel unmounts and trigger returns |
+| With progress | `walkthrough-progress` slot rendered below title block; often paired with `triggerSubtitle` |
+| With footer | Footer text link below scrollable content; separate dismiss path from header collapse |
+| Controlled `open` | Parent can force open/closed via prop; internal state follows via `watch` |
+
+Header collapse and footer dismiss both close the panel but emit **different events** — use `hide:footer` when persisting opt-out.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection
+
+- **SHOULD** use **`VJoyWalkthrough`** for persistent onboarding that can be collapsed and resumed.
+- **SHOULD** use **`VJoyProductTour`** when steps must highlight specific DOM targets with a spotlight.
+- **MUST NOT** stack multiple walkthrough instances on the same viewport without design approval — one corner panel at a time.
+
+### Implementation
+
+- **MUST** use only documented props from MCP or `VJoyWalkthrough.vue` (`open`, `triggerTitle`, `triggerSubtitle`, `triggerIcon`, `footer`, `triggerAttrs`, `disableTeleport`).
+- **MUST** style with Joy tokens — no custom `.joy-walkthrough-modal` width, elevation, radius, or z-index overrides.
+- **MUST NOT** invent props (`variant`, `size`, `placement`, `step`, …).
+- **MUST NOT** set `disableTeleport` in production.
+- **SHOULD** pass `triggerAttrs` for `data-testid`, `aria-label`, or analytics hooks on the trigger.
+- **SHOULD** listen to `hide:footer` (or `hide`) to persist permanent dismiss when `footer` is shown.
+- **SHOULD** omit `triggerSubtitle` and `walkthrough-progress` when there is no measurable progress (see Storybook `NoProgress`).
+
+### Content slots
+
+- **SHOULD** fill `walkthrough-title` and at least one of `walkthrough-content` or `walkthrough-subtitle` so the open panel is self-explanatory.
+- **SHOULD** keep `walkthrough-illustration` decorative — meaning lives in title/subtitle slots.
+- **MUST NOT** put the only actionable CTA solely in the footer if the user must complete steps in `walkthrough-content` first.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyWalkthrough` + slots for onboarding checklists | `VJoyDialog` for non-blocking corner help |
+| `VJoyProductTour` for element-anchored tours | Walkthrough pretending to spotlight page nodes |
+| `triggerAttrs` + `aria-label` when mobile hides title | Icon-only trigger with no accessible name |
+| `hide:footer` + storage for “don’t show again” | Footer copy with no persistence handler |
+| `VJoyProgressBar` in `walkthrough-progress` | Invented progress props on walkthrough |
+| Joy walkthrough z-index token | Arbitrary `z-index: 9999` in product CSS |
+
+---
+
+## Content
+
+Walkthrough copy spans the **trigger** (collapsed), **slots** (expanded), and optional **footer** (permanent dismiss). Keep lines short — the panel is narrow on desktop and full-screen on mobile.
+
+### Trigger copy
+
+| Prop | Formula | Example |
+| --- | --- | --- |
+| `triggerTitle` | Short action or topic — **2–4 words** | `Get started`, `Complete profile` |
+| `triggerSubtitle` | Progress or status — optional | `80% completed`, `3 steps left` |
+| `triggerIcon` | Reinforces task type — optional | `list`, `trending-up` |
+
+Omit `triggerSubtitle` when there is no progress to show. Do not duplicate the same percentage in both subtitle and progress bar label without reason.
+
+### Slot copy
+
+| Slot | Formula | Example |
+| --- | --- | --- |
+| `walkthrough-title` | **Benefit or step headline** — sentence case | `Welcome to your dashboard` |
+| `walkthrough-subtitle` | One line of context | `Finish these steps to publish your first project` |
+| `walkthrough-content` | Steps, bullets, or collapsible sections | Checklist items, links to settings |
+| `walkthrough-progress` | Visual meter only — pair with numeric copy nearby | `VJoyProgressBar` + subtitle |
+
+### Footer copy
+
+**Opt-out action** — infinitive or imperative, states permanence:
+
+- ✅ `Close and don't show again`
+- ✅ `Dismiss setup guide`
+- ❌ `OK` (ambiguous — does not signal persistence)
+
+Wire footer clicks to storage or backend preference in the `hide:footer` / `hide` handler.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Trigger `title` (or `aria-label` via `triggerAttrs`) names the walkthrough when collapsed |
+| **MUST** | Footer text reflects permanent dismiss when that is the behavior |
+| **MUST** | Step content in `walkthrough-content` uses scannable lists — one action per line when possible |
+| **MUST NOT** | Use the footer as the only place critical instructions appear |
+| **MUST NOT** | Show conflicting progress (subtitle says 50% while bar shows 80%) |
+| **SHOULD** | Keep `walkthrough-title` ≤ ~60 characters |
+| **SHOULD** | Use joyful / promo tone only for deliberate onboarding — default to neutral, helpful |
+| **SHOULD** | Match terminology with page headings and CTAs elsewhere |
+| **SHOULD** (FR) | Follow French grammar for titles and dismiss lines when the UI is localized |
+
+### Patterns
+
+**Checklist onboarding** — `walkthrough-content` lists tasks; completed items move per product rules (see ZeroHeight usage: done items reorder within category). Progress in `walkthrough-progress` + `triggerSubtitle`.
+
+**Resume later** — Collapsed trigger shows remaining work (`3 steps left`); open panel expands the full list.
+
+**No progress** — Drop `triggerSubtitle` and `walkthrough-progress`; rely on title + content only.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Trigger | Native `button` via `VJoyWalkthroughTrigger`; **Enter** / **Space** activate; focus ring on trigger |
+| Trigger name | `triggerTitle` / `triggerSubtitle` supply visible name; add **`aria-label`** via `triggerAttrs` if mobile layout hides title |
+| Modal header | `role="button"` on header wrapper — pointer click collapses; ensure keyboard users can still dismiss via trigger after collapse or provide an equivalent |
+| Footer | Native `button type="button"` with visible text from `footer` prop |
+| Illustration | Treat `walkthrough-illustration` as decorative unless it conveys unique information |
+| Progress | `VJoyProgressBar` needs nearby text (subtitle or label) — bar alone is not sufficient name |
+| Stacking | Teleport to `body` preserves walkthrough z-index token — do not trap focus unless product requires it |
+| Permanent dismiss | Persist opt-out when footer promises it — do not re-show on next visit without user action |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyWalkthrough,
+  VJoyIcon,
+  VJoyProgressBar,
+} from '@maltjoy/core-vue'
+
+const dismissed = ref(false)
+
+function onPermanentDismiss() {
+  dismissed.value = true
+  localStorage.setItem('onboarding-walkthrough-dismissed', '1')
+}
+</script>
+
+<template>
+  <VJoyWalkthrough
+    v-if="!dismissed"
+    :open="true"
+    trigger-icon="list"
+    trigger-title="Get started"
+    trigger-subtitle="80% completed"
+    footer="Close and don't show again"
+    :trigger-attrs="{ 'data-testid': 'onboarding-walkthrough-trigger' }"
+    @hide:footer="onPermanentDismiss"
+  >
+    <template #walkthrough-illustration>
+      <VJoyIcon name="trending-up" size="medium" />
+    </template>
+    <template #walkthrough-title>Welcome to your dashboard</template>
+    <template #walkthrough-subtitle>
+      Complete these steps to publish your first project.
+    </template>
+    <template #walkthrough-progress>
+      <VJoyProgressBar :percentage="80" show-label />
+    </template>
+    <template #walkthrough-content>
+      <ul>
+        <li>Add your profile photo</li>
+        <li>Set your availability</li>
+        <li>Publish your first project</li>
+      </ul>
+    </template>
+  </VJoyWalkthrough>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyWalkthrough` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyWalkthroughTrigger` | Collapsed pill only (rare — parent usually owns it) |
+| `VJoyProductTour` | Multi-step tour with element spotlighting |
+| `VJoyProductTourTrigger` | Entry trigger for product tours |
+| `VJoyProgressBar` | Progress meter in `walkthrough-progress` slot |
+| `VJoyIcon` | Illustration slot and `triggerIcon` |
+| `VJoyCollapse` / `VJoyCollapseItem` | Expandable steps inside `walkthrough-content` |
+| `VJoyDialog` | Blocking modal decisions |
+| `VJoyTooltip` | Single-control hints |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyWalkthrough.dsds.json`](./JoyWalkthrough.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Persistent collapsible onboarding panel | `VJoyWalkthrough` | Fixed `div` in corner + custom CSS |
+| Highlight specific page elements step-by-step | `VJoyProductTour` | `VJoyWalkthrough` with manual positioning |
+| Blocking confirm / form modal | `VJoyDialog` | Walkthrough for destructive confirm |
+| Toast after save | `pushVJoySnackbar` | Walkthrough for transient feedback |
+| Icon-only corner button without panel | `VJoyWalkthroughTrigger` | `VJoyButton` styled as dark pill |
+| Progress in panel header | `walkthrough-progress` + `VJoyProgressBar` | Invented `percentage` prop on walkthrough |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyWalkthrough")` before generating props.  
+2. **MUST** use slot names exactly: `walkthrough-illustration`, `walkthrough-title`, `walkthrough-subtitle`, `walkthrough-progress`, `walkthrough-content`.  
+3. **MUST** pass trigger a11y/test attrs via `triggerAttrs`, not on the root when targeting the pill.  
+4. **MUST** listen to `hide`, `hide:header`, or `hide:footer` when syncing `open` or persistence.  
+5. **MUST NOT** emit `disableTeleport` outside Storybook/docs.  
+6. **MUST NOT** invent props (`variant`, `size`, `step`, `placement`, …).  
+7. **MUST NOT** override `.joy-walkthrough` / `.joy-walkthrough-modal` dimensions, z-index, or elevation.  
+8. **SHOULD** omit `triggerSubtitle` and `walkthrough-progress` when there is no progress metric.  
+9. **SHOULD** set `footer` only when implementing permanent dismiss with a handler.
+
+### Checklist
+
+- [ ] Correct component (`VJoyWalkthrough` or named alternative)
+- [ ] Props / slots from MCP only
+- [ ] `triggerTitle` or `triggerAttrs['aria-label']` for collapsed state
+- [ ] `walkthrough-title` (+ content) when panel opens
+- [ ] `hide:footer` / storage when footer promises “don’t show again”
+- [ ] No `disableTeleport` in production
+- [ ] No invented props / no custom walkthrough chrome CSS
+- [ ] Product tour with spotlight → `VJoyProductTour`
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyWalkthrough.dsds.json`](./JoyWalkthrough.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / lifecycle | `anatomy` |
+| 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 |
+| Layout tokens | `design-specifications` in JSON (`--walkthrough-width`, `--joy-core-z-index-walkthrough`) |

package/dist/doc/VJoyWalkthroughTrigger/guideline.md

@@ -0,0 +1,171 @@
+---
+component: VJoyWalkthroughTrigger
+status: draft
+language: en
+dsds: JoyWalkthroughTrigger.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Walkthrough trigger
+
+Use **`VJoyWalkthroughTrigger`** as the **collapsed-state pill button** for a Joy walkthrough — a fixed, dark floating control with optional icon, title, subtitle, and chevron.
+
+In product code, **prefer `VJoyWalkthrough`** and its `triggerTitle`, `triggerSubtitle`, and `triggerIcon` props; the parent renders this trigger when the modal is closed. Mount the trigger directly only when you need the chrome without the full walkthrough shell.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyWalkthroughTrigger` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Walkthrough](https://zeroheight.com/6bf479565/p/6305853-walkthrough) |
+| **Storybook** | [VJoyWalkthrough docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoywalkthrough--docs) (subcomponent) |
+| **DSDS (machine)** | [`JoyWalkthroughTrigger.dsds.json`](./JoyWalkthroughTrigger.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyWalkthroughTrigger")` |
+
+---
+
+## When to use this component
+
+Use this trigger when a walkthrough is **collapsed** and the user needs a persistent entry point — typically “Get started”, onboarding progress, or a resume CTA fixed to the viewport corner.
+
+The button shows an optional leading icon, a **title** (primary line), an optional **subtitle** (secondary line, separated by a vertical rule), and a chevron that reflects open/closed state. Ripple feedback is built in (`v-joy-ripple`).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Full collapsible walkthrough with modal, slots, and footer | `VJoyWalkthrough` (renders this trigger automatically when closed) |
+| Spotlight tour anchored to page elements | `VJoyProductTour` |
+| Generic page action or navigation | `VJoyButton` or `VJoyLink` |
+| Short contextual hint on hover | `VJoyTooltip` |
+| Custom floating pill with ad-hoc CSS | Still use `VJoyWalkthroughTrigger` or `VJoyWalkthrough` + Joy tokens |
+
+> **Composition:** pass extra HTML attributes (for example `data-testid`, `aria-label`) through `triggerAttrs` on `VJoyWalkthrough`, or `v-bind="$attrs"` when using the trigger standalone.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root button | Yes | Native `<button type="button">` — `.joy-walkthrough-trigger` |
+| Leading icon | No | `VJoyIcon` when `icon` is set (`color="white"`) |
+| Content row | No* | `.joy-walkthrough-trigger__content` — `title` and/or `subtitle` spans |
+| Title | No | Primary label (`title` prop) |
+| Subtitle | No | Secondary label (`subtitle` prop); vertical divider when both title and subtitle are present |
+| Chevron | Yes | `VJoyIcon` — `chevron-up` when collapsed, `chevron-down` when `open` is true |
+| Ripple | Yes | `v-joy-ripple` on the button |
+
+\*At least one of `title`, `subtitle`, or `icon` should be provided so the control is recognizable.
+
+### Default values
+
+- `open` has **no default** in types — internal state starts from the prop when set; otherwise collapsed (`chevron-up`)
+- `icon`, `title`, and `subtitle` are all **optional**
+
+Props and exposed members: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Parent integration
+
+`VJoyWalkthrough` shows `VJoyWalkthroughTrigger` only while the modal is closed, forwards `triggerTitle` → `title`, `triggerSubtitle` → `subtitle`, `triggerIcon` → `icon`, merges `triggerAttrs` onto the button, and handles `@click` to open the modal. Positioning and mobile compaction (fixed bottom-left, shorter height, title hidden on narrow viewports) come from `JoyWalkthrough.scss` on the parent — not from props on the trigger.
+
+Standalone usage toggles internal `open` on click (chevron only); wire your own handler with `@click` if the button should open custom content.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection
+
+- **SHOULD** use **`VJoyWalkthrough`** instead of mounting `VJoyWalkthroughTrigger` alone when the goal is onboarding or guided help with expandable content.
+- **SHOULD** provide at least **`title`** or **`icon`** so the pill has a clear purpose at a glance.
+- **SHOULD** use **`subtitle`** for progress or status (for example `80% completed`) — omit it when there is no secondary line to show.
+- **MUST NOT** use this trigger for primary form submission or destructive actions.
+
+### Implementation
+
+- **MUST** use only documented props from MCP or `VJoyWalkthroughTrigger.vue` (`icon`, `title`, `subtitle`, `open`).
+- **MUST** use Joy tokens — no custom `.joy-walkthrough-trigger` background, radius, height, or typography overrides.
+- **MUST NOT** invent props (`variant`, `size`, `color`, `placement`, …).
+- **MUST NOT** add slots — the component has none.
+- **SHOULD** pass test and a11y attributes via **`triggerAttrs`** on `VJoyWalkthrough` or fallthrough attrs on a standalone trigger.
+- **SHOULD** use valid Joy icon names for `icon` (see `TJoyIconsNames` / MCP).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyWalkthrough` + `triggerTitle` / `triggerSubtitle` / `triggerIcon` | Rebuild the dark pill with `VJoyButton` + custom CSS |
+| `subtitle` for progress when using `walkthrough-progress` | Duplicate progress in title and subtitle |
+| `triggerAttrs` for `data-testid` or `aria-label` | Hardcode `64px` height or neutral-60 background in apps |
+| `VJoyProductTour` for element-highlight tours | `VJoyWalkthroughTrigger` as a page spotlight |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `button` (`type="button"`) |
+| Name | Visible **`title`** and/or **`subtitle`** should carry the accessible name; if neither is sufficient alone, set **`aria-label`** via `triggerAttrs` or fallthrough attrs |
+| Keyboard | **Enter** / **Space** activate the button when focused |
+| Focus | Visible focus ring — `2px solid var(--joy-color-neutral-0)` with negative outline offset; do not remove in product CSS |
+| Chevron / icon | Decorative when title or subtitle already names the control; supplement with `aria-label` if the trigger is icon-only |
+| Mobile | Parent walkthrough layout may hide the title on narrow viewports — ensure **`subtitle`** or **`aria-label`** still conveys purpose |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyWalkthrough, VJoyWalkthroughTrigger } from '@maltjoy/core-vue'
+
+const showPanel = ref(false)
+</script>
+
+<template>
+  <!-- Preferred: parent owns trigger + modal -->
+  <VJoyWalkthrough
+    trigger-icon="list"
+    trigger-title="Get started"
+    trigger-subtitle="80% completed"
+    footer="Close and don't show again"
+    :trigger-attrs="{ 'data-testid': 'onboarding-trigger' }"
+  >
+    <template #walkthrough-title>Welcome to your dashboard</template>
+    <template #walkthrough-content>Step-by-step guidance goes here.</template>
+  </VJoyWalkthrough>
+
+  <!-- Standalone trigger (uncommon — you handle open state) -->
+  <VJoyWalkthroughTrigger
+    icon="list"
+    title="Get started"
+    subtitle="3 steps left"
+    aria-label="Resume onboarding walkthrough"
+    @click="showPanel = true"
+  />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyWalkthroughTrigger` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyWalkthrough` | Full collapsible walkthrough — modal, slots, footer, teleport |
+| `VJoyProductTour` | Multi-step tour with element spotlighting |
+| `VJoyProductTourTrigger` | Trigger pattern for product tours |
+| `VJoyIcon` | Icons passed to the `icon` prop |
+| `VJoyProgressBar` | Progress slot content inside `VJoyWalkthrough` |
+| `VJoyButton` | Standard actions unrelated to walkthrough chrome |