@design-ai/cli 4.55.0

package/examples/component-resizable.md

@@ -0,0 +1,163 @@
+# `Resizable` — spec
+
+> Synthesized from shadcn-ui `resizable`. Resizable panel groups for IDE-style layouts. Distinct from `Splitter` (covered separately) — Resizable here is the shadcn primitive.
+
+## When to use
+
+- IDE-style two-pane layouts (sidebar | editor).
+- Three-pane layouts (sidebar | editor | preview).
+- Vertical splits (top pane / bottom pane — terminal below editor).
+- Any UI where users want to manually adjust pane sizes.
+
+When NOT to use:
+- Simple two-column layouts that don't need user-resize (use Grid).
+- Mobile (drag handles awkward on touch).
+
+## Anatomy
+
+```
+┌────────┬─────────────────────────┐
+│ Side   │                         │
+│ panel  ║   Main editor pane      │
+│        ║                         │
+│        ║                         │
+└────────┴─────────────────────────┘
+         ↑ draggable handle (vertical bar)
+```
+
+## API
+
+```tsx
+<Resizable.Group direction="horizontal">
+  <Resizable.Panel defaultSize={25} minSize={15}>
+    <Sidebar />
+  </Resizable.Panel>
+
+  <Resizable.Handle />
+
+  <Resizable.Panel defaultSize={75}>
+    <Resizable.Group direction="vertical">
+      <Resizable.Panel defaultSize={70}>
+        <Editor />
+      </Resizable.Panel>
+
+      <Resizable.Handle />
+
+      <Resizable.Panel defaultSize={30} minSize={20} collapsible>
+        <Terminal />
+      </Resizable.Panel>
+    </Resizable.Group>
+  </Resizable.Panel>
+</Resizable.Group>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Resizable.Group` | Wrapper; direction = "horizontal" or "vertical" |
+| `Resizable.Panel` | Single resizable pane |
+| `Resizable.Handle` | Draggable divider |
+
+| Panel prop | Type | Description |
+| --- | --- | --- |
+| `defaultSize` | `number` | Initial size as percentage |
+| `minSize` | `number` | Minimum size % |
+| `maxSize` | `number` | Maximum size % |
+| `collapsible` | `boolean` | Allow collapsing to 0 |
+| `collapsedSize` | `number` | Size when collapsed (default 0) |
+| `onResize` | `(size) => void` | Callback during drag |
+| `onCollapse` / `onExpand` | function | State callbacks |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Handles visible (subtle) |
+| Handle hover | Highlights (cursor: col-resize / row-resize) |
+| Handle dragging | Active visual; user dragging |
+| Panel collapsed | Width 0; chevron to expand |
+| Panel min reached | Handle stops at min boundary |
+
+## Tokens consumed
+
+```
+--resizable-handle-bg
+--resizable-handle-bg-hover
+--resizable-handle-bg-active
+--resizable-handle-thickness        (typically 4-8px)
+--motion-fast
+```
+
+## Accessibility
+
+- Handle: `role="separator" aria-orientation="vertical|horizontal" aria-valuenow={size} aria-valuemin={minSize} aria-valuemax={maxSize}`.
+- Keyboard:
+  - Tab to focus handle.
+  - Arrow keys (Left/Right or Up/Down) move handle by 5%.
+  - Home / End: snap to min / max.
+  - Enter (when collapsible): toggle collapse.
+- Don't make handle thinner than 4px — hard to grab.
+
+## Layout persistence
+
+Save panel sizes to localStorage so they persist across sessions:
+
+```tsx
+const [sizes, setSizes] = useLocalStorage("layout-sizes", [25, 75]);
+
+<Resizable.Group
+  direction="horizontal"
+  onLayout={(newSizes) => setSizes(newSizes)}
+>
+  ...
+</Resizable.Group>
+```
+
+## Code example — IDE shell
+
+```tsx
+function IDEShell() {
+  return (
+    <Resizable.Group direction="horizontal" className="h-screen">
+      <Resizable.Panel defaultSize={20} minSize={15} collapsible>
+        <FileExplorer />
+      </Resizable.Panel>
+      <Resizable.Handle />
+      <Resizable.Panel defaultSize={60}>
+        <Resizable.Group direction="vertical">
+          <Resizable.Panel defaultSize={70}>
+            <Editor />
+          </Resizable.Panel>
+          <Resizable.Handle />
+          <Resizable.Panel defaultSize={30} minSize={10}>
+            <Terminal />
+          </Resizable.Panel>
+        </Resizable.Group>
+      </Resizable.Panel>
+      <Resizable.Handle />
+      <Resizable.Panel defaultSize={20} minSize={15} collapsible>
+        <Outline />
+      </Resizable.Panel>
+    </Resizable.Group>
+  );
+}
+```
+
+## Don't
+
+- Don't ship without min/max sizes — users drag to 0 and lose content.
+- Don't make handles invisible — affordance must be visible.
+- Don't auto-resize on window resize without preserving user adjustments.
+- Don't use Resizable on mobile — touch drag conflicts with scroll.
+
+## References
+
+- shadcn-ui: [`resizable`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/resizable.tsx) — wraps `react-resizable-panels`
+- VS Code, Linear, Cursor — IDE layout pattern
+
+## Cross-reference
+
+- [`examples/component-splitter.md`](component-splitter.md) — Ant equivalent
+- [`examples/component-sidebar.md`](component-sidebar.md)
+- [`examples/component-layout.md`](component-layout.md)

