@design-ai/cli 4.55.0

package/examples/component-steps.md

@@ -0,0 +1,264 @@
+# `Steps` (Stepper) — spec
+
+> Citing Ant Design `Steps`, MUI `Stepper`, shadcn-ui (no built-in — composed)
+
+## Purpose
+
+Visualizes progress through a sequence of steps. Used in: multi-step forms, checkout flows, onboarding wizards, KYC / 본인인증 flows.
+
+Different from:
+
+| Pattern | Use |
+| --- | --- |
+| **Steps / Stepper** | Sequential, predetermined N steps |
+| **Breadcrumb** | Hierarchical position (not sequential) |
+| **Tabs** | Mutually exclusive views, no inherent order |
+| **Progress bar** | Continuous % completion |
+
+## Anatomy
+
+```
+Horizontal:
+┌────┐    ┌────┐    ┌────┐    ┌────┐
+│ ✓  │ ── │ 2  │ ── │ 3  │ ── │ 4  │
+└────┘    └────┘    └────┘    └────┘
+완료      현재      대기      대기
+
+Vertical:
+┌────┐
+│ ✓  │  Step 1: 본인인증
+│    │  완료
+└────┘
+  │
+┌────┐
+│ 2  │  Step 2: 정보 입력
+│    │  진행 중
+└────┘
+  │
+┌────┐
+│ 3  │  Step 3: 확인
+│    │  대기
+└────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Step indicator | yes | Number / icon — shows status |
+| Step label | usually | Title of the step |
+| Step description | optional | Subtitle or instruction |
+| Connector | yes | Line between steps (filled if completed) |
+
+## API
+
+```tsx
+<Steps current={2} status="process">
+  <Steps.Item title="본인인증" description="휴대폰 번호로 인증" />
+  <Steps.Item title="정보 입력" description="기본 정보를 입력합니다" />
+  <Steps.Item title="확인" description="입력한 정보를 확인합니다" />
+  <Steps.Item title="완료" />
+</Steps>
+```
+
+| Prop (root) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `current` | `number` | `0` | Index of the currently-active step (0-indexed) |
+| `status` | `"process" \| "wait" \| "finish" \| "error"` | `"process"` | Status of the current step |
+| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `clickable` | `boolean` | `false` | Allow user to click steps to navigate |
+| `onChange` | `(step: number) => void` | — | Called when user clicks a step (clickable mode) |
+
+| Prop (Item) | Type | Description |
+| --- | --- | --- |
+| `title` | `string \| ReactNode` | Step title |
+| `description` | `string \| ReactNode` | Subtitle |
+| `icon` | `ReactNode` | Custom icon (override number / checkmark) |
+| `disabled` | `boolean` | Skip this step (rare) |
+| `status` | overrides root | Per-step status override |
+
+## Step status states
+
+| Status | When | Visual |
+| --- | --- | --- |
+| `wait` | Steps after current | Gray indicator + gray line |
+| `process` | Currently-active step | Primary indicator + filled label |
+| `finish` | Completed steps | Primary indicator with checkmark + filled line |
+| `error` | Step failed (validation, upload error) | Error red indicator |
+
+## Variants
+
+### Numbered
+
+Steps show numbers `1, 2, 3...`. Switches to checkmark when complete.
+
+### Dot (compact)
+
+Just a dot indicator, no number. Use for many steps where number is noise:
+
+```
+●──●──●──○──○──○
+```
+
+### With icon
+
+Custom icon per step (e.g., 📞 phone for verification, 📋 form for input):
+
+```
+[📞] ── [📋] ── [✓]
+```
+
+### Status-only (just label)
+
+For text-heavy multi-step forms:
+
+```
+✓ 본인인증 완료
+● 정보 입력 (현재)
+○ 확인
+○ 완료
+```
+
+## Sizes
+
+| Size | Indicator | Font |
+| --- | --- | --- |
+| `sm` | 24px | 12px |
+| `md` (default) | 32px | 14px |
+| `lg` | 40px | 16px |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle
+--color-primary-default       (process, finish indicator + line)
+--color-text-primary
+--color-text-secondary        (wait labels)
+--color-text-tertiary         (descriptions)
+--color-on-primary             (text inside indicator when filled)
+--color-error                  (error status)
+--color-border-default         (connector line — wait state)
+--space-md, --space-base
+--radius-full                  (indicator circle)
+--motion-default               (transition between states)
+```
+
+## Accessibility
+
+- Wrap in `<ol role="list" aria-label="Form progress">` (or "checkout steps" / "verification steps").
+- Each step is `<li>`.
+- Current step: `aria-current="step"`.
+- Completed steps: include `<span class="sr-only">Completed: </span>` before label so screen reader announces status.
+- Connector lines: `aria-hidden="true"`.
+
+```html
+<ol aria-label="가입 진행 단계">
+  <li aria-current="false">
+    <span class="sr-only">완료: </span>
+    본인인증
+  </li>
+  <li aria-current="step">
+    정보 입력 (단계 2 / 4)
+  </li>
+  <li aria-current="false">
+    <span class="sr-only">대기: </span>
+    확인
+  </li>
+  ...
+</ol>
+```
+
+### When clickable
+
+Render steps as `<button>` (not just clickable divs):
+- Completed steps: clickable to revisit.
+- Future steps: disabled.
+- Use `aria-disabled="true"` for non-clickable future steps.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Move through clickable steps |
+| `Enter` / `Space` | Activate (navigate to step) |
+
+## Mobile patterns
+
+For narrow screens, horizontal steppers crunch. Three options:
+
+| Approach | Use |
+| --- | --- |
+| **Vertical stepper** | Best when label + description matter, screens are tall enough |
+| **Compact dot stepper** | Just dots showing "step N of M" |
+| **Just text** | "단계 2 / 4: 정보 입력" — simplest |
+
+For `n > 5` steps on mobile, **always switch to compact or text-only**.
+
+## Code example
+
+```tsx
+// Multi-step form
+<Form>
+  <Steps current={currentStep} status={hasError ? "error" : "process"}>
+    <Steps.Item title="본인인증" description="휴대폰으로 본인 확인" />
+    <Steps.Item title="정보 입력" description="기본 정보를 입력해 주세요" />
+    <Steps.Item title="확인" description="입력 정보를 확인합니다" />
+    <Steps.Item title="완료" />
+  </Steps>
+
+  <Form.Steps current={currentStep}>
+    <Form.Step><PhoneVerificationStep /></Form.Step>
+    <Form.Step><BasicInfoStep /></Form.Step>
+    <Form.Step><ConfirmStep /></Form.Step>
+    <Form.Step><DoneStep /></Form.Step>
+  </Form.Steps>
+
+  <div className="flex justify-between">
+    {currentStep > 0 && <Button variant="outline" onClick={prev}>이전</Button>}
+    <Button onClick={next}>{currentStep === 3 ? "완료" : "다음"}</Button>
+  </div>
+</Form>
+
+// Compact for mobile
+<div aria-label="가입 단계">
+  <p className="text-sm text-text-secondary">단계 {current + 1} / {total}</p>
+  <Progress value={(current + 1) / total * 100} />
+</div>
+```
+
+## Edge cases
+
+- **User navigates back**: previous steps must remain marked as `finish` (until they re-edit). Don't reset to `wait`.
+- **Step has an error after user advanced**: mark with `status="error"` AND keep the step accessible (don't trap user forward).
+- **Skipping optional steps**: if a step is skippable, show it as `finish` with a "Skipped" sub-label after skipping.
+- **Async server validation between steps**: lock advance with a spinner; don't let user click ahead while pending.
+- **Many steps (8+)**: switch to compact / text-only on mobile; consider splitting into sub-flows.
+- **One-step (just current shown)**: don't render Steps. Show "Step 1 of 1" or omit.
+- **Conditional steps** (steps that appear/disappear based on prior choices): manage in state; render the actual current set, not the maximum.
+
+## Don't
+
+- Don't make every step clickable. Only completed (and current); future steps locked.
+- Don't show error on a step the user hasn't yet touched.
+- Don't auto-advance steps — user explicitly clicks "Next".
+- Don't lose user input when navigating back.
+- Don't show 5+ step labels on mobile portrait — they overlap. Use compact.
+- Don't use Steps for non-sequential navigation. Use Tabs.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/steps/`](../refs/ant-design/components/steps/) — `Steps`, `Steps.Item`. Status, direction, size, progress dot variant. Most exhaustive.
+- MUI: [`refs/mui/packages/mui-material/src/Stepper/`](../refs/mui/packages/mui-material/src/Stepper/) — `Stepper`, `Step`, `StepLabel`, `StepContent`. Vertical with collapsible content per step is unique.
+- shadcn-ui: no built-in — compose from primitives. The `progress` and custom layout get you 80% there.
+
+API choices made:
+- **Adopted Ant's `current` prop** (numeric, 0-indexed) rather than per-step `active` flags — cleaner for forms.
+- **`status` at root applies to current step**; per-step override available.
+- **`clickable` opt-in**: most use cases are linear; making clickable the default invites users to skip ahead.
+
+## Cross-reference
+
+- [`examples/component-form.md`](component-form.md) — Form.Steps pattern
+- [`examples/component-progress.md`](component-progress.md) — alternative for non-discrete progress
+- [`knowledge/patterns/onboarding.md`](../knowledge/patterns/onboarding.md) — multi-step onboarding patterns
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — 본인인증 flow expectations

package/examples/component-stock-chart.md

@@ -0,0 +1,251 @@
+# `StockChart` (custom — Korean stock convention) — spec
+
+> Custom component pattern. Korean stock apps use **inverted color convention** — red for gains, blue for losses. Critical to get right.
+
+## Purpose
+
+Renders stock price data: candlestick chart, line chart, or volume bars. Used in: Korean stock trading apps (Kiwoom, NH투자, Toss Securities, Samsung Securities).
+
+## Korean color convention (CRITICAL)
+
+| Direction | Korean stock convention | Western convention |
+| --- | --- | --- |
+| Up / Gain | 🔴 **Red** | 🟢 Green |
+| Down / Loss | 🔵 **Blue** | 🔴 Red |
+| Unchanged | Gray | Gray |
+
+This is **inverted from Western** apps. Cite [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md).
+
+For multi-locale apps: provide a settings toggle ("색상 표시: 한국 / 서양") but **default to Korean for KR users**.
+
+## Anatomy
+
+```
+   1. Candlestick:                  2. Line + area:               3. Volume:
+   ┃     ┃▲                                                   ┃ ┃   ┃
+  ┃▲ ┃▲ ┃                          ─╮  ╭─╮                  ┃ ┃ ┃ ┃ ┃
+  ┃ ┃ ┃                            ╱  ╲╱  ╲                 ┃ ┃ ┃ ┃ ┃
+   ┃▼  ┃▼                       ──╯              ╲          ┃ ┃ ┃ ┃ ┃
+       ┃                                          ╲─        ┃ ┃ ┃ ┃ ┃
+
+  Date axis →
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Chart area | yes | Candle / line / bar rendering |
+| Time-range tabs | usually | 1일 / 1주 / 1개월 / 6개월 / 1년 / 5년 / 전체 |
+| Y-axis labels | yes | Price points, formatted as KRW |
+| X-axis labels | yes | Dates |
+| Crosshair (hover) | optional | Vertical + horizontal line + price + date callout |
+| Volume sub-chart | optional | Below price chart |
+
+## API
+
+```tsx
+<StockChart
+  data={priceData}
+  type="candle"
+  range="1month"
+  onRangeChange={setRange}
+  showVolume
+  korConvention                // explicit toggle
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `PricePoint[]` | — | Series of price points |
+| `type` | `"candle" \| "line" \| "area"` | `"candle"` | Chart type |
+| `range` | `"1day" \| "1week" \| "1month" \| "3month" \| "6month" \| "1year" \| "5year" \| "all"` | `"1month"` | Time window |
+| `onRangeChange` | `(range) => void` | — | |
+| `showVolume` | `boolean` | `true` | Render volume bars below |
+| `korConvention` | `boolean` | `true` (KR locale) | Red=up, blue=down |
+| `crosshair` | `boolean` | `true` | Hover indicator |
+| `tooltip` | `boolean \| (point) => ReactNode` | `true` | |
+| `loading` | `boolean` | `false` | |
+| `onCrosshairChange` | `(point) => void` | — | When user hovers |
+| `compareSeries` | `PriceSeries[]` | — | Overlay another stock for comparison |
+
+```ts
+type PricePoint = {
+  date: Date;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+};
+```
+
+## Color tokens
+
+```
+--color-stock-up           = #DC2626   (red — Korean) / #16A34A (green — Western)
+--color-stock-down         = #2563EB   (blue — Korean) / #DC2626 (red — Western)
+--color-stock-unchanged    = --color-text-tertiary
+--color-stock-volume       = --color-text-tertiary (subdued)
+--color-chart-grid         = --color-border-default
+--color-chart-axis         = --color-text-tertiary
+--color-chart-bg           = --color-bg-default
+--color-crosshair          = --color-text-secondary
+```
+
+Toggle via theme based on user's locale or preference.
+
+## Behavior
+
+### Range selector
+
+Above or below the chart:
+```
+[1일] [1주] [1개월] [3개월] [6개월] [1년] [5년] [전체]
+              ↑ active
+```
+
+Click → re-fetches and re-renders.
+
+### Crosshair on hover
+
+Hover over the chart shows:
+- Vertical line at the date hovered
+- Horizontal line at the price
+- Tooltip: date + open/high/low/close + volume
+
+```
+2026.05.07
+시가: ₩78,500
+고가: ₩79,200
+저가: ₩78,200
+종가: ₩78,800
+거래량: 1.2M
+```
+
+For touch devices: tap to show, tap elsewhere to dismiss.
+
+### Crosshair sync
+
+If volume sub-chart is shown: crosshair vertical line spans both charts.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Chart rendered |
+| Loading | Skeleton showing chart shape |
+| Error | "차트를 불러올 수 없어요" with retry |
+| Empty (no data) | "데이터가 없습니다" |
+| Hover (desktop) | Crosshair + tooltip |
+| Touch (mobile) | Tap to show crosshair, swipe to scrub |
+
+## Performance
+
+Stock charts can have 1000s of points. Optimize:
+
+- Use **Canvas / WebGL** rendering, not SVG (SVG breaks down past ~500 nodes).
+- Libraries: `lightweight-charts` (TradingView's), `recharts` (SVG-based, smaller datasets), `apexcharts`.
+- Aggregate data on long ranges (e.g., 5년 view shows monthly candles, not daily).
+- Throttle hover updates to 60fps max.
+
+For Korean apps: TradingView's `lightweight-charts` is widely used (small bundle, performant).
+
+## Tokens consumed
+
+```
+--color-stock-up
+--color-stock-down
+--color-stock-unchanged
+--color-stock-volume
+--color-chart-grid
+--color-chart-axis
+--color-chart-bg
+--color-crosshair
+--color-text-primary, --color-text-secondary
+--font-mono                 (price labels — tabular numerals)
+--font-feature-amount: 'tnum' 1
+--space-md
+--motion-fast
+```
+
+## Accessibility
+
+Charts are visual — ensure text alternatives:
+
+- `<figure aria-label="삼성전자 1개월 주가 차트">`
+- Provide a "데이터 표 보기" link that opens a tabular view of the same data.
+- Crosshair tooltip should be visible (not just hover-only) — tap pattern on mobile.
+- Text alternative: range, current price, change %, time period.
+
+```html
+<figure aria-label="삼성전자 1개월 차트, 종가 ₩78,800, 1.5% 상승">
+  <Chart />
+  <button onClick={openTableView}>데이터 표 보기</button>
+</figure>
+```
+
+## Code example
+
+```tsx
+function StockDetailScreen({ symbol }: Props) {
+  const [range, setRange] = useState("1month");
+  const { data, loading } = useStockHistory(symbol, range);
+  const userPrefersKorean = useUserPreference("stockColors") === "korean";
+
+  return (
+    <div>
+      <StockChart
+        data={data}
+        type="candle"
+        range={range}
+        onRangeChange={setRange}
+        showVolume
+        korConvention={userPrefersKorean}
+        loading={loading}
+      />
+
+      <RangeSelector value={range} onChange={setRange} />
+
+      <Stat label="종가" value={data?.[data.length - 1]?.close} type="amount" />
+      <Stat
+        label="등락"
+        value={data?.[data.length - 1]?.changePercent}
+        valueColor={getStockColor(change, userPrefersKorean)}
+      />
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+- **Pre-market / after-hours data**: dim or annotate. Korean exchanges (KOSPI/KOSDAQ) trade 9:00–15:30 KST.
+- **Holiday gaps**: skip (don't show empty space). Korean holidays affect the calendar.
+- **Stock splits / dividends**: annotate with markers on the date.
+- **Currency**: KRW (no decimals). Some stocks are USD (US-listed); show currency in label.
+- **Pinch-zoom on mobile**: support if range is "all" or longer.
+- **Crosshair on tiny screens**: tooltip should adjust to not overflow.
+
+## Don't
+
+- Don't use Western (green=up) colors in Korean apps without an explicit toggle.
+- Don't use red and green as the only signals (color-blind users) — pair with arrows or text.
+- Don't render 5,000+ candles as SVG — use canvas.
+- Don't show the chart without OHLC values somewhere accessible.
+- Don't auto-update the chart while user is hovering (jarring).
+
+## References
+
+No upstream component is exactly this — Korean stock convention is non-standard. Closest:
+- TradingView's `lightweight-charts` library (most popular)
+- Apache ECharts `candlestick` series
+- Recharts `Line` + custom candle rendering
+
+This is a **custom pattern + library wrapper** specific to Korean fintech.
+
+## Cross-reference
+
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — Korean stock color convention
+- [`knowledge/patterns/chart-color-encoding.md`](../knowledge/patterns/chart-color-encoding.md) — chart color rules
+- [`knowledge/patterns/chart-types.md`](../knowledge/patterns/chart-types.md) — when candle vs line vs area
+- [`knowledge/patterns/realtime-data.md`](../knowledge/patterns/realtime-data.md) — live price updates pattern
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — Korean fintech context

package/examples/component-swipeable-drawer.md

@@ -0,0 +1,149 @@
+# `SwipeableDrawer` — spec
+
+> Synthesized from MUI `SwipeableDrawer`. A `Drawer` variant supporting swipe gestures (open from edge / close by swiping away). Mobile-first; iOS / Android conventions.
+
+## When to use
+
+- Mobile primary navigation accessible via edge swipe.
+- Mobile bottom sheet draggable open / close.
+- Native-feel mobile menus.
+
+When NOT to use:
+- Desktop-only contexts (mouse drag is unintuitive).
+- Critical confirmation flows (use Modal / AlertDialog).
+- See [`component-drawer.md`](component-drawer.md) for non-swipeable variants.
+
+## Anatomy
+
+Same as `Drawer`, but with gesture support:
+
+```
+↓ swipe from left edge
+┌──────────┐
+│          │
+│          │
+│  Drawer  │
+│  content │
+│          │
+│          │
+└──────────┘
+   ↓ swipe right to close
+```
+
+## API
+
+```tsx
+<SwipeableDrawer
+  open={open}
+  onOpen={() => setOpen(true)}
+  onClose={() => setOpen(false)}
+  anchor="left"
+  swipeAreaWidth={20}
+  disableSwipeToOpen={false}
+>
+  <NavMenu />
+</SwipeableDrawer>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | controlled | Visibility |
+| `onOpen` / `onClose` | function | — | Gesture / click outside / Esc callbacks |
+| `anchor` | `"left" \| "right" \| "top" \| "bottom"` | `"left"` | Edge anchor |
+| `swipeAreaWidth` | `number` | `20` | Pixels from edge where swipe-open triggers |
+| `disableSwipeToOpen` | `boolean` | iOS auto-disabled | Disable open-by-swipe |
+| `disableDiscovery` | `boolean` | `false` | Hide the "discovery" peek that hints at swipe-to-open |
+| `minFlingVelocity` | `number` | `450` | Velocity threshold for flick-to-open/close |
+| `transitionDuration` | `number` | `300` | Ms for non-gesture transition |
+
+## Gesture mechanics
+
+| Gesture | Behavior |
+| --- | --- |
+| Edge swipe in | Drawer follows finger; releases → snap open or closed (based on past midpoint) |
+| Drag drawer back | Same — past midpoint snaps closed |
+| Flick (high velocity) | Always completes the action regardless of position |
+| Tap backdrop | Closes |
+| Esc (when keyboard available) | Closes |
+
+## States
+
+Same as Drawer. Plus:
+- **Following finger**: drawer position interpolated to touch X (or Y); backdrop opacity proportional.
+- **Snapping**: animate to nearest detent (open or closed) on release.
+
+## Tokens consumed
+
+Inherits from Drawer:
+```
+--drawer-bg
+--drawer-shadow
+--drawer-backdrop
+--drawer-width                    (left/right)
+--drawer-height                   (top/bottom)
+--motion-medium                   (snap animation)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- Same as Drawer (role="dialog" aria-modal="true", focus trap, Esc to close).
+- Add visible "Open menu" button — swipe is non-discoverable.
+- Touch gesture is supplemental; never the only way to open.
+
+## iOS quirk
+
+iOS Safari has its own edge-swipe gesture (back navigation). MUI auto-disables `swipeToOpen` on iOS to avoid conflict.
+
+For iOS: provide a visible hamburger button; swipe-to-close still works.
+
+## Code example — mobile nav
+
+```tsx
+function MobileApp() {
+  const [navOpen, setNavOpen] = useState(false);
+  const isMobile = useMediaQuery("(max-width: 767px)");
+
+  if (!isMobile) return <DesktopAppShell />;
+
+  return (
+    <>
+      <header>
+        <IconButton onClick={() => setNavOpen(true)} aria-label="메뉴">
+          <MenuIcon />
+        </IconButton>
+      </header>
+
+      <SwipeableDrawer
+        open={navOpen}
+        onOpen={() => setNavOpen(true)}
+        onClose={() => setNavOpen(false)}
+        anchor="left"
+      >
+        <NavList onItemClick={() => setNavOpen(false)} />
+      </SwipeableDrawer>
+
+      <main>{/* main content */}</main>
+    </>
+  );
+}
+```
+
+## Don't
+
+- Don't rely on swipe-to-open as the only access — provide a button.
+- Don't use SwipeableDrawer on desktop (mouse drag feels wrong).
+- Don't put critical actions inside without a backup access path.
+- Don't override iOS's edge swipe — let it be.
+
+## References
+
+- MUI: [`SwipeableDrawer`](../refs/mui/packages/mui-material/src/SwipeableDrawer)
+- iOS native drawer pattern; Material 3 standard drawer
+
+## Cross-reference
+
+- [`examples/component-drawer.md`](component-drawer.md) — non-swipeable variant
+- [`examples/component-sheet.md`](component-sheet.md) — bottom-sheet alternative
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md)