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

package/dist/doc/VJoyTooltip/guideline.md

@@ -0,0 +1,322 @@
+---
+component: VJoyTooltip
+status: draft
+language: en
+dsds: JoyTooltip.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Tooltip
+
+Use **`VJoyTooltip`** when you need brief, contextual help on hover or click — for example naming an icon-only control, explaining why something is disabled, or clarifying a field label.
+
+The tooltip wraps a trigger (default slot), teleports its panel to `body`, positions itself with Floating UI (auto-flip when space is tight), and exposes `role="tooltip"` with `aria-describedby` on the trigger.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTooltip` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Tooltip](https://zeroheight.com/6bf479565/p/137c09-tooltip) |
+| **Storybook** | [VJoyTooltip docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoytooltip--docs) |
+| **DSDS (machine)** | [`JoyTooltip.dsds.json`](./JoyTooltip.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTooltip")` |
+
+---
+
+## When to use this component
+
+Use a tooltip to reveal **short, supplementary** information tied to a single trigger — without pulling the user out of their current task. Typical jobs: label an icon button, explain a disabled control, or add optional detail to a form label (`VJoyLabel` uses this pattern).
+
+Default interaction is **hover** (`event="mouseenter"`). Switch to **click** when hover is unreliable (touch-first surfaces) or when the tooltip must stay open while the user reads or interacts with its content.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Information the user must read or act on | `VJoyDialog`, `VJoyDrawer`, or inline helper text |
+| A list of actions or navigation | `VJoyMenu`, `VJoyDropdown` |
+| Persistent page guidance or onboarding | Product tour / coachmark patterns (see Information helper guidelines) |
+| Toast-style feedback after an action | `pushVJoySnackbar` |
+| A custom floating panel with ad-hoc CSS | Still use `VJoyTooltip` + Joy tokens — don’t reinvent overlay chrome |
+
+> **Deprecated:** `enableClickInContent` — behavior is already the default (`true`) and the prop will be removed. Omit it in new code unless you explicitly need the legacy `false` behavior.
+
+> **Removed from API:** `variant` (`primary` / `secondary`) existed on the legacy Stencil tooltip. **`VJoyTooltip` has no `variant` prop.** Do not emit `variant="primary"` or `variant="secondary"`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Click-outside wrapper | Yes | `OnClickOutside` root — dismisses click-triggered tooltips |
+| Trigger wrapper | Yes | Wraps the default slot; holds pointer/keyboard listeners and `aria-describedby` |
+| Trigger (default slot) | Yes | The control or element the user hovers/clicks (e.g. `VJoyIconButton`) |
+| Tooltip panel | Yes* | Teleported to `body`; `role="tooltip"`; shown when visible |
+| Arrow | Yes | Positioned by Floating UI middleware |
+| Content inner | Yes* | `tooltip-content` slot or `text` prop output |
+
+\*The panel is not rendered unless `text` or the `tooltip-content` slot is provided.
+
+### Default values
+
+- `placement` defaults to **`bottom`**
+- `event` defaults to **`mouseenter`**
+- `delay` defaults to **`100`** (ms, show/hide)
+- `tooltipWidth` defaults to **`250`** (px `max-width` on the panel)
+- `enableClickInContent` defaults to **`true`**
+- `show` defaults to **`false`** (set `true` mainly in Storybook / visual tests)
+
+Props, slots, and exposed members: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Positioning and triggers
+
+- **Placement** — any [Floating UI placement](https://floating-ui.com/docs/tutorial#placements) (`top`, `bottom`, `left`, `right`, and `*-start` / `*-end`). The component **flips** to `bottom`, `top`, `left`, or `right` when there isn’t enough room.
+- **Hover (default)** — show on `mouseenter`, hide on `mouseleave`. Clicks alone do not open the tooltip.
+- **Click** — set `event="click"`. Opens on trigger click; closes on outside click or **Tab** away from the trigger. With `enableClickInContent`, clicks inside the tooltip content do not dismiss it.
+
+---
+
+## Variants
+
+`VJoyTooltip` has **no visual variant prop**. Styling is fixed: neutral background (`--joy-color-neutral-10`), body text (`--joy-color-neutral-60`), `primary-300` typography, `--joy-core-radius-3`, and `--joy-core-elevation-3`.
+
+### Not in the API: `primary` / `secondary` (legacy Stencil)
+
+ZeroHeight and the legacy `@maltjoy/core` tooltip documented `variant="primary"` (information blue) and `variant="secondary"` (neutral). These values are **not** on `VJoyTooltip`. Do not generate them. If product needs an information-colored tooltip, confirm with design before adding a new API value.
+
+---
+
+## Sizes
+
+Single visual size — no `size` prop. Typography and padding come from Joy tokens inside the component (`primary-300`, `--joy-core-spacing-4`).
+
+| Control | Use when |
+| --- | --- |
+| Default width | Short labels and icon explanations |
+| `tooltipWidth` | Longer copy that should wrap within a narrower or wider column (value is `max-width` in px) |
+
+**Don’t** hardcode font sizes or padding on `.joy-tooltip__content` in product CSS.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Hidden (default) | Only the trigger is visible |
+| Delayed show | After `delay` ms, panel fades in (hover or click path) |
+| Visible | Tooltip panel + arrow; describes the trigger for assistive tech |
+| Hiding | Opacity animation when dismissed (`mouseleave`, outside click, or Tab) |
+| Click + open | With `event="click"`, panel stays until outside click or Tab; content may be clickable when `enableClickInContent` is true |
+| `show` (dev) | Forces visible on mount — for Storybook/tests, not production UX |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show a tooltip
+
+- **SHOULD** add a tooltip on **icon-only** controls when the icon alone is not universally understood (see Button content guidelines).
+- **SHOULD** explain **why** a nearby control is disabled (forms pattern: disabled submit + tooltip).
+- **SHOULD** keep tooltips **supplementary** — the interface must remain usable if the tooltip never appears.
+- **MUST NOT** put essential instructions, links, or decisions only inside a tooltip.
+
+### Implementation
+
+- **MUST** provide content via `text` **or** the `tooltip-content` slot — omitting both means no tooltip is rendered.
+- **MUST** use only documented props and enums from MCP / component types.
+- **MUST** use Joy tokens — no custom `.joy-tooltip__content` chrome (background, shadow, radius).
+- **MUST NOT** invent props (`variant`, `size`, `color`, …).
+- **SHOULD** prefer the **`tooltip-content` slot** over `text` when content includes markup (`<strong>`, `<small>`). Use `text` only for plain, trusted strings (XSS risk if fed user input).
+- **SHOULD** set a stable **`id`** when multiple tooltips on one view need unambiguous `aria-describedby` targeting.
+- **SHOULD** use `event="click"` on touch-heavy layouts or when users must interact with tooltip content.
+
+### Interaction
+
+- **MUST NOT** cover the trigger or adjacent primary actions with the tooltip panel.
+- **SHOULD** use default hover on desktop pointer UIs; evaluate click for mobile/tablet.
+- **SHOULD** keep `delay` at default unless UX research shows a different timing need.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Wrap `VJoyIconButton` + short label in tooltip | Duplicate the button’s visible label in the tooltip |
+| `tooltip-content` slot for formatted copy | `text` with HTML strings from the API |
+| `event="click"` when content is tappable | Hover-only tooltips with links or buttons inside |
+| `tooltipWidth` for readable line length | Fixed `width` overrides in app CSS |
+| Dialog/drawer for required reading | Long paragraphs in a tooltip |
+
+---
+
+## Content
+
+Tooltips carry **short, contextual** copy. They enhance the UI; they don’t replace labels, helper text, or dialog body content.
+
+### Copy formula
+
+**Noun phrase** or **short imperative** that names the control or states the constraint:
+
+- ✅ Put to trash  
+- ✅ Notifications  
+- ✅ Complete all required fields to submit  
+- ✅ Annual billing only  
+
+Avoid full sentences unless explaining a disabled state.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | One idea per tooltip — no paragraphs |
+| **MUST** | Match the trigger’s language (icon `label`, button text, field name) |
+| **MUST NOT** | Repeat visible text already on the trigger |
+| **MUST NOT** | Put links, CTAs, or decisions only in a tooltip |
+| **MUST NOT** | Use tooltips for error validation (use inline field errors) |
+| **SHOULD** | ≤ ~60 characters; wrap naturally within `tooltipWidth` |
+| **SHOULD** | Sentence case; no trailing period for labels |
+| **SHOULD** | Name the **reason** when explaining disabled controls |
+| **SHOULD** | Use `<strong>` sparingly for one emphasized word (slot content) |
+| **SHOULD** (FR) | Non-breaking spaces before `;`, `?`, `!`, and `:` |
+
+### Patterns
+
+**Icon buttons** — Tooltip text should mirror or shorten the control’s accessible name (`label` on `VJoyIconButton`). If the icon is universal (e.g. trash → delete), tooltip still helps but label remains mandatory.
+
+**Disabled submit** — Pair with the disabled control: e.g. “Complete all required fields to submit”. Same message as inline form guidance is acceptable.
+
+**Form labels** — `VJoyLabel` exposes a `label-tooltip` slot pattern; keep copy factual (format, eligibility), not marketing.
+
+**Information helper** — For the 16px `(?)` pattern, tooltips are **text on hover**; richer patterns (badge, dialog on click) use other components — don’t overload `VJoyTooltip`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Tooltip panel uses `role="tooltip"` |
+| Relationship | Trigger wrapper sets `aria-describedby` to the tooltip `id` when open |
+| Name | Trigger must have its own accessible name (`label` on icon buttons, visible text, `aria-label`) — the tooltip **describes**, it doesn’t replace the name |
+| Keyboard | **Tab** away from the trigger closes an open tooltip; tooltips are not a separate tab stop |
+| Hover | Default `mouseenter` — ensure equivalent info is not hover-only on keyboard-only flows when content is essential (use visible text or click mode) |
+| Click mode | `event="click"` improves discoverability on touch; still provide a clear trigger name |
+| Motion | Show/hide uses `--joy-transition-duration-default`; respect `prefers-reduced-motion` at app level if you add global overrides |
+| Content | Don’t rely on color alone inside tooltip copy; inherited tokens meet contrast for default neutral theme |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyTooltip, VJoyIconButton, VJoyButton } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Icon button — default hover, plain text -->
+  <VJoyTooltip text="Put to trash">
+    <VJoyIconButton icon="trash" variant="ghost" label="Put to trash" />
+  </VJoyTooltip>
+
+  <!-- Rich content via slot -->
+  <VJoyTooltip placement="top">
+    <VJoyIconButton icon="bell" variant="ghost" label="Notifications" />
+    <template #tooltip-content>
+      You have <strong>3</strong> unread messages
+    </template>
+  </VJoyTooltip>
+
+  <!-- Click trigger (touch / interactive content) -->
+  <VJoyTooltip event="click" text="More details about this setting">
+    <VJoyIconButton icon="info" variant="ghost" label="Setting information" />
+  </VJoyTooltip>
+
+  <!-- Disabled control explanation -->
+  <VJoyTooltip text="Complete all required fields to submit">
+    <VJoyButton variant="main" label="Submit" disabled />
+  </VJoyTooltip>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTooltip` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyIconButton` | Icon-only trigger — pair with tooltip when meaning isn’t obvious |
+| `VJoyLabel` | Field label + optional `label-tooltip` slot |
+| `VJoyButton` | Disabled actions that need a “why” on hover |
+| `VJoyDialog` | User must read content or confirm a decision |
+| `VJoyDrawer` | Supplementary panel with header actions (may embed tooltips in chrome) |
+| `VJoyMenu` / `VJoyDropdown` | Action or navigation lists |
+| `pushVJoySnackbar` | Transient feedback after an action |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyTooltip.dsds.json`](./JoyTooltip.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Short hint on hover/click for one trigger | `VJoyTooltip` | Custom `position: absolute` div + title attr |
+| Icon-only control | `VJoyIconButton` inside `VJoyTooltip` | `VJoyButton` with only an icon |
+| Required reading or confirm/cancel | `VJoyDialog` | Long tooltip copy |
+| Menu of actions | `VJoyMenu` / `VJoyDropdown` | Tooltip with fake buttons |
+| Post-action feedback | `pushVJoySnackbar` | Tooltip that stays after click |
+| Legacy colored variant | Neutral `VJoyTooltip` only | `variant="primary"` / `variant="secondary"` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyTooltip")` (or read `VJoyTooltip.vue` types) before generating props.
+2. **MUST** wrap exactly one trigger in the default slot.
+3. **MUST** supply `text` or `#tooltip-content` — never an empty tooltip.
+4. **MUST NOT** invent props (`variant`, `size`, `open`, `theme`, …).
+5. **MUST NOT** pass HTML through `text` from API/user data — use the slot or sanitize upstream.
+6. **MUST NOT** override `.joy-tooltip__content` / `__arrow` colors, shadow, or radius in app CSS.
+7. **SHOULD** set `event="click"` when the tooltip contains interactive elements or on mobile-first screens.
+8. **SHOULD** reuse the icon button’s `label` text in the tooltip when clarifying the same action.
+9. **SHOULD NOT** use `show` in production pages (Storybook/tests only).
+
+### Checklist
+
+- [ ] Correct component (or named alternative from table above)
+- [ ] Props / enums from MCP only (`placement`, `event`, `delay`, `tooltipWidth`, `id`, `text`)
+- [ ] Content via `text` (plain) or `#tooltip-content` (markup)
+- [ ] No `variant` / no invented props / no custom tooltip chrome CSS
+- [ ] Trigger has its own accessible name (`label`, visible text, or `aria-label`)
+- [ ] Copy is short and non-essential; disabled/menu/dialog cases handled elsewhere if needed
+- [ ] `event="click"` when content is interactive or hover is insufficient
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyTooltip.dsds.json`](./JoyTooltip.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / placement | `anatomy` |
+| Placements / triggers | `variants` (behavioral) |
+| States | `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 |

