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

package/dist/doc/VJoyTag/guideline.md

@@ -0,0 +1,226 @@
+---
+component: VJoyTag
+status: draft
+language: en
+dsds: JoyTag.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Tag
+
+Use **`VJoyTag`** when you need a compact label — status, category, filter chip, or removable token in a list.
+
+It supports semantic color variants, four sizes, optional remove and drag-handle icons, and selectable or link styling on `primary` / `secondary`. Pass a `value` when tags are managed by **`VJoyTagsList`** or when remove/selection handlers need a stable key.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTag` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyTag docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoytag--docs) |
+| **DSDS (machine)** | [`JoyTag.dsds.json`](./JoyTag.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTag")` |
+
+---
+
+## When to use this component
+
+Use a tag to surface **short, scannable metadata** — skill names, filter chips, workflow status (`pending`, `inactive`), pricing hints, or AI-related labels. Keep copy to a few words; pair with an icon in the default slot when the meaning benefits from a pictogram.
+
+Use **`removable`** when the user can dismiss a tag (for example tokens already added to a profile). Use **`selectable`** + **`selected`** on **`primary`** or **`secondary`** for toggle-style filter chips — listen to `@selected` and update selection in the parent. For several tags with shared list behavior, prefer **`VJoyTagsList`** over hand-rolling spacing and events.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Typing and committing multiple values in one field | `VJoyTagsInput` |
+| Laying out many tags with list selection / removal wiring | `VJoyTagsList` wrapping `VJoyTag` |
+| Numeric notification count on an icon or tab | `VJoyBadge` or `VJoyDot` |
+| Achievement / level recognition (SuperMalter, verified, …) | `VJoyBadgeLevel` |
+| Real navigation via URL | `@click` + your router — `link` is **style only** |
+| Custom chip markup / ad-hoc CSS | Still use `VJoyTag` + Joy tokens |
+
+> **Deprecated:** `strikethrough` — avoid in new work; the prop remains for legacy screens.
+
+> **Not in the Vue API:** legacy Stencil `joy-tag` props `href`, `target`, `rel`, and `clickable`. **`VJoyTag` has no `href`.** Use `link` for appearance and handle navigation in `@click`.
+
+> **`draggable`** only shows a drag-handle icon and `cursor: grab` — it does **not** implement drag-and-drop. Wire your own DnD library if reordering is required.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root `<span>` | Yes | `.joy-tag` — inline-flex chip; auto-generated `id` unless `id` is set |
+| Label | Yes* | `label` prop or default slot content (*slot replaces the built-in label) |
+| Drag handle | No | Leading `VJoyIcon` (`drag`) when `draggable` — visual only |
+| Remove control | No | Trailing `VJoyIcon` (`cross`, `role="button"`) when `removable`; emits `remove` with `{ value }` |
+| Focus ring | Yes* | Token-based outline on `:focus` and when `selected` — suppressed when `disabled` |
+
+### Variants and sizes (no separate sections — pick by meaning)
+
+**Variants** (`TJoyTagVariants`):
+
+| Group | Values | Typical use |
+| --- | --- | --- |
+| Interactive filters | `primary`, `secondary` | Selectable chips; `selected` / hover / active styles apply |
+| Status / emphasis | `important`, `pending`, `inactive`, `pricing`, `special` | Read-only semantic labels |
+| AI surfaces | `ai-primary`, `ai-secondary` | AI-feature context only |
+| Placeholder / add | `empty` | Dashed-border “add” style; supports selectable **styling** but `@selected` fires only for `primary` / `secondary` |
+
+**Sizes** (`TJoyTagSizes`): `xsmall`, `small`, `medium` (default), `large`, `xxlarge`. Tokenized heights and typography are defined for `xsmall`–`large` in component styles; prefer those in product UI unless design specifies otherwise.
+
+### Default values
+
+- `size` defaults to **`medium`**
+- `variant` defaults to **`primary`**
+- `draggable`, `link`, `removable`, `strikethrough`, `disabled` default to **`false`**
+- `value` defaults to **`undefined`** — set it when handlers or `VJoyTagsList` need a stable key
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Events and interaction
+
+| Event | When |
+| --- | --- |
+| `click` | Tag surface clicked and not `disabled` |
+| `selected` | `selectable` is true **and** `variant` is `primary` or `secondary` — payload `{ selected, value }` toggles from current `selected` prop |
+| `remove` | Remove icon clicked — payload `{ value }` |
+
+`link` and `selectable` set `role="button"` and `tabindex="0"` (unless `disabled`). **`link` does not navigate** — add `@click` and call your router (see Storybook `Link` story).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Variant and copy
+
+- **SHOULD** pick `variant` by **semantic meaning** (status, pricing, AI), not decoration alone.
+- **SHOULD** keep tag text **short** (roughly 1–3 words); move longer detail to tooltips or body copy.
+- **MUST** use `ai-primary` / `ai-secondary` only on AI-related surfaces.
+- **MUST NOT** use `selectable` on static variants expecting `@selected` — only `primary` and `secondary` emit it.
+
+### Lists and removal
+
+- **SHOULD** pass a stable **`value`** on every tag in a managed list (alongside `label`).
+- **SHOULD** use **`VJoyTagsList`** when multiple tags share selection or removal logic.
+- **MUST** handle `@remove` in the parent — the tag does not remove itself from an array.
+- **MUST NOT** rely on **`draggable`** for reordering without your own DnD implementation.
+
+### Implementation
+
+- **MUST** use only documented props and enums from MCP or `JoyTag.types.ts`.
+- **MUST** use Joy tokens — no custom `.joy-tag` background, border, or radius overrides in apps.
+- **MUST NOT** invent props (`href`, `color`, `clickable`, …).
+- **SHOULD** use the **default slot** when content includes icons or markup; use **`label`** for plain text only.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `variant="pending"` for in-progress status | Random variant colors for decoration |
+| `removable` + `@remove` + `value` in lists | Expect the chip to update the parent array by itself |
+| `link` + `@click` + `router.push` for navigation | `href` on `VJoyTag` (not in API) |
+| `VJoyTagsInput` for free-form entry | One `VJoyTag` per keystroke field |
+| `VJoyWrapper` / `VJoyTagsList` for spacing | Negative margins between chips |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | `role="button"` when `link` or `selectable`; otherwise plain text in a `<span>` |
+| Keyboard | `tabindex="0"` on interactive tags (`link`, or `selectable` when not `disabled`); **Enter** on the remove icon triggers removal |
+| Focus | Visible outline via Joy form focus tokens — do not remove in product CSS |
+| Name | Expose meaningful text via `label` or slot content; icon-only tags need visible or adjacent text |
+| Disabled | `disabled` blocks click/selection, sets `cursor: not-allowed`, and clears focus outline |
+| Remove control | Separate `role="button"` on the cross icon; use `@click.stop` so it does not toggle selection |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useRouter } from 'vue-router'
+import { VJoyTag, VJoyIcon, VJoyWrapper } from '@maltjoy/core-vue'
+
+const router = useRouter()
+const filters = ref<string[]>(['remote'])
+
+function toggleFilter(value: string, selected: boolean) {
+  if (selected) {
+    filters.value = [...filters.value, value]
+  } else {
+    filters.value = filters.value.filter((v) => v !== value)
+  }
+}
+
+function removeSkill(value: string) {
+  // update parent collection
+}
+</script>
+
+<template>
+  <!-- Status label -->
+  <VJoyTag variant="pending" label="Pending review" />
+
+  <!-- Icon + text via slot -->
+  <VJoyTag variant="special">
+    <VJoyIcon name="heart-fill" />
+    Featured
+  </VJoyTag>
+
+  <!-- Removable token -->
+  <VJoyTag
+    removable
+    label="Vue.js"
+    value="vue"
+    @remove="({ value }) => removeSkill(String(value))"
+  />
+
+  <!-- Selectable filter chip -->
+  <VJoyTag
+    selectable
+    :selected="filters.includes('remote')"
+    value="remote"
+    label="Remote"
+    @selected="({ selected, value }) => toggleFilter(String(value), selected)"
+  />
+
+  <!-- Link styling + manual navigation -->
+  <VJoyTag link label="View profile" @click="router.push('/profile')" />
+
+  <!-- Row of tags -->
+  <VJoyWrapper style="flex-wrap: wrap">
+    <VJoyTag variant="secondary" label="Design" />
+    <VJoyTag variant="secondary" label="Frontend" />
+  </VJoyWrapper>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTag` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyTagsList` | Multiple tags with shared variant, selection, or removal |
+| `VJoyTagsInput` | User types and commits many values into tag chips |
+| `VJoyWrapper` | Flex layout and gap between standalone tags |
+| `VJoyBadge` | Small status pill or numeric counter |
+| `VJoyBadgeLevel` | User achievement / level badges |
+| `VJoyRadio` | Short metadata in `radio-header-right` (display-only) |
+| `VJoyIcon` | Leading icons inside the default slot |

