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

package/dist/doc/VJoyDot/guideline.md

@@ -0,0 +1,177 @@
+---
+component: VJoyDot
+status: draft
+language: en
+dsds: JoyDot.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Dot
+
+Use **`VJoyDot`** when you need a compact colored indicator — a plain status dot or a small numeric badge for counts and notifications.
+
+It supports semantic color variants and optional `number` content (number or string). Size and colors come from Joy tokens; the component does not format values for you.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDot` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Joy](https://zeroheight.com/6bf479565/) (page id `8043088`) |
+| **Storybook** | [VJoyDot docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoydot--docs) |
+| **DSDS (machine)** | [`JoyDot.dsds.json`](./JoyDot.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDot")` |
+
+---
+
+## When to use this component
+
+Use a dot when a **small, non-interactive** visual cue is enough — for example an unread marker beside custom UI, a live-status bullet, or a standalone count pill outside higher-level Joy patterns.
+
+Plain dots (no `number`) work for binary or categorical status where color carries meaning and nearby text supplies context. With `number`, the dot grows into a pill-shaped badge for short counts (`1`, `12`, `99+`).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A labeled status chip with text | `VJoyBadge` (optionally with `bulletpoint` for the dot) |
+| Notification count on a tab | `notifications` on `VJoyTab` inside `VJoyTabs` (wired to `VJoyDot` internally) |
+| Multi-step or carousel progress | `VJoyIndicators` |
+| An actionable control | `VJoyButton`, `VJoyIconButton`, or `VJoyLink` |
+| Toast or inline feedback after an action | `pushVJoySnackbar` |
+| Custom `<span>` / CSS circle for the same job | Still use `VJoyDot` + Joy tokens — don’t reinvent chrome |
+
+> **Not in the API:** legacy docs sometimes describe automatic `99+` formatting. **`VJoyDot` renders the `number` prop as-is** (number or string). Cap or format large counts in application code before passing them in.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Container | Yes | Root `<div class="joy-dot">` with variant class (`joy-dot__{variant}`) |
+| Fill | Yes | Circular or pill background from Joy color tokens |
+| Number (`span`) | No | Shown when `number` is provided; adds `joy-dot__number` sizing |
+
+The component is **presentational only** — no slots, events, or interactive states.
+
+### Modes
+
+| Mode | When | Visual |
+| --- | --- | --- |
+| Plain dot | `number` omitted | 8px circle (`--joy-core-spacing-2`) |
+| Number badge | `number` set (including `0`) | Taller pill (`--joy-core-spacing-4`), `min-width: 16px`, centered label (`primary-250` typography) |
+
+### Default values
+
+- `variant` defaults to **`info`**
+- `number` defaults to **`undefined`** (plain dot)
+
+**Variants** (`TJoyDotVariants`): `info`, `gray`, `green`, `orange`, `red`, `teal`, `pink`, `dark-blue`, `yellow`. Pick by **semantic meaning**, not decoration — e.g. `green` for success, `orange` for warning, `pink` for brand / notification accents (as on tab badges).
+
+`pink` uses `--joy-color-brand-primary-70`; other variants use `--joy-color-{semantic}-50`, overridable via `--badge-circle-color` when embedded in badge-like contexts.
+
+Props: 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**).
+
+### When to show a dot
+
+- **SHOULD** pair plain dots with visible text or an accessible name on a parent control — color alone is not enough.
+- **SHOULD** use `VJoyBadge` when the status needs a readable label, not only color.
+- **SHOULD** use `VJoyTab` `notifications` for tab counts instead of hand-placing `VJoyDot` beside tab labels.
+- **SHOULD** keep numeric badges short — pre-format values like `99+` in app code when needed.
+- **MUST NOT** use a dot as the only indicator of critical information with no text alternative.
+
+### Implementation
+
+- **MUST** use only `variant` values from `TJoyDotVariants` / MCP / component types.
+- **MUST** use Joy tokens — no custom `.joy-dot` chrome (size, radius, background) in product CSS.
+- **MUST NOT** invent props (`size`, `color`, `label`, …).
+- **SHOULD** pass `number` as a number for counts and as a string only when you need suffixes (`99+`).
+- **SHOULD** use `variant="pink"` for notification-style counts to match tab and product patterns.
+- **MAY** set `--badge-circle-color` on an ancestor when a one-off brand override is required — prefer a documented `variant` first.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Plain dot + adjacent label text | Dot as the only status message |
+| `VJoyBadge` with `bulletpoint` for labeled status | Duplicate dot + separate text span |
+| `notifications` on `VJoyTab` for tab badges | Manual `VJoyDot` in tab chrome |
+| Format `99+` before passing `number` | Expect the component to cap counts |
+| Semantic `variant` for meaning | Random swatch per screen |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Decorative indicator — no native interactive role |
+| Name | **MUST NOT** rely on the dot alone for meaning; parent control or nearby text provides the accessible name |
+| Counts | When `number` conveys quantity, the **parent** should expose it (e.g. tab label + count, `aria-label` on a wrapping button) |
+| Color | Don’t use variant color as the only differentiator — reinforce with text or position |
+| Focus | Not focusable — don’t wrap a lone dot in a clickable element without an accessible name |
+| Motion | Static — no animation API |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyDot } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Plain status dot (pair with visible text) -->
+  <span class="status-row">
+    <VJoyDot variant="green" />
+    Online
+  </span>
+
+  <!-- Notification-style count -->
+  <VJoyDot variant="pink" :number="3" />
+
+  <!-- Pre-formatted large count -->
+  <VJoyDot variant="pink" number="99+" />
+
+  <!-- Zero is a valid count -->
+  <VJoyDot variant="info" :number="0" />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyDot` is already global.
+
+**Prefer composition over direct use** when Joy already wraps the pattern:
+
+```vue
+<!-- Tab notification — use VJoyTab API -->
+<VJoyTabs v-model:selected-tab="active">
+  <VJoyTab tab="inbox" label="Inbox" :notifications="5">…</VJoyTab>
+</VJoyTabs>
+
+<!-- Labeled status — use VJoyBadge -->
+<VJoyBadge variant="green" bulletpoint label="Active" />
+```
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyBadge` | Status text with optional bullet dot (`bulletpoint`) |
+| `VJoyTabs` / `VJoyTab` | Tab labels with notification counts (`notifications` → `VJoyDot`) |
+| `VJoyIndicators` | Step or slide progress dots |
+| `VJoyTooltip` | Explaining an icon or status the dot accompanies |
+| `VJoyButton` / `VJoyIconButton` | Actions — not status dots |

