@design-ai/cli 4.55.0

package/examples/component-tooltip.md

@@ -0,0 +1,178 @@
+# `Tooltip` — spec
+
+> Citing Ant Design `Tooltip`, MUI `Tooltip`, shadcn-ui `tooltip`
+
+## Purpose
+
+A short hover/focus hint about an interactive element. **Help text, not content.** If users would miss the content without it, the content needs to be visible — not in a tooltip.
+
+## When NOT to use a tooltip
+
+- For critical instructions (use inline help text or labels).
+- For long content (use Popover).
+- On non-interactive elements that aren't focusable (keyboard users can't reach).
+- For toolbar icon-only buttons that NEED tooltips → consider visible labels instead, or accept that hover is the only path.
+
+## Anatomy
+
+```
+              ┌─────────────────────┐
+              │  Hint text          │
+              └────────┬────────────┘
+                       ▼ (arrow)
+              [trigger element]
+```
+
+Or other side: trigger above, tooltip below; etc. — depending on space.
+
+## API
+
+```tsx
+<Tooltip content="이 아이콘을 클릭하면 설정으로 이동합니다">
+  <IconButton aria-label="Settings"><SettingsIcon /></IconButton>
+</Tooltip>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `content` | `string \| ReactNode` | — | Required. The hint text. |
+| `children` | `ReactElement` | — | The trigger. **Single element only**, must support `ref`. |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` | Preferred position |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the side |
+| `delayMs` | `number` | `300` | Open delay (avoid flicker on quick mouse pass) |
+| `closeDelayMs` | `number` | `100` | Close delay |
+| `disabled` | `boolean` | `false` | Suppress tooltip without disabling trigger |
+| `open` | `boolean` | — | Controlled open (overrides hover/focus) |
+| `onOpenChange` | `(open: boolean) => void` | — | |
+| `arrow` | `boolean` | `true` | Show arrow pointing at trigger |
+
+## Behavior
+
+| Trigger | Action |
+| --- | --- |
+| Mouse over trigger | Open after `delayMs` |
+| Mouse leave | Close after `closeDelayMs` |
+| Keyboard focus on trigger | Open immediately (no delay) |
+| Keyboard blur | Close immediately |
+| Click trigger | Tooltip closes (don't override the click) |
+| Touch on trigger | **Don't show tooltip on touch** — interferes with tap. Use long-press to show OR don't show on touch at all (most common). |
+
+## Sizes
+
+| Size | Padding | Font | Max width |
+| --- | --- | --- | --- |
+| `sm` (default for icon button hints) | 4px 8px | 12px | 200px |
+| `md` (default for buttons with labels) | 6px 10px | 13px | 280px |
+| `lg` (descriptive, multi-line) | 8px 12px | 14px | 360px |
+
+> Most tooltips should be `sm`. If you need `lg`, you probably want a Popover.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | not in DOM (or `display: none`) |
+| Opening | 100ms fade + slight scale 0.95 → 1 |
+| Open | settled, dark bg + light text (or inverse, see token) |
+| Closing | 75ms fade |
+
+## Tokens consumed
+
+```
+--color-bg-tooltip          (typically inverse of bg-default — dark in light mode, light in dark mode)
+--color-text-on-tooltip     (inverse of text-primary)
+--space-xs, --space-sm
+--radius-sm
+--font-size-xs, --font-size-sm
+--shadow-popover
+--motion-fast, --easing-out
+```
+
+## Accessibility — critical
+
+The native `title` attribute does NOT meet a11y requirements:
+- Doesn't show on keyboard focus on most platforms.
+- Mobile browsers ignore it.
+- Inconsistent across screen readers.
+
+**Use a real tooltip primitive** (Radix Tooltip / shadcn / Floating UI). Don't use `title`.
+
+### ARIA wiring
+
+- Trigger: `aria-describedby={tooltipId}` when tooltip is open; remove or empty when closed.
+- Tooltip: `role="tooltip"`, `id={tooltipId}`.
+- Trigger should also have its own accessible name (`aria-label` if icon-only) — the tooltip is supplementary, not the primary name.
+
+```html
+<!-- Bad: tooltip is the only accessible name -->
+<button><CloseIcon /></button>
+<Tooltip>Close</Tooltip>
+
+<!-- Good: button has aria-label, tooltip is descriptive -->
+<button aria-label="Close"><CloseIcon /></button>
+<Tooltip>Closes the dialog and discards changes</Tooltip>
+
+<!-- Best for icon button: hide tooltip when redundant with aria-label -->
+<button aria-label="Close"><CloseIcon /></button>
+<!-- (no tooltip — aria-label is the name and the visual icon is the affordance) -->
+```
+
+### Touch / mobile
+
+- `hover` doesn't exist on touch.
+- Long-press to show tooltip is iOS/Android convention but rarely implemented.
+- **Best practice**: tooltips are a desktop affordance. On mobile, surface critical info inline or as a help drawer (`?` icon → bottom sheet).
+
+## Code example
+
+```tsx
+// Standard icon button with tooltip
+<Tooltip content="새 항목 추가">
+  <IconButton aria-label="Add item" onClick={handleAdd}>
+    <PlusIcon />
+  </IconButton>
+</Tooltip>
+
+// Disabled tooltip on disabled button (workaround — disabled buttons don't fire hover events)
+<Tooltip content="권한이 없습니다">
+  <span> {/* wrapper enables hover */}
+    <Button disabled>Edit</Button>
+  </span>
+</Tooltip>
+
+// Keyboard-shortcut hint
+<Tooltip content="Save (Cmd+S)">
+  <Button onClick={handleSave}>Save</Button>
+</Tooltip>
+```
+
+## Edge cases
+
+- **Tooltip on disabled button**: native `disabled` doesn't fire mouse events. Wrap in a `<span>` so the wrapper handles hover.
+- **Tooltip on a link that wraps to new line**: the tooltip might appear far from the cursor. Better to make the tooltip follow the trigger's bounding box, or use `align="start"`.
+- **Long content that wraps**: cap at max-width and wrap. If consistently long, you want a Popover.
+- **Rapid mouse pass**: tooltip opens on hover delay (300ms), so quick mouse-bys don't trigger. Don't reduce the delay below 200ms.
+- **Tooltip near viewport edge**: should auto-flip to opposite side. Use Floating UI or Radix's collision detection.
+- **Reduced motion**: disable fade animation, just show/hide.
+- **In a scrollable container**: tooltip should reposition or hide on scroll.
+- **Korean tooltips**: short hangul fits comfortably; if your tooltip is > 1 line, reconsider — should probably be inline help.
+
+## Don't
+
+- Don't put critical content in tooltips. Keyboard-only users on mobile cannot access them.
+- Don't use a tooltip on a non-interactive element (e.g., a static icon). Either make it interactive (focusable button) or use inline help text.
+- Don't show a tooltip on an `aria-label` that says the same thing — redundant and noisy.
+- Don't use HTML `title` attribute. Build a real tooltip.
+- Don't put interactive elements inside the tooltip. It's hover-triggered and disappears on mouse-out.
+- Don't show on click (that's a Popover).
+
+## References
+
+- Ant Design: [`refs/ant-design/components/tooltip/`](../refs/ant-design/components/tooltip/) — `Tooltip` with rich placement options (12 directions). `mouseEnterDelay` / `mouseLeaveDelay` props.
+- MUI: [`refs/mui/packages/mui-material/src/Tooltip/`](../refs/mui/packages/mui-material/src/Tooltip/) — `Tooltip` with `placement`, `enterDelay`, `leaveDelay`, `arrow`. Solid implementation.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/tooltip.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/tooltip.tsx) — Radix Tooltip primitive. **Default — best a11y of the three.**
+
+## Cross-reference
+
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) — focus-driven tooltips
+- [WAI-ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)

