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

package/dist/doc/VJoyProgressBar/guideline.md

@@ -0,0 +1,348 @@
+---
+component: VJoyProgressBar
+status: draft
+language: en
+dsds: JoyProgressBar.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Progress Bar
+
+Use **`VJoyProgressBar`** when you need a **linear, determinate** progress indicator — for example showing how far a file upload has gone, how complete a profile is, or progress inside a walkthrough header.
+
+It supports percentage-based or step-based values, optional numeric label, semantic color variants, and a smooth width transition. It is **read-only** (not interactive).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyProgressBar` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Progress Bar](https://zeroheight.com/6bf479565/) (page id `2271816`) |
+| **Storybook** | [VJoyProgressBar docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoyprogressbar--docs) |
+| **DSDS (machine)** | [`JoyProgressBar.dsds.json`](./JoyProgressBar.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyProgressBar")` |
+
+---
+
+## When to use this component
+
+Use a progress bar when completion is **known and measurable** (0–100%) and a thin horizontal bar is enough context — upload progress, checklist completion, onboarding percentage, or a compact meter beside a title.
+
+Prefer **`percentage`** when the backend or client already exposes a percent. Use **`steps`** + **`currentStep`** when progress is naturally expressed as “step 3 of 6” and you want the component to derive the fill width.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Multi-step funnel with named steps and sub-steps | `VJoyStepper` + `VJoyStep` |
+| Indeterminate / unknown duration loading | `VJoySpinner` or `VJoyScreenLoader` |
+| Blocking full-page load | `VJoyScreenLoader` |
+| Status message after an action | `pushVJoySnackbar` |
+| Semantic status callout (success, warning, error copy) | `VJoyHighlight` |
+| Custom bar with ad-hoc CSS | Still use `VJoyProgressBar` + Joy tokens — don’t reinvent chrome |
+
+> **Product note:** Progress bars are lightly used in product UIs; for guided flows with step labels, design guidance favors **`VJoyStepper`**. Use `VJoyProgressBar` when a simple meter is intentional.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root wrapper | Yes | `VJoyWrapper` (`nowrap`, `column-gap="1"`, `align="center"`) with color class `joy-progress-bar_{color}` |
+| Track | Yes | `.joy-progress-bar-wrapper` — neutral background, full width, 4px height |
+| Fill | Yes | `.joy-progress-bar-inner` — width driven by computed progress (`0%`–`100%`) |
+| Label | No | `.joy-progress-bar-label` — pill showing `{percentage}%` when `showLabel` is true |
+
+The fill animates width with `--joy-transition-duration-long` and `--joy-transition-timing-function`.
+
+### Progress value
+
+The component computes fill width in this order:
+
+1. If **`percentage`** is set (including `0`), it wins — **`steps` / `currentStep` are ignored**.
+2. Else if both **`steps`** and **`currentStep`** are set, width = `round((currentStep / steps) * 100)`.
+3. Else width is **`0%`**.
+
+Values are **clamped** to `0`–`100` (overflowing `currentStep` caps at 100%; negative values floor at 0%).
+
+### Default values
+
+- `color` defaults to **`secondary`**
+- `showLabel` defaults to **`false`**
+- `steps`, `currentStep`, and `percentage` are **optional** (unset → `0%` fill)
+
+Props: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Label behavior
+
+The built-in label renders **only** when **`showLabel` is true and `percentage` is defined** (including `0`). It does **not** appear for step-only mode (`steps` + `currentStep` without `percentage`). For step-based flows that need visible numbers, pass an explicit `percentage` or show copy outside the component.
+
+---
+
+## Variants
+
+`color` carries **semantic meaning**, not decoration. Pick the variant that matches the status being communicated.
+
+Allowed values (from `TJoyProgressBarColors`): `primary`, `secondary`, `success`, `warning`, `error`.
+
+### `secondary` (default)
+
+Use for **neutral** progress — generic completion, onboarding percentage, or walkthrough progress where no success/warning/error signal is needed.
+
+Avoid when the bar should read as a validation outcome (use `success`, `warning`, or `error`).
+
+### `primary`
+
+Use when the bar should align with the **brand primary** accent (marketing-scale or hero completion meters).
+
+Avoid pairing several primary bars on one surface unless each tracks a distinct primary task.
+
+### `success`
+
+Use when progress reflects a **completed or on-track positive** outcome (e.g. profile 100% complete, upload finished).
+
+Avoid for in-progress neutral tasks — `secondary` is clearer.
+
+### `warning`
+
+Use when progress is **incomplete or needs attention** but is not a hard failure (e.g. profile partially filled).
+
+Avoid for successful completion states.
+
+### `error`
+
+Use when the meter communicates **failure or critical shortfall** (e.g. quota exceeded, validation threshold not met).
+
+Avoid for ordinary in-progress loading.
+
+### Not in the API: `info` / `neutral`
+
+ZeroHeight and shared level tokens include **`info`** and **`neutral`**. They are **not** in `TJoyProgressBarColors`. Do not emit `color="info"` or `color="neutral"`. Use `secondary` for neutral meters or confirm with design before extending the API.
+
+---
+
+## Sizes
+
+`VJoyProgressBar` exposes **no `size` prop**. Visual scale is fixed inside the component.
+
+| Aspect | Guidance |
+| --- | --- |
+| Track height | 4px — driven by component CSS; **don’t hardcode bar height** in apps |
+| Track width | 100% of the wrapper; place inside a layout that defines available width (`VJoyWrapper`, panel body, etc.) |
+| Label typography | `joy-font-primary-250` on the pill — don’t override font size in product CSS |
+| Density | For funnels with many named steps, prefer `VJoyStepper` (bar width adapts to step count there) — not this component |
+
+---
+
+## States
+
+| State | What the user sees |
+| --- | --- |
+| Empty (`0%`) | Track only; fill width `0%`; label `0%` when `showLabel` + `percentage` |
+| In progress (`1%`–`99%`) | Partial fill; optional label |
+| Complete (`100%`) | Full fill; optional label `100%` |
+| Step-based | Fill derived from `currentStep` / `steps`; no built-in label unless you also pass `percentage` |
+| Color emphasis | Fill and label pill tint follow `color` token mapping |
+
+There is no hover, focus, disabled, or loading prop — the bar is presentational. Drive updates by changing `percentage` or `currentStep` reactively.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show progress
+
+- **SHOULD** use `VJoyProgressBar` only when progress is **determinate** (you can compute 0–100%).
+- **SHOULD** prefer `VJoyStepper` when users need **step names** and funnel navigation context.
+- **SHOULD** pair the bar with a **visible heading or status** so meaning isn’t color-only.
+- **MUST NOT** use a progress bar for **indeterminate** waits — use `VJoySpinner`.
+
+### Implementation
+
+- **MUST** use only `color` values from MCP or `JoyProgressBar.types.ts`.
+- **MUST** pass **`percentage`** when you need the built-in numeric label (`showLabel`).
+- **MUST** clamp or validate upstream values; the component clamps fill width but labels echo the `percentage` prop as given.
+- **MUST** style with Joy tokens — no custom `.joy-progress-bar-*` chrome (height, radius, colors).
+- **MUST NOT** invent props (`variant`, `size`, `value`, `max`, …).
+- **SHOULD** prefer `percentage` when the API already returns a percent; use `steps` / `currentStep` only when step indices are the source of truth.
+- **SHOULD** update `percentage` or `currentStep` as work advances — avoid jumping backwards without user context.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `color="secondary"` for neutral meters | Random hex fills on a custom `<div>` |
+| `showLabel` + `percentage` for numeric feedback | `showLabel` alone in step-only mode (label won’t render) |
+| `VJoyStepper` for named funnel steps | Progress bar as the only step indicator in a wizard |
+| `VJoySpinner` for unknown duration | Animated bar with fake percentage |
+| Heading + bar for context | Color-only status with no text |
+
+---
+
+## Content
+
+The optional label shows a **percentage only** (`42%`). It does not accept custom slot text.
+
+### Label formula
+
+**Integer percentage + `%` symbol** — rendered by the component from the `percentage` prop:
+
+- ✅ `0%`, `45%`, `100%`
+- ❌ Custom strings (`3 of 6`, `Almost done`) — use adjacent `VJoyText` or stepper labels instead
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Provide a **visible title or status** near the bar when the task name isn’t obvious from context |
+| **MUST NOT** | Rely on color alone to communicate success, warning, or error |
+| **SHOULD** | Enable `showLabel` when exact percent helps (uploads, profile completion) |
+| **SHOULD** | Hide `showLabel` when the bar is decorative or redundant with nearby copy |
+| **SHOULD** | Use `success` / `warning` / `error` colors consistently with `VJoyHighlight` semantics on the same screen |
+| **SHOULD NOT** | Show both a stepper and a redundant percentage label for the same funnel step |
+
+### Patterns
+
+**Uploads** — Bind `percentage` to upload progress; `showLabel` optional; keep filename/status in adjacent text.
+
+**Profile / checklist completion** — `percentage` from completed fields; `color="success"` at 100%; `secondary` while in progress.
+
+**Walkthrough header** — Slot pattern in `VJoyWalkthrough` (`walkthrough-progress`): compact bar + label; subtitle can carry human-readable copy (`80% completed`).
+
+**Step-derived width** — Use `steps` + `currentStep` when you only need the fill (no built-in label); add external “Step 2 of 5” copy if users need numbers.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Component uses `<div>` elements — **no `role="progressbar"`** is set by default |
+| Name | **MUST** expose purpose in nearby visible text (title, status, walkthrough subtitle) — the bar alone is not a sufficient name |
+| Value | When `showLabel` + `percentage` are set, the numeric value is visible; otherwise provide equivalent text in context |
+| Motion | Width animates on change — respect `prefers-reduced-motion` at app level if you add global overrides |
+| Color | Don’t use `color` as the only indicator of success, warning, or error — pair with text or icons |
+| Keyboard | Not focusable — no keyboard interaction required |
+
+**SHOULD** wrap or supplement with an accessible name when progress is critical (e.g. `aria-label="Upload progress"` on a parent region, or visible heading associated via `aria-labelledby`). If native `role="progressbar"` with `aria-valuenow` / `aria-valuemin` / `aria-valuemax` is required, confirm with design whether to extend the component — don’t fake it with clickable divs.
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyProgressBar } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Percentage with label (default color) -->
+  <VJoyProgressBar :percentage="45" show-label />
+
+  <!-- Step-derived width (no built-in label) -->
+  <VJoyProgressBar :steps="6" :current-step="3" />
+
+  <!-- Semantic colors -->
+  <VJoyProgressBar :percentage="100" color="success" show-label />
+  <VJoyProgressBar :percentage="40" color="warning" />
+  <VJoyProgressBar :percentage="15" color="error" show-label />
+
+  <!-- Primary accent -->
+  <VJoyProgressBar :percentage="80" color="primary" />
+
+  <!-- Zero percent is valid (v6+) -->
+  <VJoyProgressBar :percentage="0" show-label />
+
+  <!-- Label requires percentage — not steps alone -->
+  <VJoyProgressBar :percentage="50" :steps="4" :current-step="1" show-label />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyProgressBar` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyStepper` / `VJoyStep` | Named multi-step funnel with step labels |
+| `VJoySpinner` | Indeterminate loading (button, inline) |
+| `VJoyScreenLoader` | Full-viewport blocking load |
+| `VJoyWalkthrough` | Onboarding overlay — embeds progress via `walkthrough-progress` slot |
+| `VJoyHighlight` | Persistent success / warning / error messaging with copy |
+| `VJoyWrapper` | Layout wrapper used internally; also for grouping bar + adjacent text |
+| `VJoyText` | Human-readable status beside the bar |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyProgressBar.dsds.json`](./JoyProgressBar.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Known % completion, thin meter | `VJoyProgressBar` | Custom `<div>` with inline width % |
+| Named steps in a funnel | `VJoyStepper` | `VJoyProgressBar` as the only step UI |
+| Unknown wait time | `VJoySpinner` / `VJoyScreenLoader` | `VJoyProgressBar` with fake oscillating % |
+| Toast after save | `pushVJoySnackbar` | Progress bar for transient feedback |
+| Walkthrough % in header | `VJoyProgressBar` in `walkthrough-progress` | Duplicate bar + random copy |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyProgressBar")` (or read `JoyProgressBar.types.ts` / `VJoyProgressBar.vue`) before generating props.
+2. **MUST** use only documented props: `color`, `steps`, `currentStep`, `percentage`, `showLabel`.
+3. **MUST** pass **`percentage`** when `showLabel` is true — the label does not render for step-only mode.
+4. **MUST NOT** invent props (`variant`, `size`, `value`, `max`, `label`, …).
+5. **MUST NOT** emit `color="info"` or `color="neutral"`.
+6. **MUST NOT** override `.joy-progress-bar-wrapper` / `-inner` height, radius, or colors in app CSS.
+7. **SHOULD** default to `color="secondary"`; use semantic colors only when status matches.
+8. **SHOULD** prefer `percentage` over `steps`/`currentStep` when both are available — `percentage` overrides step math.
+
+### Valid enums (from `JoyProgressBar.types.ts`)
+
+| Prop | Values |
+| --- | --- |
+| `color` | `primary`, `secondary`, `success`, `warning`, `error` |
+| `showLabel` | `true`, `false` |
+| `percentage` | `number` (0–100; component clamps fill width) |
+| `steps` / `currentStep` | `number` (positive integers expected) |
+
+### Checklist
+
+- [ ] Correct component (`VJoyProgressBar` or named alternative)
+- [ ] Props / enums from MCP or types only
+- [ ] `percentage` set when `showLabel` is needed
+- [ ] No invented props / no custom progress-bar chrome CSS
+- [ ] Determinate progress only; spinner for indeterminate
+- [ ] Context text or heading — not color-only status
+- [ ] `VJoyStepper` used when step names matter
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyProgressBar.dsds.json`](./JoyProgressBar.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / progress logic | `anatomy` |
+| Colors | `variants` |
+| Single-size spec | `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/VJoyRadio/guideline.md