package/dist/doc/VJoyUserCard/guideline.md

@@ -0,0 +1,268 @@
+---
+component: VJoyUserCard
+status: draft
+language: en
+dsds: JoyUserCard.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# User Card
+
+Use **`VJoyUserCard`** when you need a compact, horizontal identity block — avatar, name, subtitle, and optional metadata (rating, badges) — in lists, side panels, activity feeds, or search results.
+
+Set `link` to make the whole card navigate as a native `<a>`; pass `target`, `rel`, and other link attributes on the component (they inherit via `$attrs`). Customize avatar, title, subtitle, or trailing content through slots when props are not enough.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyUserCard` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — User Card](https://zeroheight.com/6bf479565/p/8408347-user-card) |
+| **Storybook** | [VJoyUserCard docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoyusercard--docs) |
+| **DSDS (machine)** | [`JoyUserCard.dsds.json`](./JoyUserCard.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyUserCard")` |
+
+---
+
+## When to use this component
+
+Use a user card when someone must **recognize a person or entity at a glance** in a dense layout — for example a freelancer in search results, a participant in a conversation header, a project member row, or a sourcing snippet with rating and level badges.
+
+Prefer props (`fullName`, `subTitle`, `photoUrl`) for the default case. Reach for slots when you need a custom avatar size, formatted title, or extra rows (`VJoyRatingStars`, `VJoyBadgeLevel`, availability, tags).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Only a profile picture / initials | `VJoyAvatar` |
+| A generic interactive list row (icon + title + actions) | `VJoyListItem` |
+| A large profile hero or full profile page layout | Page template / custom layout — not `VJoyUserCard` |
+| A complex clickable card with arbitrary CTA layout | `VJoyButtonCard` |
+| Inline name inside body copy | `VJoyLink` or plain text |
+| Custom markup / ad-hoc flex row for the same job | Still use `VJoyUserCard` + Joy tokens |
+
+> **Deprecated:** do not use the `user-card-rating-stars` slot on new work — put `VJoyRatingStars` (and other metadata) in the **default** slot instead. The slot remains for backward compatibility only.
+
+> **Not in the Vue API:** legacy Stencil props `ratingValue` and `newTab`, and the `user-card-free-slot` slot name. **`VJoyUserCard` has no `ratingValue` prop** — compose `VJoyRatingStars` in the default slot. For a new tab, set `link` and pass `target="_blank"` (and `rel="noopener noreferrer"` when appropriate) as attributes.
+
+> **Not in the API:** ZeroHeight “Profile card” **Portrait** / **Landscape** types are layout patterns in design docs. The component implements a **single horizontal layout** (avatar left, text stack right). Do not invent `variant="portrait"` or `variant="landscape"`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `<div class="joy-user-card">`, or `<a class="joy-user-card">` when `link` is set |
+| Picture | Yes | `.joy-user-card__picture` — default `VJoyAvatar` or `user-card-avatar` slot |
+| Informations | Yes | `.joy-user-card__informations` — title, subtitle, and optional extra content |
+| Title | Yes* | `.joy-user-card__title` — `fullName` prop or `user-card-title` slot |
+| Subtitle | No | `.joy-user-card__subtitle` — `subTitle` prop or `user-card-subtitle` slot (`joy-font-primary-450`) |
+| Default slot | No | Free content below subtitle (rating, badges, tags, links) |
+| `title` attribute | No | On link roots, set from `fullName` for native tooltip on hover |
+
+\*Provide at least a title (prop or slot) so the card is meaningful. Avatar initials also use `fullName` when no photo is available.
+
+### Layout and tokens
+
+- **Layout** — `inline-flex`, avatar and text aligned to the start; fixed horizontal pattern (no `size` or `variant` prop on the card).
+- **Typography** — `--user-card-font-size` (default `var(--joy-font-size-primary-400)`); title uses bold weight and `--user-card-title-color`.
+- **Body text** — `--user-card-text-color` (default neutral-60).
+- **Links inside the card** — nested `<a>` elements use `--user-card-links-color` and underline on hover/focus.
+- **Link card** — when the root is `<a>`, the title is underlined and uses link colors; root has opacity transition on hover.
+
+Avatar **size** is controlled via `user-card-avatar` (e.g. `VJoyAvatar` `size="small"`) — not a prop on `VJoyUserCard`.
+
+### Default values
+
+All props are optional strings with no component defaults — supply the data your surface needs.
+
+Props, slots, and attribute inheritance: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (static) | Root is a `<div>`; informational display only |
+| Default (link) | Root is `<a href="…">`; entire card is one navigation target |
+| Hover (link card) | Root opacity transition; title color shifts to link hover token |
+| Hover / focus (nested links) | Links inside `.joy-user-card__informations` underline and change color |
+| Focus (link card) | Native link focus on the root; title styling follows link focus token |
+| Custom slot content | Rating, badges, or extra lines in the default slot — keep supplementary, not the only way to convey the name |
+
+There is no `disabled` or `loading` state on the card itself. If navigation must be blocked, omit `link` or handle it in the parent (and explain why nearby).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to link the whole card
+
+- **SHOULD** set `link` when the **primary action** is “open this person’s profile” (or equivalent destination).
+- **SHOULD** pass `target` and `rel` as native attributes when opening externally (`target="_blank"` + `rel="noopener noreferrer"`).
+- **MUST NOT** nest interactive controls that compete with the card link inside a linked card without stopping propagation — prefer static card + explicit button, or link only the title.
+- **SHOULD** use a single clear destination per card — not multiple conflicting click targets.
+
+### Implementation
+
+- **MUST** use only documented props: `link`, `photoUrl`, `fullName`, `subTitle`.
+- **MUST** put `VJoyRatingStars`, `VJoyBadgeLevel`, and similar metadata in the **default** slot (not deprecated `user-card-rating-stars`).
+- **MUST** style with Joy tokens / CSS variables (`--user-card-*`) — no custom `.joy-user-card` chrome in product CSS.
+- **MUST NOT** invent props (`ratingValue`, `newTab`, `variant`, `size`, …).
+- **SHOULD** prefer props for plain string title/subtitle; use slots for formatting, components, or i18n wrappers.
+- **SHOULD** wrap multiple default-slot items in `VJoyWrapper` with tight gaps (see Storybook `CustomSlot`).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `fullName` + `photoUrl` for standard rows | Rebuild avatar + two `<p>` tags with custom CSS |
+| Default slot for rating / badges | Deprecated `user-card-rating-stars` slot |
+| `target="_blank"` as an attribute on the card | `newTab` prop (Stencil only) |
+| `VJoyAvatar` in `user-card-avatar` when size differs | Hardcoded avatar dimensions on `.joy-user-card__picture` |
+| One profile link via `link` | Whole card linked plus unrelated buttons inside |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Static card → non-interactive container; with `link` → native `<a href>` (not a clickable `<div>`) |
+| Name | Title text (`fullName` / slot) is the primary visible identifier; avatar image uses `fullName` as `alt` via `VJoyAvatar` |
+| Link card | Root `<a>` must have meaningful link text — the title (and not image alone) should identify the destination |
+| `title` attribute | Set on link root from `fullName` — supplementary only; do not rely on it as the accessible name |
+| Nested links | Allowed in the informations block; avoid duplicate or confusing destinations |
+| Keyboard | Link cards follow native link keyboard behavior (**Enter** activates) |
+| Focus | Preserve visible focus styles on link roots and nested links — do not remove outlines in product CSS |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import {
+  VJoyUserCard,
+  VJoyAvatar,
+  VJoyRatingStars,
+  VJoyBadgeLevel,
+  VJoyWrapper,
+} from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Standard identity row -->
+  <VJoyUserCard
+    full-name="Leslie Nielsen"
+    sub-title="Actor"
+    photo-url="https://example.com/photo.jpg"
+  />
+
+  <!-- Whole card navigates — attrs pass through to <a> -->
+  <VJoyUserCard
+    link="https://www.malt.com/profile/123"
+    full-name="Leslie Nielsen"
+    sub-title="Actor"
+    photo-url="https://example.com/photo.jpg"
+    target="_blank"
+    rel="noopener noreferrer"
+  />
+
+  <!-- Rating + badge in default slot -->
+  <VJoyUserCard full-name="Leslie Nielsen" sub-title="Actor">
+    <VJoyWrapper :no-margin="true" column-gap="2" row-gap="2">
+      <VJoyRatingStars :rating-value="5" />
+      <VJoyBadgeLevel level="level-2" type="supermalter" />
+    </VJoyWrapper>
+  </VJoyUserCard>
+
+  <!-- Custom avatar size via slot -->
+  <VJoyUserCard full-name="Leslie Nielsen" sub-title="Actor">
+    <template #user-card-avatar>
+      <VJoyAvatar size="small" full-name="Leslie Nielsen" photo-url="https://example.com/photo.jpg" />
+    </template>
+  </VJoyUserCard>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyUserCard` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyAvatar` | Avatar only, or custom avatar inside `user-card-avatar` |
+| `VJoyRatingStars` | Star rating in the default slot |
+| `VJoyBadgeLevel` | SuperMalter / verification badges below the name |
+| `VJoyWrapper` | Layout and spacing for multiple default-slot children |
+| `VJoyListItem` | Generic list rows with actions, not identity-focused cards |
+| `VJoyLink` | Inline text navigation inside copy |
+| `VJoyAvatarsList` | Stacked/overlapping avatar groups without name stack |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyUserCard.dsds.json`](./JoyUserCard.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Avatar + name + subtitle (+ optional metadata) | `VJoyUserCard` | Custom flex row + raw `<img>` |
+| Profile picture only | `VJoyAvatar` | `VJoyUserCard` without text |
+| Clickable profile in search / list | `VJoyUserCard` + `link` | `<div @click>` router navigation |
+| Rating or level under the name | `VJoyRatingStars` / `VJoyBadgeLevel` in **default** slot | `ratingValue` prop or `user-card-rating-stars` |
+| Open profile in new tab | `link` + `target="_blank"` + `rel="noopener noreferrer"` | `newTab` prop |
+| Rich interactive card layout | `VJoyButtonCard` | `VJoyUserCard` with heavy custom CSS |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyUserCard")` (or read `VJoyUserCard.vue`) before generating props.
+2. **MUST** use only props: `link`, `photoUrl`, `fullName`, `subTitle`.
+3. **MUST** pass native link attributes (`target`, `rel`, …) as HTML attributes on `VJoyUserCard`, not as invented props.
+4. **MUST** place `VJoyRatingStars` and extra metadata in the **default** slot.
+5. **MUST NOT** use `ratingValue`, `newTab`, `variant`, or `size` on `VJoyUserCard`.
+6. **MUST NOT** use deprecated `user-card-rating-stars` in new code.
+7. **MUST NOT** override `.joy-user-card` layout, font-size, or colors with hardcoded app CSS — use `--user-card-*` tokens if needed.
+8. **SHOULD** set `fullName` whenever `photoUrl` may be missing (initials fallback on avatar).
+9. **SHOULD** use `user-card-avatar` only when `VJoyAvatar` needs non-default `size` or behavior.
+
+### Checklist
+
+- [ ] Correct component (`VJoyUserCard` or named alternative)
+- [ ] Props from MCP / source only (`link`, `photoUrl`, `fullName`, `subTitle`)
+- [ ] Rating / badges in default slot — not `ratingValue` or deprecated rating slot
+- [ ] `target` / `rel` as attributes when `link` opens a new tab
+- [ ] No invented props / no custom `.joy-user-card` chrome CSS
+- [ ] Link card: one clear destination; nested links don’t conflict
+- [ ] Title identifies the person or entity
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyUserCard.dsds.json`](./JoyUserCard.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / layout | `anatomy` |
+| States | `states` |
+| Best practices | `guidelines` |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Token theming | `design-specifications` in JSON (`--user-card-*`) |

package/dist/doc/VJoyUserCard/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyUserCard",
   "displayName": "VJoyUserCard",
-  "description": "A comprehensive user profile card component for displaying user information in a structured layout.\nFeatures integrated avatar display, name/subtitle presentation, rating stars support, and optional\nlink functionality for navigation. Includes multiple customization slots for avatar, title, subtitle,\nand rating components, with full attribute inheritance for link behavior and accessibility.",
+  "description": "A comprehensive user profile card component for displaying user information in a structured layout.\nFeatures integrated avatar display, name/subtitle presentation, rating stars support, and optional\nlink functionality for navigation. Includes multiple customization slots for avatar, title, subtitle,\nand free content through the default slot, with full attribute inheritance for link behavior and\naccessibility. The user-card-rating-stars slot is deprecated; use the default slot for custom\nrating stars or other free content instead.",
   "category": "View",
   "props": [
     {
@@ -31,15 +31,6 @@
         "string"
       ]
     },
-    {
-      "name": "ratingValue",
-      "type": "number | undefined",
-      "required": false,
-      "description": "Introduce a VJoyRatingStars component with given rating",
-      "possibleValues": [
-        "number"
-      ]
-    },
     {
       "name": "subTitle",
       "type": "string | undefined",
@@ -54,7 +45,7 @@
   "slots": [
     {
       "name": "default",
-      "description": ""
+      "description": "Free content displayed below the user information. Use this slot for custom content like VJoyRatingStars."
     },
     {
       "name": "user-card-avatar",
@@ -70,7 +61,7 @@
     },
     {
       "name": "user-card-rating-stars",
-      "description": "Use your own customized VJoyRatingStars here, if needed"
+      "description": ""
     }
   ],
   "exposed": [
@@ -89,11 +80,6 @@
       "type": "string | undefined",
       "isMethod": false
     },
-    {
-      "name": "ratingValue",
-      "type": "number | undefined",
-      "isMethod": false
-    },
     {
       "name": "subTitle",
       "type": "string | undefined",