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

package/dist/doc/VJoyCollapseItem/guideline.md

@@ -0,0 +1,394 @@
+---
+component: VJoyCollapseItem
+status: draft
+language: en
+dsds: JoyCollapseItem.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Collapse item
+
+Use **`VJoyCollapseItem`** when a section of content should stay hidden until the user expands it — FAQs, optional settings, or dense detail that would clutter the page when always visible.
+
+Each item has a clickable header (with optional icon, subheader, and preview), a chevron marker, and a collapsible body. Use it alone for a single disclosure, or nest several inside **`VJoyCollapse`** for grouped lists and accordion behavior.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyCollapseItem` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyCollapseItem docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-buttons-vjoycollapseitem--docs) · [VJoyCollapse docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-buttons-vjoycollapse--docs) (grouped examples) |
+| **DSDS (machine)** | [`JoyCollapseItem.dsds.json`](./JoyCollapseItem.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyCollapseItem")` |
+
+---
+
+## When to use this component
+
+Use a collapse item when users benefit from **progressive disclosure** on the same screen — they scan short headers first and open only what they need.
+
+Typical jobs: FAQ answers, advanced settings tucked under a summary, filter or form sections that are optional, or outline cards that preview key values before expansion.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Several items with shared open/close logic or accordion (one open at a time) | `VJoyCollapse` wrapping `VJoyCollapseItem` children |
+| Switching between peer panels on one surface | `VJoyTabs` + `VJoyTab` |
+| Blocking modal decision or form | `VJoyDialog` |
+| Linear multi-step flow with progress | `VJoyStepper` |
+| Primary site or app navigation | `VJoyMenu`, sidebar, or header nav |
+| Inline “show more” for long text only | Truncation / “Read more” pattern on `VJoyText` — not a full panel |
+| Custom expand/collapse markup with ad-hoc CSS | Still use `VJoyCollapseItem` + Joy tokens — don’t reinvent chrome |
+
+> **Experimental:** `mode="outline"` renders a bordered card treatment. It may become the default later; confirm with design before rolling it out broadly.
+
+---
+
+## How it works
+
+Clicking the **summary** row (header area) toggles open state. When open, the **detail** region renders the default slot. The chevron rotates to indicate state.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Summary row | Yes | Clickable header (`role="button"`) — toggles open/closed |
+| Header label | Yes | Text from the `header` prop |
+| Summary icon | No | Leading `VJoyIcon` when `summaryIcon` is set |
+| Subheader | No | Secondary line under the header (`subheader` prop) |
+| Header right (`collapse-header-right` slot) | No | Short metadata between title and chevron (e.g. `VJoyTag`) — keep non-interactive |
+| Chevron marker | Yes | Trailing `chevron-down` icon; rotates 180° when open |
+| Preview (`collapse-preview` slot) | No | Short snippet visible while collapsed (often tags or a one-line summary) |
+| Detail region | Yes (when open) | Default slot content (`role="region"`, labelled by summary `id`) |
+| Focus / hover chrome | No* | Outline `mode` adds border highlight and elevation on hover/focus |
+
+### Default values
+
+- `open` defaults to **`false`**
+- `mode` defaults to **`default`**
+- `header` is **required**
+- `subheader`, `summaryIcon`, and `id` are optional
+
+Props, events, and slots: use Joy MCP (`joy_list_components`, `joy_get_component_info`, `joy_get_component_types`) or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Open state
+
+Two patterns:
+
+1. **Per item** — set `:open="true"` on each `VJoyCollapseItem` you want expanded initially.
+2. **Grouped** — wrap items in `VJoyCollapse` and bind `v-model` to an array of open item ids. **Set a stable `id` on each item** when using `v-model` (falls back to `header` text if `id` is omitted).
+
+`VJoyCollapse` also supports `accordion` (only one item open at a time) and passes `mode` to all children.
+
+### Composition
+
+```vue
+<VJoyCollapse v-model="openIds">
+  <VJoyCollapseItem id="billing" header="Billing details">…</VJoyCollapseItem>
+  <VJoyCollapseItem id="shipping" header="Shipping address">…</VJoyCollapseItem>
+</VJoyCollapse>
+```
+
+Listen for `@collapse-item:open` and `@collapse-item:close` on each item when you need side effects outside `v-model`.
+
+---
+
+## Variants
+
+`mode` controls the visual treatment — not semantic emphasis.
+
+### `default`
+
+Use for stacked lists inside `VJoyCollapse`: items get a bottom divider from the parent wrapper. Compact, text-forward headers.
+
+Avoid when each item should read as an independent card with border and padding.
+
+### `outline`
+
+Use when each item is a **bordered card** — common in settings or selectable sections with icons, subheaders, and preview content.
+
+Hover and keyboard focus lift the border to secondary color and add elevation. Open items keep the active border.
+
+Avoid mixing `default` and `outline` items in the same `VJoyCollapse` group; set `mode` once on `VJoyCollapse` (or consistently per item).
+
+### Not in the Vue API: Stencil slot names
+
+The legacy `joy-collapse-item` web component uses slots `collapse-summary`, `collapse-marker`, and `collapse-detail`. **`VJoyCollapseItem` uses the `header` prop, built-in chevron, and the default slot** — do not port Stencil slot names into Vue templates.
+
+---
+
+## Sizes
+
+`VJoyCollapseItem` exposes **no `size` prop**. Typography scales via CSS custom properties on the root:
+
+| Token / variable | Role |
+| --- | --- |
+| `--collapse-item-font-size` | Base font size for summary and detail |
+| `--collapse-item-summary-font-size` | Summary row only (overrides base) |
+| `--collapse-item-detail-font-size` | Detail body only (overrides base) |
+
+Defaults map to Joy primary font tokens (`--joy-font-size-primary-400` summary context, `--joy-font-size-primary-300` detail). **Don’t hardcode pixel font sizes** in apps — override these variables if design requires a local tweak.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Collapsed (default) | Header, optional subheader/preview visible; detail hidden; chevron points down |
+| Expanded (`open`) | Detail region visible; chevron rotated 180°; `collapse-item:open` emitted |
+| Collapsed again | Detail unmounted from DOM; `collapse-item:close` emitted |
+| Hover (`outline` mode) | Border and chevron use secondary color; light elevation |
+| Focus (`outline` mode) | Same highlight as hover while summary has focus (`joy-collapse-item--focusing`) |
+| With preview slot | Preview content stays visible in the summary row while collapsed |
+
+Internal open state syncs from the `open` prop via a watcher — parent `v-model` on `VJoyCollapse` or explicit `:open` both work.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure and hierarchy
+
+- **SHOULD** use **`VJoyCollapse`** when there are **two or more** related items, accordion behavior, or shared `v-model`.
+- **SHOULD** give each item a **stable `id`** when `VJoyCollapse` manages open state.
+- **SHOULD** keep **3–8** collapse items per group; beyond that, rethink IA (tabs, separate page, search).
+- **SHOULD NOT** nest another collapse item inside a detail body unless the inner content is truly independent.
+- **MUST NOT** put primary page CTAs only inside collapsed content — surface the main action outside.
+
+### Implementation
+
+- **MUST** use only documented props and `mode` values from `JoyCollapseItem.types.ts` (`default`, `outline`).
+- **MUST** style with Joy tokens / CSS variables — no custom `.joy-collapse-item` chrome overrides.
+- **MUST NOT** invent props (`variant`, `size`, `disabled`, …).
+- **MUST NOT** replace the summary with a custom clickable `<div>` — use `header`, slots, and `summaryIcon`.
+- **SHOULD** set `mode` on `VJoyCollapse` when all siblings share the same treatment.
+- **SHOULD** use `collapse-preview` for at-a-glance values (tags, status) — not full detail content.
+
+### Interaction
+
+- **SHOULD** initialize `open` or `v-model` so the most helpful section is expanded on first visit (when product rules allow).
+- **SHOULD** keep `collapse-header-right` content **display-only** (badges, tags) — not buttons or links that compete with the summary toggle.
+- **MUST NOT** rely on collapse to hide required form fields without a clear way to discover them (validation + error messaging).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyCollapse` + `id` + `v-model` for groups | Duplicate toggle logic on custom wrappers |
+| Short, scannable `header` text | Full paragraphs in the header |
+| `summaryIcon` when it aids recognition | Decorative icons on every row |
+| `collapse-preview` for one-line summaries | Entire forms in the preview slot |
+| `mode="outline"` for card-style sections | Mixing modes in one list |
+| Joy typography CSS variables | Hardcoded `14px` / `16px` in app CSS |
+
+---
+
+## Content
+
+Headers are navigation labels; detail bodies hold the substance.
+
+### Header formula
+
+**Short noun phrase or topic name** naming the section:
+
+- ✅ Billing information
+- ✅ Advanced options
+- ✅ What is Malt Protect?
+
+Use **parallel structure** across siblings in the same `VJoyCollapse` (all questions, all settings categories, etc.).
+
+### Subheader and preview
+
+- **`subheader`** — one supporting line (eligibility, last updated, short context). Sentence case.
+- **`collapse-preview`** — compact collapsed-state hint (chip list, status, single metric). Not a substitute for the full body.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Header names the **topic**, not the action — ✅ `Payment method` · ❌ `Click to see payment method` |
+| **MUST** | Keep headers ≤ ~50 characters; move detail to subheader or body |
+| **MUST** | Use sentence case for headers and subheaders |
+| **MUST NOT** | Use “Show” / “Hide” / “Click here” as the header — the chevron already signals expand/collapse |
+| **MUST NOT** | Duplicate the page title as every item header |
+| **SHOULD** | Phrase FAQ headers as the user’s question |
+| **SHOULD** | Match header wording to links or buttons that scroll to the section |
+| **SHOULD** (FR) | Use articles and punctuation as grammar requires — same length discipline applies |
+
+### Patterns
+
+**FAQs** — Question as `header`, answer in the default slot. Keep answers concise; link out for long docs.
+
+**Settings** — `outline` + `summaryIcon` + optional `collapse-preview` (e.g. current value). Subheader for “Last saved …” metadata.
+
+**Forms inside detail** — Validate on submit, not on collapse. If a section has errors, consider leaving it open or expanding it when validation fails.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Summary control | `role="button"` with `tabindex="0"` on the summary row |
+| Toggle | **Click** and **Enter** activate toggle (summary `@keydown.enter`) |
+| Expanded content | `role="region"` with `aria-labelledby` pointing to the summary label element |
+| Label id | **Set `id`** on the item when multiple collapse items share a page — required for correct `aria-labelledby` on the region |
+| Name | Accessible name comes from visible `header` text (and subheader is supplementary visual text, not the primary name) |
+| Focus | Outline mode shows visible focus via border/elevation — don’t remove it in product CSS |
+| Icons | `summaryIcon` and chevron are decorative (`aria-hidden` on summary icon) |
+| Header-right slot | Must not trap focus or replace the summary’s accessible name |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+> **Gap to be aware of:** the summary does not currently expose `aria-expanded`. Don’t remove native semantics if you wrap the item; prefer upstream fixes over per-app patches.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyCollapse, VJoyCollapseItem, VJoyTag } from '@maltjoy/core-vue'
+
+const openIds = ref(['billing'])
+</script>
+
+<template>
+  <!-- Standalone item -->
+  <VJoyCollapseItem header="Release notes" :open="true">
+    <p>Version 2.4 includes performance improvements.</p>
+  </VJoyCollapseItem>
+
+  <!-- Grouped with v-model -->
+  <VJoyCollapse v-model="openIds">
+    <VJoyCollapseItem id="billing" header="Billing" subheader="Invoices and tax info">
+      <p>Update your billing address here.</p>
+    </VJoyCollapseItem>
+    <VJoyCollapseItem id="notifications" header="Notifications">
+      <p>Choose which emails you receive.</p>
+    </VJoyCollapseItem>
+  </VJoyCollapse>
+
+  <!-- Outline card with icon, tag, and preview -->
+  <VJoyCollapse mode="outline" v-model="openIds">
+    <VJoyCollapseItem
+      id="profile"
+      header="Profile"
+      subheader="Visible to clients"
+      summary-icon="user"
+    >
+      <template #collapse-header-right>
+        <VJoyTag label="Complete" size="small" />
+      </template>
+      <template #collapse-preview>
+        <span class="joy-mt-4">Paris · French · Available</span>
+      </template>
+      <p>Full profile editor content.</p>
+    </VJoyCollapseItem>
+  </VJoyCollapse>
+
+  <!-- Accordion: one open at a time -->
+  <VJoyCollapse v-model="openIds" accordion>
+    <VJoyCollapseItem id="step-1" header="Step 1">…</VJoyCollapseItem>
+    <VJoyCollapseItem id="step-2" header="Step 2">…</VJoyCollapseItem>
+  </VJoyCollapse>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit imports if `VJoyCollapseItem` and `VJoyCollapse` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyCollapse` | Multiple items, `v-model`, or accordion mode |
+| `VJoyIcon` | `summaryIcon` values (Joy icon names) |
+| `VJoyTag` / `VJoyTagsList` | Status or preview chips in header-right or preview slot |
+| `VJoyTabs` | Peer sections that should stay visible as tabs, not stacked disclosure |
+| `VJoyPanel` | Static card layout without expand/collapse interaction |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyCollapseItem.dsds.json`](./JoyCollapseItem.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| One expandable section | `VJoyCollapseItem` | Custom `<details>` with Joy-like CSS |
+| Multiple expandable sections | `VJoyCollapse` + `VJoyCollapseItem` children | Several unrelated `VJoyCollapseItem` without a parent |
+| Only one open at a time | `VJoyCollapse` + `accordion` + `v-model` | Manual open-state logic per item |
+| Card-style bordered rows | `mode="outline"` on collapse (parent or item) | Custom bordered divs + click handlers |
+| Tabbed peer content | `VJoyTabs` + `VJoyTab` | Collapse items for primary navigation |
+| Modal interrupt | `VJoyDialog` | Collapse for blocking confirmations |
+
+### Hard rules
+
+1. **MUST** read `JoyCollapseItem.types.ts` and/or `joy_list_components` before generating props (detailed MCP info may lag for this component).
+2. **MUST** use only documented props: `header`, `subheader`, `open`, `summaryIcon`, `id`, `mode`.
+3. **MUST** use `header` prop for the title — not Stencil slot names (`collapse-summary`).
+4. **MUST** put expandable body content in the **default slot** — not `collapse-detail`.
+5. **MUST** set `id` on each item when using `VJoyCollapse` `v-model`.
+6. **MUST NOT** invent props (`variant`, `size`, `disabled`, `accordion` on the item).
+7. **MUST NOT** override `.joy-collapse-item` border, padding, radius, or chevron rotation in app CSS.
+8. **SHOULD** listen for `collapse-item:open` / `collapse-item:close` (kebab-case in templates) — not Stencil `joy-collapse-item-*` event names.
+9. **SHOULD** use `summary-icon` (kebab-case) in templates for the `summaryIcon` prop.
+
+### Valid enums (from `JoyCollapseItem.types.ts`)
+
+| Prop | Values |
+| --- | --- |
+| `mode` | `default`, `outline` |
+| `open` | `boolean` (default `false`) |
+| `summaryIcon` | Any `TJoyIconsNames` value (see `VJoyIcon` / Joy icon docs) |
+
+### Slots
+
+| Slot | Purpose |
+| --- | --- |
+| `default` | Detail content when open |
+| `collapse-header-right` | Non-interactive metadata before chevron |
+| `collapse-preview` | Collapsed-state preview line |
+
+`defineSlots` also lists `collapse-subheader`, but the template uses the **`subheader` prop** — prefer the prop unless the API gains a real subheader slot.
+
+### Checklist
+
+- [ ] Correct component (`VJoyCollapseItem` alone vs. with `VJoyCollapse`)
+- [ ] `header` set; `id` set when parent uses `v-model`
+- [ ] Props / enums from types only — no invented API
+- [ ] Default slot for body; no Stencil slot names
+- [ ] `mode` consistent across siblings
+- [ ] Header copy is a topic label, not “Show/Hide”
+- [ ] `collapse-header-right` is display-only
+- [ ] No custom `.joy-collapse-item` chrome CSS
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyCollapseItem.dsds.json`](./JoyCollapseItem.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants (`mode`) | `variants` |
+| Sizes (CSS variables) | `design-specifications` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Imports | `imports` in JSON |

package/dist/doc/VJoyCompanyAvatar/guideline.md

@@ -0,0 +1,162 @@
+---
+component: VJoyCompanyAvatar
+status: deprecated
+language: en
+dsds: JoyCompanyAvatar.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Company avatar
+
+Use **`VJoyCompanyAvatar`** to show a company logo in a square, bordered frame — or a generic company placeholder when no logo URL is available.
+
+> **Deprecated:** do not use on new work. Prefer **`VJoyAvatar`** with `placeholder="company-placeholder"` and `showLetters={false}` for the same job. See [ZeroHeight — Avatar](https://zeroheight.com/6bf479565/p/52ceb2-avatar) and the V5 release note (`VJoyCompanyAvatar` merged into `VJoyAvatar`).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyCompanyAvatar` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Avatar](https://zeroheight.com/6bf479565/p/52ceb2-avatar) |
+| **Storybook** | [VJoyCompanyAvatar docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoycompanyavatar--docs) |
+| **DSDS (machine)** | [`JoyCompanyAvatar.dsds.json`](./JoyCompanyAvatar.dsds.json) |
+| **Live API** | `joy_list_components` (View category) — `joy_get_component_info` may not resolve this legacy name |
+
+---
+
+## When to use this component
+
+**Only in existing code** that already renders `VJoyCompanyAvatar`. Typical job: display a client or employer logo next to a name, in a list row, or on a user card.
+
+When `imgSrc` is set, the component shows the image (`object-fit: contain`). Without `imgSrc`, it falls back to the `company-placeholder` icon.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Any new company logo / brand mark | `VJoyAvatar` with `photoUrl`, `fullName` (company name), `placeholder="company-placeholder"`, `showLetters={false}` |
+| A person’s profile photo or initials | `VJoyAvatar` (default `user-photo` placeholder) |
+| Several logos in a row | `VJoyAvatarsList` + `VJoyAvatar` |
+| Custom square image with ad-hoc border CSS | Still use `VJoyAvatar` + Joy tokens — don’t reinvent chrome |
+
+> **Deprecated:** the whole component. The legacy Stencil `color` prop (`red`, `teal`, `turquoise`, `yellow`) is **not** on `VJoyCompanyAvatar` — do not emit it.
+
+---
+
+## How it works
+
+Presentational only: no slots, events, or `v-model`. The root is a `div.joy-company-avatar` with a size modifier.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `div` with `joy-company-avatar` and `joy-company-avatar--{size}` |
+| Logo image | No | `<img>` when `imgSrc` is set; `alt` = `imgAlt` or `companyName`; `title` = `companyName` |
+| Placeholder icon | Yes* | `VJoyIcon` `company-placeholder` when `imgSrc` is absent |
+| Border / background | Yes | Neutral border and background from Joy tokens — don’t override in product CSS |
+
+\*Shown whenever there is no `imgSrc`.
+
+### Default values
+
+- `size` defaults to **`large`** (`large` \| `medium` \| `small`)
+- `loading` defaults to **`lazy`** (only applied when `imgSrc` is set)
+- `imgSrc`, `imgAlt`, and `companyName` are **optional** — with none set, you get the anonymous placeholder icon
+
+**Size → frame** (token-driven inside the component; don’t hardcode px in apps):
+
+| `size` | Frame |
+| --- | --- |
+| `large` | 46px, `--joy-core-radius-3` |
+| `medium` | 30px, `--joy-core-radius-2` |
+| `small` | 20px, `--joy-core-radius-1` |
+
+Props: use Storybook or read `VJoyCompanyAvatar.vue` — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Deprecation and migration
+
+- **MUST NOT** add new usages of `VJoyCompanyAvatar`.
+- **SHOULD** migrate to `VJoyAvatar` when touching surrounding code.
+- **SHOULD** map `imgSrc` → `photoUrl`, `companyName` / `imgAlt` → `fullName` (avatar uses `fullName` for image `alt` and `title`).
+
+### Implementation
+
+- **MUST** set `companyName` (and `imgAlt` when the logo needs a specific description) whenever `imgSrc` is present — screen readers and hover tooltips depend on it.
+- **MUST** use only documented props: `imgSrc`, `imgAlt`, `companyName`, `size`, `loading`.
+- **MUST** use Joy tokens — no custom `.joy-company-avatar` border, radius, or background overrides.
+- **MUST NOT** invent props (`color`, `variant`, `href`, …).
+- **SHOULD** pick `size` to match adjacent avatars or list density (`large` for profile-scale, `small` in compact tables).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `companyName` + `imgAlt` with a real logo URL | Logo `img` with empty `alt` |
+| `VJoyAvatar` for new company logos | New `VJoyCompanyAvatar` instances |
+| Token-driven sizes via the `size` prop | Fixed `width` / `height` in app CSS |
+| `loading="lazy"` for below-the-fold logos | Eager-load every logo in a long list |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Image present | `alt` comes from `imgAlt` or falls back to `companyName` — provide at least one meaningful string |
+| Image absent | Placeholder is decorative; parent context must name the company in visible text nearby |
+| Title | `companyName` is exposed as the image `title` for pointer hover — supplementary only |
+| Focus | Component is not focusable; wrap in a link/button in the parent if the logo is interactive |
+| Motion | No built-in animation; respect `prefers-reduced-motion` at app level if you add transitions around it |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyCompanyAvatar } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Legacy — prefer VJoyAvatar for new code -->
+  <VJoyCompanyAvatar
+    company-name="Malt"
+    img-alt="Malt logo"
+    img-src="https://dam.malt.com/cms-front/maltLogo.png"
+  />
+
+  <VJoyCompanyAvatar size="small" />
+
+  <!-- Replacement pattern (new work) -->
+  <!--
+  <VJoyAvatar
+    full-name="Malt"
+    photo-url="https://dam.malt.com/cms-front/maltLogo.png"
+    placeholder="company-placeholder"
+    :show-letters="false"
+  />
+  -->
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if the component is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyAvatar` | **Preferred** — company logos, people, placeholders, initials |
+| `VJoyAvatarsList` | Multiple avatars or logos in one row |
+| `VJoyUserCard` | Profile card that may show a company context |
+| `VJoyListItem` | Row layout with a leading logo slot |