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

package/dist/doc/VJoyFloatingActionsBar/guideline.md

@@ -0,0 +1,372 @@
+---
+component: VJoyFloatingActionsBar
+status: draft
+language: en
+dsds: JoyFloatingActionsBar.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Floating actions bar
+
+Use **`VJoyFloatingActionsBar`** when contextual next steps should stay visible at the bottom of the viewport — for example bulk actions after a multi-select, or a primary CTA while the user scrolls a long form.
+
+It teleports to `body` by default, splits **`content`** (left) and **`actions`** (right) slots, and adapts from a floating card on desktop to a full-width bar on mobile.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyFloatingActionsBar` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Floating action bar](https://zeroheight.com/6bf479565/) (page id `8415609`) |
+| **Storybook** | [VJoyFloatingActionsBar docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoyfloatingactionsbar--docs) |
+| **DSDS (machine)** | [`JoyFloatingActionsBar.dsds.json`](./JoyFloatingActionsBar.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyFloatingActionsBar")` |
+
+---
+
+## When to use this component
+
+Use a floating actions bar when a **user action changes what they can do next** — typically after selecting items in a list or table — and those next steps should remain reachable without scrolling back to a page footer.
+
+The bar surfaces **flow-specific CTAs** (create mission, publish, submit) together with optional context on the left (selection count, avatars, short status). It appears in response to context; hide it when that context clears.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Confirmation or status after an action completes | `pushVJoySnackbar` |
+| Inline, persistent helper or field-level message | `VJoyHighlight` |
+| Blocking decision or multi-field input | `VJoyDialog` |
+| Slide-in panel with its own header/footer | `VJoyDrawer` |
+| Actions that are always visible at the bottom of a form (not selection-driven) | Page layout / form footer — not a floating bar |
+| Extra CTAs when the page already has bottom buttons for the same flow | Existing page footer — don’t duplicate actions |
+| Custom fixed bottom bar with ad-hoc CSS | Still use `VJoyFloatingActionsBar` + Joy tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Teleport host | Yes | Renders into `appendTo` (default `body`) after mount |
+| Bar container | Yes | White card (`joy-bgcolor-neutral-0`), elevation-2, radius-4 |
+| Inner row | Yes | Flex row; horizontal alignment from `justify` |
+| Content slot | No | Left area — selection summary, avatars, short copy |
+| Actions slot | Yes (content) | Right area — one or more `VJoyButton` (or compatible controls) |
+| Scoped modifier | No | `floating-actions-bar--scoped` when `appendTo` is not `body` |
+
+### Default values
+
+- `height` defaults to **`92px`**
+- `appendTo` defaults to **`body`**
+- `justify` defaults to **`space-between`**
+
+Props and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Layout and teleport
+
+1. **Mount** — the bar teleports only after `onMounted` (avoids SSR / hydration issues).
+2. **Desktop (default `appendTo`)** — `position: fixed`, ~80% width, centered, offset from bottom (`--joy-core-spacing-6`), respects `--layout-padding-left`.
+3. **Mobile (≤ 991px)** — full width, flush to bottom, square corners.
+4. **Scoped target** — when `appendTo` is not `body`, desktop uses `position: sticky`; mobile still uses `position: fixed`.
+
+**Visibility** is controlled by the parent — wrap in `v-if` / `v-show` when selection or draft state changes. The component does not manage open/close itself.
+
+---
+
+## Variants
+
+`VJoyFloatingActionsBar` has no color variant prop. Choose **layout** via `justify` and **composition** via the two slots.
+
+### `space-between` (default)
+
+Content on the left, actions on the right — the common bulk-selection pattern (avatars + count + primary CTA).
+
+Use when both slots carry meaning.
+
+### `flex-end`
+
+Actions aligned to the trailing edge; content slot omitted or empty.
+
+Use for a single CTA or a right-aligned button group (publish workflows, submit bars).
+
+### Other `justify` values
+
+`center`, `space-around`, `space-evenly`, and `flex-start` are supported for edge layouts (Storybook, narrow canvases, centered toolbars). Prefer `space-between` or `flex-end` in product UI unless design specifies otherwise.
+
+### Not in the API: `primaryActionLabel`
+
+Tests or legacy snippets may reference `primaryActionLabel`. It is **not** on `VJoyFloatingActionsBar` props — wire actions only through the **`actions`** slot.
+
+---
+
+## Sizes
+
+Single default height — no `size` prop on the bar itself. Action density comes from **`VJoyButton` `size`** inside the `actions` slot (stories use `small`).
+
+| Control | Use when |
+| --- | --- |
+| Default `height` (`92px`) | Standard button row + one line of content |
+| Custom `height` | Taller content in the `content` slot (multi-line copy, stacked chips) — adjust only when default clips content |
+
+**Don’t** hardcode bar width, shadow, or bottom offset in product CSS — the component owns layout tokens (`--joy-core-spacing-*`, `--joy-core-z-index-fixed-content`, `--layout-padding-left`).
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Hidden (default) | Parent does not render the bar — no selection / no draft context |
+| Visible (desktop) | Floating card above page content; actions reachable while scrolling |
+| Visible (mobile) | Full-width bottom bar; may cover page footer — account for padding |
+| Scoped (`appendTo` ≠ `body`) | Bar sticks within a canvas (drawer, Storybook, embedded preview) |
+| Content only | `content` slot filled, `actions` empty — rare; usually pair with actions |
+| Actions only | `justify="flex-end"`; trailing CTAs without left context |
+| Multiple actions | Gap between buttons (`--joy-core-spacing-3`); follow button hierarchy (`main` + `secondary` / `ghost`) |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show
+
+- **SHOULD** show the bar only when context warrants it (selection active, unsaved draft, publish step) — hide it when context clears.
+- **SHOULD** reflect **next steps in the current flow** in the `actions` slot — not a grab bag of unrelated shortcuts.
+- **MUST NOT** use the bar for action feedback (saved, error, sent) — use `pushVJoySnackbar`.
+- **MUST NOT** duplicate CTAs already fixed at the bottom of the same page for the same decision.
+
+### Hierarchy and composition
+
+- **SHOULD** use at most one **`main`** button in `actions` per bar (see `VJoyButton` hierarchy).
+- **SHOULD** order actions left-to-right by emphasis: `ghost` / `secondary` before `main` (Cancel · Save draft · Publish).
+- **SHOULD** keep `content` slot to **short, scannable context** (count, avatars, one line of status) — not secondary page content.
+- **SHOULD** use `justify="flex-end"` when there is no meaningful left content.
+
+### Implementation
+
+- **MUST** use only documented props and `justify` enum values from MCP / `VJoyFloatingActionsBar.vue`.
+- **MUST** place CTAs in the **`actions`** slot — no invented `primaryActionLabel` or similar props.
+- **MUST** use Joy tokens — no custom `.floating-actions-bar` chrome (background, shadow, radius, position).
+- **MUST NOT** invent props (`variant`, `open`, `primaryAction`, `visible`, …).
+- **SHOULD** use `VJoyButton` with `size="small"` in the bar for consistent density.
+- **SHOULD** set `appendTo` to a scoped selector in Storybook, drawers, or tests — default `body` for app pages.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-if` when selection count > 0 | Always-visible bar with no context |
+| `content`: “3 freelancers selected” + avatars | Paragraphs of help text in `content` |
+| `actions`: flow CTAs (`Create mission`, `Publish`) | Snackbar-style “Saved successfully” |
+| One `main` + companions in `actions` | Two competing `main` buttons |
+| Hide bar when context clears | Leave bar up after deselect all |
+| `justify="flex-end"` for actions-only | Empty `content` with default `space-between` |
+
+---
+
+## Content
+
+The bar carries **context on the left** and **action labels on the right**. Keep both scannable at a glance.
+
+### Content slot formula
+
+**Count + object** or **short status** tied to the selection:
+
+- ✅ 3 freelancers selected  
+- ✅ 12 files selected  
+- ✅ Unsaved changes  
+
+Use `VJoyText`, `VJoyAvatarsList`, and `VJoyWrapper` as in Storybook — don’t invent new summary patterns.
+
+### Action label formula
+
+Follow **`VJoyButton`** rules — **verb + noun**, ≤ 25 characters:
+
+- ✅ Create mission  
+- ✅ Publish  
+- ✅ Save draft  
+- ✅ Submit  
+
+Destructive or irreversible actions name the object: ✅ `Delete projects (3)`.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Content slot states **what is selected or pending** — not marketing copy |
+| **MUST** | Action labels describe the **next step**, not generic “Submit” / “Click” |
+| **MUST NOT** | Use the bar for success/error toasts |
+| **MUST NOT** | Push secondary page content into `content` to fill space |
+| **SHOULD** | Include a numeric count when multiple items are selected |
+| **SHOULD** | Match terminology with the list/table above (same noun: freelancer, file, mission) |
+| **SHOULD** | Use sentence case for content; button labels follow button guidelines |
+| **SHOULD** (FR) | Follow French grammar for counts and labels when the UI is localized |
+
+### Patterns
+
+**Bulk selection** — `content`: compressed avatars + count. `actions`: single `main` CTA for the bulk operation.
+
+**Publish / save workflow** — `justify="flex-end"`. `actions`: `ghost` Cancel · `secondary` Save draft · `main` Publish.
+
+**Long form submit** — `actions` only, `justify="flex-end"`, one `main` Submit while the user scrolls — only if there is no duplicate footer CTA.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Layout container — not a dialog; actions inside use native buttons from `VJoyButton` |
+| Name | Selection context in `content` must be readable text (not color-only); buttons keep their own labels |
+| Keyboard | All `actions` controls must be focusable and operable via keyboard — use `VJoyButton`, not clickable `<div>`s |
+| Focus | Bar does not trap focus; tab order follows DOM order (content then actions) |
+| Visibility | Parent `v-if` should remove the bar from the tab order when context clears |
+| Mobile | Full-width bar may cover content — ensure page has bottom padding or the bar hides when not needed |
+| Motion | No enter/leave animation in the component — avoid jarring show/hide without app-level consideration |
+| Z-index | Uses `--joy-core-z-index-fixed-content` — don’t stack opaque overlays that hide the bar’s actions without reason |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import {
+  VJoyFloatingActionsBar,
+  VJoyButton,
+  VJoyText,
+  VJoyWrapper,
+  VJoyAvatarsList,
+  VJoyAvatar,
+} from '@maltjoy/core-vue'
+
+const selectedIds = ref<string[]>(['a', 'b', 'c'])
+const hasSelection = computed(() => selectedIds.value.length > 0)
+</script>
+
+<template>
+  <!-- Bulk selection -->
+  <VJoyFloatingActionsBar v-if="hasSelection">
+    <template #content>
+      <VJoyWrapper no-margin column-gap="3" align="center">
+        <VJoyAvatarsList compress>
+          <VJoyAvatar full-name="Alice Dupont" size="small" />
+          <VJoyAvatar full-name="Bob Martin" size="small" />
+          <VJoyAvatar full-name="Carol White" size="small" />
+        </VJoyAvatarsList>
+        <VJoyText preset="primary-400">
+          {{ selectedIds.length }} freelancers selected
+        </VJoyText>
+      </VJoyWrapper>
+    </template>
+    <template #actions>
+      <VJoyButton variant="main" size="small" label="Create mission" />
+    </template>
+  </VJoyFloatingActionsBar>
+
+  <!-- Actions only — publish workflow -->
+  <VJoyFloatingActionsBar justify="flex-end">
+    <template #actions>
+      <VJoyButton variant="ghost" size="small" label="Cancel" />
+      <VJoyButton variant="secondary" size="small" label="Save draft" />
+      <VJoyButton variant="main" size="small" label="Publish" />
+    </template>
+  </VJoyFloatingActionsBar>
+</template>
+```
+
+Storybook / scoped canvas — teleport into a host element:
+
+```vue
+<VJoyFloatingActionsBar append-to="#my-canvas">
+  <template #actions>
+    <VJoyButton variant="main" size="small" label="Submit" />
+  </template>
+</VJoyFloatingActionsBar>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyFloatingActionsBar` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyButton` | CTAs in the `actions` slot |
+| `VJoyText` | Short status copy in `content` |
+| `VJoyAvatarsList` / `VJoyAvatar` | Selected people in `content` |
+| `VJoyWrapper` | Horizontal layout inside `content` |
+| `pushVJoySnackbar` | Transient feedback after an action |
+| `VJoyHighlight` | Inline persistent messages |
+| `VJoyDialog` | Blocking confirm or form |
+| `VJoyDrawer` | Side panel with its own action area |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyFloatingActionsBar.dsds.json`](./JoyFloatingActionsBar.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Bulk / contextual bottom actions while scrolling | `VJoyFloatingActionsBar` + slots | Custom `position: fixed` div |
+| Toast after save/send | `pushVJoySnackbar` | Floating bar with success text |
+| Inline error under a field | `VJoyHighlight` | Bar in `content` slot |
+| Modal confirm | `VJoyDialog` | Bar with only Cancel/Confirm |
+| Always-on form footer (no selection) | Page footer layout | `VJoyFloatingActionsBar` always mounted |
+| Primary CTA prop | `#actions` slot + `VJoyButton` | `primaryActionLabel` (invalid) |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyFloatingActionsBar")` (or read `VJoyFloatingActionsBar.vue`) before generating props.
+2. **MUST** put buttons in the **`actions`** slot — no invented action props.
+3. **MUST** control visibility with parent `v-if` / `v-show` when context applies.
+4. **MUST** use only `justify` values from the documented enum.
+5. **MUST NOT** invent props (`primaryActionLabel`, `open`, `variant`, `visible`, …).
+6. **MUST NOT** override `.floating-actions-bar` position, width, shadow, or background in app CSS.
+7. **SHOULD** use `justify="flex-end"` when `content` is empty.
+8. **SHOULD** use `VJoyButton` `size="small"` in `actions`.
+9. **SHOULD** use at most one `variant="main"` button per bar.
+
+### Checklist
+
+- [ ] Correct component (or named alternative from table above)
+- [ ] Props / `justify` enum from MCP only
+- [ ] Actions in `#actions` slot — no `primaryActionLabel`
+- [ ] Parent controls show/hide when context changes
+- [ ] No invented props / no custom bar chrome CSS
+- [ ] Not used for snackbar-style feedback
+- [ ] No duplicate footer CTAs for the same flow
+- [ ] Button labels follow `VJoyButton` content rules
+- [ ] `content` is short context — not secondary page content
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyFloatingActionsBar.dsds.json`](./JoyFloatingActionsBar.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / layout | `anatomy` |
+| `justify` / composition | `variants` |
+| Height / responsive layout | `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/VJoyFormError/guideline.md

@@ -0,0 +1,325 @@
+---
+component: VJoyFormError
+status: draft
+language: en
+dsds: JoyFormError.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Form error
+
+Use **`VJoyFormError`** when a form field or group failed validation and the user needs a **persistent, inline** explanation directly below the control.
+
+It shows a warning icon, error-colored text (`--joy-color-error-50`), and `role="alert"` so assistive tech announces the message. Pass a string array via `errors`, or use the default slot when you need custom markup (for example a hand-built `<ul>` / `<li>` list).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyFormError` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyFormError docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyformerror--docs) |
+| **DSDS (machine)** | [`JoyFormError.dsds.json`](./JoyFormError.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyFormError")` |
+
+---
+
+## When to use this component
+
+Use a form error when validation failed for a specific field or group and the user must read **what went wrong** and **how to fix it** before continuing.
+
+Place it **immediately below** the related control (input, select, checkbox group, dropzone, etc.). Pair it with the field’s `invalid` state so error styling is consistent on both the control and the message.
+
+For a single message, pass one string in `errors`. For several related failures on the same field, pass multiple strings or render a `<ul>` / `<li>` list in the default slot.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Page-level or section-level failure (not tied to one field) | `VJoyHighlight` (`level="error"`) |
+| Transient feedback after an action (saved, failed request) | `pushVJoySnackbar` |
+| Blocking decision or multi-step correction | `VJoyDialog` |
+| Helper text before any error occurs | `VJoyLabel` legend slot, field description, or `VJoyHighlight` (`level="info"`) |
+| Custom red text / icon row with ad-hoc CSS | Still use `VJoyFormError` + Joy tokens — don’t reinvent error chrome |
+
+> **Deprecated:** `visible` — inject or remove the component with `v-if` / `v-show` instead. The prop remains in the API for legacy markup but should not be used on new work.
+
+> **Not in the API:** `message` — pass copy via the `errors` prop or the default slot. Do not emit `message="…"`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `div` with `data-joy-form-error`, `role="alert"`, class `joy-form-error` |
+| Warning icon | Yes | `VJoyIcon` (`warning-triangle`), class `joy-icon-error` |
+| Message body | Yes | Default slot **or** auto-generated `<ul>` / `<li>` from `errors` |
+| Bottom spacing | Yes* | Default `margin-bottom: var(--joy-core-spacing-5)` — *removed when `noMargin` is true |
+
+The root is **not rendered** when there is no default slot content and `errors` is empty or omitted.
+
+### Default values
+
+- `noMargin` defaults to **`false`**
+- `visible` defaults to **`true`** (deprecated — prefer conditional rendering)
+- `errors` is **optional** — omit when using the default slot
+
+Props and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Content modes
+
+| Mode | When to use |
+| --- | --- |
+| `errors` prop | One or more plain strings; component renders `<ul>` / `<li>` automatically |
+| Default slot | Custom HTML (multiple lines, mixed content, framework-templated markup) |
+
+When both slot and `errors` are provided, the **slot takes precedence** (`errors` is ignored).
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Hidden (no content) | Nothing in the DOM — no `errors`, no default slot |
+| Visible (single error) | Icon + one line of error text |
+| Visible (multiple errors) | Icon + bulletless list (`<ul>` / `<li>`) |
+| `noMargin` | Same visible error without bottom margin (parent handles spacing, e.g. `VJoyFormGroup`) |
+
+There is no hover, focus, or disabled state — the component is presentational feedback, not interactive.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Placement and pairing
+
+- **MUST** place `VJoyFormError` directly below the field or group it describes.
+- **MUST** set `invalid` on the related form control when showing an error — red border or outline alone is not enough.
+- **MUST** show the error only when validation has failed (typically `v-if` on a boolean or error string).
+- **SHOULD** show one focused message per field when possible; use multiple list items only when several distinct fixes are required.
+- **MUST NOT** use `VJoyFormError` for success or neutral helper copy.
+
+### Implementation
+
+- **MUST** use only documented props (`errors`, `noMargin`) and the default slot from MCP or `VJoyFormError.vue`.
+- **MUST** style with Joy tokens — no custom `.joy-form-error` chrome (color, icon, spacing).
+- **MUST NOT** invent props (`message`, `variant`, `size`, `level`, …).
+- **MUST NOT** rely on the deprecated `visible` prop — use `v-if` / `v-show`.
+- **SHOULD** use `noMargin` when the parent layout (`VJoyFormGroup`, `VJoyWrapper`) already applies field spacing.
+- **SHOULD** prefer `errors` for simple string messages; use the slot only when markup cannot be expressed as strings.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `invalid` on field + `VJoyFormError` below | Red field border with no message |
+| `:errors="['Enter a valid email address']"` | `message="…"` prop |
+| `v-if="showError"` to toggle visibility | Deprecated `visible={false}` in DOM |
+| Short, actionable copy | Generic `Invalid` or `Error` |
+| `noMargin` inside `VJoyFormGroup` when spacing doubles | Stacking default margin on top of group gap |
+
+---
+
+## Content
+
+Error copy must tell the user what failed and what to do next.
+
+### Message formula
+
+**What went wrong + how to fix it** (imperative or instructive):
+
+- ✅ `Enter a valid email address`
+- ✅ `Password must be at least 8 characters`
+- ✅ `Choose a delivery method`
+
+Avoid blame, jargon, or internal codes unless the user needs them.
+
+### Single vs multiple messages
+
+| Pattern | When |
+| --- | --- |
+| One string in `errors` | Single rule failed (format, required, length) |
+| Multiple `errors` entries or `<li>` items | Several independent fixes on the same field (rare — prefer one clear message) |
+
+Keep list items parallel (same grammatical structure).
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | State what is wrong and how to fix it — ✅ `Enter a valid email address` · ❌ `Invalid` |
+| **MUST** | Use sentence case; no trailing period for single-line errors unless product copy requires it |
+| **MUST NOT** | Repeat the field label as the entire message — ❌ `Email` |
+| **MUST NOT** | Expose raw API / stack traces to end users |
+| **SHOULD** | Keep messages ≤ ~80 characters when possible |
+| **SHOULD** | Match terminology with the field label (`Email address` label → `Enter a valid email address`) |
+| **SHOULD** | Localize all strings passed to `errors` or the slot |
+| **SHOULD** (FR) | Use correct gender/agreement for past-participle adjectives in French error strings |
+
+### Patterns
+
+**Required field on submit** — Show after submit or blur: `You must enter a name`.
+
+**Format validation** — After blur or when format is unambiguous: `Enter a valid email address`.
+
+**Group validation** — One `VJoyFormError` below `VJoyRadioGroup` / `VJoyCheckboxGroup`: `Select one option to continue`.
+
+**Composed fields** — `VJoyTagsInput` and similar components use the default slot for multiple error types in one list.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | `role="alert"` on the root — announces when the error appears |
+| Visibility | Render with `v-if` when there is an error; component omits itself when `errors` is empty and slot is empty |
+| Name | Message text is plain content inside the alert — no extra `aria-label` needed when copy is descriptive |
+| Icon | Warning triangle is decorative; meaning is carried by the text |
+| Field association | Pair with `invalid` on the control; associate label + field with `VJoyLabel` / `for` + `id` |
+| Timing | Show errors after submit, blur, or when the value is clearly invalid — avoid shouting on first keystroke unless format is unambiguous |
+| Color | Error color (`--joy-color-error-50`) supplements text — never the only signal |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyInput,
+  VJoyFormError,
+  VJoyFormGroup,
+  VJoyLabel,
+  VJoyCheckbox,
+} from '@maltjoy/core-vue'
+
+const email = ref('')
+const showEmailError = ref(false)
+const accepted = ref(false)
+
+function validateEmail() {
+  showEmailError.value = !email.value.includes('@')
+}
+</script>
+
+<template>
+  <!-- Single error via errors prop -->
+  <VJoyFormGroup>
+    <VJoyInput
+      v-model="email"
+      name="email"
+      label="Email address"
+      :invalid="showEmailError"
+      @blur="validateEmail"
+    />
+    <VJoyFormError
+      v-if="showEmailError"
+      :errors="['Enter a valid email address']"
+    />
+  </VJoyFormGroup>
+
+  <!-- Multiple errors via slot -->
+  <VJoyFormError v-if="showEmailError">
+    <ul>
+      <li>Email is not valid</li>
+      <li>Password is not strong enough</li>
+    </ul>
+  </VJoyFormError>
+
+  <!-- Checkbox with noMargin inside a group -->
+  <VJoyFormGroup>
+    <VJoyLabel for="terms">Terms and conditions</VJoyLabel>
+    <VJoyCheckbox id="terms" v-model="accepted" value="yes">
+      I accept the terms
+    </VJoyCheckbox>
+    <VJoyFormError
+      v-if="!accepted"
+      no-margin
+      :errors="['You must accept the terms and conditions']"
+    />
+  </VJoyFormGroup>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyFormError` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyInput` / `VJoyTextarea` / `VJoySelect` | Fields that accept `invalid` and sit above the error |
+| `VJoyLabel` | Accessible label and optional legend above the field |
+| `VJoyFormGroup` | Groups label, control, and error with consistent spacing |
+| `VJoyWrapper` | Column layout between fields when not using `VJoyFormGroup` |
+| `VJoyRadioGroup` / `VJoyCheckboxGroup` | Group-level validation with one error below the set |
+| `VJoyHighlight` | Section- or page-level error/info banners |
+| `pushVJoySnackbar` | Transient action feedback, not inline validation |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyFormError.dsds.json`](./JoyFormError.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Inline validation under a field | `VJoyFormError` + `invalid` on the field | Raw `<p class="error">` |
+| Single error string | `VJoyFormError` with `:errors="['…']"` | `message="…"` prop |
+| Multiple errors, custom markup | `VJoyFormError` + default slot (`<ul>` / `<li>`) | Multiple separate alert divs |
+| Page / banner error | `VJoyHighlight` `level="error"` | `VJoyFormError` at page top |
+| Toast after save/fail | `pushVJoySnackbar` | `VJoyFormError` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyFormError")` (or read `VJoyFormError.vue`) before generating props.  
+2. **MUST** pair with `invalid` on the related form control when validation failed.  
+3. **MUST** pass messages via `errors` (string array) or the default slot — **not** a `message` prop.  
+4. **MUST** use `v-if` (or parent conditional) to show/hide errors — **not** deprecated `visible`.  
+5. **MUST NOT** invent props (`message`, `variant`, `size`, `level`, …) or custom `.joy-form-error` CSS.  
+6. **MUST NOT** render `VJoyFormError` when there is no error content (empty `errors` renders nothing).  
+7. **SHOULD** use `noMargin` when nested in `VJoyFormGroup` or when parent gap already applies.  
+8. **SHOULD** keep copy actionable: what failed + how to fix.
+
+### Checklist
+
+- [ ] Correct component (inline field error, not snackbar/highlight)
+- [ ] Props from MCP / source only (`errors`, `noMargin`, default slot)
+- [ ] Related field has `invalid` when error is shown
+- [ ] `v-if` (or equivalent) — no `visible` prop
+- [ ] No `message` prop / no invented props
+- [ ] No custom error chrome CSS
+- [ ] Actionable error copy (not bare `Invalid`)
+- [ ] Placed directly below the described control
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyFormError.dsds.json`](./JoyFormError.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 |
+| Error color / typography | `design-specifications` (`--form-error-color`, `--joy-color-error-50`, `primary-300`) |