@design-ai/cli 4.55.0

package/examples/component-navigation-menu.md

@@ -0,0 +1,295 @@
+# `NavigationMenu` — spec
+
+> Synthesized from shadcn-ui `navigation-menu` (Radix) and patterns from MUI / Ant menu primitives. Top-of-page horizontal navigation with optional megamenu / dropdown panels. Common in marketing sites and B2B SaaS app headers.
+
+## When to use
+
+- **Marketing site top nav** with Product / Solutions / Resources mega-panels.
+- **SaaS app header** for top-level sections.
+- **Documentation site** primary nav.
+
+When NOT to use:
+- Vertical nav contexts → `Sidebar`.
+- Action menus → `DropdownMenu`.
+- Mobile-only contexts → `MobileNavigation` (separate component).
+
+## Anatomy
+
+```
+[Logo]   Product ▾   Solutions ▾   Pricing   Docs   [Sign in]
+              ↓
+              ┌────────────────────────────────────┐
+              │ Product overview          [→]      │
+              │ A platform for...                  │
+              │                                    │
+              │ Components       Themes            │
+              │ Templates        Pricing           │
+              │                                    │
+              │ Featured: New design tokens       │
+              └────────────────────────────────────┘
+                  (mega-menu panel, hover/click triggered)
+```
+
+## API
+
+```tsx
+<NavigationMenu>
+  <NavigationMenu.List>
+    <NavigationMenu.Item>
+      <NavigationMenu.Trigger>Product</NavigationMenu.Trigger>
+      <NavigationMenu.Content>
+        <ul className="grid gap-2 p-4 md:w-[500px] grid-cols-2">
+          <li>
+            <NavigationMenu.Link href="/components">
+              <h3>Components</h3>
+              <p>Pre-built primitives.</p>
+            </NavigationMenu.Link>
+          </li>
+          <li>
+            <NavigationMenu.Link href="/themes">
+              <h3>Themes</h3>
+              <p>Beautiful color palettes.</p>
+            </NavigationMenu.Link>
+          </li>
+        </ul>
+      </NavigationMenu.Content>
+    </NavigationMenu.Item>
+
+    <NavigationMenu.Item>
+      <NavigationMenu.Link href="/pricing">Pricing</NavigationMenu.Link>
+    </NavigationMenu.Item>
+
+    <NavigationMenu.Item>
+      <NavigationMenu.Link href="/docs">Docs</NavigationMenu.Link>
+    </NavigationMenu.Item>
+  </NavigationMenu.List>
+
+  <NavigationMenu.Indicator /> {/* Animated underline */}
+  <NavigationMenu.Viewport /> {/* Container for active panel */}
+</NavigationMenu>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `NavigationMenu` | Wrapper |
+| `List` | Horizontal list of top-level items |
+| `Item` | Wrapper for a top-level entry |
+| `Trigger` | Hover/click target that opens a panel |
+| `Content` | Mega-menu panel content |
+| `Link` | A direct navigation link (no panel) |
+| `Indicator` | Animated underline / arrow pointing at active item |
+| `Viewport` | Single shared container that panels animate into |
+
+## Trigger modes
+
+### Hover (marketing default)
+
+Hover trigger → panel opens after 200ms. Mouse-leave → closes after 300ms (graceful).
+
+### Click (for product apps)
+
+Tap-or-click only. More predictable; preferred when nav has many panels.
+
+### Mobile
+
+NavigationMenu doesn't translate to mobile directly. On small screens:
+- Collapse to a hamburger menu that opens a `Sheet`.
+- Or use `MobileNavigation` (separate component).
+
+## Mega-menu layouts
+
+### List
+
+```
+┌─────────────────────────┐
+│ Item 1                  │
+│ Item 2                  │
+│ Item 3                  │
+│ ─────                   │
+│ Featured: ...           │
+└─────────────────────────┘
+```
+
+### Grid (most common)
+
+```
+┌──────────────┬──────────────┐
+│ Components   │ Themes       │
+│ Pre-built... │ Color...     │
+├──────────────┼──────────────┤
+│ Templates    │ Pricing      │
+│ Starter...   │ Plans...     │
+└──────────────┴──────────────┘
+```
+
+### Featured + grid
+
+```
+┌─────────────┬───────────────────┐
+│             │ Components        │
+│  Hero       │ Themes            │
+│  Promo      │ Templates         │
+│  + image    │ Pricing           │
+│             │                   │
+└─────────────┴───────────────────┘
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Resting | All triggers visible, no panel |
+| Trigger hover | Underline indicator slides under hovered item |
+| Panel open | Content visible below; Indicator points at active trigger |
+| Switching panels | Indicator slides; Content cross-fades |
+| Closing | Indicator hides; Content fades |
+
+## Animations
+
+```
+Indicator: 200ms slide between triggers (transform: translateX)
+Panel: 250ms cross-fade + slight slide (translateY -4px → 0)
+Reduced motion: instant
+```
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-fg-default
+--color-fg-muted              (panel description text)
+--color-bg-overlay             (panel bg)
+--color-bg-overlay-hover       (panel item hover)
+--color-brand-default          (active indicator)
+--color-border-default
+--radius-md
+--shadow-overlay
+--space-md, --space-lg
+--font-size-base
+--font-weight-medium
+--motion-medium                (panel transition)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- Wrapper: `<nav aria-label="Main">`.
+- List: `<ul role="menubar">`.
+- Item: `<li>` containing either `<NavigationMenu.Trigger>` or `<NavigationMenu.Link>`.
+- Trigger: `<button aria-haspopup="true" aria-expanded="...">`.
+- Content: `role="menu"` (or just rendered list).
+- Active page: `aria-current="page"` on the corresponding link.
+- Keyboard:
+  - Tab moves between top-level items.
+  - Enter / Space on Trigger opens panel; arrows navigate within panel.
+  - Esc closes panel.
+- For touch: hover doesn't fire; panels open on tap (close on second tap of same trigger or outside).
+
+## Mobile fallback pattern
+
+```tsx
+function ResponsiveNav() {
+  const isDesktop = useMediaQuery("(min-width: 1024px)");
+
+  if (isDesktop) {
+    return <NavigationMenu>...</NavigationMenu>;
+  }
+
+  return (
+    <Sheet>
+      <Sheet.Trigger asChild>
+        <Button variant="ghost"><MenuIcon /></Button>
+      </Sheet.Trigger>
+      <Sheet.Content side="right">
+        <MobileNavList items={navItems} />
+      </Sheet.Content>
+    </Sheet>
+  );
+}
+```
+
+## Code example (marketing site)
+
+```tsx
+function MarketingHeader() {
+  return (
+    <header className="site-header">
+      <Logo />
+
+      <NavigationMenu>
+        <NavigationMenu.List>
+          <NavigationMenu.Item>
+            <NavigationMenu.Trigger>Product</NavigationMenu.Trigger>
+            <NavigationMenu.Content>
+              <div className="mega-grid">
+                <div className="featured">
+                  <Image src="/hero.jpg" alt="" />
+                  <h3>What's new</h3>
+                  <p>v3.2 just shipped — explore the spatial design domain.</p>
+                  <a href="/changelog">See changelog →</a>
+                </div>
+                <ul className="links">
+                  <li><a href="/components">Components</a></li>
+                  <li><a href="/themes">Themes</a></li>
+                  <li><a href="/templates">Templates</a></li>
+                </ul>
+              </div>
+            </NavigationMenu.Content>
+          </NavigationMenu.Item>
+
+          <NavigationMenu.Item>
+            <NavigationMenu.Link href="/pricing">Pricing</NavigationMenu.Link>
+          </NavigationMenu.Item>
+
+          <NavigationMenu.Item>
+            <NavigationMenu.Link href="/docs">Docs</NavigationMenu.Link>
+          </NavigationMenu.Item>
+        </NavigationMenu.List>
+
+        <NavigationMenu.Indicator />
+        <NavigationMenu.Viewport />
+      </NavigationMenu>
+
+      <div className="actions">
+        <a href="/login">Sign in</a>
+        <Button asChild><a href="/signup">Sign up</a></Button>
+      </div>
+    </header>
+  );
+}
+```
+
+## Edge cases
+
+- **Single-item nav** (only one trigger): NavigationMenu is overkill. Just use a button.
+- **Trigger with active sub-route**: highlight Trigger when child route active (`aria-current="true"` if any descendant link matches current URL).
+- **Mega-panel taller than viewport**: cap height; scroll inside panel.
+- **Panel with images**: lazy-load; image-loading shouldn't block panel paint.
+- **Hover into panel from trigger**: panel must remain open during hover-traversal; use `closeDelay`.
+- **Mobile breakpoint switch mid-session**: re-render with appropriate component.
+- **RTL**: flip indicator direction + alignment.
+
+## Don't
+
+- Don't use NavigationMenu for in-app navigation when a Sidebar is more appropriate. Top nav for marketing-feel + flat sites; sidebar for app-shell.
+- Don't pack 7+ top-level items. Group via mega-menu or rethink IA.
+- Don't ship without a mobile fallback. Top nav doesn't work on phones.
+- Don't omit `aria-current` on active links.
+- Don't have hover-only triggers on touch devices.
+- Don't disable Esc to close panels.
+
+## References
+
+- shadcn-ui: [`navigation-menu`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/navigation-menu.tsx) (Radix)
+- Patterns: Stripe, Linear, Vercel marketing nav
+
+## Cross-reference
+
+- [`examples/component-sidebar.md`](component-sidebar.md) — vertical nav
+- [`examples/component-app-bar.md`](component-app-bar.md) — top app bar
+- [`examples/component-sheet.md`](component-sheet.md) — mobile fallback
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md)
+- [`knowledge/patterns/landing-hero-design.md`](../knowledge/patterns/landing-hero-design.md)