package/examples/component-result.md

@@ -0,0 +1,270 @@
+# `Result` + `Empty` — combined spec
+
+> Two sibling full-page components. Result for outcome of an action; Empty for no-data state. Same shape, different intent.
+>
+> Citing Ant Design `Result` + `Empty`, MUI (composition), shadcn-ui (composition)
+
+## Semantic difference
+
+| Component | Use | Trigger |
+| --- | --- | --- |
+| **Result** | Confirms an outcome (success / error / 404 / etc.) | After user action OR after navigation to a status page |
+| **Empty** | "No data here" placeholder | When data is absent (first-time, filtered, cleared) |
+
+Both render full-page-style content (icon + title + description + action). They differ in **what they communicate** and **when they appear**.
+
+The patterns for both are detailed in:
+- [`knowledge/patterns/empty-states.md`](../knowledge/patterns/empty-states.md) — full empty-state pattern reference
+- [`knowledge/patterns/error-states.md`](../knowledge/patterns/error-states.md) — full error-state pattern reference
+
+This spec provides the **component primitive** for both.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│                                                  │
+│              [icon / illustration]               │
+│                                                  │
+│                  Title                           │
+│                                                  │
+│         Description (1–2 sentences)              │
+│                                                  │
+│         [Primary CTA]   [Secondary]              │
+│                                                  │
+└──────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Icon / illustration | recommended | Conveys outcome; ~80–120px |
+| Title | yes | Plain language outcome |
+| Description | usually | Detail or recovery hint |
+| Primary action | usually | Most likely next step |
+| Secondary action | optional | Alternative path |
+| Extra content | optional | Order ID, error code, transaction details |
+
+## API
+
+### Result
+
+```tsx
+<Result
+  status="success"
+  title="결제가 완료되었습니다"
+  description="주문번호 #1234567 - 영수증이 이메일로 전송되었습니다."
+  primaryAction={{ label: "주문 내역 보기", onClick: () => nav("/orders") }}
+  secondaryAction={{ label: "쇼핑 계속", onClick: () => nav("/") }}
+  extra={<OrderSummary order={order} />}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `status` | `"success" \| "info" \| "warning" \| "error" \| "404" \| "403" \| "500"` | `"info"` | Drives icon + color |
+| `title` | `string \| ReactNode` | — | Required |
+| `description` | `string \| ReactNode` | — | |
+| `icon` | `ReactNode` | derived from status | Custom icon override |
+| `primaryAction` | `Action` | — | |
+| `secondaryAction` | `Action` | — | |
+| `extra` | `ReactNode` | — | Below actions: order details, error code, etc. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+
+### Empty
+
+```tsx
+<Empty
+  title="아직 거래 내역이 없어요"
+  description="첫 거래를 추가해 보세요."
+  illustration="default"
+  primaryAction={{ label: "거래 추가", onClick: openAddModal }}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string \| ReactNode` | — | Required |
+| `description` | `string \| ReactNode` | — | |
+| `illustration` | `"default" \| "search" \| "error" \| ReactNode` | `"default"` | Pre-set illustrations or custom |
+| `primaryAction` | `Action` | — | |
+| `secondaryAction` | `Action` | — | |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `inline` | `boolean` | `false` | Compact horizontal layout for inside cards/sidebars |
+
+## Status → icon + color
+
+| Status | Default icon | Color |
+| --- | --- | --- |
+| `success` | ✓ check circle | `--color-success` |
+| `info` | ℹ info circle | `--color-info` |
+| `warning` | ⚠ warning triangle | `--color-warning` |
+| `error` | ✕ error circle | `--color-error` |
+| `404` | 🗺 map / lost | `--color-text-secondary` |
+| `403` | 🔒 lock | `--color-text-secondary` |
+| `500` | ⚠ alert | `--color-error` |
+
+For brand-led products: replace with custom illustrations. Keep size + position consistent.
+
+## Sizes
+
+| Size | Icon | Title font | Padding |
+| --- | --- | --- | --- |
+| `sm` | 48px | 16px | 24px |
+| `md` (default) | 80px | 20px | 48px |
+| `lg` | 120px | 24px | 64px |
+
+For full-page result (404 page, post-checkout): `lg`. For inline empty in a card: `sm` or `inline`.
+
+## Layout — full-page vs inline
+
+### Full-page (default)
+
+Vertical centered. Padding pushes content to ~1/3 from top.
+
+```
+[empty space ~30vh]
+[icon centered]
+[title centered]
+[description centered, max-w 480px]
+[actions centered]
+[empty space below]
+```
+
+### Inline (Empty only, with `inline={true}`)
+
+Horizontal compact. Icon left, text right. For inside small cards/sidebars where vertical centered would waste space.
+
+```
+[icon] [title]
+       [description]
+       [link CTA]
+```
+
+## Tokens consumed
+
+```
+--color-text-primary           (title)
+--color-text-secondary         (description)
+--color-text-tertiary
+--color-success, --color-warning, --color-error, --color-info
+--color-bg-default
+--color-primary-default        (primary action)
+--space-xl, --space-2xl, --space-3xl
+--font-size-base, --font-size-xl, --font-size-2xl
+```
+
+## Accessibility
+
+- Wrap in a heading hierarchy: title is `<h1>` for full-page (404), `<h2>` for in-page.
+- Status icons: `aria-hidden="true"` (decorative — title carries meaning).
+- Container: `role="status"` for empty / info / success; `role="alert"` for error / warning.
+- Primary action gets focus when component mounts (full-page Result), so keyboard users land on the recovery path.
+
+```html
+<section role="alert">
+  <Icon aria-hidden="true" />
+  <h1>찾을 수 없는 페이지입니다</h1>
+  <p>주소를 확인하거나 홈으로 돌아가 주세요.</p>
+  <Button autoFocus>홈으로</Button>
+</section>
+```
+
+## Code examples
+
+```tsx
+// 404 page
+<Result
+  status="404"
+  title="찾을 수 없는 페이지입니다"
+  description="주소를 확인하거나 홈으로 돌아가 주세요."
+  primaryAction={{ label: "홈으로", onClick: () => nav("/") }}
+  secondaryAction={{ label: "검색", onClick: () => nav("/search") }}
+/>
+
+// Post-checkout success
+<Result
+  status="success"
+  title="결제가 완료되었습니다"
+  description={`주문번호 #${order.id}`}
+  primaryAction={{ label: "주문 내역 보기", onClick: () => nav(`/orders/${order.id}`) }}
+  secondaryAction={{ label: "쇼핑 계속", onClick: () => nav("/") }}
+  extra={
+    <Card>
+      <p>{order.items.length}개 상품 · ₩{order.total.toLocaleString()}</p>
+      <p>예상 도착일: {order.deliveryDate}</p>
+    </Card>
+  }
+/>
+
+// Permission error
+<Result
+  status="403"
+  title="접근 권한이 없습니다"
+  description="이 페이지를 보려면 관리자 권한이 필요합니다."
+  primaryAction={{ label: "관리자에게 요청", onClick: requestAccess }}
+  secondaryAction={{ label: "돌아가기", onClick: () => history.back() }}
+/>
+
+// First-time empty in a list
+<Empty
+  title="아직 거래 내역이 없어요"
+  description="첫 거래를 추가해 보세요."
+  primaryAction={{ label: "거래 추가", onClick: openAddModal }}
+/>
+
+// Filtered empty
+<Empty
+  title="검색 결과가 없습니다"
+  description="다른 검색어를 시도해 보세요."
+  illustration="search"
+  primaryAction={{ label: "검색어 지우기", onClick: clearQuery }}
+/>
+
+// Inline empty (small card)
+<Card>
+  <Empty
+    inline
+    size="sm"
+    title="할 일이 없어요"
+    description="새 작업을 추가하면 여기에 표시됩니다."
+  />
+</Card>
+```
+
+## Edge cases
+
+- **Result during async waiting**: don't render Result for "loading" state. Use Skeleton or Spinner.
+- **Result with no actions**: legitimate for "Account closed" or "Operation logged" — but most should have at least one path.
+- **Empty inside a paginated list**: empty applies to page 1 only, not page 5 of 10. Page 5 with no items means "load more" exhausted, which is different.
+- **404 with deep link guess**: detect common patterns and offer ("Did you mean /projects/123?").
+- **Mobile sizing**: full `lg` may overflow on small phones. Cap icon at 100px on mobile.
+- **Long titles** (Korean often verbose): allow 2-line wrap; don't truncate.
+
+## Don't
+
+- Don't use Result for inline status indicators (use Tag or Badge).
+- Don't use Empty when there's an error — distinct pattern. See [`error-states.md`](../knowledge/patterns/error-states.md).
+- Don't show a Result with no primary action for failure states — user is stuck.
+- Don't auto-redirect after Result without giving the user time to read.
+- Don't use technical jargon ("Error 404"). Plain language.
+- Don't show stock illustrations from a vendor library — they date.
+- Don't render multiple Results stacked. One per screen.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/result/`](../refs/ant-design/components/result/) (Result) + [`refs/ant-design/components/empty/`](../refs/ant-design/components/empty/) (Empty). Both well-developed.
+- MUI: no dedicated components. Compose with Card + Typography.
+- shadcn-ui: no built-in. Compose from primitives.
+
+API choices made:
+- **Combined spec for Result + Empty**: 90% of the visual + a11y is shared. Speccing separately would force triplicate maintenance.
+- **`status` prop on Result, not Empty**: Empty doesn't have status semantics ("empty" is the state).
+- **`extra` slot on Result**: outcome confirmations frequently need order/transaction detail.
+- **`inline` mode on Empty**: full-page is overkill for cards/sidebars; provides escape hatch.
+
+## Cross-reference
+
+- [`knowledge/patterns/empty-states.md`](../knowledge/patterns/empty-states.md) — comprehensive empty pattern guide
+- [`knowledge/patterns/error-states.md`](../knowledge/patterns/error-states.md) — error pattern guide
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — Korean tone for results
+- [`examples/component-button.md`](component-button.md) — primary/secondary actions

