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

package/dist/doc/VJoyMenu/guideline.md

@@ -0,0 +1,304 @@
+---
+component: VJoyMenu
+status: draft
+language: en
+dsds: JoyMenu.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Menu
+
+Use **`VJoyMenu`** when the user needs a **persistent vertical list of navigation destinations** — typically the sidebar in an app shell built with `VJoyTemplate`.
+
+Compose it with **`VJoyMenuItem`** children for links, buttons, or router-aware navigation. Each item can show a leading icon, a trailing status icon, a current-page state, and disabled styling. Keyboard navigation (arrow keys, Home/End, Enter) is built in.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyMenu` + `VJoyMenuItem` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Menu](https://zeroheight.com/6bf479565/p/955426-menu) |
+| **Storybook** | [VJoyMenu docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-navigation-vjoymenu--docs) |
+| **DSDS (machine)** | [`JoyMenu.dsds.json`](./JoyMenu.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyMenu")` · `joy_get_component_info("VJoyMenuItem")` |
+
+---
+
+## When to use this component
+
+Use a menu when users move between **sections or routes** from a fixed sidebar — for example app settings areas, account navigation, or funnel step lists inside `VJoyTemplate`.
+
+`VJoyMenuItem` supports plain anchors (`href`), buttons (`type="button"`), and framework links (`RouterLink` / `NuxtLink` via `type` + `linkProps`). Mark the active destination with `current`.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A contextual panel that opens from a trigger (overflow, filters) | `VJoyDropdown` |
+| Switching peer content panels on the same page | `VJoyTabs` |
+| Choosing one value inside a labeled form field | `VJoySelect` |
+| Short hover-only hints | `VJoyTooltip` |
+| Main content layout chrome | `VJoyPanel` (not as a wrapper around the menu) |
+| Custom `<ul>` / sidebar markup with ad-hoc CSS | Still use `VJoyMenu` + `VJoyMenuItem` + Joy tokens |
+
+> **Deprecated:** do not use the `items` prop on `VJoyMenu` for new work. Prefer `VJoyMenuItem` in the default slot. The `menu-item` slot only applies to the deprecated `items` API.
+
+---
+
+## How it works
+
+`VJoyMenu` renders a bordered `<ul role="menu">`. Each `VJoyMenuItem` renders a `<li role="menuitem">` with an inner interactive element (`<a>`, `<button>`, or a custom link component).
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Menu list (`VJoyMenu`) | Yes | Root `<ul>` with border, radius, and keyboard handling |
+| `aria-label` | Yes* | Accessible name for the menu (`ariaLabel` prop) — required when no visible heading labels the list |
+| `VJoyMenuItem` (default slot) | Yes (preferred) | One row per destination |
+| Leading icon | No | `icon` on `VJoyMenuItem` |
+| Label | Yes | Primary text on each item (`label` prop) |
+| Status icon | No | Trailing `status` + optional `statusColor` (check, warning, lock, …) |
+| Current indicator | No | `current` highlights the active destination (`aria-current`) |
+| `menu-item` slot | No | Custom inner content per row — **only** for deprecated `items` prop |
+
+### Default values
+
+- `items` defaults to **`[]`** (deprecated — prefer slot composition)
+- `VJoyMenuItem` `type` defaults to **`"a"`** (anchor)
+- `disabled` defaults to **`false`**
+- `current` defaults to **`false`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Visual treatment
+
+There is **no `variant` or `size` prop**. Item height, padding, colors, and border radius come from Joy tokens inside the component (e.g. `--joy-form-field-height-medium`, `--joy-core-radius-3`) — **don’t hardcode menu item heights or border colors** in product CSS.
+
+The list uses `--menu-item-min-width: 120px` internally. Long labels truncate with ellipsis; the full label is available via the native `title` attribute.
+
+### App shell placement
+
+In Malt apps, `VJoyMenu` belongs in **`VJoyTemplate`’s `#template-sidebar` slot** (enforced by the `require-vjoymenu-template-sidebar` ESLint rule). Do **not** nest `VJoyMenu` inside `VJoyPanel` (`no-vjoymenu-vjoypanel` rule) — the menu and panel serve different layout roles.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Neutral text; row is interactive |
+| Hover | Secondary background highlight (pointer devices) |
+| Focus | Inset focus ring on the inner control; current row also uses secondary background |
+| Current (`current`) | Secondary background and text color — marks the active page/section |
+| Disabled | Muted text, disabled background, `cursor: not-allowed`; not clickable |
+| Keyboard active (deprecated `items` mode) | `aria-activedescendant` tracks the focused row while arrowing |
+| Link item | Default `type="a"` or router link navigates on click / Enter |
+| Button item | `type="button"` fires `@click` on `VJoyMenuItem` without navigation |
+
+When a disabled item is visible, **explain why** nearby (tooltip or helper text) if the reason is not obvious from context.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Placement and hierarchy
+
+- **MUST** place `VJoyMenu` inside `VJoyTemplate` `#template-sidebar` in app-shell layouts.
+- **MUST NOT** nest `VJoyMenu` inside `VJoyPanel`.
+- **SHOULD** mark exactly one item `current` for the active route or section (when applicable).
+- **SHOULD** keep the menu list focused on navigation — avoid embedding heavy forms or multi-step panels inside menu rows.
+
+### Composition
+
+- **MUST** use `VJoyMenuItem` children for new work — not the deprecated `items` prop.
+- **MUST** set `aria-label` on `VJoyMenu` when the sidebar has no visible heading that names the list.
+- **SHOULD** use `type="button"` only when the row triggers an in-page action without navigation.
+- **SHOULD** use `RouterLink` / `NuxtLink` (`type` + `linkProps`) for SPA navigation instead of full page reloads.
+- **SHOULD** use `status` icons sparingly — completion, warning, or lock states users must notice at a glance.
+
+### Implementation
+
+- **MUST** use only documented prop values (MCP / `JoyMenu.types.ts` / `VJoyMenuItem` props).
+- **MUST** style with Joy tokens — no custom `.joy-menu-list` or `.joy-menu-item` chrome overrides.
+- **MUST NOT** invent props (`variant`, `size`, `open`, …).
+- **MUST NOT** use `VJoyMenu` for transient overlay menus — use `VJoyDropdown`.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyMenu` + `VJoyMenuItem` in `#template-sidebar` | `items` prop for new screens |
+| `current` on the active route | Multiple `current` items for one section |
+| `RouterLink` / `NuxtLink` for in-app nav | Raw `<a href>` that reloads the SPA unnecessarily |
+| `aria-label` when no visible list title | Unnamed menu for screen-reader users |
+| `status` for lock / warning / done | Decorative status icons on every row |
+
+---
+
+## Content
+
+Menu items are navigation labels. They should be scannable at a glance and parallel in grammar.
+
+### Label formula
+
+**Navigation items:** **short noun or noun phrase** naming the destination — e.g. `Dashboard`, `Billing`, `Team members`.
+
+**Action rows (`type="button"`):** **infinitive verb + noun** when the row triggers an action — e.g. `Sign out`, `Create project`.
+
+**Status context:** rely on the `status` icon + `statusColor` for lock/warning/done; don’t repeat the same meaning in the label unless needed for clarity.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Each `label` is unique within the menu |
+| **MUST** | Labels stay concise — long text truncates with ellipsis (`title` shows the full string) |
+| **MUST** | Disabled items include context elsewhere if the reason isn’t obvious |
+| **MUST NOT** | Vague labels — ❌ `Click here`, ❌ `Menu item` |
+| **MUST NOT** | Duplicate the section heading on every row when the group context is clear |
+| **SHOULD** | ≤ 3 words per label where possible |
+| **SHOULD** | Sentence case for multi-word labels |
+| **SHOULD** | Parallel grammar across siblings (`Overview`, `Settings`, `Billing` — not mixed verb/noun styles) |
+| **SHOULD** | Localize labels — menu copy is user-facing product UI |
+
+### Patterns
+
+**App sidebar** — Group related destinations under `VJoyTemplate` sidebar chrome (headings outside the menu if needed). One `current` item matching the active route.
+
+**Funnel / step list** — Each row is a step name (`Company details`, `Payment`). Use `status="check-circle"` + `statusColor="success"` for completed steps, `status="lock"` for locked future steps.
+
+**Mixed link + action** — Navigation rows use default `type="a"` or router links; a final `Sign out` row uses `type="button"`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Menu role | `role="menu"` on the `<ul>`; each row `role="menuitem"` |
+| Name | `aria-label` on `VJoyMenu` when no visible heading names the list |
+| Current page | `aria-current` on the item with `current` |
+| Disabled | `aria-disabled="true"`; not activatable |
+| Row name | `aria-label` and `title` from each item’s `label` |
+| Keyboard (list focus) | **ArrowDown** / **ArrowUp** move between enabled items; **Home** / **End** jump to first/last; **Enter** activates the focused row (clicks inner link/button); **Tab** clears active descendant tracking |
+| Space | Prevented from scrolling when an item is focused (deprecated `items` keyboard path) |
+| Focus ring | Visible inset ring on focused items — don’t remove in product CSS |
+| Icons | Leading/trailing icons are decorative when the label conveys meaning (Joy default) |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyMenu, VJoyMenuItem } from '@maltjoy/core-vue'
+import { NuxtLink } from '#components'
+</script>
+
+<template>
+  <!-- Preferred: VJoyMenuItem composition inside app shell -->
+  <VJoyTemplate>
+    <template #template-sidebar>
+      <VJoyMenu aria-label="Account navigation">
+        <VJoyMenuItem icon="user" label="Profile" href="/account/profile" />
+        <VJoyMenuItem icon="billing" label="Billing" href="/account/billing" current />
+        <VJoyMenuItem
+          icon="team"
+          label="Team members"
+          :type="NuxtLink"
+          :link-props="{ to: '/account/team' }"
+        />
+        <VJoyMenuItem
+          label="Security"
+          status="warning"
+          status-color="warning"
+          href="/account/security"
+        />
+        <VJoyMenuItem label="Archived" disabled icon="company-placeholder" status="lock" />
+        <VJoyMenuItem type="button" label="Sign out" @click="/* handle sign out */" />
+      </VJoyMenu>
+    </template>
+
+    <template #template-main>
+      <!-- page content -->
+    </template>
+  </VJoyTemplate>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyMenu` / `VJoyMenuItem` are already global. For Vue Router, pass `RouterLink` as `type` with `link-props="{ to: '...' }"` the same way as `NuxtLink` in Storybook.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyMenuItem` | Each row inside `VJoyMenu` (required for new work) |
+| `VJoyTemplate` | App shell with `#template-sidebar` slot for the menu |
+| `VJoyDropdown` | Contextual menus opened from a trigger |
+| `VJoyTabs` | Peer content panels on one page |
+| `VJoyPanel` | Main or sidebar content blocks — not as a parent of `VJoyMenu` |
+| `VJoyIcon` | Icons on menu items (`icon`, `status`) |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyMenu.dsds.json`](./JoyMenu.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Persistent sidebar / app navigation | `VJoyMenu` + `VJoyMenuItem` | `VJoyDropdown` |
+| Overflow menu from a button | `VJoyDropdown` | `VJoyMenu` |
+| Tab panels on one page | `VJoyTabs` | `VJoyMenu` for section switching |
+| Form single-select | `VJoySelect` | `VJoyMenu` |
+| SPA route link | `VJoyMenuItem` + `RouterLink`/`NuxtLink` | Raw `<li><a>` lists |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyMenu")` and `joy_get_component_info("VJoyMenuItem")` before generating props.
+2. **MUST** compose menus with `VJoyMenuItem` in the default slot — not the deprecated `items` prop.
+3. **MUST** set `aria-label` on `VJoyMenu` when no visible heading names the list.
+4. **MUST** place `VJoyMenu` in `VJoyTemplate` `#template-sidebar` for app-shell layouts.
+5. **MUST NOT** nest `VJoyMenu` inside `VJoyPanel`.
+6. **MUST NOT** invent props (`variant`, `size`, `open`, …) or override `.joy-menu-list` / `.joy-menu-item` chrome.
+7. **SHOULD** set `current` on the item matching the active route.
+8. **SHOULD** use `type="button"` only for non-navigation actions (e.g. sign out).
+
+### Checklist
+
+- [ ] Correct component (`VJoyMenu` + `VJoyMenuItem`, or named alternative)
+- [ ] Props from MCP / types only — no `items` prop on new code
+- [ ] `aria-label` on the menu when needed
+- [ ] `#template-sidebar` placement in `VJoyTemplate` layouts
+- [ ] Not nested inside `VJoyPanel`
+- [ ] At most one `current` item per logical section
+- [ ] Router links use `type` + `linkProps`, not bare `href` reloads in SPAs
+- [ ] No invented props / no custom menu chrome CSS
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyMenu.dsds.json`](./JoyMenu.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Visual treatment (no variants/sizes) | `design-specifications` |
+| 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 |

package/dist/doc/VJoyMenuItem/guideline.md

@@ -0,0 +1,352 @@
+---
+component: VJoyMenuItem
+status: draft
+language: en
+dsds: JoyMenuItem.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Menu item
+
+Use **`VJoyMenuItem`** when you need a single row inside a navigation menu — a labeled choice that navigates somewhere, fires an in-page action, or shows selection and status at a glance.
+
+Each item renders as a `role="menuitem"` list row with optional leading icon, required text label, and optional trailing status icon. The inner control can be a native link (`<a>`), a `<button>`, or a router component (`RouterLink`, `NuxtLink`) passed through the `type` prop.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyMenuItem` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyMenu docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-navigation-vjoymenu--docs) (see **WithSubItem** story) |
+| **DSDS (machine)** | [`JoyMenuItem.dsds.json`](./JoyMenuItem.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyMenuItem")` — if unavailable, read `VJoyMenuItem.vue` and `JoyMenu.metadata.md` |
+
+> **MCP note:** Joy MCP may not return `VJoyMenuItem` API yet (docs generation is broken for this component). Use `VJoyMenuItem.vue`, `JoyMenu.metadata.md`, or Storybook **WithSubItem** as the source of truth until MCP is updated.
+
+---
+
+## When to use this component
+
+Use a menu item when building a **persistent navigation list** inside `VJoyMenu` — for example app sidebar links, station pickers, or settings sections where each row is a destination or action.
+
+`VJoyMenuItem` is the preferred way to declare menu rows (icons, current state, disabled rows, router links). Compose one or more items in the **default slot** of `VJoyMenu`.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Contextual overflow / action menu from a trigger | `VJoyDropdown` + `VJoyDropdownList` |
+| Labeled single-select form field | `VJoySelect` |
+| Tabbed content switching on the same surface | `VJoyTabs` |
+| Standalone CTA or form submit | `VJoyButton` |
+| Data list rows with rich left/right content | `VJoyListItem` |
+| Custom `<li>` markup with ad-hoc menu styling | Still use `VJoyMenuItem` + Joy tokens — don’t reinvent menu row chrome |
+
+> **Deprecated:** do not drive menu rows through `VJoyMenu`’s `items` prop for new work. That array API is deprecated — use `VJoyMenuItem` children in the default slot instead.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| List row (`<li>`) | Yes | Outer `role="menuitem"` wrapper with `aria-label`, `aria-disabled`, and `aria-current` |
+| Inner control | Yes | `.joy-menu-item__inner` — `<a>`, `<button>`, router component, or `<div>` when `disabled` |
+| Label | Yes | Text from the `label` prop (`.joy-menu-item__label`) |
+| Leading icon | No | `VJoyIcon` when `icon` is set (`.joy-menu-item__icon-left`) |
+| Status icon | No | Trailing `VJoyIcon` when `status` is set (`.joy-menu-item__icon-right`); color via `statusColor` |
+| Focus ring | Yes | Inset `box-shadow` on inner `:focus` — don’t remove it in product CSS |
+
+### Default values
+
+- `type` defaults to **`'a'`** (native anchor)
+- `disabled` defaults to **`false`**
+- `current` defaults to **`false`**
+- `href`, `icon`, `status`, `statusColor`, and `linkProps` are optional
+
+Props, events, and composition: use Joy MCP (when available), `VJoyMenuItem.vue`, or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Link types
+
+| `type` | Inner element | Props / attrs |
+| --- | --- | --- |
+| `'a'` (default) | `<a href="…">` | `href` prop + native attrs via `$attrs` (`target`, `rel`, `data-*`, …) |
+| `'button'` | `<button type="button">` | Native button attrs via `$attrs`; emits `click` |
+| `RouterLink` / `NuxtLink` / custom component | Dynamic `:is="type"` | Pass routing props via `linkProps` (e.g. `{ to: '/' }`) |
+
+When `disabled` is true, the inner control becomes a **non-interactive `<div>`** — clicks do not emit `click`.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Neutral text (`--joy-color-neutral-60`); row is interactive |
+| Hover | Light secondary background (`--joy-color-secondary-10`) on the inner control |
+| Focus | Secondary background + inset information focus ring (`--joy-color-information-50`) |
+| Current | `current` prop — secondary background and secondary text color; `aria-current` on the row |
+| Disabled | Muted text, disabled background (`--joy-color-state-disabled-background`), `cursor: not-allowed`; inner is `<div>`; `aria-disabled="true"`; no `click` emission |
+
+Long labels truncate with ellipsis; the full string is available via the native `title` attribute on the row.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Composition
+
+- **MUST** place `VJoyMenuItem` inside `VJoyMenu` (default slot) so keyboard navigation and `role="menu"` semantics stay correct.
+- **MUST** set `aria-label` on `VJoyMenu` when the menu’s purpose isn’t obvious from visible context alone.
+- **SHOULD** use at most one `current` item per menu when indicating the active destination.
+- **SHOULD** order items logically — primary destinations first, destructive or rare actions last.
+
+### Implementation
+
+- **MUST** use only documented props from `VJoyMenuItem.vue` / `JoyMenu.metadata.md` — no invented props.
+- **MUST** style with Joy tokens — no custom `.joy-menu-item` chrome overrides.
+- **MUST** pass `href` when `type` is `'a'` and the row navigates.
+- **MUST** pass `linkProps` when `type` is `RouterLink`, `NuxtLink`, or another component.
+- **MUST NOT** use `VJoyMenu`’s deprecated `items` array for new menus.
+- **MUST NOT** hardcode row height — the component uses `--joy-form-field-height-medium`.
+- **SHOULD** pass native HTML attributes (`target`, `rel`, `data-test-id`, …) as attributes on `VJoyMenuItem` when `type` is `'a'` or `'button'` (they flow through `$attrs`).
+
+### Icons and status
+
+- **SHOULD** use `icon` for wayfinding (user, settings, section glyph) — not decoration alone.
+- **SHOULD** use `status` + `statusColor` for semantic feedback (check, warning, lock) — keep one trailing icon per row.
+- **MUST NOT** rely on icon color alone to convey meaning — the `label` must still describe the action or destination.
+
+### Interaction
+
+- **MUST** set `disabled` when the row must not activate; explain why elsewhere if the reason isn’t obvious.
+- **SHOULD** use `type="button"` + `@click` for in-page actions that do not navigate.
+- **SHOULD** use `type` router component + `linkProps` for SPA navigation instead of `<a>` + manual router pushes.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyMenu` + `VJoyMenuItem` slot children | Deprecated `items` prop on `VJoyMenu` |
+| `linkProps` with `NuxtLink` / `RouterLink` | Plain `<a>` + `@click` router hacks |
+| `current` for the active nav target | Multiple `current` rows without reason |
+| Concise `label` text (1–3 words) | Vague labels (`Click here`, `Menu`) |
+| `status` for lock / check / warning | Random decorative trailing icons |
+| Explain disabled rows when needed | Disabled row with no context |
+
+---
+
+## Content
+
+Menu items are scanned quickly. Labels must be short, parallel, and predictable.
+
+### Label formula
+
+**Navigation rows:** **noun or short noun phrase** — e.g. `Profile`, `Billing`, `Paris Montparnasse`.
+
+**Action rows** (`type="button"`): **verb or verb + object** — e.g. `Sign out`, `Export data`.
+
+Use **parallel grammar** across siblings (all nouns or all verbs — don’t mix styles in one menu).
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | `label` is required and becomes the accessible name (`aria-label` + `title`) |
+| **MUST** | Keep labels concise; overflow shows ellipsis — don’t rely on truncation for critical detail |
+| **MUST NOT** | Vague labels — ❌ `Click here`, ❌ `Options`, ❌ `Item 1` in product UI |
+| **MUST NOT** | Duplicate the parent menu title on every row when context is already clear |
+| **SHOULD** | 1–3 words per item |
+| **SHOULD** | Sentence case for multi-word labels |
+| **SHOULD** | Name destructive actions explicitly — ✅ `Delete project` · ❌ `Delete` alone in a mixed menu |
+| **SHOULD** | Start each item the same way (all verbs or all nouns) for scannability |
+
+### Patterns
+
+**App / settings navigation** — Noun labels: `Account`, `Notifications`, `Privacy`. Mark the active section with `current`.
+
+**Router-linked sidebar** — `:type="NuxtLink"` (or `RouterLink`) + `:link-props="{ to: '/path' }"`. Label names the destination page.
+
+**Status feedback** — Trailing `status` icon with `statusColor`: check for completed setup, lock for gated features, warning for attention needed. Label still states the destination.
+
+**Disabled rows** — Keep the label readable; use `status="lock"` when helpful. Explain gating in surrounding UI or a tooltip on a related control — not only via icon color.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Outer `<li role="menuitem">` inside `VJoyMenu`’s `role="menu"` list |
+| Name | From `label` (`aria-label` on the row; `title` for truncated text) |
+| Current page | `current` sets `aria-current` on the row and visible current styling |
+| Disabled | `aria-disabled="true"` on the row; inner becomes non-focusable `<div>` |
+| Keyboard | Arrow keys, Home, End, Enter, and Space are handled by parent `VJoyMenu` — don’t reimplement list keyboard logic on individual items |
+| Focus | Inner control shows visible focus ring — keep it in product CSS |
+| Icons | Leading/trailing icons are decorative when `label` is present — Joy icons default to `aria-hidden` where appropriate |
+| Links | Use real `<a href>` or router links — not clickable `<div>` except when `disabled` |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyMenu, VJoyMenuItem } from '@maltjoy/core-vue'
+
+// Nuxt example — use your app's NuxtLink import
+// import { NuxtLink } from '#components'
+</script>
+
+<template>
+  <VJoyMenu aria-label="Account sections">
+    <!-- Default: native link -->
+    <VJoyMenuItem label="Profile" href="/profile" icon="user" />
+
+    <!-- Current section -->
+    <VJoyMenuItem
+      label="Billing"
+      href="/billing"
+      icon="credit-card"
+      current
+      status="check-circle"
+      status-color="success"
+    />
+
+    <!-- Opens in new tab -->
+    <VJoyMenuItem
+      label="Help center"
+      href="https://help.malt.com"
+      target="_blank"
+      rel="noopener noreferrer"
+    />
+
+    <!-- In-page action -->
+    <VJoyMenuItem
+      label="Sign out"
+      type="button"
+      icon="logout"
+      @click="onSignOut"
+    />
+
+    <!-- SPA navigation (Nuxt) -->
+    <!--
+    <VJoyMenuItem
+      label="Dashboard"
+      :type="NuxtLink"
+      :link-props="{ to: '/' }"
+      icon="home"
+    />
+    -->
+
+    <!-- Disabled row -->
+    <VJoyMenuItem
+      label="Team settings"
+      disabled
+      icon="company-placeholder"
+      status="lock"
+    />
+  </VJoyMenu>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyMenuItem` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyMenu` | Parent list with keyboard navigation and `role="menu"` |
+| `VJoyDropdown` | Contextual menus opened from a trigger |
+| `VJoyDropdownList` | Option list UI without full menu semantics |
+| `VJoyIcon` | Icon primitive used for `icon` and `status` |
+| `VJoyButton` | Standalone actions outside a menu list |
+| `VJoyTabs` | Switching content panels on the same surface |
+| `VJoyTooltip` | Extra detail for disabled or icon-only adjacent controls |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyMenuItem.dsds.json`](./JoyMenuItem.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Row inside a nav / settings menu | `VJoyMenu` + `VJoyMenuItem` | Raw `<li>` with custom menu CSS |
+| Overflow menu from a button | `VJoyDropdown` | `VJoyMenu` for kebab menus |
+| SPA route in a menu | `VJoyMenuItem` + `:type="NuxtLink"` / `RouterLink` + `link-props` | `<a>` + `@click` router navigation |
+| External URL | `VJoyMenuItem` + `href` (default `type="a"`) | `type="button"` + window.location |
+| In-page menu action | `VJoyMenuItem` + `type="button"` + `@click` | `href="#"` + click handler |
+| Active nav destination | `current` on one item | Custom “selected” CSS classes |
+| Deprecated data-driven menu | `VJoyMenuItem` children | `VJoyMenu` `items` prop |
+
+### Hard rules
+
+1. **MUST** read `VJoyMenuItem.vue` and/or `JoyMenu.metadata.md` before generating props (`joy_get_component_info` may not work yet).
+2. **MUST** wrap items in `VJoyMenu` with an `aria-label` when context is not self-evident.
+3. **MUST** set `label` on every item — there is no default slot for label text.
+4. **MUST** use `linkProps` when `type` is a Vue/router component; use `href` + `$attrs` when `type` is `'a'`.
+5. **MUST** use `type="button"` for actions that emit `click` without navigation.
+6. **MUST NOT** invent props (`variant`, `size`, `selected`, `active`, …).
+7. **MUST NOT** override `.joy-menu-item` / `.joy-menu-item__inner` background, padding, height, or focus ring.
+8. **MUST NOT** use `VJoyMenu` `items` prop in new code.
+9. **SHOULD** set at most one `current` item per menu for active-route indication.
+10. **SHOULD** use kebab-case in templates for multi-word props (`status-color` → `statusColor`).
+
+### Documented props (from source)
+
+| Prop | Type / notes |
+| --- | --- |
+| `label` | `string` — **required** |
+| `href` | `string` — for `type="a"` |
+| `icon` | `TJoyIconsNames` — leading icon |
+| `current` | `boolean` — active / current destination |
+| `disabled` | `boolean` |
+| `status` | `TJoyIconsNames` — trailing status icon |
+| `statusColor` | `TJoyIconsColors` — trailing icon color |
+| `type` | `Component \| 'a' \| 'button'` — default `'a'` |
+| `linkProps` | `ComponentProps<T>` — for non-native `type` |
+
+**Event:** `click` — emitted on inner activation when not `disabled` (typically `type="button"`).
+
+### Checklist
+
+- [ ] Correct component (`VJoyMenuItem` inside `VJoyMenu`, or named alternative)
+- [ ] Props from source / metadata only — no invented props
+- [ ] `label` set on every row
+- [ ] `href` or `linkProps` matches `type` (link vs router vs button)
+- [ ] `current` used intentionally (≤ 1 per menu in most cases)
+- [ ] `disabled` rows explained when reason isn’t obvious
+- [ ] No custom `.joy-menu-item` chrome CSS
+- [ ] No deprecated `VJoyMenu` `items` array for new menus
+- [ ] Native attrs on `VJoyMenuItem` when using `'a'` or `'button'`
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyMenuItem.dsds.json`](./JoyMenuItem.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / link types | `anatomy` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP (when available) |
+| Imports | `imports` in JSON |
+| Token sizing | `design-specifications` in JSON (`--joy-form-field-height-medium`, color tokens) |