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

package/dist/doc/VJoyTab/guideline.md

@@ -0,0 +1,298 @@
+---
+component: VJoyTab
+status: draft
+language: en
+dsds: JoyTab.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Tab
+
+Use **`VJoyTab`** as a **child of `VJoyTabs`** to define one switchable panel — its tab-button label, optional notification badge, optional link behavior, and the panel content shown when that tab is selected.
+
+`VJoyTab` does not render or manage the tab list by itself. `VJoyTabs` reads each child’s props and slots, builds the tab buttons (`TabButton`), and provides selection context so only the active panel is visible.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTab` from `@maltjoy/core-vue` (always inside `VJoyTabs`) |
+| **Design** | [ZeroHeight — Tabs](https://zeroheight.com/6bf479565/) |
+| **Storybook** | [VJoyTabs docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-navigation-vjoytabs--docs) (`VJoyTab` is a subcomponent) |
+| **DSDS (machine)** | [`JoyTab.dsds.json`](./JoyTab.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTab")` · parent: `joy_get_component_info("VJoyTabs")` |
+
+---
+
+## When to use this component
+
+Use `VJoyTab` for **each peer section** inside a `VJoyTabs` group — for example one tab per settings category, dashboard view, or profile subsection on the same page.
+
+Each instance declares the panel’s identity (`tab`), how its button should read (`label` or `header` slot), optional count badge (`notifications`), optional external navigation (`href`), and the panel body (default slot).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| The tab list + selection orchestration | `VJoyTabs` — `VJoyTab` is only the child panel primitive |
+| A standalone tab button or panel without `VJoyTabs` | Not supported — always compose `VJoyTabs` + `VJoyTab` |
+| Sequential steps with progress | `VJoyStepper` + `VJoyStep` |
+| Collapsible sections with visible headers | `VJoyCollapse` + `VJoyCollapseItem` |
+| Mutually exclusive form options | `VJoyRadioGroup` |
+| Primary app navigation | App shell patterns (`VJoyMenu`, sidebar, header nav) |
+| Custom tab markup / ad-hoc CSS for the same job | Still use `VJoyTabs` + `VJoyTab` + Joy tokens |
+
+---
+
+## How it works
+
+`VJoyTab` renders a **`role="tabpanel"`** container. It injects `VJoyTabs` context to know whether it is selected, hides itself when inactive (`display: none`), and exposes stable `id` / `aria-labelledby` hooks that match the tab button `VJoyTabs` builds from this child’s props.
+
+The tab **button** is not part of `VJoyTab`’s template — `VJoyTabs` renders `TabButton` using this child’s `tab`, `label`, `href`, `notifications`, and `header` slot.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Tab id (`tab`) | Yes | Unique string or number — selection key and ARIA id suffix |
+| Tab label | Yes (one of) | `label` prop **or** meaningful content in the `header` slot (wired by `VJoyTabs`) |
+| Tab panel | Yes | Default slot — main content for this section |
+| `header` slot | No | Custom tab-button content (icon + text, etc.) rendered in the tab list |
+| Notification badge | No | Pink `VJoyDot` count beside the label when `notifications` is a number (including `0`) |
+| Link tab | No | When `href` is set, the tab control is an `<a>` and does not change local selection on click |
+
+### Default values
+
+- `tab` is **required** — no default.
+- `label`, `href`, and `notification` default to **unset**.
+- Panel visibility follows parent `selectedTab` — there is no `open` / `selected` prop on `VJoyTab`.
+- Selected panel gets `margin-top: var(--joy-core-spacing-9)`; inactive panels are hidden.
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Composition
+
+```vue
+<VJoyTabs :selected-tab="activeTab" @update:selected-tab="activeTab = $event">
+  <VJoyTab tab="overview" label="Overview">…</VJoyTab>
+  <VJoyTab tab="details" label="Details">…</VJoyTab>
+</VJoyTabs>
+```
+
+- Place every `VJoyTab` in the **`VJoyTabs` default slot** (including via `v-for`).
+- Bind `selectedTab` on the parent and handle `update:selected-tab` for controlled selection.
+- Use the **`header` slot** when `label` alone is not enough (icon + text). Still provide a clear accessible name.
+- Set **`href`** only when activation should navigate away; local panels should omit it.
+
+> **API note:** `VJoyTab.vue` declares `notification` (boolean), but `VJoyTabs` reads **`notifications` (number)** for badge counts (see Storybook and tests). Prefer **`notifications`** until props and MCP align. A boolean `notification` prop does not drive the badge today.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Selected | Panel visible (`joy-tab__selected`); tab button shows active underline and bold label (via parent) |
+| Inactive | Panel hidden (`display: none`, `aria-hidden="true"`); tab button in default style |
+| Hover / focus-visible | On the tab **button** (parent) — subtle background; don’t strip focus styles in product CSS |
+| Link tab (`href`) | Tab control is an anchor; click navigates; local `selectedTab` is not updated on click |
+| Notifications | Pink `VJoyDot` beside the label when `notifications` is a number |
+
+There is **no disabled tab API** on `VJoyTab`. Hide unavailable sections, explain in the panel, or choose another pattern.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure / identity
+
+- **MUST** use `VJoyTab` only inside **`VJoyTabs`** — never as a standalone panel primitive.
+- **MUST** give every `VJoyTab` a **unique**, stable **`tab`** id across renders.
+- **MUST** ensure the parent’s `selectedTab` matches an existing `tab` id on mount.
+- **SHOULD** put the default / most-used section first in the tab order.
+- **MUST NOT** use `VJoyTab` for unrelated workflows that belong on separate routes.
+
+### Props and slots
+
+- **MUST** supply a tab name via **`label`** or a meaningful **`header` slot** — icon-only headers still need an accessible name.
+- **MUST** use **`notifications` (number)** for count badges — not the undocumented boolean `notification` prop.
+- **SHOULD** use `href` only when the tab truly navigates away (external URL or another route).
+- **MUST NOT** invent props (`variant`, `size`, `disabled`, `selected`, …) on `VJoyTab`.
+
+### Implementation
+
+- **MUST** use only documented props from Joy MCP / `VJoyTab.vue` / Storybook.
+- **MUST NOT** override `.joy-tab` display rules or tab-button chrome (`.joy-tab-button`) in product CSS.
+- **SHOULD** use `v-for` on `VJoyTab` when tabs are data-driven; `VJoyTabs` unwraps a single fragment child.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| One `VJoyTab` per panel inside `VJoyTabs` | Standalone `VJoyTab` without a parent |
+| Unique `tab` ids | Duplicate ids or unstable array indexes as ids when order changes |
+| `label` or `header` for every tab button | Empty tab buttons with no accessible name |
+| `notifications` as a number for counts | Boolean `notification` for badges |
+| `href` for real navigation | `href` on tabs that only swap local panels |
+| Panel content in the default slot | Putting panel content outside `VJoyTab` |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Panel root is `role="tabpanel"` |
+| Visibility | Inactive panels use `aria-hidden="true"`; only the selected panel is shown |
+| Association | Panel `id="joy-tab-panel-{tab}"`; `aria-labelledby="joy-tab-{tab}"` points to the tab button id built by `VJoyTabs` |
+| Naming | Tab name from `label` or `header` slot content on the corresponding button |
+| Keyboard | Tab-button activation is handled by `TabButton` (**Enter** on focused button); arrow-key roving is not built into the stock primitive |
+| Focus | Preserve visible `:focus-visible` on tab buttons — don’t remove focus rings in product CSS |
+| Links | `href` tabs are real anchors — destination and context must be clear |
+| Notifications | Count badges supplement the label; the label still names the section |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyTabs, VJoyTab, VJoyIcon } from '@maltjoy/core-vue'
+
+const activeTab = ref('overview')
+
+const sections = [
+  { id: 'overview', label: 'Overview', content: 'Overview content' },
+  { id: 'details', label: 'Details', content: 'Details content' },
+]
+</script>
+
+<template>
+  <!-- Basic panels -->
+  <VJoyTabs
+    :selected-tab="activeTab"
+    @update:selected-tab="activeTab = $event"
+  >
+    <VJoyTab tab="overview" label="Overview">
+      Overview content
+    </VJoyTab>
+    <VJoyTab tab="details" label="Details">
+      Details content
+    </VJoyTab>
+    <VJoyTab tab="activity" label="Activity" :notifications="3">
+      Activity content
+    </VJoyTab>
+  </VJoyTabs>
+
+  <!-- Custom header slot -->
+  <VJoyTabs selected-tab="alerts">
+    <VJoyTab tab="alerts" label="Alerts">
+      <template #header>
+        Alerts
+        <VJoyIcon name="bell" color="info" />
+      </template>
+      Alert content
+    </VJoyTab>
+    <VJoyTab tab="archive" label="Archive">
+      Archive content
+    </VJoyTab>
+  </VJoyTabs>
+
+  <!-- Link-style tab (no local panel content required) -->
+  <VJoyTabs selected-tab="local">
+    <VJoyTab tab="help" label="Help center" href="https://help.example.com" />
+    <VJoyTab tab="local" label="On this page">
+      Local panel content
+    </VJoyTab>
+  </VJoyTabs>
+
+  <!-- Data-driven tabs -->
+  <VJoyTabs :selected-tab="activeTab" @update:selected-tab="activeTab = $event">
+    <VJoyTab
+      v-for="section in sections"
+      :key="section.id"
+      :tab="section.id"
+      :label="section.label"
+    >
+      {{ section.content }}
+    </VJoyTab>
+  </VJoyTabs>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTabs` and `VJoyTab` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyTabs` | Required parent — tab list, selection, scroll, and `update:selected-tab` |
+| `VJoyStepper` | Sequential steps with progress, not peer panels |
+| `VJoyCollapse` / `VJoyCollapseItem` | Expand/collapse sections with always-visible headers |
+| `VJoyLink` | Inline navigation inside panel content |
+| `VJoyDot` | Notification count on tab buttons (used internally via `notifications`) |
+| `VJoyIcon` | Icons inside the `header` slot |
+
+---
+
+## For agents
+
+Maps to `agentDocumentBlocks` in [`JoyTab.dsds.json`](./JoyTab.dsds.json). Humans can skip this section.
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| One panel in a tabbed surface | `VJoyTab` inside `VJoyTabs` | Standalone `VJoyTab` |
+| The full tabbed UI | `VJoyTabs` + `VJoyTab` children | Hand-rolled `role="tab"` markup |
+| Multi-step wizard | `VJoyStepper` | `VJoyTab` for funnel steps |
+| Navigate away on tab click | `VJoyTab` with `href` | Local panel + fake link button |
+| Form mutually exclusive options | `VJoyRadioGroup` | `VJoyTab` inside a single field |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyTab")` and `joy_get_component_info("VJoyTabs")` (or read Storybook) before generating props.
+2. **MUST** always emit **`VJoyTab`** inside **`VJoyTabs`** default slot — one child per panel.
+3. **MUST** set **`tab`** (unique id) on every `VJoyTab`; parent binds **`selectedTab`** / **`@update:selected-tab`**.
+4. **MUST** use **`notifications` (number)** for badge counts — not `notification` (boolean).
+5. **MUST NOT** invent `variant`, `size`, `disabled`, `selected`, or other undocumented props.
+6. **MUST NOT** override `.joy-tab` or `.joy-tab-button` display or colors in product CSS.
+7. **SHOULD** use `label` unless the `header` slot is required (icon + text).
+8. **SHOULD** set `href` only when navigation is intentional.
+
+### Checklist
+
+- [ ] `VJoyTabs` parent present — not standalone `VJoyTab`
+- [ ] Unique `tab` id on every `VJoyTab`
+- [ ] Parent `selectedTab` matches an existing `tab` id; handle `update:selected-tab`
+- [ ] `label` or accessible `header` slot on every tab
+- [ ] Props from MCP / Storybook only — no invented enums
+- [ ] `notifications` is a number when a badge is needed
+- [ ] `href` only when navigation is intentional
+- [ ] No custom tab / panel chrome CSS
+- [ ] Panel content in the default slot
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyTab.dsds.json`](./JoyTab.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| States | `states` |
+| Best practices | `guidelines` |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Parent composition | `relationships` in JSON (with `VJoyTabs`) |

package/dist/doc/VJoyTabs/guideline.md

@@ -0,0 +1,353 @@
+---
+component: VJoyTabs
+status: draft
+language: en
+dsds: JoyTabs.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Tabs
+
+Use **`VJoyTabs`** when related content on the same surface should be split into switchable panels — for example profile sections, settings categories, or dashboard views — without leaving the page.
+
+It composes **`VJoyTab`** children for each panel, manages the selected tab, supports notification badges, custom tab headers, horizontal scroll when labels overflow, and optional link-style tabs via `href`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTabs` + `VJoyTab` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Tabs](https://zeroheight.com/6bf479565/) |
+| **Storybook** | [VJoyTabs docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-navigation-vjoytabs--docs) |
+| **DSDS (machine)** | [`JoyTabs.dsds.json`](./JoyTabs.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTabs")` · `joy_get_component_info("VJoyTab")` |
+
+---
+
+## When to use this component
+
+Use tabs when users need to move between **peer sections of content** on one screen — each section is substantial enough to deserve its own panel, but not important enough to be a separate route.
+
+Tabs work well for organizing articles vs. videos, overview vs. details, or settings groups that share the same page context. Notification badges can highlight unseen items inside a section.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A linear multi-step flow with progress | `VJoyStepper` |
+| Primary app or site navigation | App shell patterns (`VJoyMenu`, sidebar, header nav) |
+| Mutually exclusive choices inside a form | `VJoyRadioGroup` or `VJoySegmentedControl` (if available) |
+| Inline navigation inside body copy | `VJoyLink` |
+| Filtering a single list without separate panels | Filters, chips, or sort controls |
+| More than ~5–7 peer sections on desktop | Rework IA — split across pages, use a menu, or nest content |
+| Custom tab markup / ad-hoc CSS for the same job | Still use `VJoyTabs` + `VJoyTab` + Joy tokens |
+
+---
+
+## How it works
+
+`VJoyTabs` renders a **tab list** from its `VJoyTab` children, shows one panel at a time, and coordinates selection through a provided context. Tab buttons are built internally (`TabButton`); panel content comes from each `VJoyTab` default slot.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Tab list wrapper | Yes | Scrollable row of tab buttons (`role="tablist"`) |
+| Tab button | Yes (per tab) | `<button type="button">` or `<a>` when `href` is set (`role="tab"`) |
+| Tab label | Yes (per tab) | Text from `label` or the `header` slot on `VJoyTab` |
+| Notification badge | No | `VJoyDot` count beside the label when `notifications` is a number |
+| Tab panel | Yes (per tab) | Content area (`role="tabpanel"`) — only the selected panel is visible |
+| Scroll fade | No | Left/right gradient when tab labels overflow horizontally |
+
+### Default values
+
+- `selectedTab` on `VJoyTabs` has **no default** — set it to the `tab` id of the initially active panel.
+- Each `VJoyTab` **must** have a unique `tab` id (string or number).
+- `label` on `VJoyTab` is optional when the `header` slot supplies the button content.
+- `--tabs-buttons-wrapper-min-width` defaults to **`250px`**; `--tabs-buttons-list-width` defaults to **`auto`**.
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Composition
+
+```vue
+<VJoyTabs :selected-tab="activeTab" @update:selected-tab="activeTab = $event">
+  <VJoyTab tab="overview" label="Overview">…</VJoyTab>
+  <VJoyTab tab="details" label="Details">…</VJoyTab>
+</VJoyTabs>
+```
+
+- **`VJoyTab`** children go in the `VJoyTabs` default slot (including via `v-for`).
+- Bind `selectedTab` and listen for `update:selected-tab` for controlled selection (same pattern as `v-model:selected-tab`).
+- When a `VJoyTab` has `href`, its control renders as a link and **does not** change the local selected tab on click.
+
+---
+
+## Variants
+
+`VJoyTabs` has **no variant or emphasis prop**. Visual treatment is fixed: neutral inactive tabs, primary-colored underline and bold label on the selected tab, hover/focus background on tab buttons.
+
+Do not simulate “primary / secondary tabs” with custom CSS — use the component as shipped.
+
+---
+
+## Sizes
+
+`VJoyTabs` has **no size prop**. Tab button typography uses `--joy-font-size-primary-400` (smaller on viewports ≤ 767px). Control density with layout and the CSS custom properties below — **do not hardcode font sizes or tab heights** in product CSS.
+
+| Mechanism | Use when |
+| --- | --- |
+| Default layout | Most product surfaces |
+| `--tabs-buttons-list-width` | Force a minimum scroll width on narrow containers (e.g. side panels) |
+| `--tabs-buttons-wrapper-min-width` | Adjust the scroll area floor (default 250px; avoid going far above ~300px per design notes) |
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (inactive tab) | Neutral label; panel hidden (`display: none`) |
+| Selected | Bold primary label, active underline, panel visible |
+| Hover / focus-visible | Subtle background on the tab button |
+| Link tab (`href` set) | Anchor styled like other tabs; navigates on activation |
+| Notifications | Pink `VJoyDot` beside the label when `notifications` is a number (including `0`) |
+| Scroll overflow | Horizontal scroll on the tab row; fade gradients at start/end when more tabs are off-screen |
+
+There is **no disabled tab API**. If a section is unavailable, hide the tab, explain in the panel, or choose a different pattern.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure / selection
+
+- **MUST** give every `VJoyTab` a **unique** `tab` id stable across renders.
+- **MUST** set `selectedTab` to a valid `tab` id when the component mounts.
+- **SHOULD** keep tab count modest (roughly **2–5** on desktop; up to ~7 only when labels stay scannable).
+- **SHOULD** order tabs by importance or natural reading order — put the default / most-used panel first.
+- **MUST NOT** use tabs for unrelated workflows that belong on separate routes.
+
+### Implementation
+
+- **MUST** compose `VJoyTabs` with `VJoyTab` children — not free-form buttons + divs.
+- **MUST** use only documented props (Joy MCP / Storybook). No `variant`, `size`, or `disabled` props exist.
+- **MUST** style with Joy tokens and documented CSS variables — no custom `.joy-tab-button` chrome overrides.
+- **MUST NOT** invent props on `VJoyTabs` or `VJoyTab`.
+- **SHOULD** use `v-for` on `VJoyTab` when tabs are data-driven; `VJoyTabs` unwraps a single fragment child.
+
+### Link tabs
+
+- **SHOULD** use `href` on `VJoyTab` only when the tab truly navigates away (external URL or another route).
+- **MUST NOT** mix link tabs and local panels without a clear UX reason — prefer all local or all navigational.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Parallel, short tab labels | Long sentences or inconsistent grammar across tabs |
+| `update:selected-tab` for controlled state | Mutating selection only inside panel content |
+| `header` slot for icons + label together | Icon-only tabs with no accessible name |
+| Scroll-friendly labels on narrow layouts | Ten equal-priority tabs across one row |
+| `notifications` for actionable counts | Decorative dots without meaning |
+
+---
+
+## Content
+
+Tab labels are navigation — they name **where** the user is going within the surface, not what they will do there.
+
+### Label formula
+
+**Short noun phrase** (or tight noun + qualifier), **parallel across tabs**:
+
+- ✅ Overview · Details · Activity  
+- ✅ Profile · Billing · Security  
+- ✅ All · Unread (12)  
+
+Use the same part of speech and level of detail for every tab in the set.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Keep labels scannable — aim for **≤ 20 characters**; never truncate with ellipsis |
+| **MUST** | Use **sentence case** (or product locale rules) consistently across the set |
+| **MUST** | Make each label distinct — no two tabs that differ only by punctuation |
+| **MUST NOT** | Use verbs alone as tab titles — ❌ `View`, `Manage` (save verbs for buttons inside panels) |
+| **MUST NOT** | Repeat the page title in every tab — ❌ `Project settings — General` / `Project settings — Team` → ✅ `General` / `Team` |
+| **SHOULD** | Prefer **2–4 words** maximum |
+| **SHOULD** | Put counts in `notifications` or inline in the `header` slot — ✅ `Messages` + badge `3` |
+| **SHOULD** | Name the content type, not the UI — ✅ `Invoices` · ❌ `Tab 2` |
+| **SHOULD** (FR) | Keep articles when grammar requires them — _Mon profil_, _Facturation_ |
+
+### Patterns
+
+**Settings / profile** — Group by domain (`Account`, `Notifications`, `Privacy`). Default tab = the section users open most often.
+
+**Dashboard sections** — Name the artifact (`Pipeline`, `Performance`, `Team`). Avoid marketing copy in tab labels.
+
+**Workflow stages with alerts** — Use `notifications` for items needing attention inside a stage; keep the label itself short (`Reviews`, `Pending`).
+
+**Custom headers** — When using the `header` slot (icon + text), still provide a clear accessible name; don’t rely on icon shape alone.
+
+**Link tabs** — Label should describe the destination (`Help center`, `Open in admin`), not an in-page section.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Roles | Tab list (`role="tablist"`), tabs (`role="tab"`), panels (`role="tabpanel"`) |
+| Naming | Tab name from `label` or `header` slot content |
+| Selection | `aria-selected="true"` on the active tab; inactive panels use `aria-hidden="true"` |
+| Association | Panel `aria-labelledby` points to `id="joy-tab-{tab}"`; panel `id="joy-tab-panel-{tab}"` |
+| Keyboard | **Enter** activates a focused tab button; implement arrow-key roving tabindex in product only if you extend the primitive — the stock component does not add Left/Right handlers |
+| Focus | Preserve visible `:focus-visible` styles — don’t remove tab button focus rings |
+| Links | `href` tabs are real anchors — ensure destination and context are clear |
+| Notifications | Count badges should not be the only indicator of meaning; label still names the section |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyTabs, VJoyTab, VJoyIcon } from '@maltjoy/core-vue'
+
+const activeTab = ref('overview')
+</script>
+
+<template>
+  <!-- Controlled selection -->
+  <VJoyTabs
+    :selected-tab="activeTab"
+    @update:selected-tab="activeTab = $event"
+  >
+    <VJoyTab tab="overview" label="Overview">
+      Overview content
+    </VJoyTab>
+    <VJoyTab tab="details" label="Details">
+      Details content
+    </VJoyTab>
+    <VJoyTab tab="activity" label="Activity" :notifications="3">
+      Activity content
+    </VJoyTab>
+  </VJoyTabs>
+
+  <!-- Custom header slot -->
+  <VJoyTabs selected-tab="alerts">
+    <VJoyTab tab="alerts" label="Alerts">
+      <template #header>
+        Alerts
+        <VJoyIcon name="bell" color="info" />
+      </template>
+      Alert content
+    </VJoyTab>
+    <VJoyTab tab="archive" label="Archive">
+      Archive content
+    </VJoyTab>
+  </VJoyTabs>
+
+  <!-- Link-style tab -->
+  <VJoyTabs selected-tab="local">
+    <VJoyTab tab="external" label="Help center" href="https://help.example.com" />
+    <VJoyTab tab="local" label="On this page">
+      Local panel content
+    </VJoyTab>
+  </VJoyTabs>
+
+  <!-- Data-driven tabs -->
+  <VJoyTabs :selected-tab="activeTab" @update:selected-tab="activeTab = $event">
+    <VJoyTab
+      v-for="section in sections"
+      :key="section.id"
+      :tab="section.id"
+      :label="section.label"
+    >
+      {{ section.content }}
+    </VJoyTab>
+  </VJoyTabs>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTabs` and `VJoyTab` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyTab` | Required child — defines each panel, label, badge, and optional `href` / `header` |
+| `VJoyStepper` | Sequential steps with progress, not peer sections |
+| `VJoyMenu` / `VJoyMenuItem` | Many actions or navigation targets in a dropdown |
+| `VJoyLink` | Inline text links inside panel content |
+| `VJoyDot` | Notification count on tab buttons (used internally) |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyTabs.dsds.json`](./JoyTabs.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Peer content panels on one surface | `VJoyTabs` + `VJoyTab` children | Hand-rolled `role="tab"` markup |
+| Multi-step wizard with progress | `VJoyStepper` | `VJoyTabs` for linear funnel steps |
+| Form field mutually exclusive options | `VJoyRadioGroup` | `VJoyTabs` inside a single field |
+| Navigate away from the page | `VJoyTab` with `href` or `VJoyLink` in content | `VJoyTabs` panel for external-only destinations |
+| Primary site navigation | Shell nav / menu patterns | `VJoyTabs` in the global header |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyTabs")` and `joy_get_component_info("VJoyTab")` (or read Storybook) before generating props.
+2. **MUST** always emit **`VJoyTab`** inside **`VJoyTabs`** default slot — one child per panel.
+3. **MUST** set `tab` (unique id) on every `VJoyTab` and bind `selectedTab` / `@update:selected-tab` for controlled usage.
+4. **MUST** use `notifications` (number) on `VJoyTab` for count badges — wired to `VJoyDot` via `VJoyTabs`.
+5. **MUST NOT** invent `variant`, `size`, `disabled`, or other undocumented props.
+6. **MUST NOT** override `.joy-tab-button`, `.joy-tabs-buttons`, or panel display rules with custom CSS.
+7. **SHOULD** default `selectedTab` to the first / primary section’s `tab` id.
+8. **SHOULD** use the `header` slot only when `label` alone is insufficient (icon + text).
+
+> **API note:** Joy MCP may list `notification` (boolean) on `VJoyTab`. The implementation path used by Storybook and tests is **`notifications` (number)** on `VJoyTab`. Emit `notifications` until types and MCP align.
+
+### Checklist
+
+- [ ] `VJoyTabs` + one `VJoyTab` per panel (not standalone `VJoyTab`)
+- [ ] Unique `tab` id on every `VJoyTab`
+- [ ] `selectedTab` matches an existing `tab` id; handle `update:selected-tab`
+- [ ] Props from MCP / Storybook only — no invented enums
+- [ ] No custom tab chrome CSS
+- [ ] Tab labels short, parallel, and meaningful (not `Tab 1`)
+- [ ] `href` only when navigation is intentional
+- [ ] `notifications` is a number when a badge is needed
+- [ ] Custom `header` slot still provides an accessible tab name
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyTabs.dsds.json`](./JoyTabs.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 |
+| Scroll / layout tokens | `design-specifications` in JSON |