package/dist/doc/VJoyDrawer/guideline.md

@@ -0,0 +1,392 @@
+---
+component: VJoyDrawer
+status: draft
+language: en
+dsds: JoyDrawer.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Drawer
+
+Use **`VJoyDrawer`** when users need a secondary panel that slides in from the right — filters, item details, settings, or longer forms — without leaving the current page.
+
+It teleports to `body` by default, supports header/body/footer slots, optional confirm/cancel CTAs, and exposes async `show()` / `hide()` methods. Use **`VJoyDrawerTrigger`** when a declarative open trigger is simpler than imperative refs.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDrawer` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Drawer](https://zeroheight.com/6bf479565/) |
+| **Storybook** | [VJoyDrawer docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoydrawer--docs) |
+| **DSDS (machine)** | [`JoyDrawer.dsds.json`](./JoyDrawer.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDrawer")` |
+
+---
+
+## When to use this component
+
+Use a drawer when the user needs extra context or a sub-task on the same page — for example filtering a list, editing a record in context, or browsing details while keeping the main view visible (especially in `elevated` mode).
+
+Drawers slide in from the right and work well for exploratory or longer content that would feel cramped in a centered dialog.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Short, focused decision or confirmation | `VJoyDialog` |
+| Mobile bottom sheet from the screen edge | `VJoyBottomSheet` |
+| Lightweight contextual hint on hover/focus | `VJoyTooltip` |
+| Inline expandable section on the same page | Page layout or `VJoyCollapse` — not a drawer |
+| Toast / transient feedback after an action | `pushVJoySnackbar` |
+| Custom slide-over markup with ad-hoc CSS | Still use `VJoyDrawer` + Joy tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Overlay | Yes* | Semi-transparent backdrop; click dismisses (*hidden when `elevated`) |
+| Panel (`joy-drawer__inner`) | Yes | White panel with elevation, slides from the right |
+| Header (`drawer-header`) | Yes (content) | Drawer title — linked via `aria-labelledby` |
+| Subheader (`drawer-subheader`) | No | Supporting description below the title (`#drawerDescription`) |
+| Close button | Yes | Top-right `VJoyIconButton` (cross icon) |
+| Body (`drawer-body`) | Yes (content) | Main content; scrolls when tall |
+| Footer | No | Cancel / confirm CTAs via props or slots |
+| Preheader (`drawer-preheader`) | No | Declared in types/MCP but **not rendered** in the current Vue template — do not rely on it |
+
+### Default values
+
+- `size` defaults to **`default`** (580px panel width; `large` → 780px)
+- `open` defaults to **`false`**
+- `teleport` defaults to **`body`**
+- `preventBodyScroll` defaults to **`true`** (locks page scroll while open, when not `elevated`)
+- `elevated` defaults to **`false`**
+- `closeLabel` defaults to **`"Close drawer"`**
+- `buttonSize` defaults to **`medium`** (footer CTAs)
+- `cancelText` / `confirmText` default to **unset** (no footer buttons until provided)
+
+Props, events, slots, and exposed methods: use Joy MCP (`joy_get_component_info`, `joy_get_component_types`) or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Open / close lifecycle
+
+1. **Open** — set `open` or call `show()` on the exposed ref. Body scroll is prevented when `preventBodyScroll` is true and `elevated` is false.
+2. **Dismiss** — close icon, backdrop click, Escape key, or cancel CTA (default wiring). All fire `drawer:hide` when the leave transition starts.
+3. **Confirm** — default confirm CTA emits `drawer:confirm` only; you still handle persistence and closing.
+4. **Guard close** — `onBeforeHide` runs before any dismiss path; return `false` (or a resolved `false`) to keep the drawer open.
+5. **Unmount while open** — emits `drawer:before-unmount` and restores body scroll.
+
+`show()` and `hide()` are **async**. `hide({ fireHideEvent: false })` closes without emitting `drawer:hide`.
+
+---
+
+## Variants
+
+Drawers don't have color variants. Choose **overlay mode** and **size** by context.
+
+### Default (overlay)
+
+Modal backdrop blocks interaction with the page behind. Backdrop click, Escape, and the close icon all dismiss.
+
+Use when the drawer needs focused attention — filters, edits, or details that should not compete with the main surface.
+
+Avoid when the user must reference or interact with the page content at the same time.
+
+### Elevated (`elevated`)
+
+Removes the overlay and does not lock body scroll. The panel floats above the page; users can still interact with content behind it.
+
+Use when the drawer supports work on the main page — contextual editing, reference panels, or supplementary information.
+
+Avoid for high-stakes flows where accidental background interaction would cause errors.
+
+### Not in the API: `drawer-preheader`
+
+MCP and `defineSlots` list `drawer-preheader`, but the Vue template does not render it. Do not emit that slot until the component wires it. Use `drawer-header` / `drawer-subheader` instead.
+
+---
+
+## Sizes
+
+Panel width is token-driven inside the component — **don't hardcode pixel widths** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `default` | Standard drawers (580px on desktop) |
+| `large` | Wider content — tables, two-column forms, rich media (780px on desktop) |
+
+On viewports ≤ 767px the drawer becomes full-width. Footer CTAs stack vertically on very narrow widths (≤ 400px).
+
+Optional CSS overrides (use sparingly, with design approval):
+
+- `--drawer-width` — panel width
+- `--drawer-padding` — inner padding (all sides)
+
+> ZeroHeight labels the size table as "Height"; the implementation controls **width** (`--drawer-width`). Do not hardcode `580px` / `780px` in product CSS.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Closed | Not in DOM flow (`v-if="isOpen"`); no overlay |
+| Opening | Slide-in from the right (enter 300ms) |
+| Open | Overlay (unless `elevated`); focusable body; dismiss via close / backdrop / Escape / cancel |
+| Closing | Slide-out (leave 100ms); `drawer:hide` fires at start |
+| Closed (after transition) | Removed from DOM; `drawer:after-hide` fires; body scroll restored |
+| Elevated | No backdrop; page remains interactive |
+| Scrollable body | Long content scrolls inside the body region |
+| Footer present | `joy-drawer--footer-filled` when cancel/confirm props or slots are used |
+| Demo / docs | `demoMode` prevents hide (Storybook only — not for production) |
+
+Prefer `loading` on footer `VJoyButton` instances during async confirm work instead of silently disabling the drawer.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Hierarchy and placement
+
+- **SHOULD** use one drawer per task — don't stack unrelated slide-overs.
+- **SHOULD** prefer `elevated` only when background interaction is intentional.
+- **MUST NOT** use a drawer for a short yes/no confirm that fits a dialog.
+
+### Implementation
+
+- **MUST** use only documented props and enum values (MCP / `JoyDrawer.types.ts`).
+- **MUST** teleport to `body` in production (`teleport` default) — `disableTeleport` is for tests/docs.
+- **MUST** wire `hide()` when using custom `drawer-cancel` / `drawer-confirm` slots.
+- **MUST NOT** invent props (`width`, `variant`, `position`, …).
+- **MUST NOT** override `.joy-drawer` chrome (background, shadow, radius, overlay) with app CSS.
+- **MUST NOT** use `demoMode` outside Storybook.
+
+### Interaction
+
+- **MUST** provide a visible dismiss path (close icon and/or cancel CTA).
+- **SHOULD** use `onBeforeHide` when closing would discard unsaved changes.
+- **SHOULD** call `show()` / `hide()` with `await` when chaining transitions or focus management.
+- **SHOULD** listen to `drawer:after-open` before moving focus into the first field.
+
+### Footer CTAs
+
+- **SHOULD** use `cancelText` / `confirmText` for simple cases (default `VJoyButton` wiring: ghost cancel, `main` confirm).
+- **SHOULD** use `drawer-cancel` / `drawer-confirm` slots when you need custom variants, icons, or sizes — and **MUST** call `hide()` yourself on cancel.
+- **SHOULD** use one `main` confirm CTA per drawer surface (see `VJoyButton` guidelines).
+
+### Do / don't
+
+| Do | Don't |
+| --- | --- |
+| `VJoyDrawerTrigger` for simple open buttons | Reimplement overlay + z-index stack |
+| `elevated` when the page stays usable | Overlay mode for reference panels that need the page |
+| `onBeforeHide` for dirty forms | Silent data loss on backdrop click |
+| Explicit `closeLabel` when locale ≠ English default | Leave default "Close drawer" in localized apps |
+| `size="large"` for wide tables/forms | Hardcode `width: 780px` on a wrapper |
+| `VJoyDialog` for small confirms | A drawer for a one-line question |
+
+---
+
+## Content
+
+Drawer copy should orient the user quickly: what they're viewing or editing, and what happens when they confirm or dismiss.
+
+### Title formula
+
+**Short noun phrase** — state the topic or object, not the implementation:
+
+- ✅ Filter projects
+- ✅ Edit billing address
+- ✅ Project brief details
+
+**Subheader** — one sentence of context. Don't repeat the title.
+
+### Body copy
+
+- **SHOULD** keep body text scannable; link out for long help or legal content.
+- **MUST** explain consequences before destructive confirms in the body or subheader.
+- **SHOULD NOT** bury the primary action below long paragraphs.
+
+### Footer CTA rules
+
+Follow `VJoyButton` content rules. Drawer-specific expectations:
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Confirm CTA names the outcome — ✅ `Apply filters`, `Save changes` |
+| **MUST** | Cancel / dismiss CTA is neutral — ✅ `Cancel`, `Close` |
+| **MUST NOT** | Vague confirm — ❌ `OK`, `Yes` (unless the title is unmistakable) |
+| **SHOULD** | Destructive confirm repeats the object — ✅ `Delete project brief` |
+| **SHOULD** | ≤ 25 characters per button label; wrap, don't truncate |
+
+### Patterns
+
+**Filters** — Title names the list (`Filter projects`); body holds controls; confirm applies filters (`Apply filters`); cancel discards (`Cancel` or `Reset` via custom slot).
+
+**Details / read-only** — Title is the entity name; body is the content; optional single `Close` or ghost cancel; confirm only when an action exists.
+
+**Dirty form** — Use `onBeforeHide` to confirm abandonment; pair with clear cancel and save CTAs.
+
+**Localized apps** — Translate `closeLabel`, `cancelText`, `confirmText`, and all slot content. French copy may need articles/pronouns per `VJoyButton` FR guidance.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | `role="dialog"` with `aria-modal="true"` |
+| Name | Title in `drawer-header` referenced by `aria-labelledby` (`{id}-header`) |
+| Description | Subheader content in `#drawerDescription` when present |
+| Close control | `VJoyIconButton` with `closeLabel` (default: "Close drawer") |
+| Keyboard | **Escape** dismisses (calls `hide()`) |
+| Focus | Body region is focusable (`tabindex="0"`); move focus into the drawer on open when implementing custom flows |
+| Scroll | Page scroll locked while open when `preventBodyScroll` and not `elevated` |
+| Elevated | Background remains interactive — ensure users are not confused about what is modal |
+| Motion | Slide transitions (300ms enter / 100ms leave); respect `prefers-reduced-motion` at app level if required |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyDrawer } from '@maltjoy/core-vue'
+
+const drawer = ref<InstanceType<typeof VJoyDrawer>>()
+
+async function openDrawer() {
+  await drawer.value?.show()
+}
+
+async function onConfirm() {
+  // persist, then close
+  await drawer.value?.hide()
+}
+
+async function onBeforeHide() {
+  // return false to block close when form is dirty
+  return confirm('Discard unsaved changes?')
+}
+</script>
+
+<template>
+  <!-- Basic drawer with prop-driven CTAs -->
+  <VJoyDrawer
+    ref="drawer"
+    cancel-text="Cancel"
+    confirm-text="Apply filters"
+    :on-before-hide="onBeforeHide"
+    @drawer:confirm="onConfirm"
+  >
+    <template #drawer-header>Filter projects</template>
+    <template #drawer-subheader>Narrow results without leaving the list.</template>
+    <template #drawer-body>
+      <!-- filter controls -->
+    </template>
+  </VJoyDrawer>
+
+  <VJoyButton variant="primary" label="Filters" @click="openDrawer" />
+
+  <!-- Elevated — page stays interactive -->
+  <VJoyDrawer elevated>
+    <template #drawer-header>Quick reference</template>
+    <template #drawer-body>…</template>
+  </VJoyDrawer>
+
+  <!-- Custom footer CTAs (you must call hide on cancel) -->
+  <VJoyDrawer ref="customDrawer">
+    <template #drawer-header>Custom actions</template>
+    <template #drawer-body>…</template>
+    <template #drawer-cancel>
+      <VJoyButton variant="ghost" label="Cancel" @click="customDrawer?.hide()" />
+    </template>
+    <template #drawer-confirm>
+      <VJoyButton variant="main" label="Save" @click="onConfirm" />
+    </template>
+  </VJoyDrawer>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit imports if `VJoyDrawer` and `VJoyButton` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyDrawerTrigger` | Declarative open trigger wrapping any activator |
+| `VJoyDialog` | Centered modal; short confirms or focused forms |
+| `VJoyBottomSheet` | Mobile-optimized bottom sheet |
+| `VJoyButton` | Footer CTAs (default or custom slots) |
+| `VJoyIconButton` | Close control (built-in) |
+| `VJoyWrapper` | Footer CTA layout (built-in) |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyDrawer.dsds.json`](./JoyDrawer.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Side panel / filters / details | `VJoyDrawer` | Custom `position: fixed` slide-over |
+| Short modal confirm | `VJoyDialog` | `VJoyDrawer` for one-line questions |
+| Page stays interactive alongside panel | `VJoyDrawer` with `elevated` | Overlay drawer when user needs the page |
+| Simple open from a button | `VJoyDrawer` + `VJoyDrawerTrigger` | Inline overlay markup |
+| Mobile bottom sheet | `VJoyBottomSheet` | `VJoyDrawer` with hacked mobile CSS |
+| Unsaved changes on close | `onBeforeHide` | Silent backdrop dismiss |
+
+### Hard rules
+
+1. **MUST** call MCP (`joy_get_component_info`, `joy_get_component_types`) before generating props.
+2. **MUST** populate `drawer-header` (accessible name) for every drawer.
+3. **MUST** handle `hide()` when using `drawer-cancel` / `drawer-confirm` slots.
+4. **MUST NOT** invent props or sizes (`size` is only `default` \| `large`).
+5. **MUST NOT** set `demoMode` in product code.
+6. **MUST NOT** use `drawer-preheader` — not rendered in the Vue component.
+7. **MUST NOT** override `.joy-drawer` overlay, shadow, radius, or z-index in app CSS.
+8. **SHOULD** set localized `closeLabel` when UI language ≠ English.
+9. **SHOULD** `await` `show()` / `hide()` when coordinating focus or route changes.
+
+### Checklist
+
+- [ ] Correct component (`VJoyDrawer` or named alternative)
+- [ ] Props / enums from MCP only
+- [ ] `drawer-header` present; no `drawer-preheader`
+- [ ] Dismiss path defined (close and/or cancel)
+- [ ] Custom slots wire `hide()` on cancel
+- [ ] Confirm CTA label names the outcome
+- [ ] `elevated` only when background interaction is intended
+- [ ] `onBeforeHide` when close would discard data
+- [ ] `closeLabel` localized when needed
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyDrawer.dsds.json`](./JoyDrawer.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 |
+| Token sizing | `design-specifications` in JSON (`--drawer-width`, spacing tokens) |