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

package/dist/doc/VJoyUserCard/guideline.md

@@ -0,0 +1,268 @@
+---
+component: VJoyUserCard
+status: draft
+language: en
+dsds: JoyUserCard.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# User Card
+
+Use **`VJoyUserCard`** when you need a compact, horizontal identity block — avatar, name, subtitle, and optional metadata (rating, badges) — in lists, side panels, activity feeds, or search results.
+
+Set `link` to make the whole card navigate as a native `<a>`; pass `target`, `rel`, and other link attributes on the component (they inherit via `$attrs`). Customize avatar, title, subtitle, or trailing content through slots when props are not enough.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyUserCard` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — User Card](https://zeroheight.com/6bf479565/p/8408347-user-card) |
+| **Storybook** | [VJoyUserCard docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoyusercard--docs) |
+| **DSDS (machine)** | [`JoyUserCard.dsds.json`](./JoyUserCard.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyUserCard")` |
+
+---
+
+## When to use this component
+
+Use a user card when someone must **recognize a person or entity at a glance** in a dense layout — for example a freelancer in search results, a participant in a conversation header, a project member row, or a sourcing snippet with rating and level badges.
+
+Prefer props (`fullName`, `subTitle`, `photoUrl`) for the default case. Reach for slots when you need a custom avatar size, formatted title, or extra rows (`VJoyRatingStars`, `VJoyBadgeLevel`, availability, tags).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Only a profile picture / initials | `VJoyAvatar` |
+| A generic interactive list row (icon + title + actions) | `VJoyListItem` |
+| A large profile hero or full profile page layout | Page template / custom layout — not `VJoyUserCard` |
+| A complex clickable card with arbitrary CTA layout | `VJoyButtonCard` |
+| Inline name inside body copy | `VJoyLink` or plain text |
+| Custom markup / ad-hoc flex row for the same job | Still use `VJoyUserCard` + Joy tokens |
+
+> **Deprecated:** do not use the `user-card-rating-stars` slot on new work — put `VJoyRatingStars` (and other metadata) in the **default** slot instead. The slot remains for backward compatibility only.
+
+> **Not in the Vue API:** legacy Stencil props `ratingValue` and `newTab`, and the `user-card-free-slot` slot name. **`VJoyUserCard` has no `ratingValue` prop** — compose `VJoyRatingStars` in the default slot. For a new tab, set `link` and pass `target="_blank"` (and `rel="noopener noreferrer"` when appropriate) as attributes.
+
+> **Not in the API:** ZeroHeight “Profile card” **Portrait** / **Landscape** types are layout patterns in design docs. The component implements a **single horizontal layout** (avatar left, text stack right). Do not invent `variant="portrait"` or `variant="landscape"`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `<div class="joy-user-card">`, or `<a class="joy-user-card">` when `link` is set |
+| Picture | Yes | `.joy-user-card__picture` — default `VJoyAvatar` or `user-card-avatar` slot |
+| Informations | Yes | `.joy-user-card__informations` — title, subtitle, and optional extra content |
+| Title | Yes* | `.joy-user-card__title` — `fullName` prop or `user-card-title` slot |
+| Subtitle | No | `.joy-user-card__subtitle` — `subTitle` prop or `user-card-subtitle` slot (`joy-font-primary-450`) |
+| Default slot | No | Free content below subtitle (rating, badges, tags, links) |
+| `title` attribute | No | On link roots, set from `fullName` for native tooltip on hover |
+
+\*Provide at least a title (prop or slot) so the card is meaningful. Avatar initials also use `fullName` when no photo is available.
+
+### Layout and tokens
+
+- **Layout** — `inline-flex`, avatar and text aligned to the start; fixed horizontal pattern (no `size` or `variant` prop on the card).
+- **Typography** — `--user-card-font-size` (default `var(--joy-font-size-primary-400)`); title uses bold weight and `--user-card-title-color`.
+- **Body text** — `--user-card-text-color` (default neutral-60).
+- **Links inside the card** — nested `<a>` elements use `--user-card-links-color` and underline on hover/focus.
+- **Link card** — when the root is `<a>`, the title is underlined and uses link colors; root has opacity transition on hover.
+
+Avatar **size** is controlled via `user-card-avatar` (e.g. `VJoyAvatar` `size="small"`) — not a prop on `VJoyUserCard`.
+
+### Default values
+
+All props are optional strings with no component defaults — supply the data your surface needs.
+
+Props, slots, and attribute inheritance: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (static) | Root is a `<div>`; informational display only |
+| Default (link) | Root is `<a href="…">`; entire card is one navigation target |
+| Hover (link card) | Root opacity transition; title color shifts to link hover token |
+| Hover / focus (nested links) | Links inside `.joy-user-card__informations` underline and change color |
+| Focus (link card) | Native link focus on the root; title styling follows link focus token |
+| Custom slot content | Rating, badges, or extra lines in the default slot — keep supplementary, not the only way to convey the name |
+
+There is no `disabled` or `loading` state on the card itself. If navigation must be blocked, omit `link` or handle it in the parent (and explain why nearby).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to link the whole card
+
+- **SHOULD** set `link` when the **primary action** is “open this person’s profile” (or equivalent destination).
+- **SHOULD** pass `target` and `rel` as native attributes when opening externally (`target="_blank"` + `rel="noopener noreferrer"`).
+- **MUST NOT** nest interactive controls that compete with the card link inside a linked card without stopping propagation — prefer static card + explicit button, or link only the title.
+- **SHOULD** use a single clear destination per card — not multiple conflicting click targets.
+
+### Implementation
+
+- **MUST** use only documented props: `link`, `photoUrl`, `fullName`, `subTitle`.
+- **MUST** put `VJoyRatingStars`, `VJoyBadgeLevel`, and similar metadata in the **default** slot (not deprecated `user-card-rating-stars`).
+- **MUST** style with Joy tokens / CSS variables (`--user-card-*`) — no custom `.joy-user-card` chrome in product CSS.
+- **MUST NOT** invent props (`ratingValue`, `newTab`, `variant`, `size`, …).
+- **SHOULD** prefer props for plain string title/subtitle; use slots for formatting, components, or i18n wrappers.
+- **SHOULD** wrap multiple default-slot items in `VJoyWrapper` with tight gaps (see Storybook `CustomSlot`).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `fullName` + `photoUrl` for standard rows | Rebuild avatar + two `<p>` tags with custom CSS |
+| Default slot for rating / badges | Deprecated `user-card-rating-stars` slot |
+| `target="_blank"` as an attribute on the card | `newTab` prop (Stencil only) |
+| `VJoyAvatar` in `user-card-avatar` when size differs | Hardcoded avatar dimensions on `.joy-user-card__picture` |
+| One profile link via `link` | Whole card linked plus unrelated buttons inside |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Static card → non-interactive container; with `link` → native `<a href>` (not a clickable `<div>`) |
+| Name | Title text (`fullName` / slot) is the primary visible identifier; avatar image uses `fullName` as `alt` via `VJoyAvatar` |
+| Link card | Root `<a>` must have meaningful link text — the title (and not image alone) should identify the destination |
+| `title` attribute | Set on link root from `fullName` — supplementary only; do not rely on it as the accessible name |
+| Nested links | Allowed in the informations block; avoid duplicate or confusing destinations |
+| Keyboard | Link cards follow native link keyboard behavior (**Enter** activates) |
+| Focus | Preserve visible focus styles on link roots and nested links — do not remove outlines in product CSS |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import {
+  VJoyUserCard,
+  VJoyAvatar,
+  VJoyRatingStars,
+  VJoyBadgeLevel,
+  VJoyWrapper,
+} from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Standard identity row -->
+  <VJoyUserCard
+    full-name="Leslie Nielsen"
+    sub-title="Actor"
+    photo-url="https://example.com/photo.jpg"
+  />
+
+  <!-- Whole card navigates — attrs pass through to <a> -->
+  <VJoyUserCard
+    link="https://www.malt.com/profile/123"
+    full-name="Leslie Nielsen"
+    sub-title="Actor"
+    photo-url="https://example.com/photo.jpg"
+    target="_blank"
+    rel="noopener noreferrer"
+  />
+
+  <!-- Rating + badge in default slot -->
+  <VJoyUserCard full-name="Leslie Nielsen" sub-title="Actor">
+    <VJoyWrapper :no-margin="true" column-gap="2" row-gap="2">
+      <VJoyRatingStars :rating-value="5" />
+      <VJoyBadgeLevel level="level-2" type="supermalter" />
+    </VJoyWrapper>
+  </VJoyUserCard>
+
+  <!-- Custom avatar size via slot -->
+  <VJoyUserCard full-name="Leslie Nielsen" sub-title="Actor">
+    <template #user-card-avatar>
+      <VJoyAvatar size="small" full-name="Leslie Nielsen" photo-url="https://example.com/photo.jpg" />
+    </template>
+  </VJoyUserCard>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyUserCard` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyAvatar` | Avatar only, or custom avatar inside `user-card-avatar` |
+| `VJoyRatingStars` | Star rating in the default slot |
+| `VJoyBadgeLevel` | SuperMalter / verification badges below the name |
+| `VJoyWrapper` | Layout and spacing for multiple default-slot children |
+| `VJoyListItem` | Generic list rows with actions, not identity-focused cards |
+| `VJoyLink` | Inline text navigation inside copy |
+| `VJoyAvatarsList` | Stacked/overlapping avatar groups without name stack |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyUserCard.dsds.json`](./JoyUserCard.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Avatar + name + subtitle (+ optional metadata) | `VJoyUserCard` | Custom flex row + raw `<img>` |
+| Profile picture only | `VJoyAvatar` | `VJoyUserCard` without text |
+| Clickable profile in search / list | `VJoyUserCard` + `link` | `<div @click>` router navigation |
+| Rating or level under the name | `VJoyRatingStars` / `VJoyBadgeLevel` in **default** slot | `ratingValue` prop or `user-card-rating-stars` |
+| Open profile in new tab | `link` + `target="_blank"` + `rel="noopener noreferrer"` | `newTab` prop |
+| Rich interactive card layout | `VJoyButtonCard` | `VJoyUserCard` with heavy custom CSS |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyUserCard")` (or read `VJoyUserCard.vue`) before generating props.
+2. **MUST** use only props: `link`, `photoUrl`, `fullName`, `subTitle`.
+3. **MUST** pass native link attributes (`target`, `rel`, …) as HTML attributes on `VJoyUserCard`, not as invented props.
+4. **MUST** place `VJoyRatingStars` and extra metadata in the **default** slot.
+5. **MUST NOT** use `ratingValue`, `newTab`, `variant`, or `size` on `VJoyUserCard`.
+6. **MUST NOT** use deprecated `user-card-rating-stars` in new code.
+7. **MUST NOT** override `.joy-user-card` layout, font-size, or colors with hardcoded app CSS — use `--user-card-*` tokens if needed.
+8. **SHOULD** set `fullName` whenever `photoUrl` may be missing (initials fallback on avatar).
+9. **SHOULD** use `user-card-avatar` only when `VJoyAvatar` needs non-default `size` or behavior.
+
+### Checklist
+
+- [ ] Correct component (`VJoyUserCard` or named alternative)
+- [ ] Props from MCP / source only (`link`, `photoUrl`, `fullName`, `subTitle`)
+- [ ] Rating / badges in default slot — not `ratingValue` or deprecated rating slot
+- [ ] `target` / `rel` as attributes when `link` opens a new tab
+- [ ] No invented props / no custom `.joy-user-card` chrome CSS
+- [ ] Link card: one clear destination; nested links don’t conflict
+- [ ] Title identifies the person or entity
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyUserCard.dsds.json`](./JoyUserCard.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / layout | `anatomy` |
+| States | `states` |
+| Best practices | `guidelines` |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Token theming | `design-specifications` in JSON (`--user-card-*`) |

package/dist/doc/VJoyUserCard/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyUserCard",
   "displayName": "VJoyUserCard",
-  "description": "A comprehensive user profile card component for displaying user information in a structured layout.\nFeatures integrated avatar display, name/subtitle presentation, rating stars support, and optional\nlink functionality for navigation. Includes multiple customization slots for avatar, title, subtitle,\nand rating components, with full attribute inheritance for link behavior and accessibility.",
+  "description": "A comprehensive user profile card component for displaying user information in a structured layout.\nFeatures integrated avatar display, name/subtitle presentation, rating stars support, and optional\nlink functionality for navigation. Includes multiple customization slots for avatar, title, subtitle,\nand free content through the default slot, with full attribute inheritance for link behavior and\naccessibility. The user-card-rating-stars slot is deprecated; use the default slot for custom\nrating stars or other free content instead.",
   "category": "View",
   "props": [
     {
@@ -31,15 +31,6 @@
         "string"
       ]
     },
-    {
-      "name": "ratingValue",
-      "type": "number | undefined",
-      "required": false,
-      "description": "Introduce a VJoyRatingStars component with given rating",
-      "possibleValues": [
-        "number"
-      ]
-    },
     {
       "name": "subTitle",
       "type": "string | undefined",
@@ -54,7 +45,7 @@
   "slots": [
     {
       "name": "default",
-      "description": ""
+      "description": "Free content displayed below the user information. Use this slot for custom content like VJoyRatingStars."
     },
     {
       "name": "user-card-avatar",
@@ -70,7 +61,7 @@
     },
     {
       "name": "user-card-rating-stars",
-      "description": "Use your own customized VJoyRatingStars here, if needed"
+      "description": ""
     }
   ],
   "exposed": [
@@ -89,11 +80,6 @@
       "type": "string | undefined",
       "isMethod": false
     },
-    {
-      "name": "ratingValue",
-      "type": "number | undefined",
-      "isMethod": false
-    },
     {
       "name": "subTitle",
       "type": "string | undefined",

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`) |