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

package/dist/doc/VJoyLink/guideline.md

@@ -0,0 +1,360 @@
+---
+component: VJoyLink
+status: draft
+language: en
+dsds: JoyLink.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Link
+
+Use **`VJoyLink`** when the user should navigate to another page, resource, or URL — inline in body copy, as a standalone call-to-action after a paragraph, or embedded in patterns such as dropzones and highlights.
+
+It renders as a native `<a>` when `href` is set, or as a `<button>` when there is no `href` (link-styled control for in-page actions). Optional leading icons, two color contexts (`teal`, `white`), and inherited typography keep links scannable without custom CSS.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyLink` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Link](https://zeroheight.com/6bf479565/p/4070710) |
+| **Storybook** | [VJoyLink docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-buttons-vjoylink--docs) |
+| **DSDS (machine)** | [`JoyLink.dsds.json`](./JoyLink.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyLink")` |
+
+---
+
+## When to use this component
+
+Use a link when the outcome is **navigation** — opening another route, an external site, documentation, or a downloadable resource — and the control should read as text, not a filled button.
+
+Typical placements: a word or phrase inside a sentence, a short standalone line after explanatory copy, or an embedded affordance inside another component (for example the “browse” action in `VJoyDropzone`).
+
+When there is no destination URL but you still want link typography for a **secondary, low-emphasis action** in tight space (and a `VJoyButton` `ghost` variant would compete with a stronger CTA), omit `href` and render as a `<button>` with `type="button"`.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Primary or emphasized actions (submit, confirm, save) | `VJoyButton` (`main`, `primary`, …) |
+| Navigation with button chrome (filled / outlined CTA) | `VJoyButton` + `href` attribute |
+| Icon-only control (no visible text) | `VJoyIconButton` |
+| Complex card-style navigation CTA | `VJoyButtonCard` |
+| App or sidebar navigation lists | `VJoyMenu` + `VJoyMenuItem` |
+| Read-only text with no navigation | `VJoyText` or plain copy |
+| Custom-styled `<a>` / `<button>` in product CSS | Still use `VJoyLink` + Joy tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root | Yes | `<a>` when `href` is set; `<button>` when `href` is omitted |
+| Label (`default` slot or `text`) | Yes* | Visible link text in `.joy-link__text` |
+| Leading icon | No | `VJoyIcon` when `icon` is set; inherits color and font size |
+| Focus ring | Yes | `2px` border on `:focus-visible` — don’t remove in product CSS |
+
+\*Provide copy via the default slot **or** the `text` prop. If both are omitted, the link has no accessible name.
+
+Native attributes (`target`, `rel`, `aria-*`, `disabled`, …) pass through via `$attrs` on the root element.
+
+### Default values
+
+- `color` defaults to **`teal`**
+- `href` defaults to **unset** (root becomes `<button>`)
+- `icon`, `text`, and `type` default to **unset**
+
+When the root is a `<button>`, set **`type="button"`** unless the control should submit a form (`type="submit"`).
+
+Props and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Link vs button root
+
+| `href` | Root | Use when |
+| --- | --- | --- |
+| Set | `<a href="…">` | Real navigation (same tab, new tab, external URL, download) |
+| Omitted | `<button>` | In-page action with link appearance (open picker, toggle panel, cancel inline edit) |
+
+Don’t use a `<button>` root when the user expects a URL in the status bar or “open in new tab”. Don’t use `href="#"` as a fake button — omit `href` and use `type="button"` instead.
+
+---
+
+## Variants
+
+`color` chooses **contrast against the background**, not arbitrary branding.
+
+### `teal` (default)
+
+Use on **light** surfaces for standard product links (secondary palette: default, hover, visited tokens).
+
+This is the default for body copy, forms, panels, and most in-app UI.
+
+### `white`
+
+Use on **dark or saturated** backgrounds (hero bands, snackbars, inverted footers) where `teal` would fail contrast.
+
+Active press reduces opacity (`0.7`) while keeping neutral-0 text. Don’t use `white` on light backgrounds.
+
+### Not in the API: size / underline mode
+
+There is no `size` prop — font size and line height **inherit** from the parent. There is no prop to force always-underlined vs hover-underline; underline appears on **hover** on the label span. Don’t invent `size`, `variant`, or `underline` props.
+
+---
+
+## Sizes
+
+`VJoyLink` exposes **no size API**. Density comes from surrounding typography.
+
+| Aspect | Guidance |
+| --- | --- |
+| Font size / line height | Inherited from parent — wrap in `VJoyText` or body styles as needed |
+| Icon | `--icon-size: inherit` — scales with link text |
+| Touch target | Rely on natural text size + padding from focus border; don’t shrink below readable body text for tappability |
+
+**Don’t** hardcode font sizes or link colors on `.joy-link` in product CSS.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Bold text; `teal` uses secondary-30, default (no color class) uses neutral-40 |
+| Hover | Label color shifts to hover token; **underline** on `.joy-link__text` |
+| Focus | Visible `2px` focus border (`neutral-60` token) — keyboard / AT |
+| Active / visited | Visited color (`secondary-90` for `teal`; `white` stays neutral-0) |
+| With icon | Icon matches link color; spacing via `--joy-core-spacing-2` |
+| Button root | Same visuals; activate with **Space** / **Enter**; set `type` explicitly |
+
+External links opened in a new tab should use `target="_blank"` and `rel="noopener noreferrer"` (or your app’s security standard) via native attributes.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to use link vs button
+
+- **SHOULD** use `VJoyLink` + `href` for navigation (in-app routes, external sites, files).
+- **SHOULD** use `VJoyButton` for actions that change data or confirm decisions, even when they navigate afterward.
+- **SHOULD** use `VJoyLink` without `href` only for **low-emphasis in-page** actions where button chrome would overpower the layout.
+- **MUST NOT** use `VJoyLink` for the principal CTA on a surface — use `VJoyButton` `main` / `primary`.
+
+### Implementation
+
+- **MUST** use only `color` values from MCP or `JoyLink.types.ts` (`teal`, `white`).
+- **MUST** provide visible label text via the default slot or `text` prop.
+- **MUST** use Joy tokens — no custom `.joy-link` color, font-weight, or underline overrides.
+- **MUST NOT** invent props (`size`, `variant`, `underline`, …).
+- **SHOULD** prefer the **default slot** for simple text; use `text` for Storybook / generated UIs.
+- **SHOULD** set `type="button"` on button roots inside forms.
+- **SHOULD** pass `target` and `rel` for external / new-tab links via `$attrs`.
+
+### Interaction
+
+- **MUST NOT** use `href="#"` with `@click.prevent` as a button substitute — omit `href` instead.
+- **SHOULD** add an external-link icon (`icon` prop) when the destination is off-platform, if space allows.
+- **SHOULD** pick `color="white"` only on backgrounds verified with design tokens.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `href` for real URLs | `href="#"` for JavaScript actions |
+| `type="button"` on non-submit button roots | Bare `<button>` inside forms (accidental submit) |
+| Specific destination labels | “Click here”, “See more”, “Know more” |
+| `teal` on light UI | `white` on white cards |
+| `VJoyButton` for primary actions | `VJoyLink` styled as a CTA button |
+
+---
+
+## Content
+
+Links name **where the user goes** or **what they open**. Keep copy short, specific, and scannable.
+
+### Copy formula
+
+**Verb + object** (standalone) or a **minimal noun phrase** (inline):
+
+- ✅ View freelancer portfolio
+- ✅ Compare pricing plans
+- ✅ Update your profile
+- ❌ Click here to update your profile
+- ❌ Know more
+
+Aim for **~3 words** and **one idea** per link.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Name the destination or outcome — not the mechanics of clicking |
+| **MUST NOT** | Vague labels — ❌ “Click here”, “Go to”, “See more”, “Know more” |
+| **MUST NOT** | Punctuation inside inline links (except proper nouns / product names) |
+| **SHOULD** | ≤ ~3 words when possible |
+| **SHOULD** | Sentence case; capitalize product/feature names only |
+| **SHOULD** | For external sites, use the **site or resource name**, not the raw URL |
+| **SHOULD** | Pair external navigation with an icon when it aids recognition |
+| **SHOULD** (FR) | Non-breaking spaces before `;`, `?`, `!`, and `:` |
+
+### Patterns
+
+**Standalone links** (after a paragraph or in a footer) — Use a short phrase or question; apply the link to the **whole phrase**, not a single word.
+
+- ✅ *Need help choosing a freelancer?*
+- ❌ Only linking the word “help” in a longer sentence meant to stand alone
+
+**Inline links** (inside body copy) — Prefer **start or end** of the sentence for scanability. Don’t bury the link mid-sentence when a standalone phrase would work.
+
+**Embedded in components** — Follow the parent pattern (`VJoyDropzone` browse link, `VJoyHighlight` actions, snackbar inline HTML). Match parent `color` (`white` on dark snackbars).
+
+**Link-styled button** — Label should still describe the action (`Browse files`, `Choose another date`), not navigation, because there is no `href`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<a href>` or `<button>` — never a clickable `<span>` |
+| Name | From default slot or `text`; must be non-empty |
+| Keyboard | Links: **Enter** activates; buttons: **Enter** and **Space** |
+| Focus | Keep `:focus-visible` border — `2px solid` using Joy focus token |
+| External | `target="_blank"` links need clear copy; add `rel` as required by security policy |
+| Icons | Decorative icons should be `aria-hidden` (Joy icon default); don’t rely on icon alone for the name |
+| Button root | Set `type="button"` to avoid accidental form submission |
+| Disabled | Use native `disabled` on `<button>`; for `<a>`, avoid fake disabled links — remove or explain in copy |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyLink } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- External navigation -->
+  <VJoyLink href="https://malt.com" text="Visit Malt" />
+
+  <!-- Inline in copy (slot) -->
+  <p>
+    You can
+    <VJoyLink href="/help/pricing">compare pricing plans</VJoyLink>
+    before subscribing.
+  </p>
+
+  <!-- With icon (e.g. external / download) -->
+  <VJoyLink
+    href="https://example.com/report.pdf"
+    icon="download"
+    target="_blank"
+    rel="noopener noreferrer"
+  >
+    Download report
+  </VJoyLink>
+
+  <!-- On dark background -->
+  <VJoyLink href="/learn-more" color="white">
+    Learn more
+  </VJoyLink>
+
+  <!-- Link-styled button (no navigation) -->
+  <VJoyLink type="button" @click="openFilePicker">
+    Browse files
+  </VJoyLink>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyLink` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyButton` | Primary actions or navigation with button chrome |
+| `VJoyIconButton` | Icon-only actions |
+| `VJoyText` | Non-interactive body typography |
+| `VJoyDropzone` | File upload with embedded browse link pattern |
+| `VJoyHighlight` | Emphasized blocks that may include links |
+| `VJoyMenu` / `VJoyMenuItem` | Structured navigation lists |
+| `VJoyIcon` | Icon primitive used inside the link |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyLink.dsds.json`](./JoyLink.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Navigate in body copy or light CTA text | `VJoyLink` + `href` | `VJoyButton` `ghost` in a paragraph |
+| Principal or form action | `VJoyButton` | `VJoyLink` as page CTA |
+| Navigate with filled button look | `VJoyButton` + `href` attribute | `VJoyLink` + custom button CSS |
+| In-page action, link appearance | `VJoyLink` without `href` + `type="button"` | `href="#"` + `@click` |
+| Icon only | `VJoyIconButton` | `VJoyLink` with icon and no text |
+| Dark / snackbar surface | `VJoyLink` + `color="white"` | `color="teal"` on dark backgrounds |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyLink")` and/or `joy_get_component_types("VJoyLink")` (or read `JoyLink.types.ts`) before generating props.
+2. **MUST** set `href` when the user navigates to a URL; omit `href` only for button-semantics actions.
+3. **MUST** supply label text via the default slot or `text` prop.
+4. **MUST** use only documented props: `href`, `color`, `icon`, `text`, `type`.
+5. **MUST** pass native HTML attributes (`target`, `rel`, `aria-*`, `disabled`, …) as attributes on `VJoyLink`, not as invented props.
+6. **MUST NOT** invent props (`size`, `variant`, `underline`, `external`, …).
+7. **MUST NOT** override `.joy-link` colors, font-weight, or underline behavior in app CSS.
+8. **MUST NOT** use `href="#"` for non-navigation click handlers.
+9. **SHOULD** default to `color="teal"` on light surfaces.
+10. **SHOULD** set `type="button"` on button roots unless submitting a form.
+
+### Valid enums (from `JoyLink.types.ts`)
+
+| Prop | Values |
+| --- | --- |
+| `color` | `teal`, `white` |
+| `type` | `button`, `submit`, `reset` (only when root is `<button>`) |
+| `icon` | Any `TJoyIconsNames` value (see Joy Icon docs / MCP) |
+
+### Checklist
+
+- [ ] Correct component (`VJoyLink` or named alternative)
+- [ ] Props / enums from MCP or types only
+- [ ] `href` set for navigation; omitted only for button-mode actions
+- [ ] Label via slot or `text` — not empty
+- [ ] `type="button"` on non-submit button roots
+- [ ] `color` matches background (`teal` vs `white`)
+- [ ] No invented props / no custom `.joy-link` chrome CSS
+- [ ] External / new-tab links use appropriate `target` and `rel`
+- [ ] Copy is specific — no “click here” / “see more”
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyLink.dsds.json`](./JoyLink.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / link vs button | `anatomy` |
+| Colors | `variants` |
+| Inherited sizing | `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/VJoyListItem/guideline.md

@@ -0,0 +1,335 @@
+---
+component: VJoyListItem
+status: draft
+language: en
+dsds: JoyListItem.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# List item
+
+Use **`VJoyListItem`** when you need a **bordered, interactive row** in a list — a primary label on the left, optional leading icon, and secondary content or actions on the right.
+
+The whole row shows hover feedback and emits `click` when the user activates the container. Use the slots for copy and trailing UI (buttons, badges, metadata); keep real controls in `list-item-right` as proper Joy components.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyListItem` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyListItem docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoylistitem--docs) |
+| **DSDS (machine)** | [`JoyListItem.dsds.json`](./JoyListItem.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyListItem")` |
+
+---
+
+## When to use this component
+
+Use a list item when several entries share the same layout — title or summary on the left, optional icon, and a trailing action or status on the right. Typical jobs: settings rows with a CTA, document or project lists with a per-row button, or stacked cards where each row is tappable.
+
+Stack multiple `VJoyListItem` instances inside a `VJoyWrapper` (column layout) or a semantic `<ul>` / `<ol>` when the list is meaningful document structure.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Persistent app or sidebar navigation | `VJoyMenu` + `VJoyMenuItem` |
+| Options inside a dropdown overlay | `VJoyDropdownList` (via `VJoyDropdown`) |
+| Rich user profile summary (avatar, rating, link) | `VJoyUserCard` |
+| Selectable option cards (single or multi) | `VJoySelectableItem` / `VJoySelectableItemGroup` |
+| Plain bullet list without row chrome | `VJoyText` or semantic list markup + Joy spacing tokens |
+| Full panel with header, body, and footer | `VJoyPanel` |
+| Custom bordered row with ad-hoc CSS | Still use `VJoyListItem` + Joy tokens — don’t reinvent chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `<div class="joy-list-item">` — border, background, hover, and `@click` emission |
+| Inner layout | Yes | `VJoyWrapper` (`row`, `space-between`, `nowrap`) splitting left and right |
+| Left area | Yes | `joy-list-item__left` — optional icon + primary text |
+| Leading icon | No | `VJoyIcon` when `icon` is set (`joy-list-item__left-icon`) |
+| Primary text | Yes* | `list-item-left` slot content (rendered in `joy-font-primary-300` inside a `<p>`) |
+| Right area | No | `list-item-right` slot — actions, badges, metadata, secondary controls |
+| Focus ring | No* | Not built into the root — see Accessibility |
+
+\*Provide meaningful content in `list-item-left` for every row. Keyboard/focus behavior is not provided on the root; see Accessibility when the row itself must be activatable.
+
+### Default values
+
+- `icon` is **optional** — omit when the label alone is clear
+- No `variant`, `size`, `disabled`, or `href` props on this component
+
+Props, events, and slots: use Joy MCP (`joy_get_component_info`) or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Slots and events
+
+| Slot / event | Role |
+| --- | --- |
+| `list-item-left` | Primary label or summary (required for meaningful rows) |
+| `list-item-right` | Trailing UI — prefer `VJoyButton`, `VJoyTag`, `VJoyBadge`, or short text |
+| `@click` | Fired when the user clicks the root container (bubbles from children unless stopped) |
+
+### Not in the API: default slot
+
+There is **no default slot**. Content belongs in `list-item-left` and `list-item-right` only.
+
+### Not in the API: `variant`, `size`, `disabled`
+
+`VJoyListItem` exposes only `icon` plus the two named slots. Do not emit `variant`, `size`, `disabled`, or `href` on this component. Use real controls in `list-item-right` (for example a disabled `VJoyButton`) when an action cannot run.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Neutral border (`--joy-color-neutral-30`), background `--joy-color-neutral-10`, pointer cursor |
+| Hover | Background `--joy-color-neutral-20`, border `--joy-color-neutral-40` (pointer devices) |
+| Click | Root emits `click`; parent handles navigation or selection |
+| With icon | Leading icon in neutral-60; does not replace the text label |
+| Right-slot controls | Buttons and links in `list-item-right` remain independently interactive |
+
+There is no built-in selected, disabled, or loading state on the row itself.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Layout and hierarchy
+
+- **SHOULD** keep one clear idea per row — primary copy in `list-item-left`, one main action or status in `list-item-right`.
+- **SHOULD** use `icon` only when it reinforces the row topic (document, user, settings) — not on every row for decoration.
+- **MUST NOT** nest another full `VJoyListItem` inside a row slot.
+- **SHOULD** stack rows with consistent vertical spacing (`VJoyWrapper` `direction="column"` + `row-gap`).
+
+### Implementation
+
+- **MUST** use only documented props from MCP or `VJoyListItem.vue` (`icon` only).
+- **MUST** use Joy tokens — no custom `.joy-list-item` border, radius, padding, or hover overrides.
+- **MUST** put primary copy in `list-item-left` and trailing UI in `list-item-right`.
+- **MUST NOT** invent props (`variant`, `size`, `disabled`, `href`, …).
+- **SHOULD** call `@click.stop` on interactive children in `list-item-right` when the row `@click` should not fire for button presses.
+
+### Interaction
+
+- **SHOULD** use `@click` on the row only when the whole row shares one action (open detail, select row).
+- **SHOULD** use `list-item-right` for distinct actions (Edit, Delete) instead of overloading row click.
+- **MUST NOT** rely on row click alone for critical actions without a visible control or accessible name on the row.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `list-item-left` + `list-item-right` slots | Default slot or unstructured divs |
+| `@click.stop` on nested buttons | Row navigation firing when user clicks a button |
+| `VJoyButton` / `VJoyTag` in the right slot | Raw `<button>` with custom styles |
+| Short, scannable left labels | Paragraphs of body copy in `list-item-left` |
+| Joy spacing between stacked rows | Hardcoded margins on `.joy-list-item` |
+
+---
+
+## Content
+
+List rows expose user-facing copy in `list-item-left` and optional metadata or actions on the right. Follow the same parallelism rules as product lists (see Joy content guidelines — Lists).
+
+### Left label formula
+
+**Short noun phrase or concise statement** naming the row:
+
+- ✅ Contract renewal  
+- ✅ Q3 marketing budget  
+- ✅ Two-factor authentication  
+
+Use **parallel structure** across siblings in the same list (all nouns, or all short verb phrases).
+
+### Right slot copy
+
+- **Actions** — verb + object on buttons (`Review contract`, `Download PDF`). Prefer `VJoyButton` `size="xsmall"` or `small` for density.
+- **Status** — short tokens (`Pending`, `Active`) via `VJoyBadge` or `VJoyTag`, not full sentences.
+- **Metadata** — dates, counts, or file size in neutral supporting style — keep to one line.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every row has identifiable primary text in `list-item-left` — icon alone is not enough |
+| **MUST** | Keep `list-item-left` to roughly one line when possible; move detail to a sub-page or panel |
+| **MUST** | Use parallel grammar across items in the same list |
+| **MUST NOT** | Repeat the page title in every row label |
+| **MUST NOT** | Put the only action label only in `list-item-right` with an empty left slot |
+| **SHOULD** | Sentence case for labels and button text |
+| **SHOULD** | Match terminology with the page heading and adjacent UI |
+| **SHOULD** | Localize slot content; `icon` names stay programmatic (`TJoyIconsNames`) |
+
+### Patterns
+
+**Action list** — Left: resource name. Right: single `VJoyButton` (`xsmall`). Row `@click` optional for “open detail”; button uses `@click.stop` for the explicit action.
+
+**Status list** — Left: item name. Right: `VJoyBadge` or status text. Row click opens detail if the whole card is tappable.
+
+**Icon + title** — `icon` reinforces category (document, folder, user). Label still spells out the item name.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Root is a **generic `<div>`** — not a native button or link |
+| Name | Primary accessible name should come from visible `list-item-left` text; icon is decorative unless redundant with text |
+| Keyboard | **No built-in keyboard activation** on the row — if the row is activatable, parent must add focusable semantics (`tabindex`, `role="button"`, Enter/Space) or use a link/button pattern |
+| Focus | No focus ring on the root by default — focus moves to real controls in `list-item-right` |
+| Click | `@click` on the container; stop propagation on nested buttons/links when they perform a different action |
+| Right-slot controls | **MUST** be real `VJoyButton`, `VJoyLink`, or native interactive elements with accessible names |
+| Lists | When rows form a meaningful list, wrap in `<ul>` / `<ol>` with appropriate list semantics or ensure structure is exposed to assistive tech |
+
+Target: **WCAG 2.2 AA** where the product requires it. Do not assume the row is accessible as a single control without additional markup.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyListItem, VJoyButton, VJoyBadge, VJoyWrapper } from '@maltjoy/core-vue'
+
+function openDetail(id: string) {
+  // navigate or open panel
+}
+
+function reviewContract(event: Event) {
+  event.stopPropagation()
+  // explicit action
+}
+</script>
+
+<template>
+  <VJoyWrapper direction="column" row-gap="3">
+    <!-- Row with icon + trailing action -->
+    <VJoyListItem
+      icon="edit-document"
+      @click="openDetail('contract-1')"
+    >
+      <template #list-item-left>
+        Contract renewal — Acme Corp
+      </template>
+      <template #list-item-right>
+        <VJoyButton
+          variant="main"
+          size="xsmall"
+          label="Review"
+          @click="reviewContract"
+        />
+      </template>
+    </VJoyListItem>
+
+    <!-- Status metadata on the right -->
+    <VJoyListItem icon="folder">
+      <template #list-item-left>
+        Q3 marketing budget
+      </template>
+      <template #list-item-right>
+        <VJoyBadge label="Pending" />
+      </template>
+    </VJoyListItem>
+
+    <!-- Text-only row -->
+    <VJoyListItem @click="openDetail('settings-2fa')">
+      <template #list-item-left>
+        Two-factor authentication
+      </template>
+    </VJoyListItem>
+  </VJoyWrapper>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyListItem` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyWrapper` | Vertical stack spacing between rows |
+| `VJoyIcon` | Leading icon primitive (used internally when `icon` is set) |
+| `VJoyButton` | Trailing actions in `list-item-right` |
+| `VJoyBadge` / `VJoyTag` | Status or category on the right |
+| `VJoyMenuItem` | Navigation menus with proper menu semantics |
+| `VJoyDropdownList` | Selectable options inside dropdowns |
+| `VJoyUserCard` | Full user profile card layout |
+| `VJoyPanel` | Section with header, body, and footer |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyListItem.dsds.json`](./JoyListItem.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Bordered list row with left label + right action | `VJoyListItem` | Custom flex card div |
+| Sidebar / app nav item | `VJoyMenuItem` inside `VJoyMenu` | `VJoyListItem` |
+| Dropdown menu option | `VJoyDropdownList` / `VJoyDropdown` | `VJoyListItem` in overlays |
+| User profile block | `VJoyUserCard` | `VJoyListItem` + avatar hacks |
+| Row with only `icon` + default slot | `VJoyListItem` with `list-item-left` / `list-item-right` | Default slot (does not exist) |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyListItem")` (or read `VJoyListItem.vue`) before generating props.  
+2. **MUST** use slots `list-item-left` and `list-item-right` — there is no default slot.  
+3. **MUST** use only the `icon` prop plus slots; `icon` values are `TJoyIconsNames`.  
+4. **MUST** handle row actions via `@click` on `VJoyListItem` when the whole row is tappable.  
+5. **MUST** use `@click.stop` on buttons in `list-item-right` when row `@click` would conflict.  
+6. **MUST NOT** emit `variant`, `size`, `disabled`, `href`, or other invented props.  
+7. **MUST NOT** override `.joy-list-item` border, background, radius, padding, or hover styles.  
+8. **SHOULD** put primary label text in `list-item-left` on every row.  
+9. **SHOULD** use `VJoyButton` `size="xsmall"` or `small` for trailing actions (see Storybook default).  
+10. **SHOULD** stack multiple items in `VJoyWrapper` `direction="column"` with `row-gap`.
+
+### Valid API (from component source + MCP)
+
+| Kind | Names |
+| --- | --- |
+| Props | `icon` (optional, `TJoyIconsNames`) |
+| Events | `click` |
+| Slots | `list-item-left`, `list-item-right` |
+
+### Checklist
+
+- [ ] Correct component (`VJoyListItem` or named alternative from table above)
+- [ ] `list-item-left` populated with primary label
+- [ ] `list-item-right` for actions/status when needed
+- [ ] No invented props / no custom `.joy-list-item` chrome CSS
+- [ ] `@click.stop` on nested buttons when row also has `@click`
+- [ ] Trailing controls are real Joy components with accessible names
+- [ ] Row keyboard/focus addressed in parent if whole row must be activatable
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyListItem.dsds.json`](./JoyListItem.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `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 |
+| Token styling | `design-specifications` in JSON (`--joy-color-neutral-*`, `--joy-core-radius-3`) |