@design-ai/cli 4.55.0

package/examples/component-doc-page.md

@@ -0,0 +1,217 @@
+# `DocPage` (full doc page layout) — spec
+
+> The canonical layout for a single documentation page. Header + sidebar + body + right TOC + footer. Shipped by most doc-site frameworks (Docusaurus, Nextra, Mintlify, GitBook).
+
+## Purpose
+
+Standard layout for documentation sites. Differs from product app `Layout` ([`component-layout.md`](component-layout.md)) — DocPage is optimized for reading prose.
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│ [Brand]  [Search Cmd+K]  [Versions] [GitHub] [Theme]               │  ← top bar
+├──────────────┬─────────────────────────────────────────┬───────────┤
+│              │ Breadcrumb · Updated 2026-05-08          │           │
+│ Sidebar nav  │                                          │ TOC       │
+│              │ # Title                                  │           │
+│ ▸ Section A  │                                          │ ▸ Anatomy │
+│   ▸ Page 1   │ Lede paragraph (2 sentences).            │ ▸ API     │
+│   ● Page 2   │                                          │ ▸ States  │
+│ ▸ Section B  │ ## Anatomy                               │ ▸ Examples│
+│              │ ...                                      │           │
+│              │                                          │           │
+│              │ ## API                                   │           │
+│              │ ...                                      │           │
+│              │                                          │           │
+│              │ ── Prev / Next ───────────────────────── │           │
+│              │ "Edit this page on GitHub"               │           │
+└──────────────┴─────────────────────────────────────────┴───────────┘
+```
+
+| Region | Width | Sticky? |
+| --- | --- | --- |
+| Top bar | full | yes |
+| Sidebar (left) | 240–280px | yes |
+| Main body | 720–800px | no |
+| TOC (right) | 200–240px | yes |
+| Footer / prev-next | matches body | no |
+
+## API
+
+```tsx
+<DocPage
+  meta={{
+    title: "Button",
+    description: "The most-used UI control.",
+    lastUpdated: "2026-05-08",
+    editUrl: "https://github.com/.../button.mdx",
+  }}
+  sidebar={navTree}
+  prevPage={{ title: "Avatar", href: "../avatar" }}
+  nextPage={{ title: "Card", href: "../card" }}
+>
+  {/* MDX content */}
+</DocPage>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `meta` | `{ title, description?, lastUpdated?, editUrl? }` | — | Page metadata |
+| `sidebar` | `NavNode[]` | — | Left nav tree |
+| `tocItems` | `{ id, level, text }[]` | derived from headings | Right TOC |
+| `prevPage` / `nextPage` | `{ title, href }` | — | Footer pagination |
+| `breadcrumb` | `BreadcrumbNode[]` | derived from URL | |
+| `children` | `ReactNode` | — | Page MDX content |
+
+## Sidebar nav
+
+The left column. Lists site sections + pages within. Cite [`knowledge/patterns/information-architecture.md`](../knowledge/patterns/information-architecture.md):
+
+- Max 3 levels deep.
+- Active page highlighted (filled bg, primary text color).
+- Active section auto-expanded.
+- Collapsible on mobile.
+- Sticky on desktop.
+
+```tsx
+const sidebar = [
+  {
+    title: "Getting started",
+    children: [
+      { title: "Installation", href: "/install" },
+      { title: "Quick start", href: "/quickstart" },
+    ],
+  },
+  {
+    title: "Components",
+    children: [
+      { title: "Button", href: "/components/button" },
+      { title: "Card", href: "/components/card" },
+    ],
+  },
+];
+```
+
+## Right TOC (in-page)
+
+Shows headings on the current page. Active section highlighted as user scrolls.
+
+Cite [`examples/component-anchor.md`](component-anchor.md) — Anchor pattern. Default: show h2 + h3 only (h4+ creates noise).
+
+## Body content
+
+Cite [`knowledge/patterns/document-typography.md`](../knowledge/patterns/document-typography.md):
+
+- Body 18px, line-height 1.6.
+- Max-width ~720px.
+- Headings with consistent vertical rhythm.
+- Code blocks with copy button.
+- Callouts where appropriate.
+
+## Footer pagination
+
+```
+┌─────────────────────────────────────────────┐
+│ ← Avatar                       Card →        │
+└─────────────────────────────────────────────┘
+```
+
+Linear nav for sequential learners. Each link shows title; arrow direction indicates flow.
+
+## "Edit on GitHub"
+
+Link below the body or in a metadata strip. Open the source MDX for editing on GitHub.
+
+```tsx
+<a href={meta.editUrl}>Edit this page on GitHub</a>
+```
+
+For community contribution: this link is high-leverage.
+
+## Search
+
+Cmd+K → opens search overlay. See [`knowledge/patterns/search-ux.md`](../knowledge/patterns/search-ux.md).
+
+For doc sites: integrate Algolia DocSearch (free for OSS), MeiliSearch, or Pagefind (no-server static search).
+
+## Mobile patterns
+
+Below `md` breakpoint:
+- Sidebar collapses to drawer (`☰` opens).
+- TOC hidden (replaced by floating "Sections" button OR inline at top of page).
+- Body full-width minus margin.
+
+## Theme toggle
+
+Light / dark / system. Toggle in top-right.
+
+For docs: dark mode is essential — many devs read docs at night, or prefer dark editors.
+
+```tsx
+<ThemeToggle current={theme} onChange={setTheme} />
+```
+
+## Tokens consumed
+
+Inherits from the broader design system. Doc-specific:
+
+```
+--color-bg-default
+--color-bg-elevated         (sidebar bg, slightly different from body)
+--color-bg-subtle           (hover states)
+--color-text-primary, --color-text-secondary, --color-text-tertiary
+--color-primary-default     (active sidebar item)
+--color-border-default      (between regions)
+--space-* full scale
+--font-* full scale (body 18px)
+--shadow-card               (mobile drawer)
+--motion-default
+```
+
+## Accessibility
+
+- Top bar: `<header>` with `<nav aria-label="Site">`.
+- Sidebar: `<aside>` or `<nav aria-label="Documentation">`.
+- Body: `<main id="main-content">`.
+- TOC: `<aside aria-label="On this page">`.
+- Footer: `<footer>`.
+- Skip link: "Skip to main content" before sidebar (keyboard users skip nav).
+
+## Versioning UI
+
+For docs with multiple versions:
+- Version selector in top bar (dropdown).
+- Banner on older-version pages: "You're viewing v1. The latest is v2 → [link]."
+- 301 redirects from old URLs.
+
+## Frameworks
+
+| Framework | Best for |
+| --- | --- |
+| **Docusaurus** | OSS docs, MDX, well-maintained |
+| **Nextra** | Next.js apps, MDX, modern |
+| **Mintlify** | Hosted, paid, polished |
+| **GitBook** | Hosted, non-engineer-friendly |
+| **VitePress** | Vue ecosystem, fast |
+| **Starlight** | Astro ecosystem |
+
+For design-ai's docs: any of these works. Pick one.
+
+## Don't
+
+- Don't ship without search. Doc sites without search are unusable past 30 pages.
+- Don't omit "Edit on GitHub" — drives community contributions.
+- Don't break URLs on doc reorgs (301 redirect).
+- Don't use full-width body for prose. Cap at ~720px.
+- Don't omit dark mode.
+- Don't have 4+ sidebar levels.
+
+## Cross-reference
+
+- [`knowledge/patterns/information-architecture.md`](../knowledge/patterns/information-architecture.md) — IA + nav
+- [`knowledge/patterns/document-typography.md`](../knowledge/patterns/document-typography.md) — body text rules
+- [`knowledge/patterns/search-ux.md`](../knowledge/patterns/search-ux.md) — search input
+- [`examples/component-anchor.md`](component-anchor.md) — TOC pattern
+- [`examples/component-breadcrumb.md`](component-breadcrumb.md) — breadcrumb
+- [`examples/component-layout.md`](component-layout.md) — product app layout (different)

