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

package/dist/doc/VJoyRadioGroup/guideline.md

@@ -0,0 +1,331 @@
+---
+component: VJoyRadioGroup
+status: draft
+language: en
+dsds: JoyRadioGroup.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Radio group
+
+Use **`VJoyRadioGroup`** when the user must pick **exactly one** option from a short, visible set and the choices belong together as a single form field.
+
+It wraps `VJoyRadio` siblings in a semantic `<fieldset role="radiogroup">`, supports a group legend, horizontal or vertical layout, shared validation (`invalid`), and native form association (`name`, `form`). Selection state lives on each child radio via a **shared** `v-model` — the group itself does not bind a model.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyRadioGroup` 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) |
+| **DSDS (machine)** | [`JoyRadioGroup.dsds.json`](./JoyRadioGroup.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyRadioGroup")` |
+
+---
+
+## When to use this component
+
+Use a radio group when only one answer is valid, every option should stay visible, and the set reads as one decision — for example billing frequency, delivery method, or profile type.
+
+Groups work best with **2–7** options composed as `VJoyRadio` children. For richer option cards (sublabels, expandable fields), keep the group and set `theme="outline"` on each radio (vertical layout).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A single radio without siblings | Don’t — radios are always grouped; use at least two `VJoyRadio` children |
+| Multiple selections from a list | `VJoyCheckbox` inside `VJoyCheckboxGroup` |
+| A single on/off preference | `VJoyToggle` (or a checkbox when the label is a statement) |
+| Many options (roughly 8+) or searchable lists | `VJoySelect` |
+| Label + spacing wrapper around unrelated fields | `VJoyFormGroup` — **not** for radios (ESLint disallows `VJoyRadio` inside `VJoyFormGroup`) |
+| Option appearance, slots, or per-radio disabled state | `VJoyRadio` (inside this group) |
+| Custom-styled native radio lists | Still use `VJoyRadioGroup` + `VJoyRadio` + Joy tokens — don’t reinvent chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Fieldset | Yes | Root `<fieldset class="joy-radio-group-fieldset">` with `role="radiogroup"` |
+| Legend (`radio-group-legend` slot) | No (but **SHOULD** in forms) | Group label — typically `VJoyLabel` |
+| Container | Yes | `.joy-radio-group-container` — flex layout for child radios |
+| Default slot | Yes | One or more `VJoyRadio` components |
+| `VJoyFormError` (sibling or inside group) | No | Explains validation failures when `invalid` is true |
+
+### Default values
+
+- `direction` defaults to **`horizontal`**
+- `invalid` defaults to **`false`**
+- `form` and `name` default to **`undefined`**
+
+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` in the group’s default slot.
+- **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` on each `VJoyRadio`.
+- **MUST NOT** bind `v-model` on `VJoyRadioGroup` — it has no selection prop.
+- Set `invalid` on the group to propagate error styling to children (they inherit via provide/inject unless a radio sets `invalid` explicitly).
+- Optional `name` / `form` on the fieldset associate the group with native form submission.
+
+### Not in the Vue API (Stencil / ZeroHeight drift)
+
+The Stencil `joy-radio-group` exposes `label`, `labelSize`, `required`, `requiredMark`, `invalidText`, and `value` on the group. **`VJoyRadioGroup` does not.** Use the `radio-group-legend` slot + `VJoyLabel`, per-radio `required`, and `VJoyFormError` beside the group instead.
+
+---
+
+## Variants
+
+`direction` controls layout — not visual emphasis. Spacing comes from Joy tokens (`--joy-core-spacing-4` gap inside the container).
+
+### `horizontal` (default)
+
+Use for compact, inline option sets where labels are short and options fit on one or wrapped rows.
+
+Avoid for `theme="outline"` radios (card layout) — Storybook documents outline only in vertical groups.
+
+### `vertical`
+
+Use when options stack (long labels, outline cards, sublabels, or expandable content).
+
+Avoid when a tight horizontal toolbar-like row is enough and every option is a simple `default`-theme radio.
+
+---
+
+## States
+
+Group-level state complements per-radio states on `VJoyRadio` (checked, disabled, focus, etc.).
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Fieldset groups radios; one may be selected via shared `v-model` |
+| Horizontal layout | Options in a row with token gap; container adds bottom margin |
+| Vertical layout | Options stacked in a column |
+| Invalid (`invalid` on group) | Error styling on child radios (inherited); pair with visible error text |
+| Valid selection | Checked radio reflects `modelValue`; arrow keys move within the group |
+| Mixed disabled | Individual radios set `disabled`; group stays interactive for enabled options |
+
+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 in a group; beyond that, prefer `VJoySelect`.
+- **SHOULD** pre-select a sensible default when one option is clearly recommended.
+- **SHOULD** keep option labels parallel across siblings (see `VJoyRadio` content guidance).
+- **MUST NOT** wrap `VJoyRadio` in `VJoyFormGroup` — use `VJoyRadioGroup` (enforced by ESLint).
+
+### Implementation
+
+- **MUST** use only documented props and `direction` values from MCP or `JoyRadioGroup.types.ts` (`horizontal`, `vertical`).
+- **MUST** share one `v-model` and one `name` across all radios in the group.
+- **MUST** style with Joy tokens — no custom `.joy-radio-group` layout overrides.
+- **MUST NOT** invent props (`label`, `size`, `variant`, `invalidText`, group `v-model`, …).
+- **MUST NOT** hardcode gap or margin pixels — spacing is token-driven in `JoyRadioGroup.scss`.
+
+### Interaction
+
+- **MUST** set `invalid` on the group (not on every radio) for field-level validation errors.
+- **SHOULD** use `direction="vertical"` when any child uses `theme="outline"`.
+- **SHOULD** place `VJoyFormError` after the radio list (the group stylesheet reserves space for `.joy-form-error`).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyRadioGroup` + shared `v-model` on each `VJoyRadio` | Lone radios or `VJoyFormGroup` around radios |
+| Legend via `radio-group-legend` + `VJoyLabel` | Stencil-only `label` prop on the group |
+| Group `invalid` + error message | Error color with no explanation |
+| `vertical` for outline / rich options | `outline` radios in a horizontal row |
+| Same `name` on every sibling | Different `name` values in one group |
+
+---
+
+## Content
+
+The group legend frames the decision; individual option copy lives on each `VJoyRadio`.
+
+### Legend formula
+
+**Short question or category name** that applies to the whole set:
+
+- ✅ Billing frequency  
+- ✅ How do you work?  
+- ✅ Delivery method  
+
+Use `VJoyLabel` in the `radio-group-legend` slot. Mark required groups on the label when the field is mandatory.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Legend describes the **set**, not a single option |
+| **MUST** | Pair required groups with clear option labels on each `VJoyRadio` |
+| **MUST NOT** | Repeat the legend text in every radio label |
+| **SHOULD** | Use sentence case for the legend |
+| **SHOULD** | Keep legends concise; move detail to radio sublabels or content slots |
+| **SHOULD** | Match error copy to the legend (`Choose a delivery method` + `Select one option to continue`) |
+
+### Patterns
+
+**Settings block** — legend names the section; radios use parallel noun phrases (`Monthly`, `Yearly`).
+
+**Plan / tier pickers** — `direction="vertical"`, `theme="outline"` on radios; legend stays short (`Select a plan`).
+
+**Validation** — `invalid` on the group + `VJoyFormError` below the container.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<fieldset role="radiogroup">` wrapping related radios |
+| Name | Group accessible name from `radio-group-legend` (e.g. `VJoyLabel`); option names from each `VJoyRadio` label |
+| Keyboard | **Arrow keys** move between radios in the group; **Space** selects the focused radio |
+| Focus | Per-radio focus rings — don’t remove them in product CSS |
+| Invalid | Group `invalid` propagates to children; pair with visible error text and `VJoyFormError` where appropriate |
+| Form | `name` on fieldset and radios; `form` attribute when the group sits outside a `<form>` element |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyRadio, VJoyRadioGroup, VJoyLabel, VJoyFormError } from '@maltjoy/core-vue'
+
+const billing = ref('monthly')
+const showError = ref(false)
+
+function validate() {
+  showError.value = !billing.value
+}
+</script>
+
+<template>
+  <!-- Horizontal — 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>
+
+  <!-- Vertical + outline cards -->
+  <VJoyRadioGroup direction="vertical">
+    <template #radio-group-legend>
+      <VJoyLabel required-mark>Delivery method</VJoyLabel>
+    </template>
+
+    <VJoyRadio v-model="billing" theme="outline" name="delivery" value="standard">
+      Standard delivery
+      <template #radio-sublabel>3–5 business days</template>
+    </VJoyRadio>
+    <VJoyRadio v-model="billing" theme="outline" name="delivery" value="express">
+      Express delivery
+    </VJoyRadio>
+  </VJoyRadioGroup>
+
+  <!-- Validation -->
+  <VJoyRadioGroup :invalid="showError" direction="vertical">
+    <template #radio-group-legend>
+      <VJoyLabel required-mark>Delivery method</VJoyLabel>
+    </template>
+
+    <VJoyRadio v-model="billing" name="delivery-required" value="standard">Standard</VJoyRadio>
+    <VJoyRadio v-model="billing" name="delivery-required" value="express">Express</VJoyRadio>
+
+    <VJoyFormError v-if="showError">Select one option to continue</VJoyFormError>
+  </VJoyRadioGroup>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if components are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyRadio` | Individual options, themes, slots, and per-option `disabled` |
+| `VJoyLabel` | Accessible group legend in `radio-group-legend` |
+| `VJoyFormError` | Explaining validation failures for the group |
+| `VJoyCheckboxGroup` | Multiple selections |
+| `VJoySelect` | Long or searchable single-choice lists |
+| `VJoyFormGroup` | Label + control + error for other field types — not for radios |
+| `VJoyTag` | Short metadata in a radio’s `radio-header-right` slot |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyRadioGroup.dsds.json`](./JoyRadioGroup.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 `VJoyRadio` or `VJoyFormGroup` wrapper |
+| Multiple selections | `VJoyCheckboxGroup` | `VJoyRadioGroup` |
+| Long dropdown list | `VJoySelect` | Many radios without a group |
+| Rich card options | `VJoyRadioGroup` `direction="vertical"` + `VJoyRadio` `theme="outline"` | Horizontal outline row |
+| Group validation error | `invalid` on `VJoyRadioGroup` + `VJoyFormError` | Stencil-only `invalidText` on the group |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyRadioGroup")` and `joy_get_component_types("VJoyRadioGroup")` (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; each `value` must be unique.  
+4. **MUST NOT** bind `v-model` on `VJoyRadioGroup` — selection is on each `VJoyRadio`.  
+5. **MUST NOT** invent props (`label`, `invalidText`, `size`, group `modelValue`, …) or custom `.joy-radio-group` CSS.  
+6. **MUST NOT** place `VJoyRadio` inside `VJoyFormGroup`.  
+7. **SHOULD** use `direction="vertical"` when any child has `theme="outline"`.  
+8. **SHOULD** put the legend in `radio-group-legend` with `VJoyLabel`.
+
+### Checklist
+
+- [ ] `VJoyRadio` children inside `VJoyRadioGroup` (not `VJoyFormGroup`)
+- [ ] Shared `v-model` + `name` on every radio; unique `value` per option
+- [ ] `direction` is `horizontal` or `vertical` only (from types)
+- [ ] No `v-model` on the group; no invented group props
+- [ ] Legend via `radio-group-legend` + `VJoyLabel`
+- [ ] Validation: `invalid` on group + visible `VJoyFormError`
+- [ ] `vertical` when using `outline` theme radios
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyRadioGroup.dsds.json`](./JoyRadioGroup.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants (`direction`) | `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 |
+| Layout spacing | `design-specifications` |

package/dist/doc/VJoyRatingStars/guideline.md

@@ -0,0 +1,306 @@
+---
+component: VJoyRatingStars
+status: draft
+language: en
+dsds: JoyRatingStars.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Rating stars
+
+Use **`VJoyRatingStars`** when you need to **display** an aggregate rating from 0 to 5 — for example on a freelancer profile, mission feedback summary, or review list row.
+
+It renders five star icons (full, half, or empty) from a numeric `ratingValue`, optional review count in parentheses, and a slot for translated supplementary text. It is **read-only** — users cannot change the rating through this component.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyRatingStars` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyRatingStars docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoyratingstars--docs) |
+| **DSDS (machine)** | [`JoyRatingStars.dsds.json`](./JoyRatingStars.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyRatingStars")` |
+
+---
+
+## When to use this component
+
+Use rating stars when a **computed or fetched score** should be shown at a glance next to optional context (number of reviews, missions completed, etc.). Typical jobs: user cards, search result rows, review headers, and profile summaries.
+
+Pair the stars with a translated `aria-label` in localized products — the built-in default is English-only.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| User must **submit** or **edit** a rating | A dedicated rating-input pattern (not `VJoyRatingStars`) |
+| Show a percentage or step progress | `VJoyProgressBar` |
+| Status, category, or tag label | `VJoyBadge` or `VJoyTag` |
+| Plain numeric score without star metaphor | `VJoyText` |
+| Custom star row with ad-hoc icons / CSS | Still use `VJoyRatingStars` + Joy tokens |
+
+> **Deprecated:** on `VJoyUserCard`, do not use the `user-card-rating-stars` slot — put `VJoyRatingStars` in the **default** slot instead.
+
+> **Legacy Stencil:** the old `@maltjoy/core` slot was `rating-stars-slot` and icons used `color="yellow"`. In Vue use **`rating-stars-content`**; star color is **`quaternary`** via `VJoyIcon` — do not recreate yellow styling.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Wrapper | Yes | Root `div` with `role="img"` and `aria-label` |
+| Star list | Yes | `<ul>` of five `<li>` items, each with a `VJoyIcon` (`star-fill`, `star-half`, or `star`) |
+| Trailing content | No | `rating-stars-content` slot; default shows `(reviewCount)` when `reviewCount > 0` |
+| Typography | Yes | Wrapper uses `primary-200`; `<strong>` inside content uses bold weight |
+
+### Default values
+
+- `ratingValue` defaults to **`0`** (all empty stars)
+- `reviewCount` defaults to **`0`** (no count text)
+- `size` defaults to **`medium`**
+
+Props and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Fractional ratings
+
+`ratingValue` may include decimals. The component maps each of the five positions to **full**, **half**, or **empty** using fixed thresholds (e.g. `3.25` → three full + one half; `3.1` → three full only; `3.85` → four full). Values outside **0–5** are not clamped in code — **SHOULD** normalize server-side before passing the prop.
+
+There is **no `variant` or `color` prop**. Star appearance is fixed (`quaternary` icons).
+
+---
+
+## Sizes
+
+Pick density to match surrounding typography — do not hardcode icon pixel sizes in product CSS.
+
+| Size | Use when |
+| --- | --- |
+| `small` | Compact rows, dense lists, secondary metadata |
+| `medium` | Default — profile cards, standard list items |
+| `large` | Hero emphasis when the rating is a primary focal point |
+
+Icon size is driven by `--rating-stars-size` inside the component (`11px` / `14px` / `17px`). **Don’t** override `.joy-icon` size on `.joy-rating-stars` in app stylesheets.
+
+---
+
+## States
+
+`VJoyRatingStars` is **presentational** — no hover, focus, disabled, or loading API. “States” here mean display configurations.
+
+| Configuration | What the user sees |
+| --- | --- |
+| Zero rating (`ratingValue: 0`) | Five empty stars |
+| Whole number (e.g. `3`) | Three full + two empty |
+| Fractional (e.g. `4.25`) | Mix of full / half / empty per threshold rules |
+| With `reviewCount` | Stars + `(12)` in default slot content |
+| Custom slot content | Stars + slot output (e.g. `15 missions`) instead of default count |
+| `size` variants | Same rating at `small`, `medium`, or `large` density |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Display semantics
+
+- **MUST** treat this as **read-only** — do not attach click handlers expecting the user to rate.
+- **SHOULD** show `reviewCount` or slot copy when the count adds trust (reviews, missions, endorsements).
+- **SHOULD** keep `ratingValue` on a **0–5** scale consistent with your backend; document if the API uses another scale and convert before render.
+- **MUST NOT** use stars to represent non-rating metrics (completion %, skill level) without design approval.
+
+### Implementation
+
+- **MUST** use only documented props: `ratingValue`, `reviewCount`, `size`.
+- **MUST** use Joy tokens — no custom star colors, gaps, or list styling on `.joy-rating-stars`.
+- **MUST NOT** invent props (`variant`, `color`, `readonly`, `interactive`, …).
+- **SHOULD** pass **`aria-label`** (attribute) with translated copy in localized apps.
+- **SHOULD** use the **`rating-stars-content`** slot when copy needs i18n or markup (not only a raw number in parentheses).
+
+### Composition
+
+- **SHOULD** place inside `VJoyUserCard` default slot (not `user-card-rating-stars`).
+- **SHOULD** align star `size` with adjacent text scale (`small` with compact cards, `medium` by default).
+- **MUST NOT** nest interactive controls inside the `role="img"` wrapper without checking accessibility with design.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `ratingValue={4.25}` from API | Hardcode five `VJoyIcon` stars in a loop |
+| `aria-label="Note : 4,25 sur 5 (12 avis)"` (FR) | Rely on default English `aria-label` in FR UI |
+| `#rating-stars-content` for `15 missions` | English-only string in app CSS `::after` |
+| `reviewCount` for simple numeric count | Duplicate count in slot and prop |
+| Normalize 0–5 before render | Pass `8.2` hoping the component clamps |
+
+---
+
+## Content
+
+Trailing text sits in **`rating-stars-content`** or comes from **`reviewCount`** (rendered as `(n)`).
+
+### Copy formula
+
+**Parenthetical count** (default slot) — digits only, wrapped by the component:
+
+- ✅ `(12)` — from `reviewCount={12}`
+- ✅ `15 missions` — via slot when the unit must be translated
+
+**Accessible name** (`aria-label`) — full sentence for screen readers:
+
+- ✅ `Rating: 4.25 out of 5, 12 reviews`
+- ✅ `Note : 4,25 sur 5, 12 avis` (localized)
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Provide a translated `aria-label` when the UI locale is not English |
+| **MUST** | Include review/mission count in `aria-label` when visible count text is shown |
+| **MUST NOT** | Put the only mention of review count solely in visual text with no `aria-label` update |
+| **SHOULD** | Use `reviewCount` for a bare number; use the slot for labeled counts (`12 reviews`, `15 missions`) |
+| **SHOULD** | Match number formatting to locale (decimal separator, spacing) in `aria-label` and slot |
+| **SHOULD** (FR) | Non-breaking spaces before `:` and inside parentheses where grammar requires |
+
+### Patterns
+
+**Profile / user card** — `medium` stars + `reviewCount` or slot under the name; full `aria-label` on the component.
+
+**Search result row** — `small` stars; omit count if shown elsewhere on the row.
+
+**Review detail header** — `large` optional; slot for rich copy (`Based on 12 verified reviews`).
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Root uses `role="img"` — treated as one graphic, not five separate buttons |
+| Name | `aria-label` from the `aria-label` attribute, or default `Rating: {ratingValue} out of 5` (English, not translated) |
+| Stars | Each icon has `aria-hidden="true"` — decoration only; name comes from the wrapper |
+| Keyboard | No focusable parts by default — correct for read-only display |
+| Interaction | **MUST NOT** imply editability; if the row navigates, put the link on the parent card (`VJoyUserCard` + `link`), not on individual stars |
+| Localization | **MUST** override default `aria-label` in non-English products |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyRatingStars } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Default: fractional rating -->
+  <VJoyRatingStars :rating-value="4.25" />
+
+  <!-- With review count -->
+  <VJoyRatingStars
+    :rating-value="4.25"
+    :review-count="12"
+    aria-label="Rating: 4.25 out of 5, 12 reviews"
+  />
+
+  <!-- Compact density -->
+  <VJoyRatingStars :rating-value="3" size="small" />
+
+  <!-- Translated supplementary text -->
+  <VJoyRatingStars :rating-value="5" aria-label="Note : 5 sur 5, 15 missions">
+    <template #rating-stars-content>
+      15 missions
+    </template>
+  </VJoyRatingStars>
+
+  <!-- Inside VJoyUserCard (default slot) -->
+  <VJoyUserCard full-name="Jane Doe" sub-title="Product designer">
+    <VJoyRatingStars :rating-value="4.8" :review-count="24" />
+  </VJoyUserCard>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyRatingStars` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyUserCard` | Profile row with avatar, title, and optional rating in default slot |
+| `VJoyIcon` | Star primitives used internally (`star`, `star-fill`, `star-half`) |
+| `VJoyText` | Numeric or textual score without the star metaphor |
+| `VJoyBadge` | Categorical labels, not aggregate ratings |
+| `VJoyProgressBar` | Completion or progress, not review scores |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyRatingStars.dsds.json`](./JoyRatingStars.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Show an existing 0–5 rating | `VJoyRatingStars` | Five manual `VJoyIcon` stars |
+| User rates / edits a score | Dedicated input pattern (not in this API) | `VJoyRatingStars` with `@click` |
+| Percent complete | `VJoyProgressBar` | Star row |
+| Tag or status | `VJoyBadge` | `VJoyRatingStars` with fake `ratingValue` |
+| Rating on user card | `VJoyRatingStars` in `VJoyUserCard` default slot | `#user-card-rating-stars` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyRatingStars")` (or read `JoyRatingStars.types.ts`) before generating props.
+2. **MUST** use only documented props: `ratingValue`, `reviewCount`, `size`.
+3. **MUST** pass `aria-label` as a native attribute when the app locale is not English.
+4. **MUST NOT** invent props (`variant`, `color`, `max`, `interactive`, `readonly`, …).
+5. **MUST NOT** use slot name `rating-stars-slot` — Vue slot is **`rating-stars-content`**.
+6. **MUST NOT** override `.joy-rating-stars` / `.joy-icon` colors or sizes in app CSS.
+7. **MUST NOT** attach click handlers to change rating — component is display-only.
+8. **SHOULD** default to `size="medium"` and `ratingValue` on 0–5 from the API.
+9. **SHOULD** use `reviewCount` for `(n)` only; use `#rating-stars-content` for translated labels.
+
+### Valid enums (from `JoyRatingStars.types.ts`)
+
+| Prop | Values |
+| --- | --- |
+| `size` | `small`, `medium`, `large` |
+| `ratingValue` | `number` (0–5 expected) |
+| `reviewCount` | `number` (≥ 0) |
+
+### Checklist
+
+- [ ] Correct component (display-only rating, not input)
+- [ ] Props / enums from MCP only
+- [ ] No invented props / no custom star chrome CSS
+- [ ] Translated `aria-label` when not English
+- [ ] `rating-stars-content` (not legacy `rating-stars-slot`)
+- [ ] `VJoyUserCard` uses default slot, not `user-card-rating-stars`
+- [ ] `ratingValue` normalized to 0–5 before render
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyRatingStars.dsds.json`](./JoyRatingStars.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / fractional logic | `anatomy` |
+| Sizes | `variants` |
+| Display configurations | `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 |