package/dist/doc/VJoyTagsInput/guideline.md

@@ -0,0 +1,387 @@
+---
+component: VJoyTagsInput
+status: draft
+language: en
+dsds: JoyTagsInput.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Tags input
+
+Use **`VJoyTagsInput`** when the user must enter **multiple free-form tokens** — skills, keywords, invitee emails, or other values that appear as removable tags inside one field.
+
+It binds to `v-model` as a `string[]`, commits tags on **Enter**, **comma**, or **blur** (and **space** when `validation="email"`), and can detect duplicates and invalid emails with built-in error messages.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTagsInput` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyTagsInput docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoytagsinput--docs) |
+| **DSDS (machine)** | [`JoyTagsInput.dsds.json`](./JoyTagsInput.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTagsInput")` |
+
+---
+
+## When to use this component
+
+Use a tags input when someone adds **several values of the same kind** in one step — for example listing skills on a profile, tagging a project, or collecting multiple email addresses for invitations.
+
+Each committed value becomes a **`VJoyTag`** chip with a remove control. The inline text field stays available for the next entry. Wrap the field with **`VJoyLabel`** (or the deprecated default slot on legacy screens) and pair validation errors with clear copy via `duplicationError` / `invalidEmailError`.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A single line of text (one value) | `VJoyInput` |
+| Multi-line paragraph | `VJoyTextarea` |
+| Picking from a fixed list (single or multi) | `VJoySelect`, `VJoyCheckbox`, or `VJoySelectableItemGroup` |
+| Read-only display of existing tags | `VJoyTag` / `VJoyTagsList` — not an input |
+| Search with one query string | `VJoyInput` with `icon="search"` and optional `clearable` |
+| Custom token field with ad-hoc chip CSS | Still use `VJoyTagsInput` + Joy tokens |
+
+> **Deprecated:** do not use the default slot for labels on new work — prefer **`VJoyLabel`** with matching `name` / `for`. Storybook’s default-slot label example is legacy.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Wrapper | Yes | Root `.joy-tags-input__wrapper` |
+| Label | No | `VJoyLabel` (recommended) or deprecated default slot |
+| Inner container | Yes | Bordered flex region (`.joy-tags-input__inner`) holding tags + input |
+| Tag chips | No (0+) | One `VJoyTag` per committed value (`removable`, `label` = tag text) |
+| Native `<input>` | Yes | Free-text entry; `data-joy-form-field`; `name` / `id` from `name` prop |
+| Error block | No | `VJoyFormError` with duplicate and/or email messages when validation fails |
+| Focus / invalid chrome | Yes | `--focused` / `--invalid` classes on the inner container — do not override in apps |
+
+### Default values
+
+- `placeholder` defaults to **`"Add your items here"`**
+- `variant` defaults to **`primary`** (passed to each `VJoyTag`)
+- `size` defaults to **`small`** (passed to each `VJoyTag`)
+- `modelValue` defaults to **`[]`**
+- `invalid` defaults to **`false`**
+- `validation` defaults to **`none`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Committing and removing tags
+
+- **Add:** type text, then press **Enter** or **,** — or **blur** the field (pending text is committed on blur). With `validation="email"`, **Space** also commits the current token.
+- **Remove:** click a tag’s remove control, or press **Backspace** when the text input is empty (removes the last tag).
+- **Model:** each successful add/remove emits `update:modelValue` with the full `string[]`. Initialize with `v-model` bound to an array (not `undefined`).
+
+### Built-in validation
+
+| Mode | Behavior |
+| --- | --- |
+| `validation="none"` | Duplicates blocked when `duplicationError` is set; no email format check |
+| `validation="email"` | Email-like format required (see `checkEmailsValidity`); duplicates still detected |
+
+On failure the inner border turns invalid, `validation:error` fires (`DUPLICATED_ENTRY` or `INVALID_EMAIL`), and the matching error string renders when provided. Trimming is applied when comparing duplicates.
+
+---
+
+## Variants
+
+`variant` controls the **chip style** inside the field (same enum as `VJoyTag`). Pick by semantic meaning of the tokens, not decoration.
+
+### `primary` (default)
+
+Use for standard form tags — skills, topics, generic keywords.
+
+### `secondary`
+
+Use when tags should read as lower emphasis than surrounding primary chips (rare inside one input — prefer one variant per field).
+
+### Status / pricing variants (`important`, `inactive`, `pending`, `pricing`, `special`)
+
+Use only when token meaning matches the tag semantics (e.g. status labels). Avoid mixing unrelated semantics in one tags field.
+
+### `empty`
+
+Minimal chip chrome. Use when tags should feel lightweight inside dense UI.
+
+### AI variants (`ai-primary`, `ai-secondary`)
+
+Use only when the field is part of an AI feature surface.
+
+### Not in the API: per-tag variants
+
+`VJoyTagsInput` applies one `variant` to every tag. For heterogeneous tag styles, use standalone `VJoyTag` lists — not this component.
+
+---
+
+## Sizes
+
+`size` is passed to every `VJoyTag` in the field. Heights and chip density come from Joy tag tokens — **do not hardcode chip or input heights** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `small` | Default — compact forms and multi-tag rows |
+| `medium` | Slightly larger chips when the field is a focal form control |
+| `large` / `xxlarge` | Prominent tagging UI (use sparingly) |
+| `xsmall` | Very dense layouts (confirm with design — default is `small`) |
+
+The inline `<input>` uses `min-height: var(--joy-core-spacing-6)` and grows within the wrapping flex row.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Empty or showing tags; neutral border; text input ready |
+| Focused | Inner border uses `--joy-color-state-focus`; user can type or remove via keyboard |
+| Hover | Border uses form hover tokens (pointer devices) |
+| Valid | Tags listed; new tokens commit on Enter / comma / blur (and Space for email mode) |
+| Duplicate error | Invalid border; `duplicationError` message when duplicate detected and prop is set |
+| Invalid email | Invalid border; `invalidEmailError` when `validation="email"` and format fails |
+| Removing tags | Remove icon on each tag; Backspace on empty input drops last tag |
+
+There is no `disabled` or `readonly` prop on `VJoyTagsInput`. If the collection must not be edited, show `VJoyTagsList` / `VJoyTag` instead.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Labels and forms
+
+- **MUST** provide a visible label via `VJoyLabel` (with `for` matching `name`) — not placeholder-only.
+- **MUST** set `name` so the label, input `id`, and form submission stay aligned.
+- **MUST** bind `v-model` to a `string[]` (initialize to `[]` when empty).
+- **SHOULD** wrap related fields in `VJoyWrapper` for consistent spacing.
+
+### Implementation
+
+- **MUST** use only documented prop / enum values from MCP or `JoyTagsInput.types.ts` / `JoyTag.types.ts`.
+- **MUST** style with Joy tokens — no custom `.joy-tags-input` border, padding, or chip overrides.
+- **MUST NOT** invent props (`maxTags`, `separator`, `disabled`, `clearable`, …).
+- **MUST** pass `duplicationError` when duplicate detection should surface copy to the user.
+- **MUST** pass `invalidEmailError` when using `validation="email"`.
+- **SHOULD** listen to `validation:error` if the parent form needs to block submit or scroll to the field.
+
+### Validation and errors
+
+- **MUST** supply explicit error strings — the component does not render a generic invalid state without `duplicationError` / `invalidEmailError`.
+- **MUST NOT** rely on border color alone; error text lives in `VJoyFormError`.
+- **SHOULD** use `validation="email"` only for email collections (invites, notifications), not arbitrary keywords.
+
+### Interaction
+
+- **SHOULD** use placeholder text that hints at the commit gesture (e.g. “Type an email and press Enter”).
+- **SHOULD** keep tag values short; long tokens wrap inside the flex container (see Storybook “Multi line”).
+- **MUST NOT** expect Space to commit tags unless `validation="email"`.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyLabel` + `name` / `for` | Placeholder as the only label |
+| `v-model` on `string[]` | `v-model` on a single string |
+| `validation="email"` + `invalidEmailError` for invite lists | Email mode without error copy |
+| `duplicationError` when duplicates matter | Silent duplicate rejection |
+| One `variant` per field | Mixed chip semantics without design sign-off |
+| Joy form-field / tag tokens | Hardcoded chip heights or borders |
+
+---
+
+## Content
+
+Labels, placeholders, and error messages must tell users **what** to enter and **how** tokens are added.
+
+### Label formula
+
+**Noun phrase** for the collection (not the commit action):
+
+- ✅ Skills  
+- ✅ Invitees  
+- ✅ Project tags  
+
+Use sentence case. Prefer plural when multiple items are expected.
+
+### Placeholder formula
+
+**Hint at entry + commit** — not a repeat of the label:
+
+- ✅ `Add a skill and press Enter` (under label “Skills”)  
+- ✅ `email@company.com` (under label “Invitees” with email validation)  
+
+- ❌ `Skills` as placeholder when the label already says “Skills”
+
+Default placeholder is `Add your items here` — override when context is clearer.
+
+### Error messages
+
+| Prop | When | Example |
+| --- | --- | --- |
+| `duplicationError` | Duplicate token (trimmed match) | `This skill is already listed` |
+| `invalidEmailError` | `validation="email"` and format fails | `Enter a valid email address` |
+
+State what went wrong and how to fix it — ✅ `This email is already added` · ❌ `Error`.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every field has a visible label |
+| **MUST** | Error messages are specific and actionable |
+| **MUST NOT** | Use labels that only make sense after failure |
+| **SHOULD** | Keep individual tag text short (display truncates/wraps in narrow containers) |
+| **SHOULD** | Use email validation copy that matches product terminology (“Invitee”, “Recipient”) |
+| **SHOULD** (FR) | Follow French grammar for labels and error strings when the UI is localized |
+
+### Patterns
+
+**Profile skills** — `validation="none"`, `duplicationError` set, placeholder mentions Enter or comma.
+
+**Email invites** — `validation="email"`, `invalidEmailError` + `duplicationError`, placeholder shows example address.
+
+**Narrow layouts** — Tags wrap to multiple lines; keep labels concise so the field doesn’t feel crowded.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native text `<input>` for entry; tags are `VJoyTag` with removable button controls |
+| Name | From associated `VJoyLabel` / `<label for="…">`; `name` sets input `id` |
+| Value | Controlled list via `v-model` (`string[]`); input holds only the pending token |
+| Keyboard | Enter / comma commit; Backspace on empty input removes last tag; Space commits only in email mode |
+| Focus | Visible focus border on inner container; removing a tag refocuses the input |
+| Invalid | Error border on inner container; messages in `VJoyFormError` below the field |
+| Remove | Each tag exposes a remove control (`VJoyTag` removable) — must be keyboard-activatable via Joy tag implementation |
+| Pending input | Standard text editing in the inline input; Tab moves focus out (blur may commit) |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyTagsInput, VJoyLabel, VJoyWrapper } from '@maltjoy/core-vue'
+
+const skills = ref<string[]>(['Vue', 'TypeScript'])
+const invitees = ref<string[]>([])
+</script>
+
+<template>
+  <!-- Skills with duplicate detection -->
+  <VJoyWrapper direction="column" row-gap="4">
+    <VJoyLabel for="skills">Skills</VJoyLabel>
+    <VJoyTagsInput
+      v-model="skills"
+      name="skills"
+      placeholder="Add a skill and press Enter"
+      duplication-error="This skill is already listed"
+    />
+  </VJoyWrapper>
+
+  <!-- Email invites -->
+  <VJoyLabel for="invitees">Invitees</VJoyLabel>
+  <VJoyTagsInput
+    v-model="invitees"
+    name="invitees"
+    validation="email"
+    invalid-email-error="Enter a valid email address"
+    duplication-error="This email is already added"
+    placeholder="name@company.com"
+    @validation:error="(type) => console.warn(type)"
+  />
+
+  <!-- Custom tag slot -->
+  <VJoyTagsInput v-model="skills" name="skills-custom">
+    <template #tag="{ name }">
+      <strong>{{ name }}</strong>
+    </template>
+  </VJoyTagsInput>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTagsInput` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyLabel` | Accessible label (preferred over default slot) |
+| `VJoyTag` | Single tag or custom tag layouts outside this input |
+| `VJoyTagsList` | Read-only or pre-styled lists of tags |
+| `VJoyFormError` | Used internally; use standalone errors for group-level messages if needed |
+| `VJoyWrapper` | Form layout and spacing |
+| `VJoyInput` | Single-value text fields |
+| `VJoySelect` | Choosing from a predefined set |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyTagsInput.dsds.json`](./JoyTagsInput.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Multiple free-form tokens in one field | `VJoyTagsInput` | Repeated `VJoyInput` or manual chip divs |
+| Multiple email addresses | `VJoyTagsInput` + `validation="email"` | `VJoyInput` with comma-separated string |
+| Single text value | `VJoyInput` | `VJoyTagsInput` with one-item array hack |
+| Display-only tags | `VJoyTagsList` / `VJoyTag` | `VJoyTagsInput` with fake `modelValue` |
+| Pick from fixed options | `VJoySelect` / checkboxes | Tags input with suggested datalist |
+| Skills / keywords with duplicates blocked | `VJoyTagsInput` + `duplicationError` | Custom duplicate logic on raw input |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyTagsInput")` (or read types) before generating props.  
+2. **MUST** bind `v-model` to `string[]` (default `[]`).  
+3. **MUST** set `name` and associate `VJoyLabel` with `for` / `name`.  
+4. **MUST** pass `invalidEmailError` when `validation="email"`.  
+5. **MUST** pass `duplicationError` when duplicate feedback is required.  
+6. **MUST NOT** invent props (`disabled`, `maxTags`, `separator`, `clearable`, …).  
+7. **MUST NOT** override `.joy-tags-input__inner` border, padding, or tag chip styles.  
+8. **MUST NOT** use the default slot for new labels — use `VJoyLabel`.  
+9. **SHOULD** use `variant` / `size` from `TJoyTagVariants` / `TJoyTagSizes` only.  
+10. **SHOULD** handle `validation:error` when parent submit must wait for a valid list.
+
+### Checklist
+
+- [ ] Correct component (`VJoyTagsInput` or named alternative)
+- [ ] Props / enums from MCP or types only
+- [ ] `v-model` as `string[]` + `name` present
+- [ ] Visible `VJoyLabel` (not placeholder-only)
+- [ ] `duplicationError` / `invalidEmailError` set when validation applies
+- [ ] `validation="email"` only for email collections
+- [ ] No invented props / no custom tags-input chrome CSS
+- [ ] Read-only tag display → `VJoyTagsList` / `VJoyTag`, not this input
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyTagsInput.dsds.json`](./JoyTagsInput.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants / 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-core-spacing-*`, `--joy-form-border-width`, tag size tokens) |