package/examples/component-drawer.md

@@ -0,0 +1,257 @@
+# `Drawer` — spec
+
+> Citing Ant Design `Drawer`, MUI `Drawer`, shadcn-ui `sheet` (which the Modal spec covers as Sheet variant)
+
+## Purpose
+
+A panel that slides in from a screen edge, covering part of the page. Used for navigation menus, edit panels, filters, and detail-without-leaving-context.
+
+This is **different from Modal** — a modal centers and blocks; a drawer slides from an edge and can be dismissed by clicking outside or swiping.
+
+In shadcn-ui, this primitive is called "Sheet" — see [`examples/component-modal.md`](component-modal.md) which treats Sheet as a variant of Modal. This spec covers the **navigation drawer** specifically: persistent or persistent-in-context navigation panels, distinct from one-shot edit sheets.
+
+## When Drawer vs Modal vs Sheet
+
+| Pattern | Use |
+| --- | --- |
+| **Drawer** (this spec) | Persistent or repeatedly-accessed navigation panel. Slides from screen edge. May be persistent (visible always above tablet width). |
+| **Sheet / Modal** (see modal spec) | One-shot edit / form / decision. Slides in for one task, dismisses. |
+| **Popover** | Small, attached to a trigger element. |
+
+The line: a Drawer often holds the app's secondary navigation (sidebar). A Sheet holds a one-time interaction.
+
+## Anatomy
+
+```
+┌─────────┬──────────────────────────────────────┐
+│  Drawer │                                       │
+│         │                                       │
+│  ──     │   Main content                        │
+│  Nav 1  │                                       │
+│  Nav 2  │                                       │
+│  Nav 3  │                                       │
+│         │                                       │
+│         │                                       │
+│  Footer │                                       │
+└─────────┴──────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Header | optional | Title + close button OR account info (in nav drawers) |
+| Body | yes | Scrollable content (nav links, list, etc.) |
+| Footer | optional | Pinned to bottom — settings, logout, version |
+
+## API
+
+```tsx
+<Drawer
+  open={open}
+  onOpenChange={setOpen}
+  side="left"
+  size="md"
+  modal={true}
+  persistent={false}
+>
+  <Drawer.Header>
+    <Drawer.Title>Menu</Drawer.Title>
+    <Drawer.Close />
+  </Drawer.Header>
+  <Drawer.Body>
+    <NavList />
+  </Drawer.Body>
+  <Drawer.Footer>
+    <UserCard />
+  </Drawer.Footer>
+</Drawer>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` / `defaultOpen` | `boolean` | — | |
+| `onOpenChange` | `(open: boolean) => void` | — | |
+| `side` | `"left" \| "right" \| "top" \| "bottom"` | `"left"` | Edge to anchor |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` or width/height | `"md"` | |
+| `modal` | `boolean` | `true` | If true, backdrop + scroll lock + focus trap. If false, persistent / inline drawer. |
+| `persistent` | `boolean` | `false` | When true on tablet+ widths, drawer is always visible (no slide-in/out). |
+| `dismissOnOutsideClick` | `boolean` | `true` (when modal) | |
+| `swipeToDismiss` | `boolean` | `true` on mobile | iOS-native swipe-to-close gesture |
+
+## Sizes
+
+| Side: left/right | Width |
+| --- | --- |
+| `sm` | 240px |
+| `md` (default) | 320px |
+| `lg` | 400px |
+| `xl` | 480px |
+
+| Side: top/bottom | Height |
+| --- | --- |
+| `sm` | 25% viewport |
+| `md` | 50% |
+| `lg` | 75% |
+| `xl` | 90% |
+
+For mobile bottom drawers (sheets): `md` with detents (drag handle, snap to multiple sizes).
+
+## Persistent vs modal mode
+
+### Modal drawer (default)
+
+- Backdrop behind drawer (50% black scrim)
+- Closes on backdrop click, Escape, swipe (mobile)
+- Body scroll locked while open
+- Focus trap inside drawer
+
+### Persistent drawer
+
+For desktop apps where the sidebar is always visible above tablet width:
+
+```
+< sm: hidden, opens via menu button (modal mode)
+≥ md: persistent, always visible
+
+@media (min-width: 768px) {
+  .drawer { transform: translateX(0); position: relative; }
+  .main-content { margin-left: 320px; }
+}
+```
+
+The drawer collapses to modal mode below the breakpoint. **Don't show both modal toggle and persistent at the same width** — use media queries to switch behavior.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed (modal) | Translated off-screen (-100% on side axis) |
+| Opening | 250–300ms slide-in with ease-out |
+| Open | Settled, focus inside, scroll locked |
+| Closing | 200ms slide-out with ease-in |
+| Persistent | Always visible, no slide animation needed |
+
+For mobile bottom drawer with detents: also have intermediate "snap" states (50%, 90%).
+
+## Tokens consumed
+
+```
+--color-bg-elevated         (drawer surface)
+--color-bg-overlay          (backdrop, ~rgba(0,0,0,0.5))
+--color-border-default
+--color-text-primary
+--space-md, --space-lg
+--radius-lg                 (top corners on bottom drawer; left/right edges on side drawers usually 0)
+--shadow-modal              (drawer's elevation)
+--motion-default            (250ms slide)
+--easing-out
+--z-modal
+```
+
+## Accessibility — same as Modal
+
+This is the WAI-ARIA dialog pattern when `modal={true}`:
+- `role="dialog"`, `aria-modal="true"`, `aria-labelledby={titleId}`
+- Focus trap on open
+- Restore focus to opener on close
+- Escape closes (unless dismissible disabled)
+
+For persistent drawers (when not modal):
+- `<nav>` element, not dialog role
+- Focus is not trapped — user can tab out into main content
+- No backdrop, no scroll lock
+- Escape doesn't close (it's not modal)
+
+### Keyboard
+
+| Key | Modal drawer | Persistent drawer |
+| --- | --- | --- |
+| `Tab` | Cycle within drawer | Move through drawer content; eventually exits to main |
+| `Esc` | Close | No-op |
+| `Enter`/`Space` | Activate focused item | Same |
+
+## Mobile-specific behaviors
+
+### Swipe to dismiss
+
+- Side drawer (left): swipe right-to-left dismisses (or left-to-right depending on side).
+- Bottom drawer (sheet): swipe down dismisses.
+- Drag handle (3px high pill) at the swipeable edge as a visual hint.
+
+### Detents (multi-size)
+
+iOS sheets support detents — the user can drag to snap to multiple sizes (small, medium, full):
+
+```tsx
+<Drawer side="bottom" detents={[0.25, 0.5, 0.9]}>
+  ...
+</Drawer>
+```
+
+## Code example
+
+```tsx
+// Mobile menu drawer
+const [menuOpen, setMenuOpen] = useState(false);
+
+<Drawer open={menuOpen} onOpenChange={setMenuOpen} side="left" size="md">
+  <Drawer.Header>
+    <UserCard user={user} />
+  </Drawer.Header>
+  <Drawer.Body>
+    <NavLink to="/dashboard">대시보드</NavLink>
+    <NavLink to="/transactions">거래 내역</NavLink>
+    <NavLink to="/settings">설정</NavLink>
+  </Drawer.Body>
+  <Drawer.Footer>
+    <Button onClick={signOut}>로그아웃</Button>
+  </Drawer.Footer>
+</Drawer>
+
+// Filter drawer (right side)
+<Drawer open={filterOpen} onOpenChange={setFilterOpen} side="right" size="md">
+  <Drawer.Header>
+    <Drawer.Title>필터</Drawer.Title>
+    <Button variant="link" onClick={resetFilters}>초기화</Button>
+  </Drawer.Header>
+  <Drawer.Body>
+    <FilterForm />
+  </Drawer.Body>
+  <Drawer.Footer>
+    <Button fullWidth onClick={applyFilters}>적용</Button>
+  </Drawer.Footer>
+</Drawer>
+
+// Persistent sidebar on desktop
+<Drawer side="left" size="md" persistent open={true}>
+  <Sidebar />
+</Drawer>
+```
+
+## Edge cases
+
+- **Drawer overflows on small phones**: cap at `100vw - 16px` (always show some main content peeking) so user knows there's a way back.
+- **Long content scrolls inside body**: header and footer stay fixed, body scrolls.
+- **Drawer above another drawer**: avoid. Refactor.
+- **Drawer + on-screen keyboard (mobile)**: keyboard pushes drawer content up, but doesn't affect drawer chrome. Test on iOS Safari.
+- **RTL**: `side="left"` becomes physical right. Use logical `side="start"`/`"end"` if your library supports it; else handle in CSS.
+- **Persistent on small viewport**: collapse to modal below breakpoint. Don't show both styles competing.
+
+## Don't
+
+- Don't use Drawer for simple confirmation. Use a Modal or AlertDialog.
+- Don't make a Drawer's content depend on the parent page's data without a way to refresh — context can become stale.
+- Don't put primary destructive actions in a drawer's footer without confirmation.
+- Don't autoplay videos / animations in a drawer that's not currently open (waste of CPU).
+- Don't combine modal + persistent at the same viewport size.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/drawer/`](../refs/ant-design/components/drawer/) — `Drawer`. Supports `placement`, `size`, `mask`, `closable`. Mature.
+- MUI: [`refs/mui/packages/mui-material/src/Drawer/`](../refs/mui/packages/mui-material/src/Drawer/) — `Drawer` with `variant="permanent" | "persistent" | "temporary"`. Best persistent-mode handling.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sheet.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sheet.tsx) — Radix Dialog primitive used as a side panel. Modal-only by default; persistent requires composition.
+
+## Cross-reference
+
+- [`examples/component-modal.md`](component-modal.md) — Sheet variant, focus management
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md) — when drawer vs bottom-tab-bar
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — focus trap rules

