@design-ai/cli 4.55.0

package/examples/component-list.md

@@ -0,0 +1,198 @@
+# `List` — spec
+
+> Synthesized from Ant Design `List` and MUI `List` + `ListItem`. The semantic + styled wrapper around a list of `Item` rows. Distinct from `Item` (single row) and `Table` (tabular data).
+
+## When to use
+
+- Vertical stack of similar entities (notifications, files, contacts).
+- With pagination, infinite scroll, or filtering.
+- When `<ul>` + items need consistent styling + a11y.
+
+When NOT to use:
+- Tabular data (use `Table`).
+- Single row of actions (use `Toolbar` / `Flex`).
+- Heterogeneous content (use composition of `Card`s).
+
+## Anatomy
+
+```
+[List header (optional)]
+─────────────────────────
+[Item 1]
+[Item 2]
+[Item 3]
+─────────────────────────
+[List footer (optional, e.g., Load more)]
+```
+
+## API
+
+```tsx
+<List
+  header={<h3>Recent activity</h3>}
+  footer={<Button onClick={loadMore}>Load more</Button>}
+  loading={loading}
+  empty={<Empty description="No activity yet" />}
+>
+  {activities.map(a => (
+    <Item key={a.id}>
+      <ItemMedia>
+        <Avatar src={a.user.avatar} />
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>{a.user.name}</ItemTitle>
+        <ItemDescription>{a.action}</ItemDescription>
+      </ItemContent>
+    </Item>
+  ))}
+</List>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `header` | `ReactNode` | — | Sticky header above items |
+| `footer` | `ReactNode` | — | Below items (Load more, totals) |
+| `loading` | `boolean` | `false` | Show Skeleton instead of items |
+| `empty` | `ReactNode` | — | Shown when 0 items |
+| `dividers` | `boolean` | `true` | Show separators between items |
+| `density` | `"compact" \| "comfortable" \| "relaxed"` | `"comfortable"` | Item padding |
+| `as` | `"ul" \| "ol" \| "div"` | `"ul"` | Underlying element |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Loading | Skeleton items |
+| Empty | `empty` prop content |
+| With items | Standard render |
+| Error | (handled externally; pass error UI in children) |
+
+## Variants
+
+### With dividers (default)
+
+```
+[Item 1]
+─────
+[Item 2]
+─────
+[Item 3]
+```
+
+### Without dividers (cards spaced)
+
+```
+[Item 1]
+
+[Item 2]
+
+[Item 3]
+```
+
+Use when items are full Cards with their own boundaries.
+
+### With sections (grouped)
+
+```
+Yesterday
+─────
+[Item 1]
+[Item 2]
+
+Last week
+─────
+[Item 3]
+```
+
+Group via wrapping headings + smaller sub-lists.
+
+## Tokens consumed
+
+```
+--list-bg
+--list-divider
+--list-header-bg                   (sticky header bg)
+--list-empty-fg
+--space-md, --space-lg
+--font-size-sm                     (header)
+```
+
+## Accessibility
+
+- Use `<ul>` (default) or `<ol>` if order matters.
+- Each `<Item>` is `<li>` semantically.
+- Header outside `<ul>` (separate element).
+- For load-more: announce new items via `aria-live="polite"`.
+- Empty state: `role="status"`.
+
+## Pagination + infinite scroll
+
+```tsx
+{/* Pagination at bottom */}
+<List footer={<Pagination ... />}>...</List>
+
+{/* Infinite scroll (trigger near bottom) */}
+<List footer={<InfiniteTrigger onTrigger={loadMore} loading={loadingMore} />}>
+  ...
+</List>
+```
+
+For long lists (1000+ items): virtualize. Use react-virtual or react-virtuoso.
+
+## Code example
+
+```tsx
+function NotificationList() {
+  const { data, isLoading, error } = useNotifications();
+
+  if (error) return <ErrorState error={error} />;
+
+  return (
+    <List
+      header={<h2>알림</h2>}
+      loading={isLoading}
+      empty={
+        <EmptyState
+          illustration="no-notifications"
+          title="알림이 없어요"
+          description="새 활동이 있을 때 여기에 표시돼요."
+        />
+      }
+    >
+      {data?.map(n => (
+        <Item key={n.id} interactive onClick={() => markRead(n.id)}>
+          <ItemMedia><n.icon /></ItemMedia>
+          <ItemContent>
+            <ItemTitle>{n.title}</ItemTitle>
+            <ItemDescription>{n.message}</ItemDescription>
+          </ItemContent>
+          <ItemActions>
+            <time>{formatRelative(n.timestamp)}</time>
+            {!n.read && <UnreadDot />}
+          </ItemActions>
+        </Item>
+      ))}
+    </List>
+  );
+}
+```
+
+## Don't
+
+- Don't use List for tabular data. Use Table.
+- Don't omit empty state. Empty list = unclear if loading or really empty.
+- Don't render 10,000 items unvirtualized. Performance dies.
+- Don't use raw `<ul>` for item-style data. Use List + Item primitives.
+
+## References
+
+- Ant: [`List`](../refs/ant-design/components/list)
+- MUI: [`List`](../refs/mui/packages/mui-material/src/List) + [`ListItem`](../refs/mui/packages/mui-material/src/ListItem)
+- HTML5 `<ul>` / `<ol>` / `<li>`
+
+## Cross-reference
+
+- [`examples/component-item.md`](component-item.md) — single row
+- [`examples/component-table.md`](component-table.md) — tabular alternative
+- [`examples/component-empty-state.md`](component-empty-state.md) — full-page empty
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md)

package/examples/component-loading-button.md

@@ -0,0 +1,125 @@
+# `LoadingButton` (pattern) — spec
+
+> **Pattern, not a separate component.** As of MUI v6, `LoadingButton` was merged into `Button` (`<Button loading>`); shadcn / Ant don't ship a separate "loading button" either. This spec documents the **loading-state pattern** that any `Button` should support — applied to `Button` props in your design system.
+
+## When to use
+
+- Any button that triggers an async operation (form submit, API call, file upload).
+- Especially destructive actions (delete, leave, transfer) — without a loading state, users double-click and trigger duplicate operations.
+
+## Anatomy
+
+```
+Default state              Loading state
+┌─────────────────┐        ┌─────────────────┐
+│ [icon]  Label   │   →    │ ⠋  Loading      │
+└─────────────────┘        └─────────────────┘
+```
+
+The label may stay or change ("저장하기" → "저장 중..."). The leading icon is replaced with a spinner. The button stays the same width (loading shouldn't reflow the layout).
+
+## API
+
+Add these props to `Button`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `loading` | `boolean` | `false` | Show spinner; disable click |
+| `loadingPosition` | `'start' \| 'end' \| 'center'` | `'center'` | Spinner position; `start`/`end` keeps the label visible |
+| `loadingIndicator` | `ReactNode` | `<CircularProgress size={16} />` | Custom indicator |
+| `loadingText` | `string` | — | Optional label override during loading (e.g., "저장 중...") |
+
+## States
+
+| State | Visual | Interaction |
+| --- | --- | --- |
+| Default | Standard button | Clickable |
+| Hover | bg-hover | Clickable |
+| Loading | Spinner + label/loadingText; bg + fg muted slightly | **NOT clickable**; cursor remains pointer (signals "we got your click, working on it") |
+| Disabled | reduced opacity | Not clickable |
+| Loading + disabled | Same as loading | (functionally equivalent) |
+
+## Tokens consumed
+
+```
+--button-bg-default
+--button-bg-hover
+--button-fg-default
+--spinner-size-16    /* default loading indicator */
+--space-sm           /* gap between spinner and label */
+--button-min-width   /* width-locked during loading */
+```
+
+## Accessibility
+
+- `aria-busy="true"` while loading. Screen readers announce "busy" status.
+- `aria-disabled="true"` while loading (NOT the `disabled` HTML attribute — that removes the button from the tab order, breaks Esc/screen reader recovery).
+- Focus stays on the button during loading. After completion, focus management depends on outcome:
+  - Success: move focus to next logical step OR a success toast.
+  - Error: announce the error via `aria-live="polite"` toast; keep focus on the button so user can retry.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Long async operation (>10s)** — show progress percentage if known, or supplement with a toast "잠시만 기다려 주세요". 10s+ silent loading reads as broken.
+- **Network failure** — exit loading, restore label, surface error inline or via toast. Don't leave the button in loading state on error.
+- **Korean labels** — "저장하기" → "저장 중..." (3 dots, not "..." typography). The 중 character signals progress; pair with spinner for redundancy.
+- **Optimistic UI** — for cheap operations (toggle a switch), prefer optimistic update over loading button.
+
+## Code example
+
+```tsx
+import { Button, CircularProgress } from "@mui/material";
+
+function SaveButton({ onSave }: { onSave: () => Promise<void> }) {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function handleClick() {
+    setLoading(true);
+    setError(null);
+    try {
+      await onSave();
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "알 수 없는 오류");
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <>
+      <Button
+        variant="contained"
+        onClick={handleClick}
+        loading={loading}
+        loadingPosition="start"
+        startIcon={<SaveIcon />}
+        aria-busy={loading}
+      >
+        {loading ? "저장 중..." : "저장하기"}
+      </Button>
+      {error && (
+        <Alert severity="error" sx={{ mt: 1 }} role="alert">
+          {error}
+        </Alert>
+      )}
+    </>
+  );
+}
+```
+
+## Don't
+
+- Don't disable the button without showing a loading indicator — users think it's broken.
+- Don't move focus away during loading; users may want to cancel (Esc, navigate back).
+- Don't reset the form on click before the async resolves — if it fails, you've lost the user's input.
+- Don't show "Loading..." with no spinner. Spinner is the universal "we're working" signal.
+- Don't allow double-click during loading. Set `loading={true}` synchronously before the async starts.
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-button.md`](component-button.md)
+- [`knowledge/patterns/empty-states.md`](../knowledge/patterns/empty-states.md) — what to show during long loads
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)

