@design-ai/cli 4.55.0

package/examples/component-payment-receipt.md

@@ -0,0 +1,277 @@
+# `PaymentReceipt` (custom — Korean fintech) — spec
+
+> Custom component pattern. Korean payment apps render post-purchase receipts in a distinctive layout — dotted divider lines, structured price breakdown, KakaoPay-style summary card.
+
+## Purpose
+
+Displays a payment confirmation receipt: items, subtotal, discounts, fees, total, payment method, timestamp. Used after checkout, in transaction detail screens, in 1:1 inquiries.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│      ✓                                  │
+│   결제가 완료되었습니다                    │  ← header
+│   2026.05.07 14:30:25                    │
+│                                          │
+│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│  ← dotted divider (Korean receipt convention)
+│                                          │
+│  주문번호  ORD-2026-001234                │
+│  상점     스타벅스 강남점                   │
+│  결제수단  KakaoPay                       │
+│                                          │
+│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│
+│                                          │
+│  아메리카노 (Tall)         ₩4,500         │  ← items
+│  카페라떼 (Grande)         ₩5,500         │
+│                                          │
+│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│
+│                                          │
+│  상품 합계                ₩10,000          │  ← breakdown
+│  할인                     -₩1,000          │
+│  ─────────────                          │
+│  총 결제 금액              ₩9,000          │  ← total (bold, larger)
+│                                          │
+│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│
+│                                          │
+│  [영수증 공유]   [재구매]                  │  ← actions
+└─────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Header | yes | Status icon + "결제 완료" + timestamp |
+| Order metadata | yes | 주문번호, 상점, 결제수단 |
+| Items | usually | Each item with name + price |
+| Subtotal breakdown | yes | 상품 합계, 할인, 배송, 부가세 |
+| Total | yes | Bold, larger |
+| Actions | optional | 영수증 공유 / 재구매 / 취소 |
+| Dotted dividers | yes | Korean receipt convention |
+
+## API
+
+```tsx
+<PaymentReceipt
+  status="completed"
+  timestamp={order.completedAt}
+  orderId={order.id}
+  merchant={order.merchant}
+  paymentMethod="KakaoPay"
+  items={order.items}
+  subtotal={order.subtotal}
+  discount={order.discount}
+  shipping={order.shipping}
+  tax={order.tax}
+  total={order.total}
+  actions={[
+    { label: "영수증 공유", onClick: shareReceipt },
+    { label: "재구매", onClick: reorder },
+  ]}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `status` | `"completed" \| "pending" \| "cancelled" \| "refunded"` | — | Drives header icon + color |
+| `timestamp` | `Date \| string` | — | When |
+| `orderId` | `string` | — | |
+| `merchant` | `string` | — | Store / business name |
+| `paymentMethod` | `string` | — | "KakaoPay", "신한카드 ****-1234", etc. |
+| `items` | `Item[]` | — | Line items |
+| `subtotal` | `number` | — | Sum of items |
+| `discount` | `number` | — | Negative number |
+| `shipping` | `number` | — | |
+| `tax` | `number` | — | |
+| `total` | `number` | — | Final amount paid |
+| `actions` | `Action[]` | — | Buttons at bottom |
+| `cancellable` | `boolean` | `false` | Show cancel option |
+| `refundable` | `boolean` | `false` | Show refund request option |
+
+```ts
+type Item = {
+  name: string;
+  description?: string;
+  quantity?: number;
+  unitPrice?: number;
+  totalPrice: number;
+};
+```
+
+## Status → header
+
+| Status | Icon | Color | Title |
+| --- | --- | --- | --- |
+| `completed` | ✓ | success | "결제가 완료되었습니다" |
+| `pending` | ⏳ | warning | "결제 처리 중입니다" |
+| `cancelled` | ✕ | error | "결제가 취소되었습니다" |
+| `refunded` | ↶ | neutral | "환불 완료" |
+
+## Sizes / variants
+
+| Variant | Use |
+| --- | --- |
+| `default` | Order detail screen / receipt detail |
+| `compact` | List-row preview |
+| `print` | Print-optimized (no actions, plain colors) |
+
+## Dotted divider
+
+The `─ ─ ─` dotted divider is a strong Korean receipt convention (mimicking thermal-printed paper receipts):
+
+```css
+.receipt-divider {
+  border-top: 1px dashed var(--color-border-default);
+  margin: 16px 0;
+}
+```
+
+Optional: render as inline SVG for a more receipt-paper feel.
+
+## Item row alignment
+
+Item names left-aligned, prices right-aligned, tabular numerals. Quantity often shown as multiplier:
+
+```
+아메리카노 (Tall) × 2          ₩9,000
+   ₩4,500 / 개                          ← optional unit price line
+카페라떼                       ₩5,500
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Completed | Success icon, full receipt visible |
+| Pending | Warning icon, "처리 중" badge |
+| Cancelled | Strikethrough on all amounts; cancellation reason |
+| Refunded | "환불 처리됨" badge, refund timestamp |
+| Loading | Skeleton matching receipt shape |
+| Error | "영수증을 불러올 수 없어요" + retry |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated
+--color-text-primary
+--color-text-secondary
+--color-text-tertiary
+--color-success            (completed)
+--color-warning            (pending)
+--color-error              (cancelled)
+--color-money-negative      (discount)
+--color-border-default      (divider)
+--space-md, --space-base, --space-lg
+--radius-md
+--font-mono                 (order ID — alphanumeric clarity)
+--font-feature-amount: 'tnum' 1
+```
+
+## Accessibility
+
+- Receipt as `<article>` with `aria-label="결제 영수증"`.
+- Status icon: `aria-hidden="true"` (header text carries meaning).
+- Total amount: `aria-label="총 결제 금액 9,000원"`.
+- Items list: `<dl>` for name → price pairs, OR `<table>` if quantities + unit prices.
+- Actions: standard buttons.
+
+## Print
+
+Receipts are commonly printed:
+
+```css
+@media print {
+  .receipt {
+    background: white;
+    color: black;
+  }
+  .receipt-actions {
+    display: none;
+  }
+  /* Use solid black for divider — dashed renders inconsistently */
+  .receipt-divider {
+    border-top-style: solid;
+  }
+}
+```
+
+For Korean app store policy compliance: receipts must be printable / saveable as PDF.
+
+## Korean conventions
+
+- "결제가 완료되었습니다" — standard completion language.
+- "총 결제 금액" — final total label.
+- "주문번호" — order ID label.
+- "상점" / "가맹점" — merchant.
+- 영수증 공유: KakaoTalk share is the most common; SMS as backup.
+- For 사업자 영수증 (business receipts): include 사업자등록번호 if applicable.
+- Tax (부가세) shown as separate line if applicable. For most e-commerce, tax is included in price (VAT-included).
+
+## Code example
+
+```tsx
+function OrderConfirmationScreen({ orderId }: Props) {
+  const order = useOrder(orderId);
+
+  return (
+    <Page>
+      <PaymentReceipt
+        status={order.status}
+        timestamp={order.completedAt}
+        orderId={order.displayId}
+        merchant={order.merchant}
+        paymentMethod={order.paymentMethodLabel}
+        items={order.items}
+        subtotal={order.subtotal}
+        discount={order.discountTotal}
+        shipping={order.shippingFee}
+        total={order.total}
+        actions={[
+          {
+            label: "영수증 공유",
+            onClick: () => share({ url: `/orders/${orderId}/receipt` }),
+          },
+          {
+            label: "재구매",
+            onClick: () => reorder(orderId),
+          },
+        ]}
+        refundable={order.canRefund}
+      />
+    </Page>
+  );
+}
+```
+
+## Edge cases
+
+- **Refunded items in a partially-fulfilled order**: show refund status per item with strikethrough.
+- **Subscription receipts**: include "다음 결제일: 2026.06.07" in the metadata.
+- **No items** (e.g., service charge, donation): hide items section, just show breakdown.
+- **Discount > subtotal** (rare): show negative total OR cap at 0; handle case-by-case.
+- **Tax-included vs tax-excluded**: clearly label. Korean apps default to tax-included; B2B may show separately.
+
+## Don't
+
+- Don't use heavy borders / boxes inside the receipt — keep it paper-like.
+- Don't omit the timestamp.
+- Don't show actions in print mode.
+- Don't break dividers across pages on print.
+- Don't shorten the order ID — full ID needed for support.
+- Don't auto-redirect from the receipt screen — let user read.
+
+## References
+
+No upstream component is exactly this. The receipt pattern is universal but **Korean visual conventions** (dotted dividers, breakdown structure, share-receipt language) are domain-specific.
+
+Closest analogs:
+- Stripe Dashboard receipts (Western convention)
+- KakaoBank / Toss receipt screens (Korean convention)
+
+## Cross-reference
+
+- [`examples/component-krw-amount.md`](component-krw-amount.md) — used internally for amounts
+- [`examples/component-payment-method-selector.md`](component-payment-method-selector.md) — pre-checkout
+- [`examples/component-result.md`](component-result.md) — result page (PaymentReceipt is its richer cousin)
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — Korean payment conventions
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — money display

package/examples/component-popconfirm.md

@@ -0,0 +1,144 @@
+# `Popconfirm` — spec
+
+> Synthesized from Ant Design `Popconfirm`. An inline confirmation popover triggered by a button — lightweight alternative to `AlertDialog` for in-place destructive actions.
+
+## Popconfirm vs AlertDialog
+
+| | Popconfirm | AlertDialog |
+| --- | --- | --- |
+| Surface | Popover anchored to trigger | Centered modal |
+| Use | Quick confirm of inline action | Full-stop destructive action |
+| Visual weight | Light | Heavy |
+| Backdrop | None | Yes |
+| Focus trap | No | Yes |
+
+For "are you sure?" on a small inline button: Popconfirm.
+For account deletion / unrecoverable destructive: AlertDialog.
+
+## Anatomy
+
+```
+[Delete]
+   ↓ click
+   ┌─────────────────────┐
+   │ ⚠  정말 삭제할까요? │
+   │ [취소] [삭제]        │
+   └─────────────────────┘
+```
+
+## API
+
+```tsx
+<Popconfirm
+  title="이 항목을 삭제할까요?"
+  description="삭제한 항목은 복구할 수 없어요."
+  onConfirm={handleDelete}
+  okText="삭제"
+  cancelText="취소"
+  okButtonProps={{ variant: "destructive" }}
+>
+  <Button>삭제</Button>
+</Popconfirm>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | required | Confirmation question |
+| `description` | `string` | — | Optional consequence detail |
+| `onConfirm` | `() => void \| Promise<void>` | — | Confirm callback |
+| `onCancel` | `() => void` | — | Cancel callback |
+| `okText` | `string` | "OK" / "확인" | Confirm button label |
+| `cancelText` | `string` | "Cancel" / "취소" | Cancel button label |
+| `okButtonProps` | Button props | — | Style confirm button (e.g., variant="destructive") |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` (with -start / -end) | `"top"` | Popover position |
+| `icon` | `ReactNode` | warning icon | Custom icon |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Trigger button only |
+| Open | Popover with title + description + buttons |
+| Loading (async confirm) | OK button shows spinner; both disabled |
+| Closing | Fade-out 150ms |
+
+## Async confirm
+
+```tsx
+<Popconfirm
+  title="삭제할까요?"
+  onConfirm={async () => {
+    await api.delete(id);  // popconfirm shows loading on OK button
+    toast.success("삭제됐어요");
+  }}
+>
+  <Button>삭제</Button>
+</Popconfirm>
+```
+
+## Tokens consumed
+
+Inherits from Popover:
+```
+--popover-bg
+--popover-fg
+--popover-border
+--popover-shadow
+--popover-icon-warning
+--radius-md
+--space-sm, --space-md
+--motion-fast
+--z-overlay
+```
+
+## Accessibility
+
+- `role="dialog"` (or `alertdialog`) on the Popover content.
+- `aria-labelledby` references title; `aria-describedby` references description.
+- Focus moves to OK button on open.
+- Esc closes (cancels).
+- Click outside cancels.
+- For destructive actions: prefer `AlertDialog` — focus trap + backdrop give the user a more deliberate moment.
+
+## Code example — list item delete with Popconfirm
+
+```tsx
+function ItemRow({ item }: Props) {
+  return (
+    <Item>
+      <ItemContent>{item.name}</ItemContent>
+      <ItemActions>
+        <Popconfirm
+          title="삭제할까요?"
+          description={`"${item.name}"을(를) 영구적으로 삭제해요.`}
+          onConfirm={() => api.delete(item.id)}
+          okText="삭제"
+          cancelText="취소"
+          okButtonProps={{ variant: "destructive" }}
+        >
+          <IconButton aria-label="삭제">
+            <TrashIcon />
+          </IconButton>
+        </Popconfirm>
+      </ItemActions>
+    </Item>
+  );
+}
+```
+
+## Don't
+
+- Don't use Popconfirm for high-stakes destructive (account deletion). Use AlertDialog.
+- Don't omit description for non-obvious consequences.
+- Don't auto-confirm without explicit click. Popconfirm IS the confirmation.
+- Don't pile up confirmations (one Popconfirm at a time per surface).
+
+## References
+
+- Ant: [`Popconfirm`](../refs/ant-design/components/popconfirm)
+
+## Cross-reference
+
+- [`examples/component-alert-dialog.md`](component-alert-dialog.md) — heavier modal alternative
+- [`examples/component-popover.md`](component-popover.md) — base primitive
+- [`examples/component-toast.md`](component-toast.md) — for "deleted, with Undo" pattern (alternative)

package/examples/component-popover.md

@@ -0,0 +1,239 @@
+# `Popover` — spec
+
+> Citing Ant Design `Popover`, MUI `Popper`/`Popover`, shadcn-ui `popover`
+
+## Purpose
+
+A non-modal overlay anchored to a trigger element. Used for: filter detail, contextual settings, "more info" content, color picker, quick actions menu.
+
+Different from related primitives:
+
+| Primitive | Use |
+| --- | --- |
+| **Tooltip** | Short hover hint. No interaction. |
+| **Popover** | Interactive content anchored to a trigger. Close on outside click. |
+| **Modal/Dialog** | Centered, blocks page interaction. |
+| **Dropdown menu** | List of actions (`Cmd+click`-style). Use Popover with menu styling. |
+
+## Anatomy
+
+```
+[trigger button]
+       │
+       ▼ (click)
+┌──────────────────────┐
+│ ▶ Popover header     │
+│ ─────────────────    │
+│   Body content       │
+│   Form / list / etc  │
+│                      │
+│   [action]   [close] │
+└──────────────────────┘
+       ▲ (arrow optional)
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Trigger | yes | The element popover anchors to |
+| Body | yes | Interactive content |
+| Arrow | optional | Pointer at trigger; usually small triangle |
+| Close button | optional | Explicit close affordance |
+
+## API
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button>Filter</Button>
+  </Popover.Trigger>
+  <Popover.Content side="bottom" align="start">
+    <FilterForm />
+  </Popover.Content>
+</Popover>
+```
+
+| Prop (root) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` / `defaultOpen` | `boolean` | — | Controlled/uncontrolled |
+| `onOpenChange` | `(open: boolean) => void` | — | |
+| `modal` | `boolean` | `false` | If true, also traps focus + scroll lock (rare for popover) |
+
+| Prop (Content) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred position |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the side |
+| `sideOffset` | `number` | `4` | Gap between trigger and popover |
+| `collisionPadding` | `number` | `8` | Distance from viewport edge before flipping |
+| `arrow` | `boolean` | `false` | Show arrow pointing at trigger |
+
+## Behavior
+
+| Trigger | Action |
+| --- | --- |
+| Click trigger | Open |
+| Click trigger (when open) | Close |
+| Click outside content | Close |
+| Press Escape | Close |
+| Tab away (focus leaves) | Close (if `modal={false}`) |
+| Window resize | Reposition |
+| Scroll | Reposition (or close if dramatic) |
+
+For `modal={true}`: closes only via Escape or explicit close button. Use rarely — popover that needs modal behavior is usually a Dialog.
+
+## Positioning
+
+The popover positions relative to the trigger with collision detection:
+
+```
+Preferred: side="bottom" align="start"
+
+Trigger:    [...]
+            ▼
+            ┌──────────┐
+            │ content  │
+            └──────────┘
+```
+
+If the popover would overflow the viewport, it auto-flips to the opposite side. Use Floating UI or Radix's collision detection — don't reinvent.
+
+## Sizes
+
+Popover doesn't have fixed sizes — content determines size. Set min-width based on the trigger's width, or use `width="trigger"` to match exactly.
+
+| Width strategy | Use |
+| --- | --- |
+| Auto (content-driven) | Default |
+| Match trigger width | Date picker, select-like popovers |
+| Fixed (e.g., 320px) | Filter panels, detail cards |
+| Max-content | Tooltips with rich content |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | not in DOM (or `display: none`) |
+| Opening | 100ms fade + slight scale 0.95 → 1 + slide |
+| Open | settled, content visible |
+| Closing | 75ms fade |
+
+## Tokens consumed
+
+```
+--color-bg-elevated         (popover surface)
+--color-border-default
+--color-text-primary
+--space-md, --space-sm
+--radius-md
+--shadow-popover
+--motion-fast, --easing-out
+--z-popover                 (above page content, below modal)
+```
+
+## Accessibility
+
+- Trigger: `aria-haspopup="true"`, `aria-expanded={open}`, `aria-controls={contentId}`.
+- Content: `role="dialog"` if interactive, OR plain region if just informational.
+- For menu-flavored popovers (list of actions): use [`<DropdownMenu>`] instead of Popover — it's a different ARIA pattern.
+
+### Focus
+
+When popover opens via click:
+- **Modal popover** (`modal={true}`): trap focus inside, return focus to trigger on close.
+- **Non-modal popover** (default): focus moves into popover automatically (first focusable element). Tab cycles within and **eventually exits**, closing the popover when focus leaves.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` (on trigger) | Reaches trigger |
+| `Enter` / `Space` | Open popover |
+| `Tab` (inside) | Cycle through interactive content |
+| `Esc` | Close, return focus to trigger |
+| Click outside | Close (no focus transfer) |
+
+## Tooltip vs Popover
+
+A common confusion. Use Tooltip for:
+- Short hint, hover-triggered
+- No interactive content
+- No persistent need to interact
+
+Use Popover for:
+- Click-triggered (or focus-triggered for keyboard)
+- Has buttons, inputs, links inside
+- User needs time to read or interact
+
+Don't put interactive content in a tooltip. Tooltips disappear on mouse-out.
+
+## Code example
+
+```tsx
+// Filter popover
+<Popover>
+  <Popover.Trigger asChild>
+    <Button variant="outline" iconStart={<FilterIcon />}>
+      필터 {activeCount > 0 && `(${activeCount})`}
+    </Button>
+  </Popover.Trigger>
+  <Popover.Content side="bottom" align="end" style={{ width: 320 }}>
+    <FilterForm />
+    <div className="flex justify-between p-3 border-t">
+      <Button variant="ghost" onClick={resetFilters}>초기화</Button>
+      <Button onClick={applyFilters}>적용</Button>
+    </div>
+  </Popover.Content>
+</Popover>
+
+// User menu popover
+<Popover>
+  <Popover.Trigger asChild>
+    <Avatar src={user.photoUrl} alt={user.name} />
+  </Popover.Trigger>
+  <Popover.Content side="bottom" align="end">
+    <div className="p-3 border-b">
+      <p className="font-medium">{user.name}</p>
+      <p className="text-sm text-text-secondary">{user.email}</p>
+    </div>
+    <ul role="menu">
+      <li><a href="/profile">프로필</a></li>
+      <li><a href="/settings">설정</a></li>
+      <li><button onClick={signOut}>로그아웃</button></li>
+    </ul>
+  </Popover.Content>
+</Popover>
+```
+
+(Note: a list of actions like the user menu is more strictly a `DropdownMenu` — use that primitive for proper menu a11y. Popover here is illustrative.)
+
+## Edge cases
+
+- **Popover near viewport edge**: auto-flip handled by Floating UI / Radix.
+- **Popover wider than viewport**: not allowed — cap at `100vw - 16px`.
+- **Trigger inside a scrollable container**: popover repositions on scroll.
+- **Multiple popovers stacked**: avoid. Refactor — usually means navigation should change.
+- **Popover with form inside**: typing must not close popover. Make sure outside-click handler ignores trigger and content.
+- **iOS Safari**: virtual keyboard pushes content; popover may need to reposition.
+- **Click on trigger that's inside another clickable** (e.g., card with popover button): event must `stopPropagation` so card doesn't also fire.
+
+## Don't
+
+- Don't use Popover when a Tooltip suffices (no interaction needed).
+- Don't use Popover when a Modal/Dialog suffices (decision/blocking interaction).
+- Don't put critical CTAs inside a popover that's not also reachable elsewhere.
+- Don't ship a popover without `aria-expanded` on the trigger — keyboard users need to know state.
+- Don't make the popover "sticky" — it should close on outside click. (Exception: `modal={true}` for special cases.)
+- Don't open popovers on hover unless they truly contain a tooltip (then use Tooltip).
+
+## References
+
+- Ant Design: [`refs/ant-design/components/popover/`](../refs/ant-design/components/popover/) — `Popover` with rich placement, `trigger="hover" | "click" | "focus"`. Hover trigger is generally avoided in modern UIs.
+- MUI: [`refs/mui/packages/mui-material/src/Popper/`](../refs/mui/packages/mui-material/src/Popper/) — low-level positioning primitive. `Popover` adds backdrop + focus management.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/popover.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/popover.tsx) — Radix Popover primitive. **Default for new projects.**
+
+## Cross-reference
+
+- [`examples/component-tooltip.md`](component-tooltip.md) — for hover-only hints
+- [`examples/component-modal.md`](component-modal.md) — for blocking/decision interactions
+- [`examples/component-select.md`](component-select.md) — uses popover-pattern for combobox
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)
+- [WAI-ARIA Dialog Pattern (modal popover)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)