package/examples/component-scroll-area.md

@@ -0,0 +1,199 @@
+# `ScrollArea` — spec
+
+> Synthesized from shadcn-ui `scroll-area` (Radix). Custom-styled scrollbar that replaces the platform default. Used when native scrollbars don't match the design system or when consistent cross-platform appearance is needed.
+
+## When to use
+
+- **Design-system-consistent scrollbars** across macOS / Windows / Linux (native scrollbars vary widely).
+- **Always-visible scrollbars** (macOS hides them by default; some UIs need them visible).
+- **Inside narrow surfaces** (sidebars, dropdowns) where native scrollbars look out of place.
+- **Brand-aligned visual** — color-customized scrollbars.
+
+When NOT to use:
+- The whole document body — let the browser handle main scroll.
+- Long-form reading content — native scroll is faster + more familiar.
+- Mobile-primary surfaces — system scroll is deeply integrated with momentum + bounce.
+
+## Anatomy
+
+```
+┌───────────────────────────┐
+│ Content                   ▒│ ← thumb (scrollbar)
+│  Item 1                   ▒│
+│  Item 2                   ▒│
+│  Item 3                   ▒│
+│  ...                      ▒│
+│                            │
+└───────────────────────────┘
+```
+
+## API
+
+```tsx
+<ScrollArea className="h-72 w-48 rounded-md border">
+  <div className="p-4">
+    {items.map(item => (
+      <div key={item.id}>{item.name}</div>
+    ))}
+  </div>
+</ScrollArea>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"auto" \| "always" \| "scroll" \| "hover"` | `"hover"` | Scrollbar visibility |
+| `scrollHideDelay` | `number` | `600` | Ms before scrollbar hides (when type is `scroll`) |
+| `dir` | `"ltr" \| "rtl"` | `"ltr"` | Direction (affects scroll position) |
+| `children` | `ReactNode` | — | Scrolling content |
+
+## Visibility modes
+
+| `type` | Behavior |
+| --- | --- |
+| `auto` | Show only when content overflows |
+| `always` | Always visible regardless of content |
+| `scroll` | Visible while scrolling, fades after `scrollHideDelay` |
+| `hover` (default) | Visible on hover or while scrolling |
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `ScrollArea` | Wrapper with overflow control |
+| `ScrollAreaViewport` | The clipping container (auto-rendered) |
+| `ScrollAreaScrollbar` | The scrollbar track + thumb (auto-rendered) |
+| `ScrollAreaThumb` | The draggable thumb (auto-rendered) |
+| `ScrollAreaCorner` | Bottom-right corner when both axes scroll (auto-rendered) |
+
+In practice, just use `<ScrollArea>` and let it manage subparts.
+
+## Custom scrollbar styles
+
+```css
+[data-radix-scroll-area-scrollbar] {
+  display: flex;
+  user-select: none;
+  touch-action: none;
+  padding: 2px;
+  background: transparent;
+  transition: background 200ms ease;
+}
+
+[data-radix-scroll-area-scrollbar][data-orientation="vertical"] {
+  width: 10px;
+}
+
+[data-radix-scroll-area-scrollbar][data-orientation="horizontal"] {
+  height: 10px;
+  flex-direction: column;
+}
+
+[data-radix-scroll-area-thumb] {
+  flex: 1;
+  background: var(--color-fg-muted);
+  border-radius: 5px;
+  position: relative;
+  cursor: pointer;
+}
+
+[data-radix-scroll-area-thumb]:hover {
+  background: var(--color-fg-default);
+}
+```
+
+## Tokens consumed
+
+```
+--color-fg-muted               (scrollbar thumb default)
+--color-fg-default             (thumb hover)
+--color-bg-secondary           (scrollbar track, optional)
+--space-xxs                    (scrollbar padding)
+--motion-fast                  (visibility transition)
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Resting (with `hover` type) | Scrollbar hidden |
+| Hovered or scrolling | Scrollbar visible (fade in 100ms) |
+| Thumb hover | Slightly darker / brighter thumb |
+| Thumb dragged | Active state visual |
+| Idle (after scroll) | Fades out (with `scroll` type) |
+
+## Accessibility
+
+- ScrollArea preserves native scroll keyboard handling (PageUp / PageDown / arrows / Space).
+- Don't replace native scroll mechanics — only the visual appearance.
+- Don't trap scroll inside without an obvious "exit" path (lock scroll OR document scroll, not both ambiguously).
+- For overflow-only-on-hover patterns: ensure keyboard users can also access (Tab to focus content, arrow / PageDown to scroll).
+- Mobile: respects native momentum scroll; thumb may be hidden on mobile (system handles it).
+
+## Code example — Sidebar nav with custom scrollbar
+
+```tsx
+function Sidebar() {
+  return (
+    <aside className="sidebar">
+      <header>
+        <Logo />
+      </header>
+
+      <ScrollArea className="flex-1 px-2">
+        <nav>
+          <NavSection title="Workspace">
+            {workspaceItems.map(item => <NavItem key={item.id} {...item} />)}
+          </NavSection>
+          <NavSection title="Projects">
+            {projects.map(p => <NavItem key={p.id} {...p} />)}
+          </NavSection>
+        </nav>
+      </ScrollArea>
+
+      <footer>
+        <UserMenu />
+      </footer>
+    </aside>
+  );
+}
+```
+
+## Code example — Chat history
+
+```tsx
+<ScrollArea type="always" className="chat-history">
+  {messages.map(m => (
+    <Message key={m.id} message={m} />
+  ))}
+</ScrollArea>
+```
+
+## Edge cases
+
+- **Content exact height as ScrollArea**: scrollbar may briefly appear during render; use `type="auto"`.
+- **Mac users with hidden scrollbars**: respect their preference; `type="hover"` works well.
+- **Touch device**: native touch scroll preserved; styled thumb usually invisible.
+- **Very long content (10,000+ items)**: virtualize content, not just the scrollbar (use react-virtual).
+- **RTL**: scrollbar appears on left; content scrolls right-to-left.
+- **Print**: native scroll; ScrollArea custom styling doesn't apply.
+- **Mobile keyboard opens**: viewport shrinks; ScrollArea height adjusts via parent layout.
+
+## Don't
+
+- Don't replace document-level scroll with ScrollArea. Browsers + native scroll handle that better.
+- Don't make custom scrollbars wildly different from system convention (users miss them).
+- Don't make the thumb so small it's hard to grab (< 8px width).
+- Don't disable native keyboard scroll keys.
+- Don't trap scroll without an exit (avoid scroll-jacking).
+- Don't add scroll-snap inside ScrollArea unless intentional — can interact unexpectedly with momentum.
+
+## References
+
+- shadcn-ui: [`scroll-area`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/scroll-area.tsx) (Radix)
+- CSS `scrollbar-color`, `scrollbar-width` properties (browser-specific styling alternative)
+
+## Cross-reference
+
+- [`examples/component-sidebar.md`](component-sidebar.md) — common consumer
+- [`examples/component-chat-interface.md`](component-chat-interface.md) — chat history scroll
+- [`examples/component-table.md`](component-table.md) — table with scrollable body