@design-ai/cli 4.55.0

package/examples/component-spin.md

@@ -0,0 +1,173 @@
+# `Spin` (Spinner) — spec
+
+> Citing Ant Design `Spin`, MUI `CircularProgress` (used as spinner), shadcn-ui (composition)
+
+## Purpose
+
+A simple loading indicator. **Indeterminate spinner** for "something is happening, no progress %." Different from `Progress` (percentage-based) and `Skeleton` (content-shape).
+
+## When Spin vs Skeleton vs Progress
+
+| Use Spin | Use Skeleton | Use Progress |
+| --- | --- | --- |
+| Async action with no shape (button submit, modal opening) | Page/list initial load (you know the shape) | Determinate operation (upload %, multi-step) |
+| Brief (< 2s) waiting | Longer (1s+) load | Any duration with % known |
+
+## Anatomy
+
+```
+Standalone:                     With overlay:
+   ⟳                            ┌─────────────────┐
+                                 │   ⟳             │
+                                 │   "로딩 중..."  │
+                                 │                  │
+                                 └─────────────────┘
+                                 (content faded behind)
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Spinner | yes | Rotating circular indicator |
+| Tip / label | optional | "로딩 중..." text |
+| Overlay | optional | Fades the wrapped content |
+| Children | optional | Wrapped element (Spin can wrap content to overlay loading) |
+
+## API
+
+```tsx
+// Standalone
+<Spin size="md" />
+<Spin tip="로딩 중..." />
+
+// Wrapping content
+<Spin spinning={isLoading}>
+  <DataTable data={data} />
+</Spin>
+
+// Inside a button (rare — buttons have their own loading)
+<Button loading><Spin size="sm" /></Button>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `spinning` | `boolean` | `true` | Whether to show |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Spinner size |
+| `tip` | `string` | — | Optional label |
+| `delay` | `number` | `0` | Show only after N ms (avoids flash for fast loads) |
+| `children` | `ReactNode` | — | Wrapped content (gets overlay) |
+| `indicator` | `ReactNode` | default circular | Custom spinner |
+
+## Sizes
+
+| Size | Diameter | Use |
+| --- | --- | --- |
+| `sm` | 16px | Inline (button, badge) |
+| `md` (default) | 24px | Standard inline |
+| `lg` | 40px | Page-level loading |
+
+## Animation
+
+Standard spinner: `360°` rotation, 1000ms loop, linear easing.
+
+```css
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+.spinner {
+  animation: spin 1000ms linear infinite;
+}
+```
+
+For Material 3 style: arc length also varies (10–80%) for a "pulsing" feel. More expensive; default static-arc spinner is fine.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Spinning (active) | Animated rotation |
+| Stopped (`spinning={false}`) | Hidden (or unmounted) |
+| Delayed (`delay > 0`) | Hidden until delay elapses |
+
+## Accessibility
+
+- Wrap with `aria-busy="true"` on the loading container.
+- The spinner itself: `aria-hidden="true"` (decorative).
+- Provide `aria-label` on the wrapper if tip is missing: "Loading...".
+- Don't announce "Loading" repeatedly via `aria-live` — single announcement at start of load.
+
+```html
+<div aria-busy="true" aria-live="polite" aria-label="데이터 로딩 중">
+  <span class="spin" aria-hidden="true">⟳</span>
+</div>
+```
+
+For `delay` > 0: don't show the spinner OR announce until the delay elapses. Avoids flash for fast loads.
+
+## Reduced motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .spinner { animation: none; }
+}
+```
+
+When motion disabled: spinner is static. Provide a text label or different non-animated indicator (dots fading, etc.). Don't leave a static rotated icon — looks broken.
+
+## Tokens consumed
+
+```
+--color-primary-default      (default spinner color)
+--color-text-secondary       (tip text)
+--color-bg-overlay           (overlay when wrapping content)
+--space-sm
+--motion-default              (rotation period; though linear loop ignores easing)
+```
+
+## Code example
+
+```tsx
+// Inline spinner
+<div>
+  <Spin /> 데이터를 불러오는 중...
+</div>
+
+// Wrapping a list
+<Spin spinning={isLoading} tip="저장하는 중...">
+  <Form>
+    {/* form content */}
+  </Form>
+</Spin>
+
+// With delay (avoid flash)
+<Spin spinning={isLoading} delay={200} />
+{/* Spinner appears only if loading takes > 200ms */}
+```
+
+## Edge cases
+
+- **Delay vs no delay**: for sub-200ms loads, don't show spinner at all (avoid flicker). Use `delay: 200` to gate.
+- **Spin wrapping a tall scrollable**: overlay covers visible viewport; spinner centered. Don't anchor to top.
+- **Multiple Spin on screen**: collapse into one spinner if they all represent the same operation.
+- **Reduced motion**: spinner is static; text "로딩 중..." carries the meaning.
+- **Custom indicator** (animated logo, etc.): provide via `indicator` prop. Don't violate reduced-motion preference.
+
+## Don't
+
+- Don't use Spin for known-shape content. Use Skeleton.
+- Don't use Spin for known-percentage operation. Use Progress.
+- Don't show Spin without context. Pair with text or place it where the content will land.
+- Don't auto-show spinner on every interaction. Sub-200ms loads don't need spinner.
+- Don't omit reduced-motion handling.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/spin/`](../refs/ant-design/components/spin/) — `Spin`. Standard spinner with `tip`, `delay`, `wrapperClassName`.
+- MUI: [`CircularProgress`](../refs/mui/packages/mui-material/src/CircularProgress/) (Material's equivalent). Same role.
+- shadcn-ui: no built-in. Use Lucide's `Loader2` icon with CSS spin.
+
+## Cross-reference
+
+- [`examples/component-skeleton.md`](component-skeleton.md) — for known-shape loading
+- [`examples/component-progress.md`](component-progress.md) — for percentage operations
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — reduced motion

package/examples/component-spinner.md

@@ -0,0 +1,204 @@
+# `Spinner` — spec
+
+> Synthesized from MUI `CircularProgress` (indeterminate variant) and shadcn-ui's spinner pattern. Indeterminate loading indicator — a small rotating circle / ring used inline or as a centered loading state.
+
+## Spinner vs Progress vs Skeleton
+
+> Pick the right loading affordance for the situation.
+
+| | Spinner | Progress | Skeleton |
+| --- | --- | --- | --- |
+| Determinate? | No | Yes | No |
+| Use | Brief loads; intermediate state | Long operations with measurable progress | Layout-aware "content is coming" |
+| Where | Buttons, inline within content | Section / page-level, file uploads | Cards, lists, full pages |
+| Duration | < 1-2s typical | 1-30s+ | Until content arrives |
+
+For "I'm doing something briefly" → Spinner. For "X% done" → Progress. For "preserve layout while loading" → Skeleton.
+
+## Anatomy
+
+```
+   ◜◝
+  ◟◞              ← rotating partial-arc
+
+[Loading...]      ← optional adjacent text
+```
+
+## API
+
+```tsx
+<Spinner />
+<Spinner size="sm" />
+<Spinner size="lg" />
+
+<Spinner aria-label="Loading data" />
+
+<Spinner color="brand" />
+<Spinner color="muted" />
+
+<Button loading>Save</Button>   {/* Spinner inside button */}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Diameter |
+| `color` | `"brand" \| "muted" \| "current" \| "white"` | `"current"` | Color |
+| `aria-label` | `string` | `"Loading"` | Screen-reader label |
+| `speed` | `"slow" \| "normal" \| "fast"` | `"normal"` | Rotation duration |
+
+## Sizes
+
+| Size | Diameter | Use |
+| --- | --- | --- |
+| `xs` | 12px | Inline within text, very compact |
+| `sm` | 16px | Inside small buttons, beside text |
+| `md` (default) | 24px | Inline within content, default buttons |
+| `lg` | 32px | Section-level loading |
+| `xl` | 48px | Page-level loading |
+
+For most cases: `sm` for inline, `md` for component-level, `lg` for full-section. Avoid going larger — use Skeleton instead.
+
+## Variants
+
+### Color
+
+- `current` (default): inherits from text color (`color: currentColor`).
+- `brand`: brand color.
+- `muted`: gray.
+- `white`: explicit white (for use on dark / colored backgrounds, e.g., inside primary button).
+
+### Speed
+
+- `slow`: 1.5s rotation (calm; for premium / luxury feel).
+- `normal` (default): 0.8-1s rotation.
+- `fast`: 0.5s rotation (urgent, snappy feedback).
+
+## States
+
+Stateless. Spinner is always animating (when rendered).
+
+For "stop spinning + show success": un-render the Spinner; render a check icon instead. Don't try to morph the spinner.
+
+## Tokens consumed
+
+```
+--color-fg-default                 (current)
+--color-brand-default              (brand variant)
+--color-fg-muted                   (muted)
+--motion-spinner-duration          (typically 1s)
+```
+
+## CSS
+
+```css
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+
+.spinner {
+  display: inline-block;
+  width: var(--spinner-size);
+  height: var(--spinner-size);
+  border: 2px solid currentColor;
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation: spin 2s linear infinite;  /* Slower; or none entirely */
+  }
+}
+```
+
+For SVG-based spinner (more flexible coloring / variants):
+
+```tsx
+<svg className="spinner" viewBox="0 0 24 24" fill="none">
+  <circle cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="2" opacity="0.25" />
+  <path d="M2 12 a10 10 0 0 1 10-10" stroke="currentColor" strokeWidth="2" />
+</svg>
+```
+
+## Accessibility
+
+- `role="status"` (preferred) OR `role="progressbar" aria-valuenow="0"` (less common for indeterminate).
+- `aria-label` (default "Loading") for screen readers.
+- For very brief loads (< 500ms): consider hiding the Spinner from screen readers (`aria-hidden`) — repeated "Loading" announcements are noise.
+- For longer loads: include text content adjacent ("Loading data...") so users with reduced-motion who don't see spinning still get feedback.
+- Reduced motion: slow the rotation OR replace with static dots.
+
+## Inside buttons
+
+```tsx
+<Button loading>
+  {loading && <Spinner size="sm" color="current" />}
+  Save
+</Button>
+```
+
+When button is loading:
+- Spinner replaces (or sits beside) the icon.
+- Button is disabled (`aria-disabled`).
+- Label may be replaced ("Saving...") OR kept (with spinner before it).
+
+## Code example
+
+```tsx
+function SaveButton() {
+  const [saving, setSaving] = useState(false);
+
+  return (
+    <Button onClick={async () => { setSaving(true); await save(); setSaving(false); }} disabled={saving}>
+      {saving && <Spinner size="sm" />}
+      {saving ? "저장 중..." : "저장"}
+    </Button>
+  );
+}
+
+function DataTable() {
+  if (loading) {
+    return (
+      <div className="table-loading">
+        <Spinner size="lg" />
+        <p>데이터를 불러오는 중...</p>
+      </div>
+    );
+  }
+  // ...
+}
+```
+
+For longer waits, Korean: "잠시만 기다려 주세요...".
+
+## Edge cases
+
+- **Spinner shown for < 200ms**: skip it. Brief flicker = bad UX. Use a debounced reveal.
+- **Spinner stuck for > 10s**: show timeout UI ("This is taking longer than expected. Retry?").
+- **Multiple concurrent spinners on a page**: coordinate so one section settles, others reveal staggered.
+- **Spinner inside disabled button + button gets focus**: `aria-disabled` prevents click but allows focus. Spinner inside is purely visual.
+- **Reduced motion**: per CSS above; can also replace with static "Loading" text.
+- **RTL**: no impact (rotation is symmetric).
+
+## Don't
+
+- Don't show Spinner for sub-200ms operations. Flickers; do nothing instead.
+- Don't use Spinner where progress is measurable. Use Progress.
+- Don't use Spinner to fill large empty regions. Use Skeleton.
+- Don't show multiple spinners in one button — confusing. One per loading control.
+- Don't rotate via JS — use CSS animation.
+- Don't omit reduced-motion handling.
+
+## References
+
+- MUI: [`CircularProgress`](../refs/mui/packages/mui-material/src/CircularProgress) (indeterminate variant)
+- Patterns: standard SVG spinner
+
+## Cross-reference
+
+- [`examples/component-progress.md`](component-progress.md) — determinate progress
+- [`examples/component-skeleton.md`](component-skeleton.md) — layout-aware loading
+- [`examples/component-button.md`](component-button.md) — Spinner inside loading button
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — duration tiers

package/examples/component-splitter.md

@@ -0,0 +1,210 @@
+# `Splitter` (resizable panel) — spec
+
+> Citing Ant Design `Splitter`, MUI (no built-in), shadcn-ui `resizable`
+
+## Purpose
+
+Two or more panels separated by draggable handles. User resizes by dragging the handle. Used for: IDE/editor layouts, three-pane email apps, dashboard with sidebar, side-by-side editors.
+
+## When Splitter vs alternatives
+
+| Pattern | Use |
+| --- | --- |
+| **Splitter** | User-driven resize between persistent panels |
+| **Collapsible drawer** | Show/hide a panel (binary, not gradient resize) |
+| **Tabs** | Switch between mutually exclusive views |
+| **Grid** | Static layout |
+
+Splitter is a desktop-first pattern. Mobile rarely uses it (small screens, touch resize is awkward).
+
+## Anatomy
+
+```
+Horizontal split:
+┌────────────┬┊┬─────────────────────────────┐
+│            │┊│                              │
+│  Panel A   │┊│   Panel B                    │
+│            │┊│                              │
+└────────────┴┊┴─────────────────────────────┘
+              ↑ draggable handle
+
+Vertical split:
+┌──────────────────────────────────────────────┐
+│                                              │
+│  Panel A                                      │
+│                                              │
+├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┤  ← drag handle
+│                                              │
+│  Panel B                                      │
+│                                              │
+└──────────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Splitter direction="horizontal">
+  <Splitter.Panel size={240} minSize={200} maxSize={400}>
+    <Sidebar />
+  </Splitter.Panel>
+  <Splitter.Panel size="auto">
+    <MainContent />
+  </Splitter.Panel>
+</Splitter>
+
+<Splitter direction="horizontal">
+  <Splitter.Panel size={240}>{nav}</Splitter.Panel>
+  <Splitter.Panel size="40%">{listing}</Splitter.Panel>
+  <Splitter.Panel size="auto">{detail}</Splitter.Panel>
+</Splitter>
+```
+
+| Prop (root) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | |
+| `lazy` | `boolean` | `false` | Defer panel rendering during drag (perf) |
+| `onResizeEnd` | `(sizes: number[]) => void` | — | Persist sizes |
+
+| Prop (Panel) | Type | Description |
+| --- | --- | --- |
+| `size` | `number \| string \| "auto"` | px, %, "auto" (consume remaining) |
+| `minSize` | `number` | Minimum size when dragging |
+| `maxSize` | `number` | Maximum size |
+| `collapsible` | `boolean` | Collapse to 0 when dragged below minSize |
+| `defaultSize` | `number \| string` | Initial (uncontrolled) |
+
+## Behavior
+
+- User drags handle: adjacent panels resize.
+- Constraints: min/max enforced.
+- Collapsible: dragging below `minSize` snaps to 0; clicking handle restores to `minSize`.
+- Total: panels share the parent's space; resizing one redistributes.
+
+## Persistence
+
+Common pattern: persist sizes to localStorage:
+
+```tsx
+const [sizes, setSizes] = useLocalStorage("splitter-sizes", [240, 400, 800]);
+
+<Splitter onResizeEnd={setSizes}>
+  <Splitter.Panel size={sizes[0]}>{...}</Splitter.Panel>
+  <Splitter.Panel size={sizes[1]}>{...}</Splitter.Panel>
+  <Splitter.Panel size={sizes[2]}>{...}</Splitter.Panel>
+</Splitter>
+```
+
+User's preference survives refresh.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default handle | Subtle 2-4px line, neutral color |
+| Hover handle | Border color changes, cursor `col-resize` (or `row-resize`) |
+| Dragging | Handle highlighted, panels shrink/grow live |
+| Focus-visible (keyboard) | 2px ring around handle |
+| Panel collapsed | Width/height 0; expand affordance visible |
+
+## Tokens consumed
+
+```
+--color-border-default       (handle line)
+--color-border-strong         (hover)
+--color-primary-default       (drag-active or focus)
+--color-bg-default
+--color-focus-ring
+--space-xs                    (handle thickness)
+--motion-fast                 (resize transitions)
+```
+
+## Sizes
+
+| Direction | Handle thickness |
+| --- | --- |
+| Horizontal | 4–6px width |
+| Vertical | 4–6px height |
+
+For touch devices: increase hit area to 12–16px around the visual line via padding.
+
+## Accessibility
+
+- Each handle: `role="separator"`, `aria-orientation`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`.
+- Handle is keyboard-reachable: `tabIndex="0"`.
+- Resize via keyboard: `←` / `→` (horizontal) or `↑` / `↓` (vertical) — increment/decrement by 10px.
+
+```html
+<div role="separator"
+     aria-orientation="vertical"
+     aria-valuenow="240"
+     aria-valuemin="200"
+     aria-valuemax="400"
+     tabindex="0"
+     aria-label="Resize navigation panel">
+</div>
+```
+
+## Mobile
+
+For mobile: usually replace with stacked panels, or a single-pane experience with drill-in. Splitter at narrow widths is awkward.
+
+If Splitter is needed on mobile (rare, e.g., for tablet apps): handle width should be 16+ px for touch.
+
+## Code example
+
+```tsx
+// IDE-style 3-pane layout
+function CodeEditor() {
+  const [sizes, setSizes] = useLocalStorage("editor-sizes", [240, 50, 50]);
+
+  return (
+    <Splitter direction="horizontal" onResizeEnd={setSizes}>
+      <Splitter.Panel size={sizes[0]} minSize={180} maxSize={400} collapsible>
+        <FileTree />
+      </Splitter.Panel>
+      <Splitter.Panel size={`${sizes[1]}%`} minSize={20}>
+        <Editor />
+      </Splitter.Panel>
+      <Splitter.Panel size="auto">
+        <Preview />
+      </Splitter.Panel>
+    </Splitter>
+  );
+}
+
+// Vertical: editor + console
+<Splitter direction="vertical">
+  <Splitter.Panel size="70%">
+    <Editor />
+  </Splitter.Panel>
+  <Splitter.Panel size="30%" minSize={100}>
+    <Console />
+  </Splitter.Panel>
+</Splitter>
+```
+
+## Edge cases
+
+- **All panels at minSize and total < parent**: leftover space shows; consider extending the last panel or showing a fallback.
+- **Window resize**: panels redistribute proportionally if percentage-based; clamp to absolute mins.
+- **Nested Splitters**: works but heavy. Avoid 3+ nested levels — UX gets confusing.
+- **Panels with text content**: ensure text wraps when narrow; otherwise, splitter becomes a horizontal-scroll trap.
+
+## Don't
+
+- Don't use Splitter for content that doesn't benefit from user-driven resize.
+- Don't remember the user's resize *globally* across all instances — be context-specific.
+- Don't allow collapse to 0 without an obvious "expand" affordance somewhere visible.
+- Don't render the handle without a clear cursor change (col-resize / row-resize) — users won't know it's draggable.
+- Don't omit aria-valuenow on the separator — keyboard users need feedback.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/splitter/`](../refs/ant-design/components/splitter/) — `Splitter` + `Splitter.Panel`. Modern Ant addition.
+- MUI: no built-in. Use `react-resizable-panels` or `allotment`.
+- shadcn-ui: [`resizable.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/resizable.tsx) — wraps `react-resizable-panels`. Cleanest impl.
+
+## Cross-reference
+
+- [`examples/component-drawer.md`](component-drawer.md) — collapsible alternative
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md) — broader layout context