@design-ai/cli 4.55.0

package/examples/component-menu-item.md

@@ -0,0 +1,102 @@
+# `MenuItem` — spec
+
+> Synthesized from MUI `MenuItem`. A single row inside a `Menu` (popover) or `Select` dropdown. Behaves like an interactive `ListItemButton` but with menu-specific keyboard semantics (auto-focus on hover, Enter to select, type-ahead).
+
+## When to use
+
+- One option inside `<Menu>`, `<Select>`, or `<Autocomplete>`.
+- Context menus, dropdown menus, command palettes (with custom item rendering).
+- For non-menu interactive rows in plain lists, use `ListItemButton` instead — `MenuItem` carries menu-specific `role` and keyboard expectations.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────┐
+│ [icon]  Label              [shortcut/✓]  │
+└──────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Menu open={open} anchorEl={anchorEl}>
+  <MenuItem onClick={...}>편집</MenuItem>
+  <MenuItem onClick={...} selected>복사</MenuItem>
+  <MenuItem disabled>삭제</MenuItem>
+</Menu>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Label + optional icon/shortcut |
+| `selected` | `boolean` | `false` | Highlighted (current value) |
+| `disabled` | `boolean` | `false` | Non-selectable; greyed |
+| `dense` | `boolean` | `false` | Reduce vertical padding |
+| `divider` | `boolean` | `false` | Bottom divider |
+| `onClick` | `(e) => void` | — | Selection handler |
+| `value` | `any` | — | When inside `Select`; matched against `Select.value` |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | transparent bg, fg-default |
+| Hover / focus | bg-subtle (mouse hover and keyboard focus share the same visual) |
+| Selected | check icon (or filled bg) + bg-selected |
+| Active | bg-pressed |
+| Disabled | reduced opacity, no hover effect |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle           /* hover/focus */
+--color-bg-selected
+--color-fg-default
+--color-fg-on-selected
+--menu-item-min-height-32   /* dense */
+--menu-item-min-height-36   /* default */
+--space-sm
+--space-md
+```
+
+## Accessibility
+
+- Semantic element: `<li role="menuitem">` (or `option` inside `Select`).
+- Keyboard: ↑/↓ navigates between items; Enter / Space activates; type-ahead jumps to matching item.
+- The currently-focused item must visually match the keyboard cursor — don't separate "hover" and "focus" visuals.
+- `aria-disabled="true"` for disabled items (don't use `disabled` attribute alone).
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Long item text** — single-line truncation with ellipsis. If you need multiline, use a custom command-palette pattern.
+- **Submenu / nested menu** — MUI doesn't ship native submenus; use a separate Menu with `anchorEl` set to the parent item.
+- **Korean text density** — pad horizontal slightly more for Korean labels (`space-md` instead of `space-sm`) to avoid cramped feel.
+
+## Code example
+
+```tsx
+<Select value={role} onChange={(e) => setRole(e.target.value)}>
+  <MenuItem value="admin">관리자</MenuItem>
+  <MenuItem value="member">일반 사용자</MenuItem>
+  <MenuItem value="guest" disabled>초대 대기</MenuItem>
+</Select>
+```
+
+## Don't
+
+- Don't render `MenuItem` outside a `Menu` / `Select` parent — keyboard navigation breaks.
+- Don't use `selected` for hover state — `selected` means "current value", a persistent state.
+- Don't put more than one primary action per item; use a separate trailing action button if you need both select + delete.
+
+## References
+
+- MUI: [`MenuItem.d.ts`](../refs/mui/packages/mui-material/src/MenuItem/MenuItem.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-menu-list.md`](component-menu-list.md)
+- [`component-select.md`](component-select.md)
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)

package/examples/component-menu-list.md

