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

package/dist/doc/VJoyInputPassword/guideline.md

@@ -0,0 +1,379 @@
+---
+component: VJoyInputPassword
+status: draft
+language: en
+dsds: JoyInputPassword.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Input Password
+
+Use **`VJoyInputPassword`** when the user must enter a password — sign-in, sign-up, password change, or API key entry where masking is expected.
+
+It wraps `VJoyInput` with a built-in show/hide toggle (`eye` / `eye-masked` icons), optional strength requirements via the `password-requirements` slot, and the same label, validation, and sizing patterns as other Joy form fields. Native attributes such as `placeholder`, `autocomplete`, and `aria-*` pass through to the underlying `<input>`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyInputPassword` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Input Password](https://zeroheight.com/6bf479565/p/8386038) |
+| **Storybook** | [VJoyInputPassword docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyinputpassword--docs) |
+| **DSDS (machine)** | [`JoyInputPassword.dsds.json`](./JoyInputPassword.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyInputPassword")` |
+
+---
+
+## When to use this component
+
+Use a password input when the value must stay masked by default and the user may optionally reveal it to check typing — login forms, registration, “confirm password” steps, or credential settings.
+
+Pair it with a visible label, `autocomplete` hints (`current-password`, `new-password`), and validation feedback when rules fail. For live strength feedback, compose `VJoyPasswordRequirement` items in the `password-requirements` slot.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Single-line non-secret text (email, name, search) | `VJoyInput` |
+| One-time / verification code (OTP, PIN) | `VJoyInputDigit` |
+| Multi-line secret or note | `VJoyTextarea` (rare — confirm with security if truly secret) |
+| Numeric value with a unit suffix | `VJoyInputNumber` |
+| Custom `<input type="password">` with ad-hoc toggle | Still use `VJoyInputPassword` + Joy tokens |
+| `type="password"` on `VJoyInput` | `VJoyInputPassword` |
+
+> **Deprecated:** do not use `type="password"` on `VJoyInput` for new work — use `VJoyInputPassword`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | Wrapper (`.joy-input-password`) around input + optional requirements |
+| `VJoyInput` | Yes | Underlying text field; `type` toggles `password` ↔ `text` |
+| Label | No | `VJoyLabel` from the `label` prop (or external `VJoyLabel` + `id` / `name`) |
+| Native `<input>` | Yes | Receives `$attrs` (placeholder, autocomplete, maxlength, etc.) |
+| Visibility toggle | Yes | Trailing `VJoyIcon` (`eye` when masked, `eye-masked` when visible) in `right-action` |
+| Password requirements | No | `password-requirements` slot — typically `VJoyPasswordRequirement` rows inside `VJoyWrapper` |
+| Focus ring | Yes | Inherited from `VJoyInput` — do not remove in product CSS |
+
+Masked characters use a local font treatment (`Verdana` + letter-spacing) on `input[type="password"]`; placeholders keep the default Joy font.
+
+### Default values
+
+- `name` defaults to **`"joy-input-password"`** — override in real forms
+- `size` defaults to **`medium`** (inherited from `VJoyInput`)
+- `labelSize` defaults to **`medium`**
+- `modelModifiers` defaults to **`{ lazy: false }`**
+- `disabled`, `invalid`, `required`, `requiredMark`, and `autofocus` default to **`false`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Not on this component
+
+`VJoyInputPasswordProps` omits **`type`**, **`clearable`**, **`clearAriaLabel`**, and **`readonly`** from `VJoyInput`. Do not pass them — passwords are not clearable or readonly through this API.
+
+### Visual treatment
+
+There is **no `variant` prop**. Appearance comes from **state** (`invalid`, `disabled`) and **density** (`size`), same as `VJoyInput`.
+
+---
+
+## Sizes
+
+Choose size for **density** within the form. Heights and radii come from `--joy-form-field-height-*` and `--joy-form-field-radius-*` — **do not hardcode pixel heights** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `small` | Dense auth panels or compact settings rows |
+| `medium` | Default login, registration, and account forms |
+| `large` | Marketing-scale or hero auth layouts |
+
+Match label size to field size when possible (`labelSize` aligns with `VJoyLabel` sizes).
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (masked) | Bullets/dots in the field; `eye` icon on the right; editable |
+| Revealed | Toggle clicked — `type="text"`, value visible; `eye-masked` icon |
+| Hover | Border shifts on the underlying input (pointer devices) |
+| Focus | Focus border and `joy-input--focusing` on the wrapper |
+| Valid (implicit) | Neutral styling when not `invalid` and not `disabled` |
+| Invalid | Error border and text color from `VJoyInput` — pair with `VJoyFormError` |
+| Disabled | Field and toggle non-interactive; toggle shows `not-allowed` cursor — explain why nearby |
+
+Toggling visibility does not change `modelValue` — only the input `type` and icon.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Labels and forms
+
+- **MUST** provide a visible label (via `label`, `VJoyLabel`, or associated `<label for="…">`).
+- **MUST** set `name` (and `id` when multiple password fields share a form) for labels, autofill, and tests. `id` falls back to `name` on `VJoyInput`.
+- **SHOULD** set `autocomplete="current-password"` on sign-in and `autocomplete="new-password"` on registration or change-password flows.
+- **SHOULD** use `requiredMark` with `required` when the form uses asterisks for mandatory fields.
+- **SHOULD** wrap related fields in `VJoyWrapper` or `VJoyFormGroup` for spacing.
+
+### Implementation
+
+- **MUST** use `VJoyInputPassword` for password entry — not `VJoyInput` with `type="password"`.
+- **MUST** bind value with `v-model` (`modelValue` / `update:modelValue`).
+- **MUST** use only documented props from MCP or `VJoyInput.types.ts` (minus omitted keys above).
+- **MUST** style with Joy tokens — no custom `.joy-input` or `.joy-input-password` chrome.
+- **MUST NOT** pass `clearable`, `readonly`, or `type` — they are not part of this API.
+- **MUST NOT** invent props (`unit`, `variant`, `errorMessage`, …).
+- **SHOULD** call exposed `focus()` programmatically only when restoring focus after an error — not on every mount.
+
+### Visibility toggle
+
+- **SHOULD** assume the toggle is pointer-driven; keyboard users edit the masked field normally.
+- **MUST NOT** rely on reveal for security-sensitive flows where shoulder-surfing is a risk without user intent.
+- **SHOULD NOT** add a leading `icon` unless design explicitly requires it — the trailing toggle already occupies the right side.
+
+### Validation and requirements
+
+- **MUST** set `invalid` when showing a validation error for this field.
+- **MUST** show the error message in `VJoyFormError` (or equivalent) — not only red border.
+- **SHOULD** use `VJoyPasswordRequirement` in `password-requirements` for live rule feedback on sign-up.
+- **SHOULD** update each requirement’s `status` (`neutral`, `success`, `error`) as rules are evaluated.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyInputPassword` + `autocomplete` | `VJoyInput` + `type="password"` |
+| `VJoyPasswordRequirement` in the slot | Custom bullet list with random icons |
+| `invalid` + `VJoyFormError` | Red border with no message |
+| Distinct `name` for “Password” and “Confirm password” | Duplicate `name` on sibling fields |
+| Joy form-field size tokens | Hardcoded `32` / `40` / `48`px heights |
+
+---
+
+## Content
+
+Password fields expose label, optional placeholder, and optional requirement lines. Copy should reduce entry errors without revealing policy only after submit.
+
+### Label formula
+
+**Noun phrase** naming the credential — not the action:
+
+- ✅ Password  
+- ✅ Current password  
+- ✅ New password  
+- ✅ Confirm password  
+
+Use sentence case. On change-password flows, distinguish **current** vs **new** vs **confirm** explicitly.
+
+### Placeholder formula
+
+**Short hint** — optional; never replace the label:
+
+- ✅ `Enter your password` (under label “Password”)  
+- ❌ `Password` as placeholder when the label already says “Password”
+
+Avoid real password examples in placeholders.
+
+### Requirement lines
+
+Each `VJoyPasswordRequirement` label states **one rule** in plain language:
+
+- ✅ At least 8 characters  
+- ✅ Contains an uppercase letter  
+- ✅ Contains a special character  
+
+Keep rules parallel (same grammar). Prefer positive wording over “No spaces” unless the rule is exclusion-only.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every field has a visible label — never placeholder-only |
+| **MUST** | Error messages say what failed and how to fix it — ✅ `Password must be at least 8 characters` · ❌ `Invalid` |
+| **MUST NOT** | Show the actual password in labels, helper text, or errors |
+| **MUST NOT** | Use “Re-enter password” without a clear “Confirm password” or “Confirm new password” label when two fields are paired |
+| **SHOULD** | Keep labels ≤ 3–5 words when possible |
+| **SHOULD** | Match `autocomplete` to the step (`current-password`, `new-password`) |
+| **SHOULD** | Localize requirement strings with the rest of the form |
+
+### Patterns
+
+**Sign-in** — One password field, `autocomplete="current-password"`, link to reset nearby — not inside the label.
+
+**Registration** — New password + confirm field; live requirements in `password-requirements`; validate match on submit or blur.
+
+**Change password** — Three fields (current, new, confirm) with distinct labels and names; requirements only under the new password field.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<input>` with `type="password"` or `type="text"` when revealed |
+| Name | From `label` / `VJoyLabel` / associated `<label for>` |
+| Value | Controlled via `v-model` |
+| Keyboard | Standard text editing; Tab moves focus into the field |
+| Focus | Visible focus ring on the input — do not remove focus tokens |
+| Invalid | `invalid` on the field; pair with `VJoyFormError` (`role="alert"`) for the message |
+| Disabled | Native `disabled`; toggle click is ignored — provide text explanation when it matters |
+| Autocomplete | Pass `autocomplete` via attrs for password managers |
+| Requirements | `VJoyPasswordRequirement` error rows use `data-joy-form-error` when `status="error"` |
+| Toggle | Icon click toggles visibility; ensure product copy does not depend on color alone for errors |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import {
+  VJoyInputPassword,
+  VJoyPasswordRequirement,
+  VJoyFormError,
+  VJoyWrapper,
+} from '@maltjoy/core-vue'
+
+const password = ref('')
+const confirm = ref('')
+const showError = ref(false)
+
+const hasMinLength = computed(() => password.value.length >= 8)
+</script>
+
+<template>
+  <!-- Sign-in -->
+  <VJoyInputPassword
+    v-model="password"
+    name="sign-in-password"
+    label="Password"
+    autocomplete="current-password"
+    required
+    required-mark
+  />
+
+  <!-- Registration with live requirements -->
+  <VJoyWrapper direction="column" row-gap="4">
+    <VJoyInputPassword
+      v-model="password"
+      name="new-password"
+      label="New password"
+      autocomplete="new-password"
+      required
+      required-mark
+      :invalid="showError && !hasMinLength"
+    >
+      <template #password-requirements>
+        <VJoyPasswordRequirement
+          :status="hasMinLength ? 'success' : 'neutral'"
+          label="At least 8 characters"
+        />
+        <VJoyPasswordRequirement status="neutral" label="Contains uppercase" />
+        <VJoyPasswordRequirement status="neutral" label="Contains special character" />
+      </template>
+    </VJoyInputPassword>
+    <VJoyFormError
+      v-if="showError && !hasMinLength"
+      message="Password must be at least 8 characters"
+    />
+  </VJoyWrapper>
+
+  <!-- Confirm password -->
+  <VJoyInputPassword
+    v-model="confirm"
+    name="confirm-password"
+    label="Confirm password"
+    autocomplete="new-password"
+    required
+    required-mark
+  />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyInputPassword` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyInput` | Non-secret single-line text |
+| `VJoyPasswordRequirement` | One rule row under the password field |
+| `VJoyFormError` | Inline validation message below the field |
+| `VJoyLabel` | Rich labels (legend, tooltip) separate from the field |
+| `VJoyWrapper` / `VJoyFormGroup` | Form layout and spacing |
+| `VJoyInputDigit` | Fixed-length codes (OTP) — not passwords |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyInputPassword.dsds.json`](./JoyInputPassword.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Password / secret with show-hide | `VJoyInputPassword` | `VJoyInput` + `type="password"` |
+| Email, name, search, free text | `VJoyInput` | `VJoyInputPassword` |
+| OTP / PIN digits | `VJoyInputDigit` | Password input |
+| Number with unit (€, %, days) | `VJoyInputNumber` | `VJoyInput` + `unit` |
+| Strength rules under the field | `#password-requirements` + `VJoyPasswordRequirement` | Custom unstyled list |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyInputPassword")` or read `VJoyInput.types.ts` (omitted props) before generating props.  
+2. **MUST** bind `v-model` for editable values.  
+3. **MUST** set `name` (and `id` when needed for label association).  
+4. **MUST** pass native attrs (`placeholder`, `autocomplete`, `maxlength`, `aria-*`) on the component — they flow to `<input>`.  
+5. **MUST** set `invalid` when showing validation errors and render `VJoyFormError` with a message.  
+6. **MUST NOT** emit `type`, `clearable`, `readonly`, or `clearAriaLabel` on `VJoyInputPassword`.  
+7. **MUST NOT** emit `unit` — not supported on this wrapper (MCP may list it from `VJoyInput`; ignore for passwords).  
+8. **MUST NOT** override `.joy-input` / `.joy-input-password` height, border, radius, or padding.  
+9. **SHOULD** use `autocomplete="current-password"` or `new-password` as appropriate.  
+10. **SHOULD** use `password-requirements` + `VJoyPasswordRequirement` for sign-up strength UI.
+
+### Checklist
+
+- [ ] Correct component (`VJoyInputPassword`, not masked `VJoyInput`)
+- [ ] Props / enums from MCP or types only
+- [ ] `v-model` + `name` present
+- [ ] Visible label (not placeholder-only)
+- [ ] `autocomplete` set for password managers
+- [ ] `invalid` + `VJoyFormError` when validation fails
+- [ ] No `type` / `clearable` / `readonly` / invented props
+- [ ] Confirm field uses a distinct `name` and clear label
+- [ ] Requirements slot uses `VJoyPasswordRequirement` when showing rules
+- [ ] Disabled state explained if user-visible
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyInputPassword.dsds.json`](./JoyInputPassword.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Sizes | `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 (`--joy-form-field-height-*`, `--joy-form-field-radius-*`) |