package/examples/component-loading-sequence.md

@@ -0,0 +1,254 @@
+<!-- hand-written -->
+# `LoadingSequence` (custom — splash + first-screen coordination) — spec
+
+> Coordinates the cold-launch experience: brand splash → biometric / auth gate (optional) → first screen reveal. Wraps the moments after process start and before the user sees real content. Pairs with [`knowledge/motion/app-loading-sequences.md`](../knowledge/motion/app-loading-sequences.md).
+
+## Purpose
+
+Make cold launch feel **intentional** instead of like a stall:
+
+1. Show brand-led splash that matches the first screen's background (no flash).
+2. Optionally chain a biometric gate (Korean fintech default).
+3. Cross-fade into the real app content as soon as it's ready.
+4. Respect `prefers-reduced-motion`.
+
+Without this: blank screen → flash of unstyled content → spinner → app. Reads as broken.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────┐
+│                                      │
+│                                      │
+│                                      │
+│            [logo / wordmark]         │  ← splash (brand bg)
+│                                      │
+│                                      │
+│                                      │
+└──────────────────────────────────────┘
+              ↓ (optional)
+┌──────────────────────────────────────┐
+│        🔒 Face ID                    │
+│        본인 확인이 필요합니다          │  ← biometric gate
+│        [지문으로 잠금 해제]            │
+└──────────────────────────────────────┘
+              ↓
+┌──────────────────────────────────────┐
+│  Header                              │
+│  [content cross-fades in]            │  ← first screen
+│  ...                                 │
+└──────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<LoadingSequence
+  brand={{ logo: <Logo />, backgroundColor: "var(--color-brand-bg)" }}
+  minDurationMs={600}
+  gate={biometricEnabled ? <BiometricGate onUnlock={resolve} /> : null}
+  onReady={() => setAppReady(true)}
+>
+  <App />
+</LoadingSequence>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `brand` | `{ logo: ReactNode; backgroundColor: string }` | — | Splash content + bg color (must match first screen) |
+| `minDurationMs` | `number` | `600` | Floor on splash duration to avoid flash if app boots in 80ms |
+| `gate` | `ReactNode \| null` | `null` | Optional auth gate (biometric, PIN). When present, splash → gate → content. |
+| `onReady` | `() => void` | — | Fires when content is fully visible |
+| `children` | `ReactNode` | — | Real app content; rendered behind splash, revealed on transition |
+| `disableAnimation` | `boolean` | auto via `prefers-reduced-motion` | Skip cross-fade |
+
+## Behavior
+
+### State machine
+
+```
+       ┌─────────┐
+       │ booting │  ← process started; splash fully opaque
+       └────┬────┘
+            │ minDurationMs reached AND app ready
+            ▼
+       ┌─────────┐
+       │  gate?  │ ← if `gate` prop, render it (splash bg stays)
+       └────┬────┘
+            │ gate resolves (or no gate)
+            ▼
+    ┌─────────────┐
+    │ revealing   │ ← 200ms cross-fade splash → content
+    └──────┬──────┘
+           │
+           ▼
+       ┌────────┐
+       │ ready  │ ← onReady fires; LoadingSequence unmounts splash
+       └────────┘
+```
+
+### Timing budget
+
+| Phase | Duration | Notes |
+| --- | --- | --- |
+| Splash visible | `max(minDurationMs, timeToAppReady)` | Floor prevents flash; ceiling is real boot time |
+| Gate (if present) | User-driven | Typically 1–3s for biometric; can be longer |
+| Cross-fade | 200ms | Cross-fade splash out + content in simultaneously |
+| Total cold launch | 0.6–3s typical | Korean fintech: 1.5–3s with biometric |
+
+### Cross-fade
+
+```css
+.splash {
+  opacity: 1;
+  transition: opacity var(--motion-medium) var(--ease-out);
+}
+.splash[data-state="revealing"] { opacity: 0; }
+
+.content {
+  opacity: 0;
+  transition: opacity var(--motion-medium) var(--ease-out);
+}
+.content[data-state="revealing"],
+.content[data-state="ready"] { opacity: 1; }
+```
+
+Both run together — true cross-fade, not sequential.
+
+## States
+
+| State | Splash | Gate | Content |
+| --- | --- | --- | --- |
+| `booting` | Visible (opacity 1) | hidden | Hidden behind splash |
+| `gating` | Hidden | Visible | Behind gate |
+| `revealing` | Fading out | Hidden | Fading in |
+| `ready` | Unmounted | Unmounted | Visible |
+
+## Tokens consumed
+
+```
+--color-brand-bg                (splash + first screen background — MUST match)
+--color-brand-fg                (logo color on splash)
+--motion-medium                 (200ms cross-fade)
+--ease-out                      (cross-fade easing)
+--z-splash                      (above all app chrome)
+```
+
+## Korean fintech convention
+
+Toss / KakaoBank pattern:
+
+```tsx
+<LoadingSequence
+  brand={{ logo: <TossLogo />, backgroundColor: "#0064FF" }}
+  minDurationMs={400}
+  gate={
+    user.biometricEnrolled ? (
+      <BiometricGate
+        prompt="Face ID로 잠금 해제"
+        fallback={<PINGate />}
+      />
+    ) : null
+  }
+>
+  <Dashboard />
+</LoadingSequence>
+```
+
+- Brand color splash (full bleed)
+- Biometric gate appears almost immediately (within minDurationMs floor)
+- Gate dominates the cold-launch experience; actual app boot hides underneath
+- After unlock: 200ms cross-fade to dashboard
+
+See [`examples/component-biometric-gate.md`](component-biometric-gate.md).
+
+## Accessibility
+
+- Splash: `role="presentation"` (decorative). Logo gets `alt="[brand name]"` if `<img>`, or `aria-label` if `<svg>`.
+- Gate: standard a11y from gate component.
+- During splash: focus is trapped on splash root with `tabindex="-1"` so screen readers don't read app behind it prematurely.
+- Content reveal: announce via `<div role="status" aria-live="polite">앱 준비 완료</div>` only if minDurationMs is hit and reveal is delayed beyond 1s. Otherwise silent.
+- `prefers-reduced-motion`: skip cross-fade; instant swap. Splash still shows for `minDurationMs`.
+
+## Implementation hints
+
+```tsx
+function LoadingSequence({ brand, minDurationMs = 600, gate, onReady, children }: Props) {
+  const [phase, setPhase] = useState<"booting" | "gating" | "revealing" | "ready">("booting");
+  const mountedAt = useRef(Date.now());
+  const [appReady, setAppReady] = useState(false);
+  const reduced = usePrefersReducedMotion();
+
+  // Wait for app content to render at least once
+  useEffect(() => {
+    requestIdleCallback(() => setAppReady(true));
+  }, []);
+
+  // Transition booting → gating/revealing once minDuration + appReady
+  useEffect(() => {
+    if (!appReady) return;
+    const elapsed = Date.now() - mountedAt.current;
+    const wait = Math.max(0, minDurationMs - elapsed);
+    const id = setTimeout(() => {
+      setPhase(gate ? "gating" : "revealing");
+    }, wait);
+    return () => clearTimeout(id);
+  }, [appReady, gate, minDurationMs]);
+
+  // Reveal → ready
+  useEffect(() => {
+    if (phase !== "revealing") return;
+    const id = setTimeout(() => {
+      setPhase("ready");
+      onReady?.();
+    }, reduced ? 0 : 200);
+    return () => clearTimeout(id);
+  }, [phase, onReady, reduced]);
+
+  return (
+    <>
+      {phase !== "ready" && (
+        <div
+          className="splash"
+          data-state={phase}
+          style={{ background: brand.backgroundColor }}
+          role="presentation"
+        >
+          {phase === "gating" ? gate : brand.logo}
+        </div>
+      )}
+      <div className="content" data-state={phase}>
+        {children}
+      </div>
+    </>
+  );
+}
+```
+
+## Edge cases
+
+- **App boots faster than `minDurationMs`**: splash still shown until floor. Prevents 80ms flash.
+- **App boots slower than splash floor**: splash stays until app is ready. No premature reveal.
+- **Gate fails (biometric denied 3×)**: bubble up to gate's `onFallback`; LoadingSequence stays in `gating` until resolved.
+- **App backgrounded during splash**: pause timers via `visibilitychange` listener; resume on focus.
+- **Hot reload in dev**: `LoadingSequence` should NOT re-trigger on every HMR — only on real cold mount.
+- **Server-side rendering**: render content directly without splash on SSR; client-side mount triggers splash only if `document.readyState !== "complete"` at mount.
+
+## Don't
+
+- Don't put a spinner on the splash. Static logo only. Looping spinner reads as stuck.
+- Don't animate the logo with bounce / pulse on every cold launch — once the user has seen it, animation feels precious.
+- Don't mismatch `brand.backgroundColor` with the first screen's bg. The whole point is seamless transition.
+- Don't keep splash up longer than 3 seconds without a gate. User thinks the app froze.
+- Don't tie `onReady` to data fetching — fires when first paint completes, not when feed is loaded.
+
+## References
+
+No upstream component matches. This composes splash + gate + cross-fade in a single shell.
+
+## Cross-reference
+
+- [`knowledge/motion/app-loading-sequences.md`](../knowledge/motion/app-loading-sequences.md) — strategy
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — duration / easing
+- [`examples/component-biometric-gate.md`](component-biometric-gate.md) — gate component
+- [`examples/component-page-transition.md`](component-page-transition.md) — route-level transitions (after splash)