package/examples/component-tour.md

@@ -0,0 +1,176 @@
+# `Tour` (in-product overlay tour) — spec
+
+> Citing Ant Design `Tour`, MUI (no built-in), shadcn-ui (composition with Popover)
+
+## Purpose
+
+A series of overlay tooltips that highlight UI elements one at a time, with "Next / Previous / Skip" navigation. Used for: onboarding new users, surfacing new features, complex tool walkthroughs.
+
+**Use sparingly.** See [`knowledge/patterns/onboarding.md`](../knowledge/patterns/onboarding.md) — tours have the highest friction of any onboarding pattern.
+
+## Anatomy
+
+```
+[Page content, dimmed except for the highlighted element]
+
+   ┌──[ highlighted UI element ]──┐
+   │   [target, brightly visible]  │
+   └──────────────────────────────┘
+        ▼ (callout pointer)
+   ┌────────────────────────────────────┐
+   │  Step 1 of 4                        │
+   │                                      │
+   │  Click here to add a transaction.   │
+   │                                      │
+   │       [Skip]    [Next]              │
+   └────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Backdrop dim | yes | Darkens the page (~50% black) |
+| Spotlight area | yes | Cuts a hole around the target element so it's bright |
+| Callout | yes | Position relative to target |
+| Step indicator | yes | "Step N of M" |
+| Title | yes | Action description |
+| Next / Previous / Skip | yes | Step navigation |
+
+## API
+
+```tsx
+<Tour
+  open={tourOpen}
+  steps={[
+    {
+      target: "#add-button",
+      title: "거래 추가",
+      description: "여기를 클릭해 첫 거래를 추가해 보세요.",
+      placement: "bottom",
+    },
+    {
+      target: "#filter-area",
+      title: "필터링",
+      description: "기간 / 카테고리로 거래를 필터링할 수 있어요.",
+    },
+    {
+      target: "#export",
+      title: "내보내기",
+      description: "거래 내역을 CSV로 내보낼 수 있어요.",
+    },
+  ]}
+  onClose={() => setTourOpen(false)}
+  onComplete={() => markFirstRunDone()}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | Whether tour is active |
+| `current` | `number` | `0` | Current step index (controlled mode) |
+| `onChange` | `(step: number) => void` | — | |
+| `steps` | `Step[]` | — | Tour steps |
+| `onClose` | `() => void` | — | User clicked Skip / closed |
+| `onComplete` | `() => void` | — | Reached the end |
+| `placement` | `"top" \| "right" \| "bottom" \| "left"` (default callout side) | `"bottom"` | Per-step override possible |
+| `mask` | `boolean` | `true` | Show backdrop dim |
+| `maskClosable` | `boolean` | `false` | Click on backdrop closes |
+
+```ts
+type Step = {
+  target: string | HTMLElement;     // CSS selector or element ref
+  title: string;
+  description: ReactNode;
+  placement?: "top" | "right" | "bottom" | "left";
+  hideArrow?: boolean;
+  beforeShow?: () => void | Promise<void>;   // e.g., scroll target into view
+  afterHide?: () => void;
+};
+```
+
+## Behavior
+
+### Step transition
+
+1. Tour finds target element by selector/ref.
+2. Calls `beforeShow` (e.g., scroll into view, expand a section).
+3. Fades in backdrop + cuts spotlight around target.
+4. Renders callout near target.
+5. User clicks Next → repeat for next step.
+
+### Target element off-screen
+
+`beforeShow` should `scrollIntoView` to bring the target into view. Wait for scroll to complete (200–300ms), then position callout.
+
+### Target element not present
+
+If selector doesn't match (e.g., conditional UI not rendered), skip the step or show error. Best: validate steps when starting tour.
+
+### Closing
+
+- **Skip**: closes tour, `onClose` fires. Current step is remembered (offer to resume later).
+- **Complete**: reaches last step + clicks Done. `onComplete` fires.
+- **Backdrop click**: only if `maskClosable=true`.
+- **Escape key**: closes (UX convention — provide).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Idle | not visible |
+| Animating in | fade backdrop + scale-in callout |
+| Active step | spotlight + callout visible |
+| Transitioning between steps | smooth cross-fade or slide |
+
+## Tokens consumed
+
+```
+--color-bg-overlay         (backdrop)
+--color-bg-elevated         (callout)
+--color-text-primary
+--color-text-secondary
+--color-primary-default     (Next button bg)
+--space-md, --space-base
+--radius-md
+--shadow-popover
+--motion-default            (250-300ms transitions)
+```
+
+## Accessibility
+
+- Tour is a modal-equivalent: focus trap inside the callout while active.
+- Each callout: `role="dialog"`, `aria-labelledby={titleId}`, `aria-describedby={descId}`.
+- Backdrop: `aria-hidden="true"`.
+- Step indicator: announced ("Step 1 of 4").
+- Focus moves into callout on step change.
+- Escape closes tour.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Cycle through callout interactive elements (Next, Prev, Skip) |
+| `Enter` (on Next) | Advance |
+| `Escape` | Close tour |
+| `←` `→` | Optional: previous / next step (not standard) |
+
+## Don't
+
+- Don't use Tour as the primary onboarding for simple products. Empty-state CTA is friendlier. See [`knowledge/patterns/onboarding.md`](../knowledge/patterns/onboarding.md).
+- Don't run tours longer than 5 steps. User fatigue is real.
+- Don't auto-show tours on every visit. Show once, dismiss, persist.
+- Don't tour features the user might never use. Tour the core path.
+- Don't make tours required. Always provide Skip.
+- Don't run tour without scroll/visibility setup — target out of view = broken.
+- Don't gate the feature behind the tour ("can't proceed until you complete tour").
+
+## References
+
+- Ant Design: [`refs/ant-design/components/tour/`](../refs/ant-design/components/tour/) — `Tour` with steps, target refs, custom rendering. Modern Ant addition.
+- MUI: no built-in. Use libraries like `react-joyride` or `intro.js`.
+- shadcn-ui: no built-in. Compose with Popover + custom backdrop.
+
+## Cross-reference
+
+- [`knowledge/patterns/onboarding.md`](../knowledge/patterns/onboarding.md) — when to use Tour vs other patterns
+- [`examples/component-popover.md`](component-popover.md) — Tour callouts use popover pattern
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — focus trap, Escape behavior