@@ -0,0 +1,346 @@
+---
+component: VJoyRadio
+status: draft
+language: en
+dsds: JoyRadio.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Radio
+
+Use **`VJoyRadio`** when the user must pick **exactly one** option from a small, visible set of mutually exclusive choices.
+
+Each radio is a labeled option with optional supporting copy and content slots. Pair radios inside **`VJoyRadioGroup`** so the group gets a fieldset, legend, layout, and shared invalid state.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyRadio` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyRadioGroup docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyradiogroup--docs) (includes `VJoyRadio` examples) |
+| **DSDS (machine)** | [`JoyRadio.dsds.json`](./JoyRadio.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyRadio")` |
+
+---
+
+## When to use this component
+
+Use a radio when only one answer is valid and every option should stay visible — for example choosing a billing cycle, a delivery method, or a profile type.
+
+Radios work best with **2–7** parallel options. When options need extra description, pricing, or conditional fields, use the `outline` theme and the content slots rather than stacking unrelated UI beside a bare label.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Multiple selections from a list | `VJoyCheckbox` inside `VJoyCheckboxGroup` |
+| Card-style multi-select | `VJoyCheckboxCard` |
+| A single on/off preference | `VJoyToggle` (or a checkbox when the label is a statement) |
+| Many options (roughly 8+) or searchable lists | `VJoySelect` |
+| Group label, layout, and shared validation | `VJoyRadioGroup` — **always** wrap radios; don’t use `VJoyFormGroup` around a lone radio |
+| Custom-styled native `<input type="radio">` | Still use `VJoyRadio` + Joy tokens — don’t reinvent chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Native radio input | Yes | Visually hidden `<input type="radio">` with `data-joy-form-field` |
+| Label (`default` slot) | Yes | Primary option text beside the radio circle |
+| Radio circle | Yes | Styled via the label pseudo-element (not a separate component) |
+| Sublabel (`radio-sublabel` slot) | No | Secondary, pre-styled helper text under the label |
+| Header right (`radio-header-right` slot) | No | Short metadata in the top-right (e.g. a tag) — non-interactive only |
+| Content (`radio-content` slot) | No | Always-visible body content below the label (common with `outline`) |
+| Expandable content (`expandable-content` slot) | No | Revealed only when this radio is selected (`outline` theme) |
+| Focus ring | Yes | Theme-specific focus treatment — don’t remove it in product CSS |
+
+### Default values
+
+- `theme` defaults to **`default`**
+- `disabled` defaults to **`false`**
+- `required` defaults to **`false`**
+- `invalid` defaults to **`undefined`** (inherits from parent `VJoyRadioGroup` when omitted)
+- `value` is **required** — the option’s submitted value
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Grouping and model
+
+- **MUST** place every `VJoyRadio` inside `VJoyRadioGroup`.
+- **MUST** bind the **same** `v-model` (`modelValue`) on each sibling radio.
+- **MUST** give siblings the same `name` so the browser treats them as one group.
+- **MUST** use a distinct `value` per option.
+- Set group-level `invalid` on `VJoyRadioGroup`; override per radio with `invalid` only when needed.
+
+---
+
+## Variants
+
+`theme` controls layout density and which slots are meaningful — not a color swatch choice.
+
+### `default`
+
+Use for compact, inline option lists (horizontal or vertical groups) where the label alone is enough.
+
+Avoid when each option needs a bordered card, always-on body content, or fields that appear only after selection.
+
+### `outline`
+
+Use when options should read as **selectable cards** — pricing tiers, plan comparison, or choices with sublabels and extra content.
+
+Supports `radio-sublabel`, `radio-content`, `radio-header-right`, and `expandable-content`. The expandable region opens with a height/opacity transition when the radio becomes checked.
+
+Avoid in dense horizontal toolbars; Storybook documents `outline` for **vertical** group layouts.
+
+### Not in the API: size
+
+There is no `size` prop. The radio control uses an internal `--radio-size` token (20px). Don’t hardcode circle dimensions in apps.
+
+---
+
+## Sizes
+
+`VJoyRadio` exposes **no size API**. Visual scale comes from Joy form tokens inside the component.
+
+| Aspect | Guidance |
+| --- | --- |
+| Radio circle | Fixed via `--radio-size` (20px) and Joy color tokens — don’t override in product CSS |
+| Label typography | Inherited from Joy primary body styles |
+| Outline cards | Padding and border from Joy spacing / form tokens (`--joy-core-spacing-4`, `--joy-form-border-width`) |
+| Density | Prefer `VJoyRadioGroup` `direction` and slot content for density — not invented `size` props |
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (unchecked) | Empty radio circle; option is selectable |
+| Checked | Filled circle; label weight increases; `outline` border/elevation highlight |
+| Hover | Circle border uses hover token (pointer devices); `outline` border accent on hover when enabled |
+| Focus | Visible focus ring — `default` theme on the circle; `outline` theme on the card |
+| Disabled | Muted label and circle; `not-allowed` cursor; **disabled styling wins over invalid** |
+| Invalid | Error color on circle and/or `outline` border; inherits from `VJoyRadioGroup` unless overridden per radio |
+| Expanded (`outline` + `expandable-content`) | Slot content visible only while this radio is checked |
+
+When validation fails, set `invalid` on the **group** and show a `VJoyFormError` (or equivalent) explaining what to fix. Don’t rely on color alone.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection and hierarchy
+
+- **SHOULD** offer **2–7** options; beyond that, prefer `VJoySelect`.
+- **SHOULD** pre-select a sensible default when one option is clearly recommended.
+- **SHOULD** keep option labels **parallel** (same grammatical structure and length order of magnitude).
+- **MUST NOT** use radios when the user may need “none of the above” unless product rules allow clearing the group.
+- **MUST NOT** wrap `VJoyRadio` in `VJoyFormGroup` — use `VJoyRadioGroup` (enforced by ESLint).
+
+### Implementation
+
+- **MUST** use only documented props and `theme` values from MCP or `JoyRadio.types.ts` (`default`, `outline`).
+- **MUST** share one `v-model` and one `name` across siblings in the same group.
+- **MUST** style with Joy tokens — no custom `.joy-radio` chrome overrides.
+- **MUST NOT** invent props (`size`, `variant`, `color`, …).
+- **MUST NOT** put interactive controls (buttons, links) in `radio-header-right` — display-only metadata only.
+
+### Interaction
+
+- **MUST** set `disabled` on individual radios the user cannot choose (not just visually dim the label).
+- **SHOULD** explain **why** an option is disabled when the reason isn’t obvious from context.
+- **SHOULD** use `expandable-content` for fields that belong to the selected option — not for unrelated UI.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyRadioGroup` + shared `v-model` | Lone radios without a group |
+| Parallel, scannable labels | Long paragraphs as the primary label |
+| `outline` + slots for rich options | Custom card divs that behave like radios |
+| Group `invalid` + error message | Error color with no explanation |
+| `radio-header-right` for tags / short meta | Buttons or links in the header-right slot |
+
+---
+
+## Content
+
+Radio copy should make each option distinct at a glance and read consistently as a set.
+
+### Label formula
+
+**Short noun phrase or concise statement** naming the option:
+
+- ✅ Monthly billing  
+- ✅ Standard delivery  
+- ✅ Freelancer  
+
+Use the **same part of speech** across siblings (all nouns, or all short sentences).
+
+### Sublabel and body copy
+
+- **`radio-sublabel`** — one line of supporting detail (price, timing, eligibility).  
+- **`radio-content`** — always-visible elaboration (feature list, highlight).  
+- **`expandable-content`** — inputs or details that only apply after selection.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Label the **option**, not the action — ✅ `Express shipping` · ❌ `Select express shipping` |
+| **MUST** | Keep primary labels ≤ ~40 characters; move detail to sublabel or content slots |
+| **MUST** | Use sentence case for labels and sublabels |
+| **MUST NOT** | Repeat the group legend text in every option label |
+| **MUST NOT** | Use yes/no as two radio labels when the question isn’t literally binary — name the outcomes |
+| **SHOULD** | Put numbers, prices, or badges in `radio-header-right` or sublabel, not the main label |
+| **SHOULD** | Write the group legend as a question or instruction (`Billing frequency`, `How do you work?`) via `VJoyRadioGroup`’s `radio-group-legend` slot with `VJoyLabel` |
+| **SHOULD** | Localize all slot content; `value` stays a stable programmatic key |
+
+### Patterns
+
+**Plan / tier pickers** — `outline` theme: title in `default`, price or cadence in `radio-sublabel`, feature summary in `radio-content`, payment fields in `expandable-content` when selected.
+
+**Settings with side effects** — sublabel states what changes if the user picks this option (`Invoices are sent on the 1st of each month`).
+
+**Validation** — group legend + `VJoyFormError` below the group: ✅ `Choose a delivery method` + `Select one option to continue`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<input type="radio">` inside a `<label>`; group wrapped in `VJoyRadioGroup` `<fieldset role="radiogroup">` |
+| Name | Option name from the `default` slot (associated via `<label>`); group name from `radio-group-legend` |
+| Keyboard | **Arrow keys** move between radios in the same group (browser default); **Space** selects focused radio |
+| Focus | Visible focus ring — `joy-radio--focus` / `joy-radio--outline-focus`; never `outline: none` on product overrides |
+| Disabled | `disabled` on the input; don’t rely on color alone — explain when needed |
+| Invalid | Error styling plus programmatic invalid state from group; pair with visible error text |
+| Expansion | Expanding content must not trap focus; treat revealed fields as part of the selected option’s context |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyRadio, VJoyRadioGroup, VJoyLabel } from '@maltjoy/core-vue'
+
+const billing = ref('monthly')
+</script>
+
+<template>
+  <!-- Default theme — compact list -->
+  <VJoyRadioGroup>
+    <template #radio-group-legend>
+      <VJoyLabel>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>
+
+  <!-- Outline theme — rich option -->
+  <VJoyRadioGroup direction="vertical">
+    <template #radio-group-legend>
+      <VJoyLabel>Delivery method</VJoyLabel>
+    </template>
+
+    <VJoyRadio v-model="billing" theme="outline" name="delivery" value="standard">
+      Standard delivery
+      <template #radio-sublabel>3–5 business days</template>
+      <template #expandable-content>
+        <!-- Fields shown only when this option is selected -->
+      </template>
+    </VJoyRadio>
+  </VJoyRadioGroup>
+
+  <!-- Disabled option -->
+  <VJoyRadio v-model="billing" name="billing" value="enterprise" disabled>
+    Enterprise (contact sales)
+  </VJoyRadio>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyRadio` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyRadioGroup` | Grouping, legend, layout (`direction`), and shared `invalid` |
+| `VJoyLabel` | Accessible group legend in `radio-group-legend` |
+| `VJoyFormError` | Explaining validation failures for the group |
+| `VJoyCheckbox` / `VJoyCheckboxGroup` | Multiple selections |
+| `VJoySelect` | Long or searchable option lists |
+| `VJoyTag` | Short metadata in `radio-header-right` |
+| `VJoyHighlight` | Informational blocks in `radio-content` or `expandable-content` |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyRadio.dsds.json`](./JoyRadio.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Exactly one of a few visible options | `VJoyRadio` inside `VJoyRadioGroup` | Standalone radio or `VJoyFormGroup` wrapper |
+| Multiple selections | `VJoyCheckbox` | `VJoyRadio` with duplicate values |
+| Long dropdown list | `VJoySelect` | Many `VJoyRadio` rows |
+| Rich card option with conditional fields | `VJoyRadio` `theme="outline"` + slots | Custom clickable `<div>` cards |
+| Group validation error | `invalid` on `VJoyRadioGroup` + error text | `invalid` on every radio without a message |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyRadio")` and `joy_get_component_types("VJoyRadio")` (or read types) before generating props.  
+2. **MUST** wrap all `VJoyRadio` instances in `VJoyRadioGroup`.  
+3. **MUST** bind the same `v-model` and `name` to every sibling in a group; each `value` must be unique.  
+4. **MUST** pass a required `value` prop on every radio.  
+5. **MUST NOT** invent props (`size`, `variant`, `color`, …) or custom `.joy-radio` CSS.  
+6. **MUST NOT** use interactive elements in `radio-header-right`.  
+7. **SHOULD** use `theme="outline"` only with `direction="vertical"` on the group.  
+8. **SHOULD** use `expandable-content` only with `theme="outline"` and only for content tied to the selected option.
+
+### Checklist
+
+- [ ] `VJoyRadio` inside `VJoyRadioGroup` (not `VJoyFormGroup`)
+- [ ] Shared `v-model` + `name`; unique `value` per option
+- [ ] `theme` is `default` or `outline` only (from types)
+- [ ] No invented props / no custom radio chrome CSS
+- [ ] Group legend via `radio-group-legend` + `VJoyLabel`
+- [ ] Validation: `invalid` on group + visible error message
+- [ ] Parallel, concise labels; detail in sublabel/content slots
+- [ ] `radio-header-right` is display-only (e.g. `VJoyTag`)
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyRadio.dsds.json`](./JoyRadio.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants (`theme`) | `variants` |
+| Sizes (no size API) | `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 |