@design-ai/cli 4.55.0

package/examples/component-sheet.md

@@ -0,0 +1,277 @@
+# `Sheet` — spec
+
+> Synthesized from shadcn-ui `sheet` (Radix Dialog with side anchoring) and Material 3 bottom sheet. A modal panel that slides in from a screen edge — distinct from `Drawer` (typically navigation) and `Modal` (centered).
+
+## When to use Sheet vs Drawer vs Modal
+
+| Component | Anchor | Primary use |
+| --- | --- | --- |
+| **Modal** | Center | Confirmation, focused task |
+| **Drawer** | Left/Right | Persistent or modal navigation menu |
+| **Sheet** | Any side | Modal supplemental flow / detail view, mobile-first |
+
+Sheet's distinguishing properties:
+- **Side-anchored** like a drawer, but **always modal**.
+- **Mobile-first** patterns (bottom sheet on phone; drawer on desktop).
+- **Detents / snap points** common (peek vs full).
+
+## Anatomy
+
+```
+┌────────────────────────────────────┐
+│                                    │
+│   [backdrop scrim]                 │
+│                                    │
+│                                    │
+├────────────────────────────────────┤
+│ ━━━ (drag handle, optional)         │
+│ Sheet header                    [×]│
+│ ───────────────                     │
+│                                    │
+│  Sheet content                     │
+│                                    │
+│  ...                               │
+│                                    │
+└────────────────────────────────────┘
+       (Bottom-anchored sheet)
+```
+
+## API
+
+```tsx
+<Sheet open={open} onOpenChange={setOpen}>
+  <Sheet.Trigger asChild>
+    <Button>Open settings</Button>
+  </Sheet.Trigger>
+  <Sheet.Content side="right">
+    <Sheet.Header>
+      <Sheet.Title>Settings</Sheet.Title>
+      <Sheet.Description>Configure your preferences.</Sheet.Description>
+    </Sheet.Header>
+
+    {/* form content */}
+
+    <Sheet.Footer>
+      <Sheet.Close asChild>
+        <Button variant="ghost">Cancel</Button>
+      </Sheet.Close>
+      <Button onClick={save}>Save</Button>
+    </Sheet.Footer>
+  </Sheet.Content>
+</Sheet>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | controlled | Visibility |
+| `onOpenChange` | `(open: boolean) => void` | — | Close handler |
+| `modal` | `boolean` | `true` | Trap focus + lock scroll |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Anchor edge |
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Width (top/bottom) or height (left/right) |
+| `dismissible` | `boolean` | `true` | Click outside or Esc closes |
+| `detents` | `number[]` | — | Optional snap points (mobile bottom sheet); e.g., `[0.4, 0.9]` |
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Trigger` | Element that opens the sheet |
+| `Content` | The sheet panel |
+| `Header` | Title + description region |
+| `Title` | Heading (announced to screen readers) |
+| `Description` | Helper text |
+| `Footer` | Actions row |
+| `Close` | Button that closes the sheet |
+| `Overlay` | Backdrop scrim |
+
+## Side variants
+
+### Right (default — desktop settings, detail panels)
+
+```
+                  ┌──────────────┐
+[main content]    │ Sheet panel  │
+                  │              │
+                  │              │
+                  └──────────────┘
+```
+
+### Left (alternative navigation)
+
+Less common; use Drawer for nav.
+
+### Bottom (mobile-first)
+
+```
+[main content]
+            ┌───────────────┐
+            │   Sheet       │ ← slides up
+            │               │
+            └───────────────┘
+```
+
+Mobile: bottom sheet is the canonical action / detail pattern. iOS / Android native.
+
+### Top (notification center, full-page filter)
+
+Less common. Use for app-wide announcements or full-page-spanning filter overlays.
+
+## Size variants
+
+| Size | Width (left/right) | Height (top/bottom) |
+| --- | --- | --- |
+| `sm` | 320px | 30vh |
+| `md` (default) | 480px | 50vh |
+| `lg` | 640px | 70vh |
+| `xl` | 800px | 90vh |
+| `full` | 100% | 100% |
+
+For mobile (< 640px viewport): all sizes default to ~90% of viewport.
+
+## Detents (mobile bottom sheet)
+
+```
+detents: [0.4, 0.9]
+            ↑     ↑
+         peek  full
+
+User can drag to switch between detents:
+- Drag up from peek → snap to full
+- Drag down from full → snap to peek (or close if dragged to 0)
+```
+
+iOS-style sheet behavior. Common for map apps (peek shows summary, drag up for full).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Hidden |
+| Opening | Slide-in from side (200-300ms) + backdrop fade |
+| Open | Visible, focus trapped |
+| Dragging (mobile, with detents) | Following finger; backdrop opacity proportional |
+| Snapping | Animate to nearest detent |
+| Closing | Reverse |
+
+## Animation
+
+```css
+[data-side="right"] {
+  --slide: translateX(100%);
+}
+[data-side="left"] {
+  --slide: translateX(-100%);
+}
+[data-side="bottom"] {
+  --slide: translateY(100%);
+}
+[data-side="top"] {
+  --slide: translateY(-100%);
+}
+
+.sheet[data-state="closed"] {
+  transform: var(--slide);
+}
+.sheet[data-state="open"] {
+  transform: translate(0);
+}
+.sheet {
+  transition: transform 250ms var(--ease-out);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sheet { transition: none; }
+}
+```
+
+## Tokens consumed
+
+```
+--color-bg-overlay-scrim         (backdrop, ~50% opacity)
+--color-bg-default               (sheet bg)
+--color-fg-default
+--color-border-default           (header / footer divider)
+--shadow-overlay
+--radius-lg                      (mobile bottom sheet has rounded top corners)
+--space-md, --space-lg
+--motion-medium                  (slide-in)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- `Content`: `role="dialog"` (or `alertdialog` if it interrupts), `aria-modal="true"`.
+- `aria-labelledby` references `Title`.
+- `aria-describedby` references `Description`.
+- Focus trap on open; first focusable in Content gets focus.
+- `Esc` closes; `Tab` cycles within Content.
+- `Close` button is inside Content; users find it via Tab.
+- Click outside (on overlay) closes — but not for forms with unsaved changes (confirm first).
+- Backdrop is non-interactive (just visual scrim) — clicks bubble to close handler.
+- Touch-drag (mobile detents) uses `aria-valuenow` for screen reader; announce position changes.
+- Reduced motion: no slide; instant appearance.
+
+## Mobile-specific
+
+- Bottom sheet rounded-top corners (`--radius-lg` on top-left + top-right only).
+- Drag handle (small bar at top): visual + accessible (`role="button" aria-label="Drag to resize"`).
+- Safe-area inset: respect device safe-area for iPhone home indicator (`padding-bottom: env(safe-area-inset-bottom)`).
+- Dynamic height for keyboard: when virtual keyboard opens, shrink sheet so input visible.
+
+## Code example
+
+```tsx
+function FilterSheet({ filters, onChange, onApply }: Props) {
+  return (
+    <Sheet>
+      <Sheet.Trigger asChild>
+        <Button variant="outline">필터</Button>
+      </Sheet.Trigger>
+      <Sheet.Content side="bottom" size="lg" detents={[0.5, 0.95]}>
+        <Sheet.Header>
+          <Sheet.Title>필터 설정</Sheet.Title>
+        </Sheet.Header>
+        <FilterControls value={filters} onChange={onChange} />
+        <Sheet.Footer>
+          <Button variant="ghost" onClick={() => onChange({})}>초기화</Button>
+          <Button onClick={onApply}>적용하기</Button>
+        </Sheet.Footer>
+      </Sheet.Content>
+    </Sheet>
+  );
+}
+```
+
+## Edge cases
+
+- **Form with unsaved changes + click outside**: confirm before close ("Discard changes?").
+- **Sheet inside a Sheet**: stack, but close inner first; ensure focus returns correctly.
+- **Very long content**: scroll inside Content (header / footer stay pinned).
+- **Mobile keyboard opens while sheet open**: shrink sheet to fit; ensure focused input visible.
+- **Detents + content scroll** conflict: drag from header drags sheet; drag from content scrolls content. Detect target.
+- **RTL**: `right` and `left` swap automatically.
+- **Multi-step flow inside Sheet**: each step within same Sheet; or stack sheets (max 2).
+
+## Don't
+
+- Don't use Sheet for full-page navigation (use Drawer).
+- Don't use Sheet for centered confirm dialogs (use Modal).
+- Don't put 3+ stacked Sheets — too deep, users lose context.
+- Don't omit close button. Users need an obvious dismiss path.
+- Don't forget the click-outside guard for forms with unsaved data.
+- Don't auto-close after task completion without confirmation animation; user feedback matters.
+- Don't ignore safe-area insets on iOS.
+
+## References
+
+- shadcn-ui: [`sheet`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sheet.tsx) (Radix Dialog primitive)
+- Material 3: bottom sheet pattern
+- iOS: UISheetPresentationController detents
+
+## Cross-reference
+
+- [`examples/component-modal.md`](component-modal.md) — centered dialog
+- [`examples/component-drawer.md`](component-drawer.md) — persistent navigation
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — slide-in timing
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — focus trap

package/examples/component-sidebar.md

@@ -0,0 +1,257 @@
+# `Sidebar` — spec
+
+> Synthesized from shadcn-ui `sidebar` (the flagship Radix-based primitive). A persistent navigation panel — collapsible, themed, often the primary nav surface in dashboards / docs sites / IDE-style apps.
+
+## When to use Sidebar vs Drawer
+
+| | Sidebar | Drawer |
+| --- | --- | --- |
+| Persistence | Always visible (collapsible) | Modal or persistent; usually toggled |
+| Use | Primary navigation in apps | Secondary nav, mobile-only nav |
+| Desktop | Standard | Sometimes overkill |
+| Mobile | Becomes a sheet | Full-screen takeover |
+
+## Anatomy
+
+```
+┌────────────┬───────────────────────────┐
+│ [logo]     │                           │
+│ ──────     │                           │
+│ Header     │                           │
+│            │                           │
+│ Workspace  │                           │
+│  ▶ Project │      Main content         │
+│    Inbox   │                           │
+│    Tasks   │                           │
+│            │                           │
+│ Settings   │                           │
+│ ──────     │                           │
+│ [user]     │                           │
+└────────────┴───────────────────────────┘
+       ↑
+   Sidebar
+```
+
+## API
+
+```tsx
+<Sidebar>
+  <Sidebar.Header>
+    <Logo />
+    <WorkspaceSwitcher />
+  </Sidebar.Header>
+
+  <Sidebar.Content>
+    <Sidebar.Group>
+      <Sidebar.GroupLabel>Workspace</Sidebar.GroupLabel>
+      <Sidebar.Menu>
+        <Sidebar.MenuItem>
+          <Sidebar.MenuButton href="/projects" active>
+            <FolderIcon /> Projects
+          </Sidebar.MenuButton>
+          <Sidebar.MenuSub>
+            <Sidebar.MenuSubItem href="/projects/active">Active</Sidebar.MenuSubItem>
+            <Sidebar.MenuSubItem href="/projects/archive">Archive</Sidebar.MenuSubItem>
+          </Sidebar.MenuSub>
+        </Sidebar.MenuItem>
+        <Sidebar.MenuItem>
+          <Sidebar.MenuButton href="/inbox">
+            <InboxIcon /> Inbox
+            <Sidebar.MenuBadge>12</Sidebar.MenuBadge>
+          </Sidebar.MenuButton>
+        </Sidebar.MenuItem>
+      </Sidebar.Menu>
+    </Sidebar.Group>
+  </Sidebar.Content>
+
+  <Sidebar.Footer>
+    <UserMenu />
+  </Sidebar.Footer>
+</Sidebar>
+
+<SidebarTrigger /> {/* in main content header — toggles sidebar */}
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Sidebar` | Wrapper |
+| `Header` | Top section (logo, workspace switcher) |
+| `Content` | Scrollable middle (groups + menus) |
+| `Footer` | Bottom section (user menu, settings) |
+| `Group` | Logical section |
+| `GroupLabel` | Section heading |
+| `Menu` | List of items |
+| `MenuItem` | Single item wrapper |
+| `MenuButton` | Clickable item |
+| `MenuSub` | Nested sub-menu (collapsible) |
+| `MenuSubItem` | Sub-menu item |
+| `MenuBadge` | Count / indicator on menu item |
+| `MenuAction` | Right-aligned secondary action (e.g., "More" menu) |
+| `Separator` | Visual divider |
+| `Trigger` | Renders elsewhere; toggles sidebar |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Expanded (default desktop) | Full width with labels |
+| Collapsed (icon-only) | ~64px width; only icons visible |
+| Mobile (offcanvas) | Off-screen by default; opens as Sheet on trigger |
+| Item active | Highlighted bg + brand-color indicator |
+| Item hover | Subtle bg shift |
+| Sub-menu collapsed | Hidden, parent item shows chevron |
+| Sub-menu expanded | Items revealed, parent chevron rotated |
+
+## Variants
+
+### Width modes
+
+```tsx
+<Sidebar variant="sidebar" />      // standard fixed
+<Sidebar variant="floating" />     // detached, with shadow
+<Sidebar variant="inset" />        // inset within rounded shell
+```
+
+### Collapsibility
+
+```tsx
+<Sidebar collapsible="offcanvas" />  // mobile-style: slides off-canvas
+<Sidebar collapsible="icon" />       // collapses to icon-only
+<Sidebar collapsible="none" />       // always full width
+```
+
+### Side
+
+```tsx
+<Sidebar side="left" />   // default
+<Sidebar side="right" />  // for tools / settings panels
+```
+
+## Responsive behavior
+
+```
+Desktop (≥ 1024px):
+  Expanded → user can collapse to icon mode
+
+Tablet (768-1023px):
+  Default to icon mode → user can expand
+
+Mobile (< 768px):
+  Offcanvas → invisible until trigger; opens as Sheet
+
+```
+
+State persists in localStorage so collapse preference survives sessions.
+
+## Tokens consumed
+
+```
+--sidebar-width                  (default 16rem / 256px)
+--sidebar-width-icon             (collapsed; default 4rem / 64px)
+--sidebar-bg                     (sidebar background, slightly different from main)
+--sidebar-fg                     (text)
+--sidebar-fg-muted               (group labels)
+--sidebar-item-hover-bg
+--sidebar-item-active-bg
+--sidebar-item-active-fg
+--sidebar-border                 (right border)
+--space-xs, --space-sm, --space-md
+--motion-medium                  (collapse animation)
+--ease-out
+--z-fixed                        (when fixed-position)
+```
+
+shadcn names them `--sidebar-*` so they don't conflict with main app theme.
+
+## Accessibility
+
+- Sidebar: `<aside aria-label="Main navigation">`.
+- Active item: `aria-current="page"` (not just visual).
+- Menu: `<ul>` semantically; items as `<li>`.
+- MenuButton: real `<a>` for nav links, `<button>` for actions.
+- Sub-menus: `aria-expanded` on parent toggle, `aria-controls` referencing sub-menu id.
+- Collapsed icon-only mode: each icon button needs `aria-label` (e.g., `<button aria-label="Inbox">`).
+- Mobile offcanvas: opens as Sheet with focus trap.
+- Keyboard: Tab navigates items; arrow keys can navigate within menu (optional, depends on design).
+
+## Code example
+
+```tsx
+function AppShell({ children }: Props) {
+  return (
+    <SidebarProvider>
+      <Sidebar collapsible="icon">
+        <Sidebar.Header>
+          <Logo />
+        </Sidebar.Header>
+        <Sidebar.Content>
+          <Sidebar.Group>
+            <Sidebar.GroupLabel>Workspace</Sidebar.GroupLabel>
+            <Sidebar.Menu>
+              {workspaceItems.map(item => (
+                <Sidebar.MenuItem key={item.path}>
+                  <Sidebar.MenuButton href={item.path} active={pathname === item.path}>
+                    <item.icon />
+                    <span>{item.label}</span>
+                    {item.count && <Sidebar.MenuBadge>{item.count}</Sidebar.MenuBadge>}
+                  </Sidebar.MenuButton>
+                </Sidebar.MenuItem>
+              ))}
+            </Sidebar.Menu>
+          </Sidebar.Group>
+        </Sidebar.Content>
+        <Sidebar.Footer>
+          <UserMenu />
+        </Sidebar.Footer>
+      </Sidebar>
+
+      <main>
+        <header>
+          <SidebarTrigger />
+          <h1>{pageTitle}</h1>
+        </header>
+        {children}
+      </main>
+    </SidebarProvider>
+  );
+}
+```
+
+## Korean apps
+
+- Sidebar 너비: 한글 메뉴는 영문보다 약간 더 넓은 너비가 필요 (typically 18rem instead of 16rem).
+- Group label: 한글 ("워크스페이스", "관리") works well; keep concise.
+- Active item indicator: 좌측 색상 막대 + 배경 강조; classic KR enterprise pattern.
+
+## Edge cases
+
+- **Long item labels**: truncate with ellipsis; show full text in tooltip on hover.
+- **Many items (50+)**: scroll inside Content; pin Header + Footer.
+- **Nested too deep**: 3+ levels = navigation pain. Cap at 2 levels.
+- **Sidebar in nested layouts**: only one Sidebar per layout root; nested sidebars indicate over-decomposition.
+- **Cross-tab sync**: collapse state via localStorage works across tabs after refresh.
+- **Reduced motion**: skip collapse animation; instant width change.
+- **Right-to-left**: `side="right"` becomes `left`; borders swap.
+
+## Don't
+
+- Don't omit collapse on icon mode for desktop — power users need it.
+- Don't put non-navigation items (status, ads) in Sidebar — that's main content territory.
+- Don't lock to one width; respect collapse preference.
+- Don't omit `aria-current="page"` on active items.
+- Don't put 30 ungrouped items — use Group + GroupLabel.
+- Don't overload icon-only mode with no tooltip — users see only icons.
+
+## References
+
+- shadcn-ui: [`sidebar`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sidebar.tsx) — flagship primitive
+- Patterns: VS Code, Linear, Notion sidebars
+
+## Cross-reference
+
+- [`examples/component-drawer.md`](component-drawer.md) — modal nav alternative
+- [`examples/component-sheet.md`](component-sheet.md) — mobile offcanvas variant
+- [`examples/component-navigation-menu.md`](component-navigation-menu.md) — top nav alternative
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md)