package/examples/component-notification.md

@@ -0,0 +1,166 @@
+# `Notification` — spec
+
+> Synthesized from Ant Design `Notification`. Richer card-style notification — title + description + optional actions, anchored to a screen corner. Distinct from `Toast` (smaller, action-focused), `Message` (top thin pill), and `Banner` (persistent in-page).
+
+## When to use
+
+- **System-level events** that need title + body description.
+- **Multi-action notifications** ("New message from John" with Reply / Mark read buttons).
+- **Push-notification surface** for in-app-only events.
+
+When NOT to use:
+- Brief result confirmation (use Message or Toast).
+- Critical actions blocking workflow (use Modal / AlertDialog).
+- In-page persistent strip (use Banner).
+
+## Anatomy
+
+```
+                          ┌───────────────────────────┐
+                          │ ⓘ  새 알림                  │
+                          │    @sungjin이 댓글을        │
+                          │    남겼어요.                │
+                          │                            │
+                          │    [답장] [읽음 처리] [×]   │
+                          └───────────────────────────┘
+                              ↑ top-right corner
+```
+
+## API
+
+```tsx
+import { notification } from "antd";
+
+notification.open({
+  message: "새 알림",
+  description: "@sungjin이 댓글을 남겼어요.",
+  placement: "topRight",
+  duration: 4.5,
+  btn: <Button onClick={reply}>답장</Button>,
+  onClose: handleClose,
+});
+
+notification.success({ message: "성공", description: "저장됐어요." });
+notification.error({ message: "실패", description: "저장에 실패했어요." });
+notification.info({ message: "알림", description: "..." });
+notification.warning({ message: "경고", description: "..." });
+```
+
+| Config field | Description |
+| --- | --- |
+| `message` | Title (bold) |
+| `description` | Body (multiple lines OK) |
+| `placement` | `"top" \| "topLeft" \| "topRight" \| "bottom" \| "bottomLeft" \| "bottomRight"` |
+| `duration` | Seconds; 0 = persistent until dismissed |
+| `key` | Unique key (replace existing) |
+| `btn` | Custom action button(s) |
+| `onClose` | Dismiss callback |
+| `onClick` | Click on notification (optional) |
+| `icon` | Custom icon override |
+| `closable` | Show × dismiss button |
+
+## States
+
+| Severity | Visual |
+| --- | --- |
+| `open` (neutral) | Generic info icon |
+| `success` | Green check |
+| `error` | Red X |
+| `info` | Blue info |
+| `warning` | Amber triangle |
+
+## Animation
+
+```
+Enter: slide-in from corner (250ms)
+Hold: full opacity for `duration` seconds
+Exit: fade + slide-out (200ms)
+```
+
+Reduced motion: fade only.
+
+## Stacking
+
+Multiple Notifications stack vertically in their corner. Newest on top (or bottom — configurable).
+
+Cap visible: 3-5. Beyond that, oldest collapse to "+ N more" indicator.
+
+## Tokens consumed
+
+```
+--notification-bg
+--notification-fg
+--notification-fg-muted            (description)
+--notification-success-icon
+--notification-error-icon
+--notification-warning-icon
+--notification-info-icon
+--notification-shadow
+--radius-md
+--space-md, --space-lg
+--font-size-sm                     (description)
+--font-weight-medium               (title)
+--motion-medium
+--z-notification                   (above modals OR below; pick consciously)
+```
+
+## Accessibility
+
+- `role="alert"` for time-sensitive (errors, warnings).
+- `role="status"` for non-urgent.
+- `aria-live="polite"` (status) or `assertive` (alert) — be sparing with assertive.
+- Focus management: Notification doesn't steal focus by default. For action-required: persistent + focus the first button.
+- Touch target ≥ 44pt for action buttons.
+
+## Korean conventions
+
+```
+새 메시지
+@sungjin이 메시지를 보냈어요.
+[답장] [확인]
+```
+
+- 해요체 for casual brands; 합쇼체 for formal / banking.
+- Title: 20자 이내; Body: 50자 이내.
+- For 카카오톡 / KakaoTalk-style notifications: avatar + title + preview.
+
+## Code example
+
+```tsx
+function NewMessageNotification({ message }: Props) {
+  return (
+    notification.info({
+      message: `새 메시지 — ${message.from}`,
+      description: message.preview,
+      placement: "topRight",
+      duration: 4.5,
+      icon: <Avatar src={message.fromAvatar} size="sm" />,
+      btn: (
+        <Button size="sm" onClick={() => navigate(`/messages/${message.id}`)}>
+          확인
+        </Button>
+      ),
+    })
+  );
+}
+```
+
+## Don't
+
+- Don't use Notification for fleeting confirmation. Use Message or Toast.
+- Don't show 6+ Notifications stacked. Cap visible.
+- Don't auto-show on page load — feels like spam. Triggered by user action only.
+- Don't put long body text. Description ≤ 2 lines; longer = open a Modal or page.
+- Don't omit dismiss button on persistent notifications.
+
+## References
+
+- Ant: [`Notification`](../refs/ant-design/components/notification)
+- Native browser Notification API (different — uses OS-level notifications)
+- iOS / Android notification card patterns
+
+## Cross-reference
+
+- [`examples/component-toast.md`](component-toast.md) — smaller corner variant with Undo
+- [`examples/component-message.md`](component-message.md) — top thin pill
+- [`examples/component-banner.md`](component-banner.md) — persistent in-page strip

