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

package/dist/doc/VJoyAvatarsList/guideline.md

@@ -0,0 +1,328 @@
+---
+component: VJoyAvatarsList
+status: draft
+language: en
+dsds: JoyAvatarsList.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Avatars list
+
+Use **`VJoyAvatarsList`** when you need to show **several `VJoyAvatar` instances as a group** — with consistent spacing and alignment, or in a compact overlapping stack.
+
+The list is a layout container only: put avatars in the default slot, set `compress` when they should overlap (for example bulk-selection toolbars), and let provide/inject pass compression styling to each child. Overflow counts (`+N`) still belong on the last `VJoyAvatar` via `totalNumber`, not on the list itself.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyAvatarsList` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Avatar](https://zeroheight.com/6bf479565/p/52ceb2-avatar) (list patterns) |
+| **Storybook** | [VJoyAvatarsList docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoyavatarslist--docs) |
+| **DSDS (machine)** | [`JoyAvatarsList.dsds.json`](./JoyAvatarsList.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyAvatarsList")` *(not indexed in Joy MCP yet — use Storybook or `VJoyAvatarsList.vue`)* |
+
+---
+
+## When to use this component
+
+Use an avatars list when multiple people should read as **one visual unit** — team members on a card, participants in a thread, or freelancers in a bulk-action bar. `VJoyAvatarsList` handles flex layout, token-based gaps, and optional overlap so product code does not hand-roll negative margins or borders.
+
+Typical jobs:
+
+- **Spaced row** — default mode; avatars wrap with Joy spacing when the row is long.
+- **Compressed stack** — `compress` for dense UI (floating action bars, table selection summaries) where avatars overlap left-to-right.
+
+Always compose **`VJoyAvatar` children** inside the list. Person-level props (`fullName`, `photoUrl`, `size`, `totalNumber`, …) stay on each avatar.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A single person | `VJoyAvatar` alone |
+| Avatar + name, role, metadata in a card | `VJoyUserCard` |
+| Overlapping avatars with manual CSS / negative margins | `VJoyAvatarsList` + `compress` |
+| Setting `compress` on individual avatars | `VJoyAvatarsList` with `compress` — compression is injected, not a per-avatar prop |
+| A scrollable roster with row actions | List/table patterns with `VJoySelectableItem` or data tables |
+| Custom flex wrapper / ad-hoc gap CSS for the same job | Still use `VJoyAvatarsList` + Joy tokens |
+
+> **Not in the Vue API:** legacy Stencil `joy-avatars-list` and per-avatar `compress` / `is-first-from-list`. In Vue, only **`VJoyAvatarsList`** exposes `compress`; children pick it up via provide/inject.
+
+---
+
+## How it works
+
+`VJoyAvatarsList` renders a flex container, applies list-level classes, and **`provide`s** `{ compress }` under the key `VJoyAvatarsList`. Each `VJoyAvatar` **injects** that value and toggles `.joy-avatar__wrapper--compressed` and overlap styles automatically.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `<div class="joy-avatars-list">` — flex row, wrap, token gaps |
+| Default slot | Yes* | One or more `VJoyAvatar` instances (*empty list is valid but usually avoided in product UI) |
+| Compressed modifier | No | `.joy-avatars-list--compressed` when `compress` is true — zero gap, overlap margins on children |
+
+There are no events, no `v-model`, and no nested subcomponents beyond slot content.
+
+### Default values
+
+- `compress` defaults to **`false`**
+
+Props and slots: use Storybook or read `VJoyAvatarsList.vue` — Joy MCP may not list this component yet. This page focuses on **when** and **how**, not a full API dump.
+
+### Layout tokens (default mode)
+
+- `display: flex`, `flex-wrap: wrap`, `align-items: center`, `justify-content: flex-start`
+- Gap: `var(--joy-core-spacing-3)` (row) and `var(--joy-core-spacing-6)` (column)
+
+**Don’t** reimplement these gaps in product CSS when wrapping avatars in a plain `div`.
+
+---
+
+## Variants
+
+`VJoyAvatarsList` has **no color or emphasis prop**. Layout is controlled by **`compress`** only.
+
+### Default (spaced)
+
+Use when avatars should remain **distinct circles** with breathing room — member grids, color/size showcases, or anywhere overlap would reduce legibility.
+
+Avoid when horizontal space is very tight and the design calls for a stacked “pile” of faces.
+
+### Compressed (`compress`)
+
+Use when several avatars must fit in a **compact horizontal stack** — bulk selection bars, dense summaries beside a count label, table toolbars.
+
+The list sets `gap: 0` and applies per-size negative `margin-left` on each avatar wrapper (one quarter of the avatar diameter). Non-empty avatars get a **white separator border** so faces remain distinguishable. Empty avatars (`isEmpty`) skip the white border in compressed mode.
+
+Avoid compress when avatars are large (`large` / `xlarge`) and the stack would obscure identity — prefer fewer visible avatars plus a `totalNumber` overflow chip.
+
+### Not in the API: per-avatar `compress`
+
+Legacy Stencil documented `compress` and `is-first-from-list` on `joy-avatar`. **`VJoyAvatar` has no `compress` prop.** Set `compress` only on `VJoyAvatarsList`.
+
+---
+
+## Sizes
+
+`VJoyAvatarsList` has **no `size` prop**. Density comes from the **`size` on each `VJoyAvatar`** child.
+
+| Practice | Use when |
+| --- | --- |
+| Same `size` on every child in one list | Always — mixed sizes break alignment and compressed overlap math |
+| `small` inside compressed stacks | Bulk actions, table selections (`VJoyFloatingActionsBar` pattern) |
+| `medium` (avatar default) in spaced lists | General member rows and cards |
+| Larger sizes (`large`, `xlarge`) | Hero or profile contexts — usually **without** `compress` |
+
+Overlap offset is computed from each child’s size token (`--negative-margin: calc(avatarSize / -4)`). **Don’t** hardcode overlap pixels in app CSS.
+
+---
+
+## States
+
+| State | What the user sees |
+| --- | --- |
+| Default (`compress: false`) | Avatars in a wrapped flex row with token gaps |
+| Compressed (`compress: true`) | Overlapping stack; later avatars sit above earlier ones (`z-index`); white ring between faces |
+| Empty list | Container renders with no avatars — valid technically; avoid in product unless loading |
+| Empty avatars in stack | `isEmpty` on `VJoyAvatar` — neutral placeholder circles; compressed borders omitted for empty wrappers |
+| Overflow | Not a list state — last child uses `VJoyAvatar` `totalNumber` (e.g. `+3`) |
+
+The list itself is **not interactive**. Clicks and keyboard focus live on individual `VJoyAvatar` instances when `link` is set.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Composition
+
+- **MUST** place only `VJoyAvatar` (or wrappers that render avatars) in the default slot — the list does not render avatars for you.
+- **MUST** use the same `size` on every avatar in a given list.
+- **SHOULD** use `compress` for selection summaries and floating action bars; use default spacing elsewhere.
+- **SHOULD** show at most **three** person avatars in selection UI, then a **`totalNumber`** overflow avatar for the remainder (see Content).
+- **SHOULD** keep avatars in **selection order** (left-to-right) — do not reorder by name or recency for display alone.
+- **MUST NOT** set `compress` on individual avatars — only on `VJoyAvatarsList`.
+- **MUST NOT** combine `totalNumber` with `fullName` or `photoUrl` on the same avatar (ESLint).
+
+### Implementation
+
+- **MUST** use Joy tokens — no custom `.joy-avatars-list` gap, margin, or overlap CSS.
+- **MUST NOT** invent props on `VJoyAvatarsList` (`variant`, `size`, `max`, `gap`, …).
+- **SHOULD** pair compressed lists with a visible text summary (`3 freelancers selected`) when the selection count matters.
+- **SHOULD** pass `fullName` on person avatars for accessible images and tooltips (`title` on the avatar surface).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyAvatarsList` + `VJoyAvatar` children | Bare `div` + manual negative margins |
+| `compress` on the list | `compress` on each avatar |
+| Consistent `size` across the set | Mixed `small` + `medium` in one list |
+| `totalNumber` on the last avatar for overflow | Extra fake avatars to imply count |
+| Text label beside compressed stacks | Avatars alone when count is the main message |
+
+---
+
+## Content
+
+`VJoyAvatarsList` does not render copy. Content rules apply to **how you compose** the list with labels and overflow chips in selection and summary UI.
+
+### Selection summary pattern
+
+When selected items are identifiable people (for example freelancers to contact):
+
+- Show up to **three** person avatars, then collapse overflow into a **`+N`** avatar (`totalNumber` on the last `VJoyAvatar`).
+- Place a **count label after the stack**: `6 selected` (follow locale plural rules).
+- For a **single** selection: one avatar + `1 selected` — do not pluralize the label.
+- When selection has **no** associated people, use a plain count — do not show an avatars list.
+
+### Overflow chip
+
+- Use `totalNumber` for the **hidden count only** (not total headcount). Example: two visible faces + `totalNumber={4}` → reads as two photos and `+4` for four more.
+- Keep the overflow avatar the **same `size`** as the visible avatars.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Expose the selection count in visible text when the list is the primary selection indicator |
+| **MUST NOT** | Rely on avatars alone when users need an exact count |
+| **SHOULD** | Use sentence case for count labels — `3 freelancers selected` |
+| **SHOULD** | Match count copy to the entity type (freelancers, members, participants) |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Presentational group — no interactive role on the list container |
+| Names | Each person avatar should have a meaningful `fullName` (photo `alt` / `title`) or nearby text that identifies the set |
+| Overflow | `+N` text is visible content on the overflow avatar; pair with a textual count for screen-reader context when the number is critical |
+| Keyboard | List does not trap focus; focusable avatars use `link` + `@click` on `VJoyAvatar` only |
+| Selection context | When the list indicates bulk selection, expose the count in **visible text** next to the stack — not only in a tooltip |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyAvatar, VJoyAvatarsList, VJoyText, VJoyWrapper } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Spaced member row -->
+  <VJoyAvatarsList>
+    <VJoyAvatar full-name="Alan Grant" photo-url="https://example.com/alan.webp" size="medium" />
+    <VJoyAvatar full-name="Ellie Sattler" size="medium" />
+    <VJoyAvatar full-name="Ian Malcolm" size="medium" />
+  </VJoyAvatarsList>
+
+  <!-- Compressed stack with overflow (bulk selection) -->
+  <VJoyWrapper no-margin column-gap="3" align="center">
+    <VJoyAvatarsList compress>
+      <VJoyAvatar full-name="Alice Dupont" size="small" />
+      <VJoyAvatar full-name="Bob Martin" size="small" />
+      <VJoyAvatar :total-number="4" size="small" />
+    </VJoyAvatarsList>
+    <VJoyText preset="primary-400">6 freelancers selected</VJoyText>
+  </VJoyWrapper>
+
+  <!-- v-for-driven list -->
+  <VJoyAvatarsList compress>
+    <VJoyAvatar
+      v-for="member in members"
+      :key="member.id"
+      :full-name="member.fullName"
+      :photo-url="member.photoUrl"
+      size="small"
+    />
+  </VJoyAvatarsList>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyAvatarsList` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyAvatar` | A single person, overflow `+N` chip, or anonymous placeholder |
+| `VJoyUserCard` | Avatar plus name, subtitle, and actions |
+| `VJoyFloatingActionsBar` | Bulk actions — often pairs `compress` avatars with action buttons |
+| `VJoyWrapper` | Horizontal layout beside the list (avatar stack + count label) |
+| `VJoyText` | Selection count or summary copy next to the list |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyAvatarsList.dsds.json`](./JoyAvatarsList.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| One person | `VJoyAvatar` | `VJoyAvatarsList` with a single child (unless design explicitly groups it) |
+| Multiple people, spaced | `VJoyAvatarsList` + `VJoyAvatar` children | `div` with flex + gap |
+| Overlapping stack | `VJoyAvatarsList` with `compress` | Per-avatar `compress` or negative margins |
+| Hidden count / +N | Last `VJoyAvatar` with `totalNumber` | Extra avatars or list-level `overflow` prop |
+| Full identity card | `VJoyUserCard` | List + manual name markup |
+
+### Hard rules
+
+1. **MUST** read `VJoyAvatarsList.vue` and Storybook before generating props — `joy_get_component_info("VJoyAvatarsList")` may fail until MCP indexes the component.
+2. **MUST** use only documented list prop: `compress` (boolean, default `false`).
+3. **MUST** put avatars in the **default slot** — no `avatars` prop array on the list.
+4. **MUST NOT** invent list props (`size`, `variant`, `maxVisible`, `gap`, `avatars`, …).
+5. **MUST NOT** set `compress` on `VJoyAvatar` — compression is provide/inject from the list parent.
+6. **MUST NOT** override `.joy-avatars-list` gap, overlap, or border styles in product CSS.
+7. **SHOULD** use `compress` with `size="small"` in dense toolbars; default spacing otherwise.
+8. **SHOULD** use identical `size` on all children in one list.
+9. **SHOULD** cap visible person avatars at three in selection UI and use `totalNumber` for overflow.
+
+### Valid API (from source)
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `compress` | `boolean` | `false` |
+
+| Slot | Purpose |
+| --- | --- |
+| `default` | `VJoyAvatar` instances |
+
+### Checklist
+
+- [ ] `VJoyAvatarsList` wraps multiple `VJoyAvatar` children (not a lone avatar unless required)
+- [ ] `compress` only on the list, never on avatars
+- [ ] Same `size` on every child in the set
+- [ ] Overflow via last child `totalNumber` — not combined with `fullName` / `photoUrl`
+- [ ] Selection UI: ≤ 3 faces + overflow chip + textual count when needed
+- [ ] No custom overlap / gap CSS on `.joy-avatars-list`
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyAvatarsList.dsds.json`](./JoyAvatarsList.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Layout modes (`compress`) | `variants` |
+| Child `size` consistency | `design-specifications` |
+| States | `states` |
+| Best practices / composition rules | `guidelines` |
+| Selection copy / overflow | `content` |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Storybook / source |

package/dist/doc/VJoyBadge/guideline.md

@@ -0,0 +1,169 @@
+---
+component: VJoyBadge
+status: draft
+language: en
+dsds: JoyBadge.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Badge
+
+Use **`VJoyBadge`** when you need a compact, colored label to communicate status, category, or metadata — for example “Active”, “Draft”, “Premium”, or a row state in a table.
+
+The badge renders short text from the `label` prop or default slot, with an optional leading bullet (`bulletpoint`) and a semantic `variant` color. It is presentational and non-interactive.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyBadge` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Badge](https://zeroheight.com/6bf479565/p/574c8a) |
+| **Storybook** | [VJoyBadge docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoybadge--docs) |
+| **DSDS (machine)** | [`JoyBadge.dsds.json`](./JoyBadge.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyBadge")` |
+
+---
+
+## When to use this component
+
+Use a badge when a short, scannable label should sit beside or inside content — table cells, list rows, card headers, or inline metadata — and color helps users spot status or category at a glance.
+
+Enable `bulletpoint` when design calls for a colored pastille before the label (common in data tables and status rows). Omit it for simpler chips where the pill background alone is enough.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Malt-specific user achievement or program status (SuperMalter, Verified, …) | `VJoyBadgeLevel` |
+| Removable filters, selectable chips, or skill tags | `VJoyTag` / `VJoyTagsList` |
+| Standalone notification count (numeric dot on an icon) | `VJoyDot` with `number` |
+| Clickable or dismissible token | `VJoyTag` (interactive) — `VJoyBadge` has no click or remove API |
+| Long descriptions or multi-sentence copy | `VJoyText` or inline body copy — badges stay short |
+| Custom pill markup with ad-hoc colors | Still use `VJoyBadge` + documented `variant` values |
+
+---
+
+## How it works
+
+`VJoyBadge` is a `<span role="status">` with pill styling (`joy-badge`, `joy-badge__{variant}`). When `bulletpoint` is true, a `VJoyDot` shares the same `variant` and sits to the left of the label.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-badge` pill; `role="status"` |
+| Label text | Yes* | `label` prop or default slot content |
+| Bullet (`VJoyDot`) | No | Colored dot when `bulletpoint` is true (`.joy-badge_dot`) |
+| Variant class | Yes | Background from `variant` (`joy-badge__{variant}`) |
+
+\*Provide text via `label` or the default slot — empty badges are possible but useless in product UI.
+
+### Variants (`variant`)
+
+Allowed values (`TJoyBadgeVariants` / `TJoyDotVariants`): `info`, `gray`, `green`, `orange`, `red`, `teal`, `pink`, `dark-blue`, `yellow`.
+
+| `variant` | Typical meaning | Background token |
+| --- | --- | --- |
+| `info` | Informational / default | `--joy-color-information-10` |
+| `gray` | Neutral / inactive | `--joy-color-neutral-20` |
+| `green` | Success / positive | `--joy-color-success-10` |
+| `orange` | Warning / attention | `--joy-color-warning-10` |
+| `red` | Primary emphasis / critical | `--joy-color-primary-10` |
+| `teal` | Secondary accent | `--joy-color-secondary-10` |
+| `pink` | Brand primary | `--joy-color-brand-primary-10` |
+| `dark-blue` | Brand secondary | `--joy-color-brand-secondary-10` |
+| `yellow` | Quaternary highlight | `--joy-color-quaternary-10` |
+
+Pick `variant` by **meaning in context**, not by which swatch looks best. The component docs mention `--badge-bg-color` and `--badge-circle-color` overrides — prefer documented variants before custom CSS.
+
+### Default values
+
+- `variant` defaults to **`info`**
+- `bulletpoint` defaults to **`false`**
+- `label` defaults to **`""`**
+
+Props and slots: use Joy MCP or Storybook — 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**).
+
+### Selection and content
+
+- **SHOULD** keep badge copy **short** (one or two words, or a compact count) — badges are not paragraphs.
+- **SHOULD** choose `variant` to match semantic intent (success, warning, neutral) so color reinforces the label.
+- **SHOULD** enable `bulletpoint` when the design system pattern expects a pastille (e.g. table status columns); hide it for plain pills.
+- **MUST NOT** use `VJoyBadge` for Malt profile achievements — use `VJoyBadgeLevel` with the correct `type`.
+
+### Implementation
+
+- **MUST** use only documented `variant` values from MCP or `JoyBadge.types.ts`.
+- **MUST** use Joy tokens — no custom `.joy-badge` chrome or hardcoded hex backgrounds in product CSS.
+- **MUST NOT** invent props (`size`, `clickable`, `removable`, …).
+- **SHOULD** use the `label` prop for plain strings; use the default slot when the label needs inline markup (keep it minimal).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `variant="green"` + label “Paid” for success | Random `red` because it “pops” |
+| `bulletpoint` in table status columns | Recreate pills with `<span>` + custom CSS |
+| `VJoyBadgeLevel` for SuperMalter / Verified | `VJoyBadge` for platform achievement icons |
+| `VJoyTag` for removable filter chips | `VJoyBadge` with click handlers wrapped around it |
+
+---
+
+## Accessibility
+
+Presentational status label — not interactive by default.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | `role="status"` on the root — suitable for status text; avoid stacking many live `status` regions that update constantly |
+| Name | Visible label text (`label` prop or default slot) is the accessible name |
+| Bullet | When `bulletpoint` is true, the dot is decorative if the text conveys the same status — don’t rely on color alone |
+| Interaction | No built-in keyboard or pointer handling — if the badge must be clickable, wrap it in a proper link/button with its own name |
+| Contrast | Text uses `--joy-color-neutral-50` on light variant backgrounds — don’t override text color without a design review |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyBadge } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Default informational badge -->
+  <VJoyBadge label="Draft" />
+
+  <!-- Success status with bullet (table-style) -->
+  <VJoyBadge variant="green" bulletpoint label="Approved" />
+
+  <!-- Slot for short custom content -->
+  <VJoyBadge variant="orange" bulletpoint>
+    Pending review
+  </VJoyBadge>
+
+  <!-- Neutral metadata -->
+  <VJoyBadge variant="gray" label="Archived" />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyBadge` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyBadgeLevel` | Malt-specific user or program recognition badges |
+| `VJoyTag` | Interactive, removable, or selectable chips |
+| `VJoyTagsList` | Horizontal list of tags |
+| `VJoyDot` | Standalone colored dot or numeric notification badge |
+| `VJoyText` | Longer supporting copy beside a badge |
+| `VJoyTooltip` | Optional clarification when icon-only or terse labels need context |

package/dist/doc/VJoyBadgeLevel/guideline.md

@@ -0,0 +1,166 @@
+---
+component: VJoyBadgeLevel
+status: draft
+language: en
+dsds: JoyBadgeLevel.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Badge level
+
+Use **`VJoyBadgeLevel`** when you need to show a Malt-specific user recognition level or program status — SuperMalter crowns, High Potential, Verified, Malt Linker, New, and related program badges.
+
+Each `type` renders a fixed SVG icon (when applicable) and an optional text label. Set `visibleText` to `false` for icon-only display, or use the default slot to override the built-in label.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyBadgeLevel` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyBadgeLevel docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoybadgelevel--docs) |
+| **DSDS (machine)** | [`JoyBadgeLevel.dsds.json`](./JoyBadgeLevel.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyBadgeLevel")` |
+
+---
+
+## When to use this component
+
+Use a badge level when the UI must communicate a **predefined Malt achievement or program status** tied to a freelancer or profile — for example SuperMalter tier, High Potential program membership, verified identity, Malt Linker designation, or a “New” profile marker.
+
+Typical placements: next to a user name in a card or list row, inside `VJoyUserCard`, or inline in profile headers where the recognition is part of the user’s identity rather than a generic tag.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Generic status, category, or count chips | `VJoyBadge` or `VJoyTag` |
+| Custom achievement graphics not in the Joy badge-level set | Confirm with design — don’t recreate badge SVGs in product CSS |
+| Interactive filters or removable tokens | `VJoyTag` / `VJoyTagsList` |
+| Availability or online status | `VJoyAvailability` |
+| Ad-hoc badge markup with copied SVG paths | Still use `VJoyBadgeLevel` + documented `type` values |
+
+> **Deprecated:** `type="highpotential"` (`JoyBadgeLevelEnum.HIGH_POTENTIAL`) — prefer `type="high-potential-auto"` or `type="program_high-potential"` for new work. Rendering matches High Potential today; only the keyword differs for program tracking.
+
+---
+
+## How it works
+
+`VJoyBadgeLevel` is a presentational `<span>`: one or more inline SVGs (depending on `type`) plus an optional `.joy-badge-level__tag` label. Label color is derived from `type` (`red`, `blue`, or `turquoise` modifier classes) — not a separate prop.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-badge-level` flex row (icon + label) |
+| SVG icon(s) | No* | Type-specific artwork; SuperMalter repeats 1–3 crown icons |
+| Text tag | No | `.joy-badge-level__tag` with built-in or slotted label |
+| Default slot | No | Overrides the computed label when `visibleText` is true |
+
+\*`new` and `verified` are label-only (no icon). Other types render at least one SVG.
+
+### Badge types (`type`)
+
+| `type` value | Icon | Default label | Tag color |
+| --- | --- | --- | --- |
+| `supermalter` | 1–3 crowns (`superMalterLevel`) | Supermalter | blue |
+| `highpotential` | Diamond | High Potential | blue |
+| `program_high-potential` | Diamond (program variant) | High Potential | blue |
+| `high-potential-auto` | Flame | High Potential Auto | red |
+| `maltlinker` | Linker mark | Malt Linker | red |
+| `new` | — | New | red |
+| `verified` | — | Verified | turquoise |
+
+### Default values
+
+- `type` is **required** — must be a `TJoyBadges` enum string
+- `superMalterLevel` defaults to **`1`** (only applies when `type="supermalter"`; valid range 1–3)
+- `visibleText` defaults to **`true`**
+
+Props and slots: use Joy MCP or Storybook — 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**).
+
+### Selection and data
+
+- **MUST** pass a documented `type` from `JoyBadgeLevelEnum` / `JoyBadgeProgramEnum` — never invent badge keywords.
+- **MUST** source `type` and `superMalterLevel` from backend/profile data; don’t hardcode achievement levels in the UI layer.
+- **SHOULD** use `:visible-text="false"` in dense layouts (avatars, compact list rows) when the icon alone is recognizable in context.
+- **SHOULD** keep the default English labels unless product copy requires localization — override via the default slot when translations differ.
+
+### Implementation
+
+- **MUST** use `VJoyBadgeLevel` as shipped — no custom SVG recreations or `.joy-badge-level__*` color overrides in product CSS.
+- **MUST NOT** invent props (`variant`, `size`, `color`, …).
+- **MUST NOT** use `type="highpotential"` on new features — use `high-potential-auto` or `program_high-potential`.
+- **SHOULD** pair with the user’s name or profile context so the badge meaning is clear without hover tooltips.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `type="supermalter"` + `superMalterLevel` from API | Always show 3 crowns regardless of level |
+| `:visible-text="false"` in tight headers | Shrink or recolor badge SVGs in app CSS |
+| Default slot for localized label text | Duplicate badge artwork in `<img>` or inline SVG |
+| `VJoyBadge` for generic “Pro” / status chips | `VJoyBadgeLevel` for non-Malt-specific labels |
+
+---
+
+## Accessibility
+
+Decorative presentational badge — not interactive by default.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Plain text/graphics in a `<span>` — no button or link role unless wrapped by the app |
+| Name | When `visibleText` is true, the visible label provides the text alternative; icon-only instances **SHOULD** sit beside a visible user name or have nearby text that conveys the same status |
+| Icon-only | Don’t rely on color or icon shape alone in isolation — ensure context (name, title, or adjacent copy) states the achievement |
+| Motion | Static SVGs — no animation in the component |
+| Links | If the badge is wrapped in a link, the **link** must have an accessible name; don’t make the badge itself the only clickable target without a label |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyBadgeLevel } from '@maltjoy/core-vue'
+
+// Example profile fields from an API
+const superMalterLevel = 2
+</script>
+
+<template>
+  <!-- SuperMalter with level from backend -->
+  <VJoyBadgeLevel type="supermalter" :super-malter-level="superMalterLevel" />
+
+  <!-- High Potential program badge -->
+  <VJoyBadgeLevel type="program_high-potential" />
+
+  <!-- Icon only in a compact row -->
+  <VJoyBadgeLevel type="verified" :visible-text="false" />
+
+  <!-- Localized label override -->
+  <VJoyBadgeLevel type="new">
+    Nouveau
+  </VJoyBadgeLevel>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyBadgeLevel` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyUserCard` | Profile row that may include badge level beside the user name |
+| `VJoyAvatar` | User photo/initials — badge level is usually adjacent, not inside the avatar |
+| `VJoyBadge` | Generic semantic badges (status, category, counts) |
+| `VJoyTag` | Removable or selectable chips, filters, skills |
+| `VJoyTooltip` | Optional extra explanation when icon-only badges need clarification |