package/examples/component-transaction-list-item.md

@@ -0,0 +1,243 @@
+# `TransactionListItem` (custom — Korean fintech / 가계부) — spec
+
+> Custom component pattern. The most-rendered row in any 가계부 / banking / payment app. Many tens of these per screen — performance + visual consistency matters.
+
+## Purpose
+
+A single row in a transaction list — date, category, description, amount. Tappable to open detail.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ [icon]  Description                       -₩12,500       │
+│         Subtitle (category, payment method, time)        │
+└─────────────────────────────────────────────────────────┘
+
+Example (expense):
+🍽  스타벅스 강남점                              -₩5,500
+    카페 · 12:34
+
+Example (income):
+💰  급여                                       +₩2,500,000
+    회사 · 09:00
+
+Example (transfer between own accounts):
+🔄  자동이체 (적금)                              ₩-100,000
+    국민은행 → 우리은행 · 어제 17:00
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Category icon | yes | Emoji or icon (matches CategoryPicker) |
+| Title | yes | Merchant name or transaction description |
+| Subtitle | yes | Category / payment method / time |
+| Amount | yes | Right-aligned, tabular numerals, signed |
+| Trailing chevron | optional | Drill-in affordance |
+| Status badge | optional | "취소" (cancelled), "보류" (pending) |
+
+## API
+
+```tsx
+<TransactionListItem
+  icon="🍽"
+  title="스타벅스 강남점"
+  subtitle="카페 · 12:34"
+  amount={-5500}
+  type="expense"
+  onClick={() => openTransaction(id)}
+/>
+
+<TransactionListItem
+  icon="💰"
+  title="급여"
+  subtitle="회사 · 09:00"
+  amount={2500000}
+  type="income"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `string \| ReactNode` | — | Emoji or icon (typically matches CategoryPicker) |
+| `title` | `string \| ReactNode` | — | Merchant or description |
+| `subtitle` | `string \| ReactNode` | — | Category · time / payment method |
+| `amount` | `number` | — | Signed amount in smallest unit (won) |
+| `type` | `"expense" \| "income" \| "transfer" \| "neutral"` | inferred from sign | Drives amount color |
+| `currency` | `"KRW" \| ...` | `"KRW"` | Format |
+| `onClick` | `() => void` | — | Drill-in handler |
+| `status` | `"pending" \| "cancelled" \| "settled"` | `"settled"` | Optional status badge |
+| `trailingMeta` | `ReactNode` | — | After amount; e.g., balance after this transaction |
+
+## Amount color (critical)
+
+Per [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md):
+
+| Type | Color | Sign |
+| --- | --- | --- |
+| `expense` | `--color-money-negative` | `-` (e.g., `-₩5,500`) |
+| `income` | `--color-money-positive` | `+` (e.g., `+₩2,500,000`) |
+| `transfer` | `--color-money-neutral` (gray) | `-` or no sign |
+| `neutral` | `--color-text-primary` | based on amount |
+
+For Korean banking (not stocks): `money-positive` is green, `money-negative` is red. For Korean stock convention (red=up): different rules apply, but stock apps don't use `TransactionListItem` typically.
+
+## Sizes
+
+| Size | Row height | Icon | Title font | Subtitle font | Amount font |
+| --- | --- | --- | --- | --- | --- |
+| `compact` | 56px | 32px | 14px | 12px | 14px |
+| `default` | 64px | 40px | 15px | 13px | 15px |
+| `comfortable` | 72px | 48px | 16px | 14px | 17px |
+
+Korean consumer apps: `default` is the right balance.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | resting |
+| Hover | bg `--color-bg-subtle` |
+| Pressed (tap) | bg `--color-bg-elevated` (mobile feedback) |
+| Focus-visible | 2px ring around the row |
+| Pending | "보류" badge + reduced opacity 0.7 |
+| Cancelled | "취소" badge + strikethrough on amount |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle              (hover)
+--color-bg-elevated            (pressed)
+--color-text-primary
+--color-text-secondary         (subtitle)
+--color-money-positive
+--color-money-negative
+--color-money-neutral
+--color-text-tertiary           (separator dot, "·")
+--color-warning                  (pending badge)
+--color-error                    (cancelled badge)
+--color-focus-ring
+--space-sm, --space-md
+--font-feature-amount: 'tnum' 1  (tabular numerals — critical)
+--font-size-sm, --font-size-base
+--radius-full                    (icon container)
+```
+
+## Accessibility
+
+- Render as `<button>` (or `<a>` if `onClick` is navigation). Don't use `<div onClick>`.
+- Icon: `aria-hidden="true"` — the title carries meaning.
+- `aria-label` on the row for screen readers, including amount and date:
+  ```html
+  <button aria-label="스타벅스 강남점, 카페, 12:34, 5,500원 지출">
+    ...
+  </button>
+  ```
+- For lists, `<ul>` + `<li>` containers.
+- Touch target: ≥ 44×44 pt — `default` size at 64px exceeds.
+
+## List performance
+
+Lists of 100+ transactions:
+- **Virtualize** with FlatList (React Native) or react-virtual / @tanstack/react-virtual (web).
+- Memoize the row component to prevent re-renders.
+- Lazy-load icons if using SVG imports.
+
+Per [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md).
+
+## Date / time grouping
+
+Most apps group transactions by date with sticky headers:
+
+```
+─── 5월 7일 (목) ────────────────────
+🍽 스타벅스 강남점          -₩5,500
+🚌 지하철                   -₩1,500
+
+─── 5월 6일 (수) ────────────────────
+💰 급여                    +₩2,500,000
+🛍 마켓컬리                  -₩48,000
+```
+
+Header style: small (12-13px), `--color-text-tertiary`, sticky on scroll.
+
+For "오늘" (today) and "어제" (yesterday): use the words instead of dates.
+
+## Mobile patterns
+
+### Swipe actions
+
+iOS-style swipe to reveal actions (delete, edit, pin):
+
+```
+[🍽 스타벅스 ...]  ←(swipe)  [Edit] [Delete]
+```
+
+Use sparingly per [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md).
+
+### Long-press menu
+
+Long-press opens a contextual action sheet:
+- 수정 (Edit)
+- 카테고리 변경 (Change category)
+- 메모 추가 (Add memo)
+- 삭제 (Delete)
+
+Common in Korean 가계부 apps.
+
+## Code example
+
+```tsx
+function TransactionList({ transactions }: Props) {
+  const groupedByDate = useMemo(() => groupByDate(transactions), [transactions]);
+
+  return (
+    <FlatList
+      data={groupedByDate}
+      keyExtractor={(item) => item.date}
+      renderItem={({ item: group }) => (
+        <>
+          <DateHeader sticky>{formatDate(group.date)}</DateHeader>
+          {group.transactions.map((tx) => (
+            <TransactionListItem
+              key={tx.id}
+              icon={tx.category.icon}
+              title={tx.merchant}
+              subtitle={`${tx.category.label} · ${formatTime(tx.time)}`}
+              amount={tx.amount}
+              type={tx.type}
+              onClick={() => navigation.navigate("TransactionDetail", { id: tx.id })}
+            />
+          ))}
+        </>
+      )}
+    />
+  );
+}
+```
+
+## Don't
+
+- Don't omit tabular numerals — amounts won't align in column.
+- Don't use `--color-error` for expense color. Use `--color-money-negative`.
+- Don't omit category icon — Korean users scan by emoji.
+- Don't render 1000+ rows without virtualization.
+- Don't truncate the amount — full precision matters in financial UI.
+- Don't show "0원" for zero-amount placeholder rows. Hide them.
+- Don't right-align title. Left-align (LTR) — only amount is right-aligned.
+
+## API rationale
+
+- **`amount: number` not formatted string**: source of truth is the integer; formatting is presentation. AmountInput stores numbers; consistent with this.
+- **`type` separate from amount sign**: positive amount might still be a "transfer" (visually neutral), not income.
+- **Icon as string accepts emoji**: Korean apps use emoji directly; allows flexibility for icons too.
+
+## Cross-reference
+
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — money color semantics
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md) — list patterns, virtualization
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — Korean fintech conventions
+- [`examples/component-category-picker.md`](component-category-picker.md) — paired with CategoryPicker
+- [`examples/component-amount-input.md`](component-amount-input.md) — paired in transaction forms
+- [`examples/component-card.md`](component-card.md) — TransactionListItem is essentially a list-row card