package/dist/doc/VJoyInputPassword/metadata.json

@@ -146,15 +146,6 @@
       "possibleValues": [
         "Partial<Record<\"number\" | \"trim\" | \"lazy\", boolean>>"
       ]
-    },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "required": false,
-      "description": "Adds a legend like symbol on the right of the component. Made for number based values",
-      "possibleValues": [
-        "string"
-      ]
     }
   ],
   "events": [
@@ -246,11 +237,6 @@
       "type": "((value: string) => any) | undefined",
       "isMethod": true
     },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "isMethod": false
-    },
     {
       "name": "focus",
       "type": "() => void",

package/dist/doc/VJoyLabel/guideline.md

@@ -0,0 +1,200 @@
+---
+component: VJoyLabel
+status: draft
+language: en
+dsds: JoyLabel.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Label
+
+Use **`VJoyLabel`** when a form field or option group needs a visible, accessible name — with optional required/optional markers, helper legend text, or a contextual tooltip.
+
+Render it as a `<label>` (default) linked to a control via `for` / `id`, or as a `<legend>` inside fieldsets. Native attributes (`for`, `id`, `aria-*`, …) pass through to the root label/legend element via `$attrs`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyLabel` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyLabel docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoylabel--docs) |
+| **DSDS (machine)** | [`JoyLabel.dsds.json`](./JoyLabel.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyLabel")` |
+
+---
+
+## When to use this component
+
+Use a label when someone must understand what a form control is for before they interact with it — field titles, group legends, or standalone labels paired with inputs, selects, textareas, and similar controls.
+
+Typical jobs: external label above a control (`VJoyLabel` + `for` / `id`), group legend in `VJoyRadioGroup`’s `radio-group-legend` slot, or richer label chrome (required asterisk, “optional” suffix, helper line, question-mark tooltip).
+
+Many Joy form components (`VJoyInput`, `VJoySelect`, `VJoyTextarea`, …) render `VJoyLabel` internally when you set their `label` prop. Use a **standalone** `VJoyLabel` when you need more control (custom slots, external layout, or `VJoyFormGroup` composition).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Page or section heading (not tied to one control) | `VJoyText`, semantic headings (`h1`–`h6`), or `VJoyTitleBrand` |
+| Button or link text | `VJoyButton` / `VJoyLink` label or slot content |
+| Inline copy inside a sentence | Plain text or `VJoyLink` |
+| Tooltip on an icon-only control with no field label | `VJoyTooltip` on the trigger |
+| Simple one-line label on a Joy input with no legend/tooltip | The control’s `label` prop (still `VJoyLabel` under the hood) |
+| Custom-styled `<label>` / ad-hoc label CSS | Still use `VJoyLabel` + Joy tokens — don’t reinvent chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Group wrapper | Yes | `.joy-label__group`; adds `--standalone` spacing when not inside a Joy form field |
+| Label / legend | Yes | `<label>` or `<legend>` with `data-joy-form-label` and size modifier (`joy-label--{size}`) |
+| Label text | Yes* | Default slot or `text` prop (*one should provide the visible name) |
+| Required mark | No | `*` span when `required` is true |
+| Optional suffix | No | Italic `- {optionalLabel}` when `optionalLabel` is set |
+| Tooltip trigger | No | `VJoyTooltip` + `question-circle` icon when `label-tooltip` slot is used |
+| Legend line | No | `label-legend` slot — secondary helper text below the main label |
+
+When nested inside a Joy form component that `provide`s `JoyFormElementContext`, the wrapper **omits** standalone outer spacing (the parent owns field layout).
+
+### Default values
+
+- `size` defaults to **`medium`** (`small`, `medium`, `large`)
+- `tagName` defaults to **`label`** (`label` or `legend`)
+- `required` defaults to **`false`**
+- `optionalLabel` has **no default** — omit unless the field is explicitly optional
+- `text` has **no default** — use `text` or the default slot
+
+Props and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Label association
+
+- **External label:** set `for` on `VJoyLabel` (via attribute) to match the control’s `id` (or `name` when `id` is omitted).
+- **Built-in label:** pass `label` to `VJoyInput`, `VJoySelect`, etc. — the component wires `for` automatically.
+- **Group legend:** set `tagName="legend"` (or rely on group patterns) inside `VJoyRadioGroup` / `VJoyCheckboxGroup` legend slots.
+
+Match `size` to the paired control when possible (`labelSize` on inputs aligns with `VJoyLabel` sizes).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure
+
+- **MUST** provide a visible label for every form control (via `VJoyLabel`, a control’s `label` prop, or an equivalent associated `<label>`).
+- **MUST** keep `for` on the label aligned with the control’s `id` (or `name`) when using the external-label pattern.
+- **SHOULD** use `required` on the label only when the field is actually required — pair with `required` on the control and validation messaging.
+- **SHOULD** use `optionalLabel` (e.g. localized `"optional"`) instead of hiding that the field is optional.
+- **SHOULD** put format hints or eligibility detail in `label-legend`, not in the primary label line.
+- **SHOULD** reserve `label-tooltip` for short, factual context — not essential instructions.
+
+### Implementation
+
+- **MUST** use only documented props and enums from MCP or `JoyLabel.types.ts` (`size`: `small` | `medium` | `large`; `tagName`: `label` | `legend`).
+- **MUST** pass native label attributes (`for`, `id`, `aria-*`) as attributes on `VJoyLabel` — they are not declared props but bind to the root element.
+- **MUST** style with Joy tokens — no custom `.joy-label` font, color, or spacing overrides.
+- **MUST NOT** invent props (`variant`, `color`, `invalid`, …).
+- **MUST NOT** use `VJoyLabel` as a page heading or non-form title.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyLabel for="email"` + `VJoyInput id="email"` | Mismatched or missing `for` / `id` |
+| `label-legend` for “We’ll never share your email” | Long helper text in the main label |
+| `tagName="legend"` in radio/checkbox group slots | Bare `<legend>` with custom CSS |
+| `required` + asterisk when the field is required | Decorative `*` with no `required` semantics on the control |
+| `label-tooltip` for brief format hints | Paragraphs of help only in a tooltip |
+| Control `label` prop for simple fields | Duplicate standalone `VJoyLabel` + `label` prop on the same field |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<label>` (default) or `<legend>` when `tagName="legend"` |
+| Name | Primary text from default slot or `text` prop |
+| Association | `for` on `<label>` must reference the control `id`; built-in labels on Joy inputs handle this when `label` + `id`/`name` are set |
+| Required | Visual `*` when `required` is true — also set `required` on the associated control and surface errors with `VJoyFormError` |
+| Tooltip | `label-tooltip` adds supplementary info via `VJoyTooltip`; the label text must still make sense without it |
+| Marker | `data-joy-form-label` on the root label/legend for Joy form styling hooks |
+| Grouping | Option groups use `<fieldset>` + `<legend>` via `VJoyRadioGroup` / `VJoyCheckboxGroup` — don’t rely on `VJoyLabel` alone for fieldset semantics |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyLabel, VJoyInput, VJoyRadio, VJoyRadioGroup } from '@maltjoy/core-vue'
+
+const email = ref('')
+const referral = ref('')
+const taxId = ref('')
+const billing = ref('monthly')
+</script>
+
+<template>
+  <!-- External label + input -->
+  <VJoyLabel for="signup-email" required>
+  Email address
+  <template #label-legend>We'll send your receipt here</template>
+  </VJoyLabel>
+  <VJoyInput
+    id="signup-email"
+    v-model="email"
+    name="signup-email"
+    type="email"
+    autocomplete="email"
+  />
+
+  <!-- Optional field -->
+  <VJoyLabel for="referral" optional-label="optional">
+    Referral code
+  </VJoyLabel>
+  <VJoyInput id="referral" v-model="referral" name="referral" />
+
+  <!-- Label with tooltip -->
+  <VJoyLabel for="tax-id" size="small">
+    Tax ID
+    <template #label-tooltip>
+      Your national tax identification number
+    </template>
+  </VJoyLabel>
+  <VJoyInput id="tax-id" v-model="taxId" name="tax-id" label-size="small" />
+
+  <!-- Group legend -->
+  <VJoyRadioGroup>
+    <template #radio-group-legend>
+      <VJoyLabel tag-name="legend">Billing frequency</VJoyLabel>
+    </template>
+    <VJoyRadio v-model="billing" name="billing" value="monthly">Monthly</VJoyRadio>
+    <VJoyRadio v-model="billing" name="billing" value="yearly">Yearly</VJoyRadio>
+  </VJoyRadioGroup>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyLabel` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyInput` / `VJoySelect` / `VJoyTextarea` | Control with optional built-in `label` prop |
+| `VJoyFormGroup` | Vertical stack of label + control + `VJoyFormError` |
+| `VJoyFormError` | Validation message below the labeled control |
+| `VJoyRadioGroup` / `VJoyCheckboxGroup` | Fieldset + legend slot for option groups |
+| `VJoyTooltip` | Standalone contextual help (used inside `label-tooltip`) |
+| `VJoyText` | Non-form headings or body copy |