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

package/dist/doc/VJoyTagsList/guideline.md

@@ -0,0 +1,311 @@
+---
+component: VJoyTagsList
+status: draft
+language: en
+dsds: JoyTagsList.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Tags list
+
+Use **`VJoyTagsList`** when you need a horizontal, wrapping row of **`VJoyTag`** chips driven from data — for example skills on a profile, applied filters, selected categories, or removable tokens.
+
+It applies shared layout (`flex`, wrap, gap), optional alignment, list-level `variant` / `removable` / `selectable` defaults, and `v-model` for multi-select toggling. Per-tag options in the `tags` array can override those defaults.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTagsList` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyTagsList docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoytagslist--docs) |
+| **DSDS (machine)** | [`JoyTagsList.dsds.json`](./JoyTagsList.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTagsList")` |
+
+---
+
+## When to use this component
+
+Use a tags list when several labels should appear together as chips with consistent spacing and alignment — especially when the set comes from an array and you want list-level styling or selection/removal behavior without hand-rolling a flex wrapper.
+
+Typical jobs: show assigned skills or technologies, display active filters, let users toggle filter chips on/off, or present removable tokens after a search or tags-input flow.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A single standalone chip | `VJoyTag` |
+| Full control over layout, drag-and-drop, or one-off tag markup | `VJoyTag` (or several) inside `VJoyWrapper` — the metadata explicitly allows dropping `VJoyTagsList` for flexibility |
+| Typing and adding new tags in a form field | `VJoyTagsInput` |
+| Choosing exactly one option from a list | `VJoyRadio` / `VJoyRadioGroup` |
+| Multi-select inside a dropdown | `VJoySelect` (multi) or `VJoyCheckboxGroup` |
+| Custom flex row / ad-hoc chip CSS | Still use `VJoyTagsList` or `VJoyTag` + Joy tokens |
+
+> **Note:** `selectable` and `removable` are **not compatible** on the same list. Pick one interaction model per instance.
+
+---
+
+## How it works
+
+`VJoyTagsList` renders one `VJoyTag` per entry in `tags`, forwarding each tag’s props and merging list-level defaults. Selection state is driven by `v-model` (`modelValue` as an array of tag `value`s). Removal emits `removeTag` with the removed tag’s `value` — the parent must update `tags`.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-tags-list` flex wrapper with alignment modifier |
+| `VJoyTag` (per item) | Yes | One chip per `tags` entry; label from `tag.label` unless `tag` slot overrides |
+| `tag` slot | No | Custom content per tag; forwarded tag props as slot props |
+| Gap | Yes | `--joy-core-spacing-4` between tags — don’t hardcode margins in apps |
+
+### Default values
+
+- `align` defaults to **`left`**
+- `variant` defaults to **`primary`** (applied to every tag unless a tag sets its own `variant`)
+- `removable` defaults to **`false`**
+- `selectable` defaults to **`false`**
+- `tags` defaults to **`[]`**
+- `modelValue` has **no default** — bind `v-model` when using selectable tags
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Selection and removal
+
+- **Selectable** — set `selectable` (or per-tag `selectable`) **and** bind `v-model`. Each tag **must** have a unique `value`. Toggling a tag updates `modelValue` with that `value` added or removed.
+- **Removable** — set `removable` (or per-tag `removable`) and listen for `@removeTag`. Update the `tags` array in the parent; the list does not remove items by itself.
+- **Per-tag overrides** — any `IJoyTag` field on a `tags` entry overrides the list default (`variant`, `selectable`, `removable`, `size`, `draggable`, etc.).
+
+---
+
+## Variants
+
+List-level `variant` sets the default chip style for all tags. Override individual entries with `tags[i].variant` when one chip needs different emphasis (e.g. one `important` tag in a `secondary` list).
+
+Choose variant by **meaning**, not decoration.
+
+| Variant | Use when |
+| --- | --- |
+| `primary` | Default product chips; supports **selectable** styling |
+| `secondary` | Lower emphasis; supports **selectable** styling |
+| `important` | Critical or high-attention labels |
+| `inactive` | Deprecated, archived, or unavailable items |
+| `pending` | Awaiting action or in-progress state |
+| `pricing` | Price or billing-related labels |
+| `special` | Promotional or highlighted offers |
+| `empty` | Placeholder or “no value” styling |
+| `ai-primary` / `ai-secondary` | Tags that are explicitly part of an AI feature |
+
+### Selectable styling constraint
+
+On `VJoyTag`, **selectable interaction only applies to `primary` and `secondary`**. Other variants render as chips but won’t toggle selection on click even if `selectable` is true.
+
+### Not in the API: list-level `size`
+
+There is no `size` prop on `VJoyTagsList`. Set `size` on each tag object (`small`, `medium`, `large`, `xsmall`, `xxlarge`) when density must differ within the list.
+
+---
+
+## Sizes
+
+`VJoyTagsList` has **no size API**. Density comes from per-tag `size` on `VJoyTag` entries (default **`medium`** on each tag).
+
+| Tag `size` | Use when |
+| --- | --- |
+| `medium` | Default product chips |
+| `small` / `xsmall` | Dense toolbars, tables, or filter rows |
+| `large` / `xxlarge` | Marketing or hero-scale emphasis (rare for lists) |
+
+Layout gap is fixed via `--joy-core-spacing-4` on the list — **don’t** hardcode pixel gaps between tags in product CSS.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (read-only) | Chips in a wrapping row; no remove icon; not toggleable |
+| Selected (`v-model` + `selectable`) | Matching tags show selected styling (`joy-tag__selected`) |
+| Removable | Cross icon on each removable tag; click emits `removeTag` |
+| Hover / focus | Per `VJoyTag` — selectable tags use `role="button"` and `tabindex="0"` |
+| Disabled (per tag) | Set `disabled: true` on a tag entry; click and selection are blocked |
+| Custom `tag` slot | Full control of chip content; **you** must reimplement remove/select/drag if needed |
+
+When `removable` is true at list level, selected styling is suppressed (`tagIsSelected` returns false).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Data and interaction
+
+- **MUST** give every tag a unique **`value`** when using `selectable` or `removable`.
+- **MUST** bind **`v-model`** when tags should toggle selection; `selectable` alone does nothing without `modelValue`.
+- **MUST** handle **`@removeTag`** and update the `tags` source — the list only emits the event.
+- **MUST NOT** combine **`selectable`** and **`removable`** on the same list.
+- **SHOULD** keep tag sets **scannable** (roughly under ~10 visible chips before considering truncation, “show more”, or a summary).
+- **SHOULD** use **`secondary`** for filter chips and **`primary`** for assigned metadata unless design specifies otherwise.
+
+### Implementation
+
+- **MUST** use only documented props and enums from MCP or `JoyTagsList.types.ts` / `JoyTag.types.ts`.
+- **MUST** use Joy tokens — no custom `.joy-tags-list` or `.joy-tag` chrome overrides.
+- **MUST NOT** invent list-level props (`size`, `gap`, `color`, …).
+- **SHOULD** prefer list-level `variant` / `removable` / `selectable` and override per tag only when needed.
+- **SHOULD** use raw **`VJoyTag` + `VJoyWrapper`** when you need drag-and-drop reordering or non-standard layout — `draggable` on a tag only shows a drag icon; it does not implement sorting.
+
+### Custom slot
+
+- **MUST** reimplement remove, select, and drag behavior yourself when using the **`tag` slot — default `VJoyTag` behaviors for `draggable` / `removable` are bypassed.
+- **SHOULD** avoid the `tag` slot unless the default label + icon layout is insufficient.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-model` + `selectable` + unique `value`s | `selectable` without `v-model` |
+| `@removeTag` → filter `tags` in parent | Expect the list to mutate `tags` automatically |
+| List `variant="secondary"` for filters | Mix `selectable` and `removable` on one list |
+| Per-tag `variant` for one outlier chip | Different list components for the same chip row |
+| `VJoyTagsInput` for adding tags | `VJoyTagsList` as a free-text input |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Structure | Plain `div` list; semantics come from each `VJoyTag` |
+| Selectable tags | `role="button"`, `tabindex="0"` on `VJoyTag`; toggle via click (keyboard activation follows tag implementation) |
+| Removable tags | Remove control is a `VJoyIcon` with `role="button"`; `@keydown.enter` removes |
+| Name | Each chip’s accessible name should come from visible `label` text (or meaningful slot content) |
+| Selection state | Don’t rely on color alone — selected chips use `joy-tag__selected` styling; ensure contrast meets product requirements |
+| Disabled tags | Set `disabled: true` on the tag entry; don’t only dim with CSS |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyTagsList } from '@maltjoy/core-vue'
+import type { TJoyTagsList, TJoyTagsListModel } from '@maltjoy/core-vue'
+
+const skills = ref<TJoyTagsList>([
+  { value: 'vue', label: 'Vue.js' },
+  { value: 'ts', label: 'TypeScript' },
+  { value: 'design', label: 'Design systems' },
+])
+
+const selectedFilters = ref<TJoyTagsListModel>(['vue'])
+
+const filters = ref<TJoyTagsList>([
+  { value: 'vue', label: 'Vue.js' },
+  { value: 'ts', label: 'TypeScript' },
+  { value: 'design', label: 'Design systems' },
+])
+
+function onRemoveTag(tagValue: string | number | undefined) {
+  filters.value = filters.value.filter((t) => t.value !== tagValue)
+}
+</script>
+
+<template>
+  <!-- Read-only metadata -->
+  <VJoyTagsList variant="secondary" :tags="skills" />
+
+  <!-- Toggleable filter chips -->
+  <VJoyTagsList
+    v-model="selectedFilters"
+    variant="secondary"
+    selectable
+    :tags="skills"
+  />
+
+  <!-- Removable tokens (parent updates tags) -->
+  <VJoyTagsList
+    variant="secondary"
+    removable
+    :tags="filters"
+    @remove-tag="onRemoveTag"
+  />
+
+  <!-- Centered row -->
+  <VJoyTagsList align="center" variant="primary" :tags="skills" />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTagsList` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyTag` | A single chip, or manual lists with custom layout |
+| `VJoyTagsInput` | Users type and add tags in a form field |
+| `VJoyWrapper` | Spacing wrapper when composing tags manually |
+| `VJoySelectableItemGroup` | Selectable list rows rather than chips |
+| `VJoyCheckbox` / `VJoyCheckboxGroup` | Multi-select with checkbox affordance |
+
+---
+
+## For agents
+
+Maps to `agentDocumentBlocks` in [`JoyTagsList.dsds.json`](./JoyTagsList.dsds.json). Humans can skip this section.
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Display chips from an array | `VJoyTagsList` | Manual `div` + custom chip CSS |
+| One chip | `VJoyTag` | `VJoyTagsList` with one item |
+| User adds tags by typing | `VJoyTagsInput` | `VJoyTagsList` with a text field |
+| Toggle filters on/off | `VJoyTagsList` + `v-model` + `selectable` | `removable` on the same list |
+| Remove chips | `VJoyTagsList` + `removable` + `@removeTag` | `selectable` on the same list |
+| Full layout / DnD control | `VJoyTag` in `VJoyWrapper` | `VJoyTagsList` + heavy `tag` slot hacks |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyTagsList")` (or read types) before generating props.  
+2. **MUST** include unique `value` on each tag when `selectable` or `removable` is used.  
+3. **MUST** bind `v-model` for selectable lists.  
+4. **MUST** handle `@removeTag` and update `tags` in the parent for removable lists.  
+5. **MUST NOT** set `selectable` and `removable` together on one list.  
+6. **MUST NOT** invent props (`size`, `gap`, `color`, …) on `VJoyTagsList`.  
+7. **MUST NOT** override `.joy-tags-list` or `.joy-tag` layout/colors in product CSS.  
+8. **SHOULD** use `primary` or `secondary` variants when chips are selectable.
+
+### Checklist
+
+- [ ] Correct component (`VJoyTagsList` or named alternative)
+- [ ] Props / enums from MCP only
+- [ ] `tags` entries have `label`; `value` when selectable or removable
+- [ ] `v-model` present when `selectable` is true
+- [ ] Not mixing `selectable` and `removable`
+- [ ] `@removeTag` wired when `removable` is true
+- [ ] No custom chip/list chrome CSS
+- [ ] `tag` slot only when custom content is required (and behaviors reimplemented if needed)
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyTagsList.dsds.json`](./JoyTagsList.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 | `guidelines` |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |

package/dist/doc/VJoyTemplate/guideline.md

@@ -0,0 +1,366 @@
+---
+component: VJoyTemplate
+status: draft
+language: en
+dsds: JoyTemplate.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Template
+
+Use **`VJoyTemplate`** when you need a consistent **page-level layout** — header (title, subtitle, actions, optional back control), a main content column, and an optional sidebar.
+
+It handles responsive stacking, optional full-width mode, a loading overlay via `VJoyScreenLoader`, and decorative background shapes. Compose page sections inside the slots with `VJoyPanel`, forms with `VJoyWrapper`, and navigation menus in the sidebar when needed.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTemplate` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyTemplate docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-layout-vjoytemplate--docs) |
+| **DSDS (machine)** | [`JoyTemplate.dsds.json`](./JoyTemplate.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTemplate")` |
+
+---
+
+## When to use this component
+
+Use the template when building a **new product screen** that needs a predictable page chrome: page title, optional subtitle, top-right actions, primary content, and sometimes a secondary column (filters, navigation, summary card).
+
+It is the default wrapper for most in-app pages. Stack `VJoyPanel` components in `template-main` (and optionally `template-sidebar`) to create sections with consistent spacing.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Multi-step guided flow / onboarding funnel | `VJoyFunnel` |
+| Card or section inside an existing page (not the page shell) | `VJoyPanel` |
+| Modal overlay interrupting the current task | `VJoyDialog` |
+| Slide-in panel from the edge | `VJoyDrawer` |
+| Flexbox utility layout inside a form or toolbar | `VJoyWrapper` |
+| Custom page markup with ad-hoc layout CSS | Still use `VJoyTemplate` + Joy tokens — don’t reinvent page chrome |
+
+> **Internal:** `VJoyTemplateShape` / `TemplateShape` is not public API. Use the `shapes` prop on `VJoyTemplate` — do not import the shape component directly.
+
+---
+
+## How it works
+
+The root is a `<div class="joy-template">` (not `<main>`) so apps can own the document landmark and avoid duplicate `<main>` regions. Content is organized through **named slots**; the header row renders only when at least one header slot is provided.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-template` — padding, max width, optional `--full` / `--loading` modifiers |
+| Decorative shapes | No | Fixed bottom-right shapes when `shapes` is true (primary palette; not customizable) |
+| Header row | No* | `.joy-template__heading` — back, title block, actions (*shown when any header slot is used) |
+| Back slot | No | `#template-back` — typically a `VJoyIconButton` left of the title |
+| Title slot | Yes (product rule) | `#template-title` — page heading; ESLint requires an `h1`–`h6` (prefer `h1`) |
+| Subtitle slot | No | `#template-subtitle` — supporting description below the title |
+| Actions slot | No | `#template-actions` — top-right area, usually primary/secondary CTAs |
+| Content row | No* | `.joy-template__content` — flex row for main + sidebar (*when those slots are used) |
+| Main slot | No | `#template-main` — primary page body (panels, forms, lists) |
+| Sidebar slot | No | `#template-sidebar` — secondary column (e.g. `VJoyMenu`, summary, filters) |
+| Loading overlay | No | `VJoyScreenLoader` with blur on content when `loading` is true |
+| Loader content slot | No | `#template-loader-content` — message beside the spinner |
+
+### Default values
+
+- `full` defaults to **`false`** (`true` → content wrapper spans 100% width)
+- `sidebar` defaults to **`right`** (`left` reverses the flex order)
+- `loading` defaults to **`false`**
+- `loadingColor` defaults to **`light`** (`dark` for darker backgrounds)
+- `shapes` defaults to **`false`**
+
+Layout tokens (CSS custom properties on `.joy-template`):
+
+- `--template-layout-width` — **`1024px`** (overridden to `100%` when `full` is true)
+- `--template-sidebar-width` — **`320px`**
+- `--template-inner-spacing` — **`var(--joy-core-spacing-8)`** (spacing-6 ≤ 991px, spacing-4 ≤ 760px)
+
+Props and slots: use Joy MCP (`joy_get_component_info`, `joy_get_component_types`) or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Responsive behavior
+
+- **≤ 1024px:** main and sidebar stack vertically (sidebar below main by default; order follows `sidebar` prop).
+- **≤ 767px:** header actions wrap to a full-width row below the title block.
+
+---
+
+## Layout options
+
+`VJoyTemplate` has no color variant prop. Choose **layout behavior** by props and slots.
+
+### Default (centered column)
+
+Content wrapper is capped at `--template-layout-width` (1024px) and centered. Use for standard product pages.
+
+### Full width (`full`)
+
+Sets `--template-layout-width` to `100%`. Use when the page must use the full viewport width (dashboards, wide tables) while keeping inner padding from `--template-inner-spacing`.
+
+Avoid `full` when a readable line length matters and the design expects the default 1024px column.
+
+### Sidebar right (`sidebar="right"`)
+
+Default. Main content on the left, sidebar on the right — typical for detail pages with a nav or summary column.
+
+### Sidebar left (`sidebar="left"`)
+
+Reverses the flex row. Use when design places the secondary column on the left (uncommon; confirm with layout specs).
+
+### Decorative shapes (`shapes`)
+
+Fixed primary-colored shapes in the bottom-right corner. Disabled by default; no palette or position customization.
+
+Use only when design approves decorative branding on that screen. Avoid on dense or data-heavy pages where shapes compete with content.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Page content visible; header and columns per provided slots |
+| Loading (`loading`) | `VJoyScreenLoader` overlay; main wrapper blurred; optional message in `#template-loader-content` |
+| Loading color `light` / `dark` | Spinner/contrast tuned for light vs dark page backgrounds |
+
+Prefer `loading` during initial page fetch or route transitions instead of empty shells with no feedback.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (same idea as DSDS `guidelines.level`).
+
+### Page structure
+
+- **MUST** provide `#template-title` on every `VJoyTemplate` (enforced by ESLint `require-vjoytemplate-template-title`).
+- **MUST** put an **`h1`–`h6` inside `#template-title`**, preferably **`h1`** (ESLint `require-vjoytemplate-template-title-heading`).
+- **SHOULD** place `VJoyMenu` in `#template-sidebar` when used as page nav (ESLint `require-vjoymenu-template-sidebar`).
+- **SHOULD** stack sections with `VJoyPanel` inside `#template-main` rather than ad-hoc margin on every block.
+- **SHOULD** use `#template-back` with `VJoyIconButton` (e.g. `arrow-left`, `variant="ghost"`) for upward navigation.
+- **SHOULD** reserve `#template-actions` for page-level CTAs (one principal action + companions).
+
+### Implementation
+
+- **MUST** use only documented props: `full`, `sidebar`, `loading`, `loadingColor`, `shapes`.
+- **MUST** use Joy tokens and documented CSS variables — no custom page-shell chrome.
+- **MUST NOT** import or render `VJoyTemplateShape` / `TemplateShape` directly — use `shapes`.
+- **MUST NOT** override `--template-layout-width` unless unavoidable; design treats 1024px as a strict rule.
+- **MAY** override `--template-sidebar-width` when the sidebar needs a different fixed width.
+- **MUST NOT** wrap the template root in another `<main>` if the app already exposes a single page `<main>`.
+
+### Interaction
+
+- **MUST** set `loading` while async page data is not ready (with a short message in `#template-loader-content` when helpful).
+- **SHOULD** keep sidebar content supplementary — primary tasks stay in `#template-main`.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `#template-title` with `<h1>` | Plain `<div>` or missing title slot |
+| `VJoyPanel` for sections | Random margin utilities on every block |
+| `shapes` prop for decoration | Import internal shape component |
+| `full` for intentional wide layouts | `full` on every page by default |
+| `VJoyMenu` in `#template-sidebar` | `VJoyMenu` floating outside the template sidebar slot |
+
+---
+
+## Content
+
+The template does not own copy — it structures where **page title**, **subtitle**, and **actions** appear. Follow product voice in those slots.
+
+### Title (`#template-title`)
+
+- **MUST** use a real heading element (`h1` preferred) — one primary page title per view.
+- **SHOULD** match the browser tab / route purpose; keep it scannable (short noun phrase or task name).
+- **MAY** use `VJoyTitleBrand` inside the slot for marketing-style highlighted titles (also valid in `VJoyDialog`).
+
+### Subtitle (`#template-subtitle`)
+
+- **SHOULD** clarify scope or context in one line — not duplicate the title.
+- **SHOULD NOT** hold long paragraphs; move body copy to `#template-main`.
+
+### Actions (`#template-actions`)
+
+- **SHOULD** use `VJoyButton` with clear verb + noun labels (see Button guidelines).
+- **SHOULD** limit to a small set of actions (typically one `main`/`primary` + secondary/ghost companions).
+- **SHOULD NOT** crowd the header with many equal-weight CTAs.
+
+### Loading message (`#template-loader-content`)
+
+- **SHOULD** use short, present-tense text (`Loading projects…`) — not marketing copy.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Document landmark | Template root is a `<div>` — the **app** provides `<main>` (or equivalent) around or above this component; avoid nested `<main>` |
+| Page title | `#template-title` contains a heading (`h1` preferred) so assistive tech can find the page name |
+| Heading order | Don’t skip levels inside the page; template title is typically the page `h1` |
+| Back control | `#template-back` should expose an accessible name (`label` on `VJoyIconButton`) |
+| Loading | Overlay blocks interaction on blurred content; provide meaningful loader text when the wait is non-trivial |
+| Shapes | Decorative only — no information conveyed by shapes alone |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyTemplate,
+  VJoyIconButton,
+  VJoyButton,
+  VJoyPanel,
+} from '@maltjoy/core-vue'
+
+const loading = ref(false)
+</script>
+
+<template>
+  <!-- Standard page with sidebar -->
+  <VJoyTemplate>
+    <template #template-title>
+      <h1>Project settings</h1>
+    </template>
+    <template #template-subtitle>
+      Manage visibility, team, and billing for this project.
+    </template>
+    <template #template-actions>
+      <VJoyButton variant="main" label="Save changes" />
+    </template>
+    <template #template-main>
+      <VJoyPanel title="General">…</VJoyPanel>
+      <VJoyPanel title="Team">…</VJoyPanel>
+    </template>
+    <template #template-sidebar>
+      <!-- e.g. VJoyMenu for section nav -->
+      …
+    </template>
+  </VJoyTemplate>
+
+  <!-- Back navigation + loading -->
+  <VJoyTemplate :loading="loading" loading-color="light">
+    <template #template-back>
+      <VJoyIconButton
+        icon="arrow-left"
+        variant="ghost"
+        label="Back to projects"
+      />
+    </template>
+    <template #template-title>
+      <h1>Acme brief</h1>
+    </template>
+    <template #template-main>
+      …
+    </template>
+    <template #template-loader-content>
+      Loading project…
+    </template>
+  </VJoyTemplate>
+
+  <!-- Full width + decorative shapes (design-approved) -->
+  <VJoyTemplate full shapes sidebar="left">
+    <template #template-title>
+      <h1>Analytics</h1>
+    </template>
+    <template #template-main>
+      …
+    </template>
+  </VJoyTemplate>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTemplate` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyPanel` | Sections inside `template-main` or `template-sidebar` |
+| `VJoyFunnel` | Multi-step flows instead of a standard page shell |
+| `VJoyWrapper` | Form field spacing and flex layout inside a panel |
+| `VJoyMenu` | Sidebar navigation (place in `#template-sidebar`) |
+| `VJoyIconButton` | Back control in `#template-back` |
+| `VJoyButton` | Page-level actions in `#template-actions` |
+| `VJoyTitleBrand` | Branded / highlighted page titles |
+| `VJoyScreenLoader` | Standalone full-screen loading (template embeds it when `loading`) |
+| `VJoyDialog` / `VJoyDrawer` | Overlays on top of the page — not replacements for the template |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyTemplate.dsds.json`](./JoyTemplate.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Standard app page layout | `VJoyTemplate` + slots | Custom page grid CSS |
+| Section/card inside a page | `VJoyPanel` inside `#template-main` | Nested `VJoyTemplate` |
+| Onboarding / step funnel | `VJoyFunnel` | `VJoyTemplate` with fake stepper chrome |
+| Decorative corner shapes | `VJoyTemplate` + `shapes` | `VJoyTemplateShape` / `TemplateShape` import |
+| Page nav menu | `VJoyMenu` in `#template-sidebar` | `VJoyMenu` outside the sidebar slot |
+| Modal task | `VJoyDialog` | `VJoyTemplate` pretending to be a dialog |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyTemplate")` and/or read `JoyTemplate.types.ts` before generating props.
+2. **MUST** include `#template-title` with an **`h1`–`h6`** element (prefer **`h1`**).
+3. **MUST** use only documented props: `full`, `sidebar`, `loading`, `loadingColor`, `shapes`.
+4. **MUST** use slot names exactly: `template-back`, `template-title`, `template-subtitle`, `template-actions`, `template-main`, `template-sidebar`, `template-loader-content`.
+5. **MUST NOT** import `VJoyTemplateShape` or `TemplateShape`.
+6. **MUST NOT** override `--template-layout-width` except via `full` or documented emergency override.
+7. **MUST NOT** add a `<main>` wrapper inside the template — root is already a `<div>`.
+8. **SHOULD** default `sidebar="right"`, `loading={false}`, `shapes={false}`, `full={false}`.
+9. **SHOULD** set `loading` during async page load and optional `#template-loader-content` text.
+
+### Valid enums (from `JoyTemplate.types.ts` + MCP)
+
+| Prop | Values |
+| --- | --- |
+| `sidebar` | `left`, `right` |
+| `loadingColor` | `light`, `dark` |
+| `full`, `loading`, `shapes` | `boolean` |
+
+### Checklist
+
+- [ ] Correct component (`VJoyTemplate` or named alternative)
+- [ ] `#template-title` present with heading (`h1` preferred)
+- [ ] Props / enums from MCP or types only
+- [ ] No invented props / no custom template chrome CSS
+- [ ] `VJoyMenu` in `#template-sidebar` when used as page nav
+- [ ] `loading` + loader slot for async page states
+- [ ] `shapes` only when decorative branding is intended
+- [ ] Sections composed with `VJoyPanel`, not one-off layout hacks
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyTemplate.dsds.json`](./JoyTemplate.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / layout options | `anatomy` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Layout tokens | `design-specifications` in JSON (token names, not raw px dumps) |