package/examples/component-otp-countdown.md

@@ -0,0 +1,245 @@
+# `OTPCountdown` (custom — Korean SMS verification timer) — spec
+
+> Korean fintech custom component. Pairs with `InputOTP` to manage SMS code resend cooldown + expiration timer. Shipped in every Korean SMS-auth flow.
+
+## Purpose
+
+Show:
+1. **Time until code expires** (typically 3 minutes for SMS verification).
+2. **Time until resend allowed** (typically 30–60 seconds cooldown).
+3. **Resend button** when cooldown completes.
+
+Without this: users frustrate themselves by tapping "재전송" repeatedly OR don't know when they can re-request.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────┐
+│  인증번호 입력                        │
+│  ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐    │
+│  │ 1│ │ 2│ │ 3│ │ 4│ │ 5│ │ 6│    │  ← InputOTP
+│  └──┘ └──┘ └──┘ └──┘ └──┘ └──┘    │
+│                                       │
+│  남은 시간: 02:47                      │  ← code expiration
+│  [재전송하기]                          │  ← becomes active after cooldown
+│  (30초 후 재전송 가능)                  │  ← cooldown indicator (alternates with button)
+└─────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<>
+  <InputOTP length={6} value={code} onValueChange={setCode} onComplete={verify} />
+  <OTPCountdown
+    expiresAt={codeExpiresAt}             // 3 min from issue
+    cooldownSeconds={30}                   // resend cooldown
+    onResend={requestNewCode}
+    onExpired={() => setError("인증번호가 만료되었습니다.")}
+  />
+</>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `expiresAt` | `Date \| number` | — | When the code expires (Date or unix ms) |
+| `cooldownSeconds` | `number` | `30` | Seconds before resend allowed |
+| `onResend` | `() => void \| Promise<void>` | — | Trigger new code request |
+| `onExpired` | `() => void` | — | Fired when expiresAt reached |
+| `expiredMessage` | `string` | `"인증번호가 만료되었습니다"` | When code expires |
+| `disabled` | `boolean` | `false` | Disable both timer + resend |
+
+## Behavior
+
+### Expiration timer
+
+- Counts down from now to `expiresAt`.
+- Format: `mm:ss` for typical 3-min window. `0:30` when under 1 min.
+- Color shift to warning when < 30s remaining.
+- At 0: fires `onExpired`, shows expired message, disables InputOTP.
+
+### Resend cooldown
+
+- Starts at `cooldownSeconds` after component mount (or after each resend).
+- Shows "30초 후 재전송 가능" while counting down.
+- At 0: replaces with active "재전송하기" button.
+- Tapping resend: triggers `onResend`, restarts both timers (cooldown + expiration).
+
+### State machine
+
+```
+              ┌──────────┐
+              │ initial  │ ← timer starts, cooldown counts down
+              └─────┬────┘
+                    │ cooldown reaches 0
+                    ▼
+              ┌──────────────┐
+              │ resend ready │ ← button visible + active
+              └─────┬────────┘
+                    │ user taps resend
+                    ▼
+              ┌──────────┐
+              │ resending│ ← spinner; new request to server
+              └─────┬────┘
+                    │ server returns new code expiry
+                    ▼  (loop back to initial with new timers)
+
+OR (independent):
+                    │ expiresAt reached
+                    ▼
+              ┌──────────┐
+              │ expired  │ ← onExpired fires; ui shows message
+              └──────────┘
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Initial — counting down | "남은 시간 02:47" + cooldown indicator |
+| Cooldown done | "재전송하기" button active |
+| Expiration warning (<30s) | Timer text in `--color-warning` |
+| Expired | "인증번호가 만료되었습니다" + reload button |
+| Resending | Button shows spinner; cooldown restarts after success |
+| Disabled | All elements muted |
+
+## Tokens consumed
+
+```
+--color-text-primary       (timer)
+--color-text-secondary      (cooldown indicator)
+--color-warning             (timer warning <30s)
+--color-error               (expired)
+--color-primary-default     (active resend button)
+--color-text-tertiary       (disabled cooldown)
+--space-sm, --space-md
+--font-feature-amount: 'tnum'   (digits align)
+--font-size-sm, --font-size-base
+--motion-fast
+```
+
+## Tabular numerals (critical)
+
+Timer "02:47" → "02:46" → "02:45" must not visually shift width. Use `font-feature-settings: 'tnum'` so digits are equal-width.
+
+## Korean copy
+
+| State | Copy |
+| --- | --- |
+| Time remaining | "남은 시간 mm:ss" or "유효시간 mm:ss" |
+| Cooldown | "N초 후 재전송 가능" |
+| Resend ready | "재전송하기" |
+| Resending | "재전송 중..." |
+| Expired | "인증번호가 만료되었습니다. 다시 발급받아 주세요." |
+| Re-issue button | "인증번호 재발급" |
+
+## Accessibility
+
+- Timer in `<span aria-live="off">` — don't announce every second (chatter).
+- Update `aria-label` at milestones: "1분 남음", "30초 남음", "만료됨".
+- Resend button: standard a11y, `aria-disabled` when in cooldown.
+- Screen reader on expiration: announce once via `role="alert"`.
+
+## Implementation hints
+
+```tsx
+function OTPCountdown({ expiresAt, cooldownSeconds, onResend, ... }: Props) {
+  const [now, setNow] = useState(Date.now());
+  const [cooldownEnd, setCooldownEnd] = useState(Date.now() + cooldownSeconds * 1000);
+  const [resending, setResending] = useState(false);
+
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), 500);  // 500ms is enough; UI shows seconds
+    return () => clearInterval(id);
+  }, []);
+
+  const expiresMs = Math.max(0, expiresAt - now);
+  const cooldownMs = Math.max(0, cooldownEnd - now);
+
+  // ... render based on state
+}
+```
+
+For server clock skew: pair `expiresAt` from server with a periodic time-sync. For 3-min SMS windows, ±5 seconds skew is tolerable.
+
+## Code example
+
+```tsx
+function VerifyPhoneScreen({ phone }: Props) {
+  const [code, setCode] = useState("");
+  const [codeIssue, setCodeIssue] = useState({
+    expiresAt: Date.now() + 3 * 60 * 1000,
+    issuedAt: Date.now(),
+  });
+  const [error, setError] = useState<string>();
+
+  const handleResend = async () => {
+    const result = await api.resendCode({ phone });
+    setCodeIssue({
+      expiresAt: result.expiresAt,
+      issuedAt: Date.now(),
+    });
+    setCode("");  // clear input
+  };
+
+  const handleVerify = async (otpCode: string) => {
+    try {
+      await api.verifyCode({ phone, code: otpCode });
+      navigate("/success");
+    } catch (err) {
+      setError(err.message);
+      setCode("");
+    }
+  };
+
+  return (
+    <Page>
+      <Heading>인증번호 입력</Heading>
+      <p>{phone}로 보낸 6자리 인증번호를 입력해 주세요.</p>
+
+      <InputOTP
+        length={6}
+        value={code}
+        onValueChange={setCode}
+        onComplete={handleVerify}
+        autoFocus
+        errorText={error}
+      />
+
+      <OTPCountdown
+        expiresAt={codeIssue.expiresAt}
+        cooldownSeconds={30}
+        onResend={handleResend}
+        onExpired={() => setError("인증번호가 만료되었습니다. 재발급 받아주세요.")}
+      />
+    </Page>
+  );
+}
+```
+
+## Edge cases
+
+- **User backgrounds the app, returns minutes later**: timer continues based on real time (not React Time). On return: re-render with current diff.
+- **Server-issued expiry slightly off from client clock**: tolerate ±5s.
+- **Multiple rapid resends**: rate-limit via cooldown. If user spams tap: button stays cooldown.
+- **Page navigation away + back**: timer state should persist (URL search params or shared store) — otherwise re-issuing on every nav is annoying.
+- **Slow network on resend**: button stays in "재전송 중..." state until response. Don't allow second tap.
+
+## Don't
+
+- Don't restart the expiration timer on resend without re-issuing a new code from server.
+- Don't omit cooldown — users will spam-resend, server-side rate-limit will kick in confusingly.
+- Don't update timer every 100ms (60Hz updates are wasteful for a 1-second display).
+- Don't expire silently — user must know.
+- Don't allow more than 3-5 resends per session (typical Korean carrier limit).
+
+## References
+
+No upstream component matches exactly. This is a Korean-market-specific composition over `InputOTP` + countdown logic.
+
+## Cross-reference
+
+- [`examples/component-input-otp.md`](component-input-otp.md) — pairs with this
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — Korean phone-auth conventions
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — broader 본인인증
+- [`examples/component-pass-auth.md`](component-pass-auth.md) — full PASS / 본인인증 wrapper