package/examples/component-dropdown.md

@@ -0,0 +1,220 @@
+# `DropdownMenu` — spec
+
+> Synthesized from Ant Design `Dropdown`, MUI `Menu`, shadcn-ui `dropdown-menu` (Radix). Triggered overlay menu of actions; the canonical "more options" / overflow menu, profile menu, action menu.
+
+## Anatomy
+
+```
+┌────────────────────┐
+│ [trigger button]   │ ← user clicks
+└────────────────────┘
+       ↓ opens
+       ┌────────────────────┐
+       │ ⌃ caret pointing up│
+       │ ────────────────── │
+       │  Profile         ⌘P│
+       │  Settings        ⌘,│
+       │ ────────────────── │
+       │ ▶ Workspace        │ ← submenu trigger
+       │  ────              │
+       │  Sign out          │
+       └────────────────────┘
+```
+
+## API
+
+```tsx
+<DropdownMenu>
+  <DropdownMenu.Trigger asChild>
+    <Button variant="ghost">More ▾</Button>
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Content align="end">
+    <DropdownMenu.Item onSelect={handleProfile}>
+      Profile
+      <DropdownMenu.Shortcut>⌘P</DropdownMenu.Shortcut>
+    </DropdownMenu.Item>
+    <DropdownMenu.Item onSelect={handleSettings}>Settings</DropdownMenu.Item>
+    <DropdownMenu.Separator />
+    <DropdownMenu.Sub>
+      <DropdownMenu.SubTrigger>Workspace</DropdownMenu.SubTrigger>
+      <DropdownMenu.SubContent>
+        <DropdownMenu.Item>Switch workspace</DropdownMenu.Item>
+        <DropdownMenu.Item>Invite members</DropdownMenu.Item>
+      </DropdownMenu.SubContent>
+    </DropdownMenu.Sub>
+    <DropdownMenu.Separator />
+    <DropdownMenu.Item destructive onSelect={handleSignOut}>Sign out</DropdownMenu.Item>
+  </DropdownMenu.Content>
+</DropdownMenu>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Trigger` | Element that opens the menu (Button, IconButton, etc) |
+| `Content` | Menu surface; positioned via floating-ui |
+| `Item` | Individual action |
+| `CheckboxItem` | Toggleable item with check state |
+| `RadioGroup` + `RadioItem` | Mutually exclusive items |
+| `Sub` + `SubTrigger` + `SubContent` | Nested submenu |
+| `Label` | Section heading (non-interactive) |
+| `Separator` | Visual divider |
+| `Group` | Logical grouping for screen readers |
+| `Shortcut` | Keyboard shortcut hint (visual only; doesn't bind) |
+
+## Item types
+
+```tsx
+<DropdownMenu.Item>Standard action</DropdownMenu.Item>
+
+<DropdownMenu.CheckboxItem
+  checked={notificationsOn}
+  onCheckedChange={setNotificationsOn}
+>
+  Email notifications
+</DropdownMenu.CheckboxItem>
+
+<DropdownMenu.RadioGroup value={theme} onValueChange={setTheme}>
+  <DropdownMenu.RadioItem value="light">Light</DropdownMenu.RadioItem>
+  <DropdownMenu.RadioItem value="dark">Dark</DropdownMenu.RadioItem>
+  <DropdownMenu.RadioItem value="system">System</DropdownMenu.RadioItem>
+</DropdownMenu.RadioGroup>
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Trigger only; menu hidden |
+| Opening | Menu fades + scales in (200ms) |
+| Open | Menu visible; first item focused |
+| Item hover | Bg highlight |
+| Item focus (keyboard) | Bg highlight + visible focus ring |
+| Item disabled | Reduced opacity, no events, `aria-disabled="true"` |
+| Item destructive | Red text + hover |
+| Submenu opening | Right-side adjacent panel slides in |
+| Closing | Reverse 150ms |
+
+## Positioning
+
+- Default: `bottom-start` (below trigger, left-aligned).
+- `align="end"`: right-aligned (common for header avatar menus).
+- `side="top"`: above trigger (when near bottom of viewport).
+- **Auto-flip**: floating-ui adjusts side / align based on available space.
+- **Collision padding**: 8px from viewport edges.
+- **Sub-menus**: open to the right by default; flip to left if collision.
+
+## Keyboard contract (WAI-ARIA Menu pattern)
+
+| Key | Action |
+| --- | --- |
+| `Enter` / `Space` (on trigger) | Open menu, focus first item |
+| `↓` / `↑` | Move between items |
+| `Home` / `End` | Jump to first / last item |
+| `Enter` / `Space` (on item) | Activate; close menu |
+| `Esc` | Close; return focus to trigger |
+| `Tab` | Close; move to next focusable in document |
+| `→` (on submenu trigger) | Open submenu |
+| `←` (in submenu) | Close submenu, focus parent item |
+| typeahead (letter keys) | Jump to item starting with letter |
+
+## Tokens consumed
+
+```
+--color-bg-overlay              (menu bg)
+--color-fg-on-overlay           (item text)
+--color-bg-overlay-hover        (item hover bg)
+--color-fg-emphasis             (selected item)
+--color-error-default           (destructive item)
+--color-border-overlay
+--color-fg-muted                (Shortcut, Label)
+--radius-md
+--shadow-overlay                (drop shadow)
+--space-xs, --space-sm, --space-md
+--font-size-sm
+--motion-fast                   (open/close)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- Trigger: `<button>` with `aria-haspopup="menu" aria-expanded="true|false"`.
+- Content: `role="menu"`; auto-focuses first item on open.
+- Items: `role="menuitem"`; `tabindex="-1"` (managed by parent `roving tabindex`).
+- CheckboxItem: `role="menuitemcheckbox"` + `aria-checked`.
+- RadioItem: `role="menuitemradio"` + `aria-checked`.
+- Separator: `role="separator"`.
+- Label: `role="presentation"` (just visual).
+- Submenu trigger: `aria-haspopup="menu" aria-expanded`.
+- Touch target: each item ≥ 36px tall.
+- Don't disable focus outline; brand the ring color but keep visible.
+
+## Tokens for Korean
+
+For Korean menus:
+- Menu items in Korean text — Pretendard / NanumSquare; line-height 1.6 for legibility.
+- Shortcut display: 한글 keyboards have different keys; show "Cmd / Ctrl" + Latin letter (typing layouts mostly Latin).
+
+## Code example
+
+```tsx
+function UserMenu({ user, onSignOut }: Props) {
+  return (
+    <DropdownMenu>
+      <DropdownMenu.Trigger asChild>
+        <button className="user-menu-trigger" aria-label="사용자 메뉴">
+          <Avatar src={user.avatar} />
+        </button>
+      </DropdownMenu.Trigger>
+      <DropdownMenu.Content align="end">
+        <DropdownMenu.Label>{user.name}</DropdownMenu.Label>
+        <DropdownMenu.Item onSelect={() => navigate("/profile")}>
+          프로필
+        </DropdownMenu.Item>
+        <DropdownMenu.Item onSelect={() => navigate("/settings")}>
+          설정
+        </DropdownMenu.Item>
+        <DropdownMenu.Separator />
+        <DropdownMenu.Item destructive onSelect={onSignOut}>
+          로그아웃
+        </DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu>
+  );
+}
+```
+
+## Edge cases
+
+- **Long item list**: scroll inside menu; cap at ~60% of viewport height.
+- **Item label too long**: truncate with ellipsis OR wrap (pick a system-wide rule).
+- **Menu opens off-screen on small viewport**: floating-ui auto-flips. Test on mobile.
+- **Closing while submenu open**: closes both at once; focus returns to trigger.
+- **Disabled state with destructive variant**: still grayed but red tint preserved.
+- **Async action inside Item**: don't close menu before action completes; show inline spinner.
+- **Right-click context menu**: use `ContextMenu` component, not DropdownMenu.
+
+## Don't
+
+- Don't use DropdownMenu for navigation links — use NavigationMenu.
+- Don't pack > 10 items in one menu. Use sections / groups, or move some to a settings page.
+- Don't open menu on hover (except submenus). Click-only.
+- Don't put inputs inside DropdownMenu (use `Popover` for that — different keyboard model).
+- Don't omit `aria-label` on icon-only triggers.
+- Don't disable Esc closing — accessibility foundation.
+
+## References
+
+- Ant: [`Dropdown`](../refs/ant-design/components/dropdown)
+- MUI: [`Menu`](../refs/mui/packages/mui-material/src/Menu)
+- shadcn-ui: [`dropdown-menu`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/dropdown-menu.tsx) (Radix-based)
+- WAI-ARIA: [Menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)
+
+## Cross-reference
+
+- [`examples/component-context-menu.md`](component-context-menu.md) — right-click variant
+- [`examples/component-popover.md`](component-popover.md) — for non-menu floating content
+- [`examples/component-command.md`](component-command.md) — for searchable menus
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)