@@ -0,0 +1,98 @@
+# `MenuList` — spec
+
+> Synthesized from MUI `MenuList`. The container that holds `MenuItem` children — handles keyboard navigation (arrow keys, type-ahead, focus trap). When you need a menu without the floating Menu's anchor/popover machinery, use MenuList directly inside your own Paper / Popover.
+
+## When to use
+
+- Custom popover / drawer that should behave like a menu inside.
+- Static "all options" page that uses menu-style keyboard nav.
+- Inside `Menu` (MUI wraps it for you — direct MenuList use is for the unwrapped case).
+
+## API
+
+```tsx
+<Paper>
+  <MenuList autoFocusItem>
+    <MenuItem onClick={handleProfile}>프로필</MenuItem>
+    <MenuItem onClick={handleSettings}>설정</MenuItem>
+    <Divider />
+    <MenuItem onClick={handleLogout}>로그아웃</MenuItem>
+  </MenuList>
+</Paper>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | `MenuItem` children (Dividers OK) |
+| `autoFocus` | `boolean` | `false` | Focus the menu on mount |
+| `autoFocusItem` | `boolean` | `false` | Focus the first item on mount |
+| `disabledItemsFocusable` | `boolean` | `false` | Allow focus on disabled items |
+| `disableListWrap` | `boolean` | `false` | Don't wrap from last to first item |
+| `variant` | `'menu' \| 'selectedMenu'` | `'selectedMenu'` | Menu without selection vs with-selection (focus jumps to selected) |
+
+## States
+
+Layout/keyboard primitive — no own visual states. Children own theirs.
+
+## Tokens consumed
+
+```
+--menu-bg
+--menu-padding
+--menu-min-width
+```
+
+## Accessibility
+
+- Renders as `<ul role="menu">` (or `role="listbox"` in some Select variants).
+- Arrow Up/Down navigates; Home/End jump to first/last; Esc closes (when inside Menu); Enter activates.
+- Type-ahead: typing letters jumps to first MenuItem starting with those letters. Korean Hangul: works via the input characters (not a Korean-specific feature).
+- For variant `selectedMenu`: focus moves to the currently-selected item on open (correct UX for picker menus).
+
+## Edge cases
+
+- **No focusable items** — all disabled = focus traps in nowhere. Set `disabledItemsFocusable={true}` so keyboard users can at least navigate.
+- **Long menus** — scrollable; keyboard nav scrolls into view automatically.
+- **Mixed actions and selections** — distinguish via icon (check for selected, not for action). Keyboard semantics treat both the same.
+
+## Code example
+
+```tsx
+<Popover
+  open={open}
+  anchorEl={anchorEl}
+  onClose={handleClose}
+  anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+>
+  <MenuList autoFocusItem>
+    <MenuItem onClick={() => { navigate('/profile'); handleClose(); }}>
+      <ListItemIcon><PersonIcon /></ListItemIcon>
+      <ListItemText>프로필</ListItemText>
+    </MenuItem>
+    <MenuItem onClick={() => { navigate('/settings'); handleClose(); }}>
+      <ListItemIcon><SettingsIcon /></ListItemIcon>
+      <ListItemText>설정</ListItemText>
+    </MenuItem>
+    <Divider />
+    <MenuItem onClick={handleLogout}>
+      <ListItemIcon><LogoutIcon /></ListItemIcon>
+      <ListItemText>로그아웃</ListItemText>
+    </MenuItem>
+  </MenuList>
+</Popover>
+```
+
+## Don't
+
+- Don't use as a plain List — kbd nav semantics differ.
+- Don't put non-MenuItem children (random buttons) — keyboard nav breaks.
+
+## References
+
+- MUI: [`MenuList`](../refs/mui/packages/mui-material/src/MenuList/)
+
+## Cross-reference
+
+- [`component-menu-item.md`](component-menu-item.md)
+- [`component-menu.md`](component-menu.md) — the wrapping floating menu
+- [`component-popover.md`](component-popover.md)

package/examples/component-menu.md

@@ -0,0 +1,139 @@
+# `Menu` — spec
+
+> Synthesized from Ant Design `Menu`. The structured navigation menu primitive — distinct from `DropdownMenu` (action overlay), `NavigationMenu` (top horizontal), and `Sidebar` (app shell).
+
+## When to use
+
+- Sidebar navigation menu with hierarchical items + active state.
+- App-level navigation rendered as a vertical or horizontal menu.
+- As an alternative to `Sidebar` for simpler app shells.
+
+When NOT to use:
+- Triggered popup of actions → `DropdownMenu`.
+- Marketing top nav with mega-menus → `NavigationMenu`.
+- Persistent collapsible sidebar → `Sidebar`.
+
+## Anatomy
+
+```
+┌─────────────────────────┐
+│ ▶ Dashboard              │
+│ ▼ Workspace             │
+│   ▶ Projects             │
+│   ▶ Members              │
+│   ▶ Settings             │
+│ ▶ Inbox                  │
+│ ▶ Help                  │
+└─────────────────────────┘
+```
+
+## API
+
+```tsx
+<Menu mode="vertical" selected={["projects"]} onSelect={onSelect}>
+  <Menu.Item key="dashboard" icon={<HomeIcon />}>
+    Dashboard
+  </Menu.Item>
+  <Menu.SubMenu key="workspace" icon={<FolderIcon />} title="Workspace">
+    <Menu.Item key="projects">Projects</Menu.Item>
+    <Menu.Item key="members">Members</Menu.Item>
+    <Menu.Item key="settings">Settings</Menu.Item>
+  </Menu.SubMenu>
+  <Menu.Item key="inbox" icon={<InboxIcon />}>
+    Inbox
+  </Menu.Item>
+</Menu>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `"vertical" \| "horizontal" \| "inline"` | `"vertical"` | Layout |
+| `selected` | `string[]` | controlled | Active item keys |
+| `onSelect` | `(key: string) => void` | — | Selection callback |
+| `expanded` | `string[]` | controlled | Open SubMenu keys |
+| `onExpandChange` | `(keys: string[]) => void` | — | SubMenu toggle |
+| `theme` | `"light" \| "dark"` | `"light"` | Color scheme |
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Menu` | Outer wrapper |
+| `Item` | Single menu item |
+| `SubMenu` | Group with nested items (collapsible) |
+| `ItemGroup` | Visual grouping with heading |
+| `Divider` | Visual separator |
+
+## Modes
+
+### `vertical` (default)
+
+Sidebar-style. Items stacked top-to-bottom.
+
+### `horizontal`
+
+Top-nav style. Items in a row.
+
+### `inline` (with collapsibles)
+
+Like `vertical` but SubMenus expand inline (push items below). Vs vertical's pop-out submenu.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Standard text + icon |
+| Hover | Bg shift |
+| Selected (active) | Brand-color highlight + indicator |
+| Disabled | Reduced opacity |
+| Submenu collapsed | Chevron right; no children visible |
+| Submenu expanded | Chevron down; children visible |
+
+## Tokens consumed
+
+```
+--menu-bg                          (light or dark)
+--menu-fg
+--menu-fg-muted                    (group headings)
+--menu-bg-hover
+--menu-bg-active                   (selected)
+--menu-fg-active
+--menu-active-indicator            (left-border or bg)
+--menu-divider
+--space-sm, --space-md
+--motion-fast
+```
+
+## Accessibility
+
+- `<nav aria-label="Main">` outer.
+- `<ul role="menu">` items list.
+- `<li role="menuitem">` each item.
+- Submenu trigger: `aria-expanded` + `aria-haspopup`.
+- Active item: `aria-current="page"` (for nav links).
+- Keyboard: Tab navigates; arrow keys within (configurable); Enter/Space activates.
+
+## Korean apps
+
+- 메뉴 항목: 홈 / 워크스페이스 / 받은편지함 / 도움말 / 설정 (typical ordering)
+- Active state visualization: left-border 색상 막대 + 배경 강조 (KR enterprise convention)
+- 합쇼체 / 해요체 not relevant (menu items are nouns)
+
+## Don't
+
+- Don't use Menu for action overlays. Use DropdownMenu.
+- Don't use Menu for marketing nav. Use NavigationMenu.
+- Don't omit `aria-current` on the active item.
+- Don't pile up 4+ levels of nested SubMenu. Flatten or refactor.
+
+## References
+
+- Ant: [`Menu`](../refs/ant-design/components/menu)
+- WAI-ARIA: Menu pattern (different from menubar)
+
+## Cross-reference
+
+- [`examples/component-dropdown.md`](component-dropdown.md) — overlay action menu
+- [`examples/component-navigation-menu.md`](component-navigation-menu.md) — marketing nav
+- [`examples/component-sidebar.md`](component-sidebar.md) — app shell sidebar
+- [`examples/component-menubar.md`](component-menubar.md) — desktop File/Edit/View

package/examples/component-menubar.md

@@ -0,0 +1,259 @@
+# `Menubar` — spec
+
+> Synthesized from shadcn-ui `menubar` (Radix). Persistent menu bar with multiple top-level menus — the canonical desktop "File / Edit / View / Help" pattern. Common in editor / power-user / desktop-style web apps.
+
+## When to use
+
+- **Desktop-style web apps** (Linear, Notion, Figma) emulating native app menus.
+- **Editor surfaces** with many actions organized into File / Edit / View / Insert / Format / Help.
+- **Web-as-OS** apps (cloud IDEs, design tools).
+
+When NOT to use:
+- Simple consumer apps — feels heavy.
+- Mobile primary — desktop convention.
+- Marketing sites — use `NavigationMenu`.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────┐
+│ File   Edit   View   Insert   Format   Help     │ ← Menubar
+└──┬──────────────────────────────────────────────┘
+   │
+   ↓ click File
+   ┌──────────────────┐
+   │ New          ⌘N  │
+   │ Open...      ⌘O  │
+   │ Save         ⌘S  │
+   │ Save As...   ⇧⌘S │
+   │ ─────             │
+   │ Close        ⌘W  │
+   └──────────────────┘
+```
+
+## API
+
+```tsx
+<Menubar>
+  <Menubar.Menu>
+    <Menubar.Trigger>File</Menubar.Trigger>
+    <Menubar.Content>
+      <Menubar.Item onSelect={handleNew}>
+        New <Menubar.Shortcut>⌘N</Menubar.Shortcut>
+      </Menubar.Item>
+      <Menubar.Item onSelect={handleOpen}>
+        Open... <Menubar.Shortcut>⌘O</Menubar.Shortcut>
+      </Menubar.Item>
+      <Menubar.Separator />
+      <Menubar.Sub>
+        <Menubar.SubTrigger>Recent</Menubar.SubTrigger>
+        <Menubar.SubContent>
+          {recentFiles.map(f => (
+            <Menubar.Item key={f.id} onSelect={() => open(f)}>{f.name}</Menubar.Item>
+          ))}
+        </Menubar.SubContent>
+      </Menubar.Sub>
+      <Menubar.Separator />
+      <Menubar.Item onSelect={handleSave}>
+        Save <Menubar.Shortcut>⌘S</Menubar.Shortcut>
+      </Menubar.Item>
+    </Menubar.Content>
+  </Menubar.Menu>
+
+  <Menubar.Menu>
+    <Menubar.Trigger>Edit</Menubar.Trigger>
+    <Menubar.Content>
+      <Menubar.Item>Undo <Menubar.Shortcut>⌘Z</Menubar.Shortcut></Menubar.Item>
+      <Menubar.Item>Redo <Menubar.Shortcut>⇧⌘Z</Menubar.Shortcut></Menubar.Item>
+      <Menubar.Separator />
+      <Menubar.Item>Cut <Menubar.Shortcut>⌘X</Menubar.Shortcut></Menubar.Item>
+      <Menubar.Item>Copy <Menubar.Shortcut>⌘C</Menubar.Shortcut></Menubar.Item>
+      <Menubar.Item>Paste <Menubar.Shortcut>⌘V</Menubar.Shortcut></Menubar.Item>
+    </Menubar.Content>
+  </Menubar.Menu>
+
+  <Menubar.Menu>
+    <Menubar.Trigger>View</Menubar.Trigger>
+    <Menubar.Content>
+      <Menubar.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
+        Show Grid
+      </Menubar.CheckboxItem>
+      <Menubar.CheckboxItem checked={showRulers} onCheckedChange={setShowRulers}>
+        Show Rulers
+      </Menubar.CheckboxItem>
+      <Menubar.Separator />
+      <Menubar.RadioGroup value={zoom} onValueChange={setZoom}>
+        <Menubar.RadioItem value="50">50%</Menubar.RadioItem>
+        <Menubar.RadioItem value="100">100%</Menubar.RadioItem>
+        <Menubar.RadioItem value="200">200%</Menubar.RadioItem>
+      </Menubar.RadioGroup>
+    </Menubar.Content>
+  </Menubar.Menu>
+</Menubar>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Menubar` | Wrapper |
+| `Menu` | Single top-level menu |
+| `Trigger` | The button label (File, Edit, etc.) |
+| `Content` | The dropdown panel |
+| `Item`, `CheckboxItem`, `RadioGroup`, `RadioItem` | Same as DropdownMenu |
+| `Sub`, `SubTrigger`, `SubContent` | Nested submenu |
+| `Label`, `Separator`, `Shortcut` | Same |
+
+Menubar is essentially a **horizontal row of DropdownMenu triggers** with extra keyboard handling (arrow keys move between menus while open).
+
+## Behavior
+
+### Hover-roving (the killer feature)
+
+Once one menu is open, hovering an adjacent Trigger opens that menu (closing the previous). This makes File → Edit → View browsing feel native.
+
+### Click-then-hover
+
+Clicking a Trigger when no menu is open: opens it. Subsequent hovers on triggers swap menus.
+
+Clicking outside: closes all.
+
+## Keyboard contract
+
+| Key | Action |
+| --- | --- |
+| Tab into Menubar | Focus first Trigger |
+| Tab away | Focus exits Menubar |
+| `←` / `→` (when menu closed) | Move focus between Triggers |
+| `Enter` / `Space` / `↓` | Open focused menu |
+| `←` / `→` (when menu open) | Close current, open adjacent menu |
+| `↓` / `↑` (within menu) | Navigate items |
+| `Esc` | Close menu, focus stays on Trigger |
+| Letter key (when menu open) | Jump to item starting with letter |
+| Letter key (when no menu open + Trigger has accelerator like `_F_ile`) | Open that menu |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Resting | All triggers visible, none active |
+| Trigger focus (keyboard) | Visible focus ring |
+| Trigger hover | Subtle bg shift |
+| Menu open | Active Trigger highlighted, panel below visible |
+| Item hover | Bg highlight |
+| Item disabled | Reduced opacity |
+| Item destructive | Red text |
+
+## Tokens consumed
+
+```
+--menubar-bg                    (slightly different from main bg, e.g. tinted)
+--menubar-fg
+--menubar-fg-muted              (separators, shortcuts)
+--menubar-trigger-hover-bg
+--menubar-trigger-active-bg     (when its menu is open)
+--menubar-content-bg            (dropdown panel)
+--menubar-item-hover-bg
+--menubar-error-fg              (destructive items)
+--menubar-border
+--radius-md
+--shadow-overlay
+--space-xs, --space-sm
+--font-size-sm
+--motion-fast                   (open/close)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- Menubar wrapper: `role="menubar"`.
+- Trigger: `role="menuitem"` with `aria-haspopup="true" aria-expanded`.
+- Content: `role="menu"`.
+- Item: `role="menuitem"` (or `menuitemcheckbox` / `menuitemradio`).
+- Roving tabindex on triggers (only one tabbable at a time).
+- Clear visual focus ring.
+- Keyboard fully usable without mouse.
+
+## Mobile
+
+Menubar doesn't translate to mobile. On small screens:
+- Replace with a hamburger trigger that opens a Sheet.
+- Or move all actions into a CommandPalette accessible via hotkey.
+
+## Korean apps
+
+- 메뉴바 (menubar) typical in Korean desktop-style web apps.
+- Trigger labels: 파일 / 편집 / 보기 / 도구 / 도움말 (canonical pattern from native KR software).
+- 합쇼체 typical for menu items in formal apps; 해요체 for casual.
+- Hangul on accelerator keys: omit underline-letter pattern (Korean characters can't be single-letter accelerators); use Cmd/Ctrl + Latin letter shortcuts.
+
+## Code example
+
+```tsx
+function EditorHeader() {
+  return (
+    <header className="editor-header">
+      <Logo />
+      <Menubar>
+        <Menubar.Menu>
+          <Menubar.Trigger>파일</Menubar.Trigger>
+          <Menubar.Content>
+            <Menubar.Item onSelect={newDoc}>
+              새 문서 <Menubar.Shortcut>⌘N</Menubar.Shortcut>
+            </Menubar.Item>
+            <Menubar.Item onSelect={openDoc}>
+              열기... <Menubar.Shortcut>⌘O</Menubar.Shortcut>
+            </Menubar.Item>
+            <Menubar.Separator />
+            <Menubar.Item onSelect={save}>
+              저장 <Menubar.Shortcut>⌘S</Menubar.Shortcut>
+            </Menubar.Item>
+          </Menubar.Content>
+        </Menubar.Menu>
+
+        <Menubar.Menu>
+          <Menubar.Trigger>편집</Menubar.Trigger>
+          {/* ... */}
+        </Menubar.Menu>
+
+        <Menubar.Menu>
+          <Menubar.Trigger>도움말</Menubar.Trigger>
+          {/* ... */}
+        </Menubar.Menu>
+      </Menubar>
+    </header>
+  );
+}
+```
+
+## Edge cases
+
+- **Many menus (8+)**: feels cluttered. Group or move to CommandPalette.
+- **Long menus (20+ items)**: split into submenus (e.g., File > Recent).
+- **Disabled menu** (no items applicable in current context): Trigger grayed; clicking does nothing.
+- **Menubar in collapsed sidebar layout**: hide Menubar entirely on narrow screens.
+- **Multi-window app**: each window has its own Menubar instance with its own state.
+- **Reduced motion**: skip open/close transitions.
+
+## Don't
+
+- Don't use Menubar in mobile-primary apps. Wrong convention.
+- Don't omit shortcuts on common actions — power users expect them.
+- Don't have inconsistent shortcuts (different across menus for same action).
+- Don't put primary CTAs in Menubar — they should be visible buttons.
+- Don't have only one menu — that's a DropdownMenu.
+- Don't disable Esc to close.
+
+## References
+
+- shadcn-ui: [`menubar`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/menubar.tsx) (Radix)
+- Patterns: macOS native menubar, VS Code, Figma desktop apps
+- WAI-ARIA: [Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)
+
+## Cross-reference
+
+- [`examples/component-dropdown.md`](component-dropdown.md) — single-menu variant
+- [`examples/component-command.md`](component-command.md) — keyboard-first alternative
+- [`examples/component-navigation-menu.md`](component-navigation-menu.md) — for marketing nav
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)