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

package/dist/doc/VJoyScreenLoader/guideline.md

@@ -0,0 +1,172 @@
+---
+component: VJoyScreenLoader
+status: draft
+language: en
+dsds: JoyScreenLoader.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Screen loader
+
+Use **`VJoyScreenLoader`** when a page, panel, or section is loading and you need to block interaction while showing a centered spinner and optional status message.
+
+Set `overlay` to cover the parent container absolutely (typical inside `VJoyPanel` or `VJoyTemplate`). Choose `color` to match the surface behind the loader — `light` on pale backgrounds, `dark` on imagery or dark overlays.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyScreenLoader` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyScreenLoader docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-loader-vjoyscreenloader--docs) |
+| **DSDS (machine)** | [`JoyScreenLoader.dsds.json`](./JoyScreenLoader.dsds.json) |
+| **Live API** | `joy_list_components` (Loader) · types in `VJoyScreenLoader.types.ts` |
+
+---
+
+## When to use this component
+
+Use a screen loader when content is not ready yet and the user should not interact with the underlying UI — for example fetching panel data, switching template routes, or waiting for a large section to render.
+
+Mount it over a **positioned parent** (`position: relative` on the container) with `overlay` so it fills that region. Add a short message in the `content` slot when the wait may exceed a second or two.
+
+Prefer the built-in `loading` prop on **`VJoyPanel`** and **`VJoyTemplate`** when the loader belongs to those layouts — they wire `VJoyScreenLoader` with `overlay`, blur the content behind, and expose `panel-loader-content` / `template-loader-content` slots.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Inline loading on a single button or form control | `VJoyButton` `loading` prop or `VJoySpinner` |
+| Skeleton placeholder while layout is known | `VJoyBlockSkeleton`, `VJoyFormFieldSkeleton` |
+| Full-page app bootstrap before Vue mounts | App-level splash / router guard pattern — not this component alone |
+| Progress with a known completion ratio | `VJoyProgressBar` |
+| Custom full-screen overlay with ad-hoc CSS | Still use `VJoyScreenLoader` + Joy tokens — don’t reinvent loader chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | Flexbox centering wrapper (`joy-screen-loader`, `joy-screen-loader--{color}`) |
+| Overlay layer | No | `joy-screen-loader--overlay` when `overlay` is true — `position: absolute`, fills parent |
+| Spinner area | Yes | Default `VJoySpinner` (`teal` on `light`, `white` on `dark`); override via `spinner` slot |
+| Content area | No | `content` slot — centered text or markup below the spinner |
+| Scrim background | Yes | Semi-transparent `light` (`rgba(255, 255, 255, 0.8)`) or `dark` (`var(--joy-color-overlay)`) |
+
+### Default values
+
+- `color` defaults to **`light`**
+- `overlay` defaults to **`false`**
+
+Props and slots: use Storybook, `VJoyScreenLoader.vue`, or `VJoyScreenLoader.types.ts` — this page focuses on **when** and **how**, not a full API dump.
+
+### Color modes
+
+| `color` | Background | Default spinner |
+| --- | --- | --- |
+| `light` | White scrim (80% opacity) | `VJoySpinner` `teal` |
+| `dark` | `--joy-color-overlay` | `VJoySpinner` `white` |
+
+Allowed values: `TJoyScreenLoaderColors` — **`light`** \| **`dark`** only.
+
+### Layout tokens
+
+Padding uses `--screen-loader-padding` (default `var(--joy-core-spacing-4)`). Parent containers may set `--screen-loader-min-height` when the loader should fill a minimum area without `overlay`.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show
+
+- **SHOULD** use a screen loader when the entire panel or template content is unavailable — not for partial inline updates.
+- **SHOULD** pair `overlay` with a parent that has `position: relative` so coverage is predictable.
+- **SHOULD** add a short `content` message when loading may take more than ~1 second.
+- **MUST NOT** leave the loader visible after data has loaded — tie visibility to a boolean loading flag.
+
+### Implementation
+
+- **MUST** use only `color` values from `TJoyScreenLoaderColors` (`light`, `dark`).
+- **MUST** use Joy tokens — no custom `.joy-screen-loader` background or z-index overrides in product CSS.
+- **MUST NOT** invent props (`size`, `variant`, `message`, …).
+- **SHOULD** prefer `VJoyPanel` / `VJoyTemplate` `loading` props instead of duplicating loader wiring.
+- **SHOULD** keep the default `VJoySpinner` unless design requires a custom animation via the `spinner` slot.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `overlay` inside a positioned panel or template | Loader without a sized/positioned parent |
+| `color="dark"` on busy or photographic backgrounds | `light` scrim on dark imagery (poor contrast) |
+| Short status copy in `content` | Long paragraphs or error details in the loader |
+| `VJoyPanel` `loading` for panel fetches | Manual duplicate loader + blur logic |
+| Hide loader when `loading` becomes false | Indefinite spinner with no feedback |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | No dedicated ARIA role on the component — treat as a **status** region in the parent when loading blocks the UI |
+| Name | If `content` slot text is shown, it should describe what is loading (`Loading projects…`) — not generic `Please wait` alone |
+| Keyboard | Underlying controls should be **unreachable** while overlay is active (overlay covers the parent); ensure focus does not land on blurred content behind |
+| Focus | When loading ends, return focus to a sensible control in the newly loaded content if focus was trapped in the loading region |
+| Motion | Spinner uses CSS animation via `VJoySpinner`; respect `prefers-reduced-motion` at app level where implemented |
+| Timing | Avoid flashing the loader for sub-300ms requests — debounce or minimum display time at app level if flicker is noticeable |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyScreenLoader, VJoyPanel } from '@maltjoy/core-vue'
+
+const loading = ref(true)
+</script>
+
+<template>
+  <!-- Standalone section loader -->
+  <div style="position: relative; min-height: 200px">
+    <VJoyScreenLoader v-if="loading" overlay>
+      <template #content>Loading projects…</template>
+    </VJoyScreenLoader>
+    <!-- section content -->
+  </div>
+
+  <!-- Panel-integrated (preferred) -->
+  <VJoyPanel :loading="loading" loading-color="light">
+    <template #panel-body>…</template>
+    <template #panel-loader-content>Fetching latest data…</template>
+  </VJoyPanel>
+
+  <!-- Dark overlay on imagery -->
+  <VJoyScreenLoader color="dark" overlay>
+    <template #content>Preparing your workspace…</template>
+  </VJoyScreenLoader>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyScreenLoader` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoySpinner` | Small inline loading indicator (buttons, fields) — default inside this loader |
+| `VJoyPanel` | Card/section layout with built-in `loading` + `panel-loader-content` |
+| `VJoyTemplate` | Full page layout with built-in `loading` + `template-loader-content` |
+| `VJoyBlockSkeleton` | Placeholder blocks when structure is known before data arrives |
+| `VJoyFormFieldSkeleton` | Skeleton rows for form-heavy loading states |
+| `VJoyProgressBar` | Determinate progress (upload %, step completion) |

package/dist/doc/VJoySelect/guideline.md

@@ -0,0 +1,396 @@
+---
+component: VJoySelect
+status: draft
+language: en
+dsds: JoySelect.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Select
+
+Use **`VJoySelect`** when the user must pick **one** option from a predefined list in a form — country, role, status, or any bounded enumeration.
+
+It wraps a native `<select>` with Joy form-field styling, optional integrated labeling, size variants, and validation states. Options are native `<option>` elements in the default slot (including `v-for`). Bind the value with `v-model`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoySelect` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoySelect docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyselect--docs) |
+| **DSDS (machine)** | [`JoySelect.dsds.json`](./JoySelect.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoySelect")` |
+
+---
+
+## When to use this component
+
+Use a select when the user chooses a single value from a list that is known upfront and does not need rich per-option layout — for example picking a country, currency, contract type, or workflow status.
+
+Selects work well with **roughly 4–20** options (fewer is fine). They save vertical space compared to radio groups and use familiar native dropdown behavior on every platform.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Every option should stay visible (2–7 parallel choices) | `VJoyRadio` inside `VJoyRadioGroup` |
+| Multiple selections from a list | `VJoyCheckbox` inside `VJoyCheckboxGroup` |
+| Card-style selectable tiles | `VJoySelectableItemGroup` |
+| Contextual menu or overflow actions from a custom trigger | `VJoyDropdown` |
+| Free-text entry or search-as-you-type | `VJoyInput` (or a combobox pattern if the product provides one) |
+| Custom-styled native `<select>` | Still use `VJoySelect` + Joy tokens — don’t reinvent chrome |
+
+> **Deprecated:** the `select-label` slot is deprecated. Prefer the `label` prop for simple text, or place `VJoyLabel` **above** the select with matching `for` / `id` (see [With external label](#with-external-label)).
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Label | No (but **SHOULD** in forms) | Built-in `VJoyLabel` when `label` is set, or external `VJoyLabel` / `select-label` slot |
+| Select wrapper | Yes | Styled container (`.joy-select__wrapper`) with size and state classes |
+| Native `<select>` | Yes | Focusable control with `data-joy-form-field`; inherits undeclared native attributes |
+| Options (`default` slot) | Yes | Native `<option>` elements (supports `v-for`) |
+| Chevron icon | Yes | Decorative `chevron-down` — pointer events disabled |
+| Focus ring | Yes | Focus styling on the native select — don’t remove it in product CSS |
+
+### Default values
+
+- `size` defaults to **`medium`**
+- `modelValue` defaults to **`""`**
+- `disabled` defaults to **`false`**
+- `invalid` defaults to **`false`**
+- `required` defaults to **`false`**
+- `requiredMark` defaults to **`false`**
+- `labelSize` — when omitted, **`medium`** select uses label size `medium`; **`small`** / **`xsmall`** selects use label size `small`
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Label binding
+
+- **Simple:** set `label` — the component renders `VJoyLabel` linked via `for` to `id` or `name`.
+- **Flexible:** omit `label` and render `VJoyLabel` above the select; **`for` on the label MUST match `id` or `name` on the select**.
+- **No visible label:** set `ariaLabel` only when `label` is undefined (e.g. compact toolbar filters).
+
+### Options and model
+
+- **MUST** provide options as native `<option>` tags in the default slot.
+- **SHOULD** include a disabled placeholder option (`value=""`) when no value is pre-selected.
+- `v-model` binds `modelValue`; changes emit `update:modelValue` with a **string** (native select value).
+- `v-for` on options is supported — the component flattens option VNodes from the slot.
+
+---
+
+## Variants
+
+`VJoySelect` has **no visual emphasis variants** (no primary/secondary). Appearance is controlled by **size** and **state** (`disabled`, `invalid`, focus) only.
+
+Choose a different component if you need card layouts, custom option rows, or a non-native overlay list.
+
+---
+
+## Sizes
+
+Choose size for **density**, not decoration. Heights come from `--joy-form-field-height-*` inside the component — **don’t hardcode pixel heights** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `medium` | Default product forms and settings |
+| `small` | Dense forms, side panels, or secondary filters |
+| `xsmall` | Compact toolbars, table inline filters, very tight layouts |
+
+Typography scales with size via Joy font tokens (`--joy-font-size-primary-*`). The chevron uses a smaller icon token on `xsmall`.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Enabled; shows current selection or placeholder |
+| Hover | Border accent on pointer devices (when not disabled) |
+| Focus | Border and text use focus color; `.joy-select--focusing` on wrapper |
+| Disabled | Muted field; `not-allowed` cursor; not submittable — **explain why** nearby when the reason isn’t obvious |
+| Invalid | Error border and chevron color; `aria-invalid="true"` — pair with `VJoyFormError` or helper text |
+| Required | Native `required` on the select; optional asterisk via `required` + `requiredMark` on the label |
+
+When validation fails, set `invalid` 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** use `VJoySelect` when there are **roughly 4+** options or vertical space is limited.
+- **SHOULD** pre-select a sensible default when one option is clearly recommended (omit the placeholder).
+- **SHOULD** keep option labels **parallel** (same grammatical structure and similar length).
+- **MUST NOT** use a select for yes/no when two radios would be clearer — unless space is critically tight.
+- **MUST NOT** use a select for actions (Save, Delete) — use `VJoyButton` or `VJoyDropdown`.
+
+### Implementation
+
+- **MUST** use only `size` values from MCP or `JoySelect.types.ts` (`xsmall`, `small`, `medium`).
+- **MUST** set `id` or `name` on every select in a form (unique per field).
+- **MUST** style with Joy tokens — no custom `.joy-select` chrome overrides.
+- **MUST NOT** invent props (`variant`, `color`, `placeholder`, …).
+- **MUST NOT** replace the native `<select>` with a custom div list for standard form fields.
+- Native attributes not declared as Vue props (e.g. `autocomplete`, `form`) are forwarded to the underlying `<select>`.
+
+### Labeling
+
+- **MUST** provide an accessible name: `label` prop, external `VJoyLabel` with correct `for`, or `ariaLabel` when no visible label.
+- **MUST** match `VJoyLabel` `for` to the select’s `id` (or `name` when `id` is omitted).
+- **SHOULD** use `optionalLabel` for optional fields instead of spelling “(optional)” in the main label.
+- **SHOULD** use `required` + `requiredMark` for required fields in line with other Joy form fields.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Native `<option>` in the default slot | Custom divs pretending to be options |
+| Disabled placeholder for “no selection yet” | First real option selected by default with no hint |
+| `VJoyFormError` below invalid selects | Error color with no message |
+| `VJoyLabel` + `for` / `id` pairing | Mismatched or missing label association |
+| `size` + Joy tokens | Hardcoded `32` / `40` / `48`px heights |
+| `VJoyRadioGroup` for 3 visible choices | Select hiding 3 obvious options |
+
+---
+
+## Content
+
+Select copy should make the field purpose obvious and keep options scannable in a native dropdown.
+
+### Label formula
+
+**Noun phrase** naming what is being chosen (not the action):
+
+- ✅ Country  
+- ✅ Payment method  
+- ✅ Contract status  
+
+Avoid imperative labels on the field itself — ✅ `Billing country` · ❌ `Select your country`.
+
+### Placeholder option
+
+Use a **disabled** first option with an empty `value` when nothing is selected yet:
+
+- ✅ `Select a value`  
+- ✅ `Choose an option`  
+- ❌ `---` or blank with no instruction  
+
+Keep placeholder text short and neutral; localize it.
+
+### Option labels
+
+- **MUST** label each `<option>` with the human-readable choice (`France`, `Pending review`).
+- **MUST** use stable programmatic `value` attributes (codes, IDs) distinct from display text when needed.
+- **SHOULD** use parallel phrasing across options (all countries, all statuses, all “Noun” labels).
+- **MUST NOT** embed instructions or marketing copy inside option text — put that in helper text below the field.
+- **SHOULD** sort options in a predictable order (alphabetical, chronological, or product-defined priority).
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Field label ≤ ~40 characters; move long guidance to helper text or `VJoyFormError` |
+| **MUST** | Sentence case for labels and options |
+| **MUST** | `optionalLabel` for optional fields (e.g. `Optional`) — not mixed into the primary label |
+| **MUST NOT** | Duplicate the label text as the placeholder (`Country` + placeholder `Country`) |
+| **MUST NOT** | Use “Select …” as the field label — name the **thing** (`Country`, not `Select country`) |
+| **SHOULD** | Option text ≤ ~60 characters; abbreviate consistently if truncation is unavoidable on mobile |
+| **SHOULD** | Group long lists logically (prefer separate fields or product-side optgroups only if native `<optgroup>` is added to the slot) |
+| **SHOULD** (FR) | Use articles when grammar requires them in labels and options |
+
+### Patterns
+
+**Required field** — `label` + `required` + `requiredMark`; validation message via `VJoyFormError`: ✅ `Country` + `Select a country to continue`.
+
+**Optional filter** — `optionalLabel="Optional"` on a filter select in a dense toolbar; consider `size="xsmall"` and `ariaLabel` if the layout has no visible label.
+
+**Pre-selected default** — omit the placeholder option when a valid default exists (e.g. user’s current locale).
+
+**Invalid state** — `invalid` on the select + error list: ✅ `Payment method` + `Choose a payment method before continuing`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<select>` — never a clickable `<div>` for standard form selection |
+| Name | From associated `VJoyLabel` (`label` prop or external label with `for`/`id`), or `aria-label` when no visible label |
+| Keyboard | **Tab** to focus; **Space** / **Arrow keys** open and move within the list (platform-native) |
+| Focus | Visible focus styling on the select; wrapper gets `.joy-select--focusing` — don’t remove focus rings in product CSS |
+| Disabled | `disabled` on the select; don’t rely on color alone — explain when needed |
+| Invalid | `aria-invalid="true"` when `invalid`; pair with visible error text (`VJoyFormError`) |
+| Required | Native `required` when the field is mandatory; required mark on label is visual supplement |
+| Chevron | Decorative; meaning comes from the labeled select |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoySelect, VJoyLabel, VJoyFormError } from '@maltjoy/core-vue'
+
+const country = ref('')
+const invalid = ref(false)
+</script>
+
+<template>
+  <!-- Happy path — integrated label -->
+  <VJoySelect
+    v-model="country"
+    label="Country"
+    name="country"
+    required
+    required-mark
+  >
+    <option disabled value="">Select a value</option>
+    <option value="fr">France</option>
+    <option value="de">Germany</option>
+    <option value="es">Spain</option>
+  </VJoySelect>
+
+  <!-- Invalid + error message -->
+  <VJoySelect
+    v-model="country"
+    label="Country"
+    name="country"
+    :invalid="invalid && !country"
+  >
+    <option disabled value="">Select a value</option>
+    <option value="fr">France</option>
+    <option value="de">Germany</option>
+  </VJoySelect>
+  <VJoyFormError
+    v-if="invalid && !country"
+    :errors="['Select a country to continue']"
+  />
+
+  <!-- Dense size -->
+  <VJoySelect v-model="country" label="Status" name="status" size="small">
+    <option disabled value="">Choose an option</option>
+    <option value="active">Active</option>
+    <option value="paused">Paused</option>
+  </VJoySelect>
+
+  <!-- Options from data -->
+  <VJoySelect v-model="country" label="Country" name="country">
+    <option disabled value="">Select a value</option>
+    <option v-for="c in ['France', 'Germany', 'Spain']" :key="c" :value="c">
+      {{ c }}
+    </option>
+  </VJoySelect>
+</template>
+```
+
+### With external label
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoySelect, VJoyLabel } from '@maltjoy/core-vue'
+
+const value = ref('')
+</script>
+
+<template>
+  <VJoyLabel for="custom-label">Payment method</VJoyLabel>
+
+  <VJoySelect id="custom-label" v-model="value" name="custom-label">
+    <option disabled value="">Select a value</option>
+    <option value="card">Credit card</option>
+    <option value="transfer">Bank transfer</option>
+  </VJoySelect>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoySelect` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyLabel` | External labels, legends, or richer label content than the `label` string prop |
+| `VJoyFormError` | Validation messages below the select |
+| `VJoyFormGroup` | Stacking label + select + error with consistent spacing |
+| `VJoyRadioGroup` / `VJoyRadio` | Few mutually exclusive options that should stay visible |
+| `VJoyCheckboxGroup` | Multiple selections |
+| `VJoyDropdown` | Contextual menus from a custom trigger, not a labeled form field |
+| `VJoySelectableItemGroup` | Card-style single or multi selection |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoySelect.dsds.json`](./JoySelect.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Single choice from a predefined form list | `VJoySelect` + native `<option>` children | `VJoyDropdown` as a faux form select |
+| 2–7 visible mutually exclusive options | `VJoyRadio` inside `VJoyRadioGroup` | `VJoySelect` hiding obvious choices |
+| Multiple selections | `VJoyCheckboxGroup` | `VJoySelect` with `multiple` (not supported) |
+| Overflow / action menu from a button | `VJoyDropdown` | `VJoySelect` |
+| Rich card pickers | `VJoySelectableItemGroup` | Custom styled `<select>` |
+| No visible label (toolbar filter) | `VJoySelect` with `ariaLabel` | Missing accessible name |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoySelect")` and `joy_get_component_types("VJoySelect")` (or read types) before generating props.  
+2. **MUST** render options as native `<option>` elements in the default slot.  
+3. **MUST** set `name` (and `id` when using an external `VJoyLabel`) on every form field instance.  
+4. **MUST** bind value with `v-model` / `modelValue` + `@update:modelValue`.  
+5. **MUST NOT** invent props (`variant`, `placeholder`, `options` array prop, …).  
+6. **MUST NOT** override `.joy-select` border, padding, height, or radius in product CSS.  
+7. **MUST NOT** use the deprecated `select-label` slot in new code — use `label` or external `VJoyLabel`.  
+8. **SHOULD** include a disabled empty-value placeholder option when no default is selected.  
+9. **SHOULD** set `invalid` and render `VJoyFormError` when validation fails.  
+10. **SHOULD** use `size` from `TJoySelectSizes` only: `xsmall`, `small`, `medium`.
+
+### Checklist
+
+- [ ] Correct component (`VJoySelect` or named alternative)
+- [ ] `size` from MCP enums only (`xsmall` | `small` | `medium`)
+- [ ] Native `<option>` children in default slot (not invented `options` prop)
+- [ ] `name` / `id` set; label associated (`label` prop, `VJoyLabel` `for`, or `ariaLabel`)
+- [ ] No invented props / no custom select chrome CSS
+- [ ] Placeholder option when nothing pre-selected
+- [ ] `invalid` + visible error text when validation fails
+- [ ] Parallel, concise option labels; stable `value` attributes
+- [ ] Not using deprecated `select-label` slot
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoySelect.dsds.json`](./JoySelect.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants (none) | — |
+| Sizes | `variants` / `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 |