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

package/dist/doc/VJoyToggle/guideline.md

@@ -0,0 +1,327 @@
+---
+component: VJoyToggle
+status: draft
+language: en
+dsds: JoyToggle.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Toggle
+
+Use **`VJoyToggle`** when the user needs to switch a single setting **on or off** with immediate effect — especially in settings rows, preferences, or compact forms.
+
+It supports checked and disabled states, a label via prop or slot (left or right of the switch), native form attributes (`name`, `value`, `required`), and two visual variants: **`default`** (customer product) and **`admin`** (internal tooling).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyToggle` from `@maltjoy/core-vue` |
+| **Design** | [Joy — Toggle](https://zeroheight.com/6bf479565/p/67497f) (page id `1423634`) |
+| **Storybook** | [VJoyToggle docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoytoggle--docs) |
+| **DSDS (machine)** | [`JoyToggle.dsds.json`](./JoyToggle.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyToggle")` |
+
+---
+
+## When to use this component
+
+Use a toggle when there are **exactly two mutually exclusive states** (on / off) that the user may change often and see take effect right away — for example enabling notifications, showing optional UI, or turning a feature on.
+
+Toggles work well when space is tight and the two states are clearly related. Place the label beside the switch so the user knows what flips when they interact with the control.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| More than two options | `VJoyRadio` / `VJoyRadioGroup` or `VJoySelect` |
+| Multiple independent selections | `VJoyCheckbox` / `VJoyCheckboxGroup` |
+| Consent, agreement, or “I accept…” copy | `VJoyCheckbox` |
+| Options that are not mutually exclusive | `VJoyCheckbox` |
+| A change that only applies after Save / Submit | Checkbox or explicit submit — not an instant toggle |
+| Customer-facing product UI with admin chrome | `variant="default"` — never `admin` |
+| Custom-styled switch markup | Still use `VJoyToggle` + Joy tokens — don’t reinvent chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Wrapper | Yes | Root container (`.joy-toggle__wrapper`) |
+| Label | Yes | Clickable `<label>` wrapping the input and content row |
+| Input | Yes | Visually hidden `<input type="checkbox">` with `data-joy-form-field` and `role="checkbox"` |
+| Switch track | Yes | `.joy-toggle__symbol` — rounded track behind the bubble |
+| Bubble | Yes | `.joy-toggle__symbol-bubble` — slides horizontally when checked |
+| Variant icon | No | Smile SVG (`default`) or `VJoyIcon` `eye` (`admin`) inside the bubble |
+| Label text | Yes* | Default slot or `label` prop in `.joy-toggle__content-label` (*one must provide an accessible name) |
+| Focus ring | Yes | Outline on the track when the input is focused (`joy-toggle__focusing`) |
+
+The component `provide`s `JoyFormElementContext` so it integrates with Joy form field patterns (e.g. labels, validation groups).
+
+### Default values
+
+- `modelValue` defaults to **`false`**
+- `variant` defaults to **`default`**
+- `labelPosition` defaults to **`right`**
+- `disabled` defaults to **`false`**
+- `invalid` defaults to **`false`** (declared on props; no dedicated invalid styling in component CSS yet — pair with `VJoyFormError` or group messaging)
+- `required` defaults to **`false`**
+- `value` defaults to **`"on"`** (submitted value when checked in native forms)
+
+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 `size` prop**. Track and bubble dimensions come from component CSS variables (e.g. `--toggle-width`, `--toggle-height`) and Joy color tokens — **don’t hardcode switch width, height, or track colors** in product CSS.
+
+---
+
+## Variants
+
+Pick variant by **surface audience**, not by color preference.
+
+### `default`
+
+Use on **customer-facing** product UI. The bubble shows the Joy smile motif when checked.
+
+Avoid `admin` styling on public or client surfaces.
+
+### `admin`
+
+Use **only** in internal / admin tooling. Checked state uses quaternary tokens; the bubble shows an **eye** icon instead of the smile.
+
+Avoid `variant="admin"` outside admin contexts — it is documented separately in Storybook under Admin.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Off (`modelValue: false`) | Bubble on the left; neutral track; label in normal weight |
+| On (`modelValue: true`) | Bubble slides right; track uses secondary (or quaternary for `admin`); smile or eye visible in bubble |
+| Hover | Track and bubble border lighten (pointer devices); checked hover uses `--toggle-bg-color-hover-checked` |
+| Focus | Visible focus outline on the track — don’t remove in product CSS |
+| Disabled | No interaction; muted track, bubble, label, and icon — **explain why** nearby when possible |
+| Disabled + on | Same as disabled with bubble in the “on” position |
+
+Bind state with `v-model` (or `:model-value` + `@update:modelValue`). Changes emit immediately on `change` — there is no separate “Apply” step inside the component.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection model
+
+- **SHOULD** use a toggle only for **two** mutually exclusive, immediately applied states.
+- **MUST NOT** use a toggle when the user can select multiple options — use checkboxes.
+- **MUST NOT** use a toggle when more than two choices exist — use radio or select.
+- **SHOULD** prefer `VJoyCheckbox` when the label is a consent statement (“I agree to…”) rather than a setting name.
+
+### Implementation
+
+- **MUST** bind state with `v-model` (or `:model-value` + `@update:modelValue`).
+- **MUST** use only documented props from MCP or `VJoyToggle.vue` props.
+- **MUST** use Joy tokens — no custom `.joy-toggle` track, bubble, or focus CSS.
+- **MUST NOT** invent props (`size`, `color`, `checked` as v-model name, …).
+- **MUST** use `variant="default"` on customer surfaces; reserve `admin` for internal tools.
+- **SHOULD** set `name` and `value` when multiple toggles participate in the same native form submit.
+- **SHOULD** surface validation errors with `VJoyFormError` or `VJoyFormGroup` — don’t rely on `invalid` alone until invalid styling is wired.
+
+### Interaction
+
+- **MUST** keep the label clickable (component wraps input in `<label>` — don’t break that association).
+- **SHOULD** use `labelPosition="left"` when the switch must align with a column of controls on the right (e.g. settings tables).
+- **SHOULD** disable rather than hide a setting the user cannot change, when the setting must remain visible.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-model` for on/off state | Separate Save button for a single instant setting (unless product requires it) |
+| Short setting names as labels | Full sentences that read like checkboxes (“I agree…”) |
+| `default` on product UI | `admin` variant on customer flows |
+| `VJoyCheckbox` for consent | Toggle for legal acceptance |
+| Radio / select for 3+ options | Toggle as a multi-option picker |
+
+---
+
+## Content
+
+Toggle labels name **what is enabled when the switch is on**. They are scannable, parallel in lists, and use the **infinitive** mood in English (per Joy conjugation guidelines).
+
+### Label formula
+
+**Infinitive verb + optional object** (English):
+
+- ✅ Enable notifications  
+- ✅ Show completed projects  
+- ✅ Use dark mode  
+
+The label describes the **on** state. Off is implied.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every toggle has a visible label (prop or default slot) — no unlabeled switches |
+| **MUST** | Label states what is on when checked — ✅ `Enable email alerts` · ❌ `Email alerts are enabled` |
+| **MUST** | Use infinitive mood (EN) — ✅ `Show profile` · ❌ `Showing profile` |
+| **MUST NOT** | Use Yes / No as the only label — name the setting |
+| **MUST NOT** | Use checkbox-style agreement copy — ✅ move to `VJoyCheckbox` |
+| **SHOULD** | ≤ 40 characters; wrap rather than truncate |
+| **SHOULD** | Sentence case; parallel grammar in stacked settings |
+| **SHOULD** | Avoid “Turn on/off” padding when the infinitive alone is clear — ✅ `Enable notifications` |
+| **SHOULD** (FR) | Follow product locale rules; infinitive is still preferred for toggle labels |
+
+### Patterns
+
+**Settings row** — One toggle per row; label on the right by default. Group related toggles under a `VJoyLabel` or section heading.
+
+**Dialog / panel** — Use when the choice is binary and applies immediately (e.g. “Show archived items”). Prefer explicit labels over “On / Off” alone.
+
+**Forms** — If the form is submitted as a whole, still bind `v-model`; set `name` / `value` so unchecked toggles behave as expected in native submit (checkbox semantics).
+
+**Validation** — When a toggle must be on to proceed, show error copy next to the control (`VJoyFormError`) rather than only relying on border color.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native checkbox (`<input type="checkbox">`) with `role="checkbox"` |
+| Name | From default slot or `label` prop; associated via wrapping `<label>` |
+| State | `aria-checked` reflects `modelValue` |
+| Keyboard | **Space** toggles when focused; **Tab** moves focus |
+| Focus | Visible focus ring on the track (`joy-toggle__focusing`); don’t remove in product CSS |
+| Disabled | `disabled` on input; explain restriction in visible text when it matters |
+| Motion | Bubble animates with `--joy-transition-duration-default`; respect `prefers-reduced-motion` at app level if you add wrappers |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyToggle } from '@maltjoy/core-vue'
+
+const notifications = ref(true)
+const showArchived = ref(false)
+</script>
+
+<template>
+  <!-- Basic setting (label right) -->
+  <VJoyToggle v-model="notifications" label="Enable notifications" />
+
+  <!-- Label on the left (settings table alignment) -->
+  <VJoyToggle
+    v-model="showArchived"
+    label="Show archived projects"
+    label-position="left"
+  />
+
+  <!-- Custom label slot -->
+  <VJoyToggle v-model="showArchived">
+    Show <strong>archived</strong> projects
+  </VJoyToggle>
+
+  <!-- Disabled -->
+  <VJoyToggle disabled :model-value="true" label="Managed by your organization" />
+
+  <!-- Native form field -->
+  <VJoyToggle
+    v-model="notifications"
+    name="email_alerts"
+    value="enabled"
+    label="Enable email alerts"
+  />
+
+  <!-- Admin tooling only -->
+  <VJoyToggle variant="admin" v-model="showArchived" label="Admin view" />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyToggle` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyCheckbox` | Consent, multi-select, or non-immediate binary confirmation |
+| `VJoyCheckboxGroup` | Several independent checkboxes with shared legend |
+| `VJoyRadio` / `VJoyRadioGroup` | Exactly one of three or more visible options |
+| `VJoySelect` | Many options or searchable lists |
+| `VJoyLabel` / `VJoyFormGroup` | Section headings, required marks, and form-level validation messaging |
+| `VJoyFormError` | Explicit error text when validation fails |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyToggle.dsds.json`](./JoyToggle.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Single on/off setting, immediate | `VJoyToggle` | `VJoyCheckbox` for a settings row |
+| “I agree to terms” | `VJoyCheckbox` | `VJoyToggle` |
+| Pick one of 3+ options | `VJoyRadio` / `VJoySelect` | `VJoyToggle` |
+| Multi-select filters | `VJoyCheckbox` / `VJoyCheckboxGroup` | `VJoyToggle` |
+| Customer product UI | `VJoyToggle` `variant="default"` | `variant="admin"` |
+| Internal admin surface | `VJoyToggle` `variant="admin"` | `admin` on public pages |
+
+### Hard rules
+
+1. **MUST** read `VJoyToggle.vue` props (or MCP when available) before generating props — `joy_get_component_info("VJoyToggle")` may not be registered yet.  
+2. **MUST** use `v-model` / `:model-value` + `@update:modelValue` — not `v-model:checked`.  
+3. **MUST NOT** invent props — there is no `size`, `checked` v-model alias, or `color`.  
+4. **MUST NOT** override `.joy-toggle` track, bubble, or focus styles with custom CSS.  
+5. **MUST NOT** use `variant="admin"` outside admin / internal tooling.  
+6. **MUST** provide a visible label (prop or default slot) on every instance.  
+7. **SHOULD** use infinitive labels (EN): `Enable notifications`, not `Notifications enabled`.  
+8. **SHOULD** use `label-position="left"` only when layout requires label-before-switch alignment.
+
+### Checklist
+
+- [ ] Correct component (`VJoyToggle` or named alternative)
+- [ ] Props from source / MCP only — no invented API
+- [ ] `v-model` wired for boolean on/off state
+- [ ] Visible label on every instance
+- [ ] `variant="default"` on customer surfaces
+- [ ] No custom `.joy-toggle` chrome CSS
+- [ ] 3+ options → radio or select, not toggle
+- [ ] Consent copy → checkbox, not toggle
+- [ ] Disabled / validation explained in visible text when user-facing
+- [ ] `name` / `value` set when needed for native form submit
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyToggle.dsds.json`](./JoyToggle.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants | `variants` |
+| 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 sizing | `design-specifications` in JSON (token names, not raw px dumps) |

package/dist/doc/VJoyTooltip/guideline.md

@@ -0,0 +1,322 @@
+---
+component: VJoyTooltip
+status: draft
+language: en
+dsds: JoyTooltip.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Tooltip
+
+Use **`VJoyTooltip`** when you need brief, contextual help on hover or click — for example naming an icon-only control, explaining why something is disabled, or clarifying a field label.
+
+The tooltip wraps a trigger (default slot), teleports its panel to `body`, positions itself with Floating UI (auto-flip when space is tight), and exposes `role="tooltip"` with `aria-describedby` on the trigger.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTooltip` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Tooltip](https://zeroheight.com/6bf479565/p/137c09-tooltip) |
+| **Storybook** | [VJoyTooltip docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoytooltip--docs) |
+| **DSDS (machine)** | [`JoyTooltip.dsds.json`](./JoyTooltip.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTooltip")` |
+
+---
+
+## When to use this component
+
+Use a tooltip to reveal **short, supplementary** information tied to a single trigger — without pulling the user out of their current task. Typical jobs: label an icon button, explain a disabled control, or add optional detail to a form label (`VJoyLabel` uses this pattern).
+
+Default interaction is **hover** (`event="mouseenter"`). Switch to **click** when hover is unreliable (touch-first surfaces) or when the tooltip must stay open while the user reads or interacts with its content.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Information the user must read or act on | `VJoyDialog`, `VJoyDrawer`, or inline helper text |
+| A list of actions or navigation | `VJoyMenu`, `VJoyDropdown` |
+| Persistent page guidance or onboarding | Product tour / coachmark patterns (see Information helper guidelines) |
+| Toast-style feedback after an action | `pushVJoySnackbar` |
+| A custom floating panel with ad-hoc CSS | Still use `VJoyTooltip` + Joy tokens — don’t reinvent overlay chrome |
+
+> **Deprecated:** `enableClickInContent` — behavior is already the default (`true`) and the prop will be removed. Omit it in new code unless you explicitly need the legacy `false` behavior.
+
+> **Removed from API:** `variant` (`primary` / `secondary`) existed on the legacy Stencil tooltip. **`VJoyTooltip` has no `variant` prop.** Do not emit `variant="primary"` or `variant="secondary"`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Click-outside wrapper | Yes | `OnClickOutside` root — dismisses click-triggered tooltips |
+| Trigger wrapper | Yes | Wraps the default slot; holds pointer/keyboard listeners and `aria-describedby` |
+| Trigger (default slot) | Yes | The control or element the user hovers/clicks (e.g. `VJoyIconButton`) |
+| Tooltip panel | Yes* | Teleported to `body`; `role="tooltip"`; shown when visible |
+| Arrow | Yes | Positioned by Floating UI middleware |
+| Content inner | Yes* | `tooltip-content` slot or `text` prop output |
+
+\*The panel is not rendered unless `text` or the `tooltip-content` slot is provided.
+
+### Default values
+
+- `placement` defaults to **`bottom`**
+- `event` defaults to **`mouseenter`**
+- `delay` defaults to **`100`** (ms, show/hide)
+- `tooltipWidth` defaults to **`250`** (px `max-width` on the panel)
+- `enableClickInContent` defaults to **`true`**
+- `show` defaults to **`false`** (set `true` mainly in Storybook / visual tests)
+
+Props, slots, and exposed members: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Positioning and triggers
+
+- **Placement** — any [Floating UI placement](https://floating-ui.com/docs/tutorial#placements) (`top`, `bottom`, `left`, `right`, and `*-start` / `*-end`). The component **flips** to `bottom`, `top`, `left`, or `right` when there isn’t enough room.
+- **Hover (default)** — show on `mouseenter`, hide on `mouseleave`. Clicks alone do not open the tooltip.
+- **Click** — set `event="click"`. Opens on trigger click; closes on outside click or **Tab** away from the trigger. With `enableClickInContent`, clicks inside the tooltip content do not dismiss it.
+
+---
+
+## Variants
+
+`VJoyTooltip` has **no visual variant prop**. Styling is fixed: neutral background (`--joy-color-neutral-10`), body text (`--joy-color-neutral-60`), `primary-300` typography, `--joy-core-radius-3`, and `--joy-core-elevation-3`.
+
+### Not in the API: `primary` / `secondary` (legacy Stencil)
+
+ZeroHeight and the legacy `@maltjoy/core` tooltip documented `variant="primary"` (information blue) and `variant="secondary"` (neutral). These values are **not** on `VJoyTooltip`. Do not generate them. If product needs an information-colored tooltip, confirm with design before adding a new API value.
+
+---
+
+## Sizes
+
+Single visual size — no `size` prop. Typography and padding come from Joy tokens inside the component (`primary-300`, `--joy-core-spacing-4`).
+
+| Control | Use when |
+| --- | --- |
+| Default width | Short labels and icon explanations |
+| `tooltipWidth` | Longer copy that should wrap within a narrower or wider column (value is `max-width` in px) |
+
+**Don’t** hardcode font sizes or padding on `.joy-tooltip__content` in product CSS.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Hidden (default) | Only the trigger is visible |
+| Delayed show | After `delay` ms, panel fades in (hover or click path) |
+| Visible | Tooltip panel + arrow; describes the trigger for assistive tech |
+| Hiding | Opacity animation when dismissed (`mouseleave`, outside click, or Tab) |
+| Click + open | With `event="click"`, panel stays until outside click or Tab; content may be clickable when `enableClickInContent` is true |
+| `show` (dev) | Forces visible on mount — for Storybook/tests, not production UX |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show a tooltip
+
+- **SHOULD** add a tooltip on **icon-only** controls when the icon alone is not universally understood (see Button content guidelines).
+- **SHOULD** explain **why** a nearby control is disabled (forms pattern: disabled submit + tooltip).
+- **SHOULD** keep tooltips **supplementary** — the interface must remain usable if the tooltip never appears.
+- **MUST NOT** put essential instructions, links, or decisions only inside a tooltip.
+
+### Implementation
+
+- **MUST** provide content via `text` **or** the `tooltip-content` slot — omitting both means no tooltip is rendered.
+- **MUST** use only documented props and enums from MCP / component types.
+- **MUST** use Joy tokens — no custom `.joy-tooltip__content` chrome (background, shadow, radius).
+- **MUST NOT** invent props (`variant`, `size`, `color`, …).
+- **SHOULD** prefer the **`tooltip-content` slot** over `text` when content includes markup (`<strong>`, `<small>`). Use `text` only for plain, trusted strings (XSS risk if fed user input).
+- **SHOULD** set a stable **`id`** when multiple tooltips on one view need unambiguous `aria-describedby` targeting.
+- **SHOULD** use `event="click"` on touch-heavy layouts or when users must interact with tooltip content.
+
+### Interaction
+
+- **MUST NOT** cover the trigger or adjacent primary actions with the tooltip panel.
+- **SHOULD** use default hover on desktop pointer UIs; evaluate click for mobile/tablet.
+- **SHOULD** keep `delay` at default unless UX research shows a different timing need.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Wrap `VJoyIconButton` + short label in tooltip | Duplicate the button’s visible label in the tooltip |
+| `tooltip-content` slot for formatted copy | `text` with HTML strings from the API |
+| `event="click"` when content is tappable | Hover-only tooltips with links or buttons inside |
+| `tooltipWidth` for readable line length | Fixed `width` overrides in app CSS |
+| Dialog/drawer for required reading | Long paragraphs in a tooltip |
+
+---
+
+## Content
+
+Tooltips carry **short, contextual** copy. They enhance the UI; they don’t replace labels, helper text, or dialog body content.
+
+### Copy formula
+
+**Noun phrase** or **short imperative** that names the control or states the constraint:
+
+- ✅ Put to trash  
+- ✅ Notifications  
+- ✅ Complete all required fields to submit  
+- ✅ Annual billing only  
+
+Avoid full sentences unless explaining a disabled state.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | One idea per tooltip — no paragraphs |
+| **MUST** | Match the trigger’s language (icon `label`, button text, field name) |
+| **MUST NOT** | Repeat visible text already on the trigger |
+| **MUST NOT** | Put links, CTAs, or decisions only in a tooltip |
+| **MUST NOT** | Use tooltips for error validation (use inline field errors) |
+| **SHOULD** | ≤ ~60 characters; wrap naturally within `tooltipWidth` |
+| **SHOULD** | Sentence case; no trailing period for labels |
+| **SHOULD** | Name the **reason** when explaining disabled controls |
+| **SHOULD** | Use `<strong>` sparingly for one emphasized word (slot content) |
+| **SHOULD** (FR) | Non-breaking spaces before `;`, `?`, `!`, and `:` |
+
+### Patterns
+
+**Icon buttons** — Tooltip text should mirror or shorten the control’s accessible name (`label` on `VJoyIconButton`). If the icon is universal (e.g. trash → delete), tooltip still helps but label remains mandatory.
+
+**Disabled submit** — Pair with the disabled control: e.g. “Complete all required fields to submit”. Same message as inline form guidance is acceptable.
+
+**Form labels** — `VJoyLabel` exposes a `label-tooltip` slot pattern; keep copy factual (format, eligibility), not marketing.
+
+**Information helper** — For the 16px `(?)` pattern, tooltips are **text on hover**; richer patterns (badge, dialog on click) use other components — don’t overload `VJoyTooltip`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Tooltip panel uses `role="tooltip"` |
+| Relationship | Trigger wrapper sets `aria-describedby` to the tooltip `id` when open |
+| Name | Trigger must have its own accessible name (`label` on icon buttons, visible text, `aria-label`) — the tooltip **describes**, it doesn’t replace the name |
+| Keyboard | **Tab** away from the trigger closes an open tooltip; tooltips are not a separate tab stop |
+| Hover | Default `mouseenter` — ensure equivalent info is not hover-only on keyboard-only flows when content is essential (use visible text or click mode) |
+| Click mode | `event="click"` improves discoverability on touch; still provide a clear trigger name |
+| Motion | Show/hide uses `--joy-transition-duration-default`; respect `prefers-reduced-motion` at app level if you add global overrides |
+| Content | Don’t rely on color alone inside tooltip copy; inherited tokens meet contrast for default neutral theme |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyTooltip, VJoyIconButton, VJoyButton } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Icon button — default hover, plain text -->
+  <VJoyTooltip text="Put to trash">
+    <VJoyIconButton icon="trash" variant="ghost" label="Put to trash" />
+  </VJoyTooltip>
+
+  <!-- Rich content via slot -->
+  <VJoyTooltip placement="top">
+    <VJoyIconButton icon="bell" variant="ghost" label="Notifications" />
+    <template #tooltip-content>
+      You have <strong>3</strong> unread messages
+    </template>
+  </VJoyTooltip>
+
+  <!-- Click trigger (touch / interactive content) -->
+  <VJoyTooltip event="click" text="More details about this setting">
+    <VJoyIconButton icon="info" variant="ghost" label="Setting information" />
+  </VJoyTooltip>
+
+  <!-- Disabled control explanation -->
+  <VJoyTooltip text="Complete all required fields to submit">
+    <VJoyButton variant="main" label="Submit" disabled />
+  </VJoyTooltip>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTooltip` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyIconButton` | Icon-only trigger — pair with tooltip when meaning isn’t obvious |
+| `VJoyLabel` | Field label + optional `label-tooltip` slot |
+| `VJoyButton` | Disabled actions that need a “why” on hover |
+| `VJoyDialog` | User must read content or confirm a decision |
+| `VJoyDrawer` | Supplementary panel with header actions (may embed tooltips in chrome) |
+| `VJoyMenu` / `VJoyDropdown` | Action or navigation lists |
+| `pushVJoySnackbar` | Transient feedback after an action |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyTooltip.dsds.json`](./JoyTooltip.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Short hint on hover/click for one trigger | `VJoyTooltip` | Custom `position: absolute` div + title attr |
+| Icon-only control | `VJoyIconButton` inside `VJoyTooltip` | `VJoyButton` with only an icon |
+| Required reading or confirm/cancel | `VJoyDialog` | Long tooltip copy |
+| Menu of actions | `VJoyMenu` / `VJoyDropdown` | Tooltip with fake buttons |
+| Post-action feedback | `pushVJoySnackbar` | Tooltip that stays after click |
+| Legacy colored variant | Neutral `VJoyTooltip` only | `variant="primary"` / `variant="secondary"` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyTooltip")` (or read `VJoyTooltip.vue` types) before generating props.
+2. **MUST** wrap exactly one trigger in the default slot.
+3. **MUST** supply `text` or `#tooltip-content` — never an empty tooltip.
+4. **MUST NOT** invent props (`variant`, `size`, `open`, `theme`, …).
+5. **MUST NOT** pass HTML through `text` from API/user data — use the slot or sanitize upstream.
+6. **MUST NOT** override `.joy-tooltip__content` / `__arrow` colors, shadow, or radius in app CSS.
+7. **SHOULD** set `event="click"` when the tooltip contains interactive elements or on mobile-first screens.
+8. **SHOULD** reuse the icon button’s `label` text in the tooltip when clarifying the same action.
+9. **SHOULD NOT** use `show` in production pages (Storybook/tests only).
+
+### Checklist
+
+- [ ] Correct component (or named alternative from table above)
+- [ ] Props / enums from MCP only (`placement`, `event`, `delay`, `tooltipWidth`, `id`, `text`)
+- [ ] Content via `text` (plain) or `#tooltip-content` (markup)
+- [ ] No `variant` / no invented props / no custom tooltip chrome CSS
+- [ ] Trigger has its own accessible name (`label`, visible text, or `aria-label`)
+- [ ] Copy is short and non-essential; disabled/menu/dialog cases handled elsewhere if needed
+- [ ] `event="click"` when content is interactive or hover is insufficient
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyTooltip.dsds.json`](./JoyTooltip.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / placement | `anatomy` |
+| Placements / triggers | `variants` (behavioral) |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Token sizing | `design-specifications` in JSON |