@design-ai/cli 4.55.0

package/examples/component-payment-brand-button.md

@@ -0,0 +1,253 @@
+# `PaymentBrandButton` (custom — Korean) — spec
+
+> Custom component for KakaoPay / NaverPay / Toss / Apple Pay / Samsung Pay branded buttons.
+>
+> Vendors require their official asset use. Don't restyle. This component encapsulates correct rendering + interaction.
+
+## Purpose
+
+Renders a vendor-branded one-tap payment button. Used in:
+- Checkout shortcut: "Pay with KakaoPay"
+- Buy-now flows (Toss merchant button)
+- Login shortcuts (KakaoPay / Toss are also identity providers)
+- Standalone CTAs (Buy with NaverPay)
+
+The selector ([`component-payment-method-selector.md`](component-payment-method-selector.md)) lists multiple methods; this component renders one method as a brand-styled CTA.
+
+## Anatomy
+
+```
+KakaoPay (yellow):              NaverPay (green):
+┌────────────────────────┐      ┌────────────────────────┐
+│ [💛]  Pay with KakaoPay│      │ [N]  Pay with NaverPay │
+└────────────────────────┘      └────────────────────────┘
+
+Toss (blue):                    Apple Pay (black):
+┌────────────────────────┐      ┌────────────────────────┐
+│ [t.] Toss로 결제        │      │   [logo] Apple Pay     │
+└────────────────────────┘      └────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Brand logo | yes | Official asset, fixed aspect ratio |
+| Label | yes (most brands) | "Pay with [Brand]" or KR equivalent |
+| Loading spinner | when authenticating | Replaces label, brand color background |
+
+## API
+
+```tsx
+<PaymentBrandButton
+  brand="kakaopay"
+  amount={45000}
+  onClick={initiateKakaoPay}
+  loading={isInitiating}
+  size="lg"
+  fullWidth
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `brand` | `"kakaopay" \| "naverpay" \| "toss" \| "applepay" \| "samsungpay" \| "tosspayments"` | — | Required |
+| `onClick` | `() => void` | — | Required. Triggers the brand SDK. |
+| `amount` | `number` | — | Optional. Some brands display amount in button (e.g., "Pay ₩45,000 with KakaoPay") |
+| `label` | `string` | derived from brand + locale | Override default label |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `fullWidth` | `boolean` | `false` | |
+| `loading` | `boolean` | `false` | Spinner replaces label |
+| `disabled` | `boolean` | `false` | |
+
+## Brand assets — official requirements
+
+**Critical**: each vendor publishes brand guidelines. Following them is **required** by their merchant agreements.
+
+| Brand | Background | Logo | Text color | Min height | Notes |
+| --- | --- | --- | --- | --- | --- |
+| **KakaoPay** | `#FFCD00` (yellow) | Speech-bubble icon + "kakao pay" wordmark | `#000000` (black) | 44px | Official assets at [pay.kakao.com](https://developers.kakaopay.com/) |
+| **NaverPay** | `#00C73C` (green) | "N" + "Pay" wordmark | `#FFFFFF` (white) | 44px | Naver brand kit |
+| **Toss** | `#3182F6` (blue) | "toss" lowercase wordmark | `#FFFFFF` (white) | 44px | Toss merchant guidelines |
+| **Apple Pay** | `#000000` (black) | Apple Pay logo | `#FFFFFF` (white) | 44px | Strict — see Apple PassKit guidelines. Available only on iOS / Safari. |
+| **Samsung Pay** | `#000000` (black) | Samsung Pay logo | `#FFFFFF` (white) | 44px | Samsung Pay developer guidelines |
+
+**Don't**:
+- Don't change the background color.
+- Don't replace the logo with your own.
+- Don't add additional brand colors (no 2-color KakaoPay).
+- Don't add custom text styling that conflicts with the wordmark.
+- Don't use the brand name without the logo.
+
+## Korean localized labels
+
+| Brand | Korean label |
+| --- | --- |
+| KakaoPay | "카카오페이 결제" or "카카오페이로 결제" |
+| NaverPay | "네이버페이 결제" |
+| Toss | "토스로 결제" |
+| Apple Pay | "Apple Pay" (don't translate) |
+| Samsung Pay | "Samsung Pay" (don't translate) |
+
+If `amount` is provided:
+- "카카오페이로 ₩45,000 결제"
+
+## Sizes
+
+Per brand guidelines, minimum height is **44px** (mobile touch target). Recommended:
+
+| Size | Height | Min width | Use |
+| --- | --- | --- | --- |
+| `sm` | 36px | 120px | Inline with other content (rare) |
+| `md` (default) | 44px | 160px | Standard CTA |
+| `lg` | 56px | 240px | Hero / primary checkout |
+
+For mobile primary checkout: `lg` + `fullWidth: true`.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Brand color bg, logo + label |
+| Hover | Subtle darken / opacity 0.92 |
+| Active (press) | Slight darken / scale 0.98 |
+| Focus-visible | 2px ring (use `--color-focus-ring`, ensure 3:1 against brand bg) |
+| Loading | Logo + spinner replaces label; bg remains brand color |
+| Disabled | Opacity 0.5, no events |
+
+## Tokens consumed
+
+In addition to the brand-specific tokens (above), inherits:
+
+```
+--color-focus-ring
+--color-on-brand-yellow      (computed: #000 for KakaoPay, etc.)
+--space-sm, --space-md
+--radius-md
+--font-size-base, --font-size-lg
+--font-weight-semibold
+--motion-fast, --easing-out
+```
+
+## Accessibility
+
+- Render as `<button>`. Never `<div onClick>`.
+- `aria-label` includes brand + action ("Pay 45,000 won with KakaoPay") if the visible text is just "KakaoPay 결제".
+- Logo: `aria-hidden="true"` (the label carries meaning).
+- Loading state: `aria-busy="true"`.
+- Disabled state: `aria-disabled="true"` + native `disabled`.
+- Focus indicator: brand-color buttons need a custom focus ring that clears 3:1 against the brand background. Often a 2px ring offset 2px in `--color-bg-default` works (page background visible behind ring).
+
+## Behavior
+
+### Click flow
+
+1. User taps button.
+2. Button enters loading state.
+3. Brand SDK opens (popup, redirect, or wallet app handoff).
+4. User authenticates / approves in the brand UX.
+5. SDK callback returns success or failure.
+6. Button exits loading; parent flow handles outcome.
+
+### SDK initialization
+
+This component wraps `onClick`. The `onClick` is responsible for calling the brand SDK:
+
+```ts
+const initiateKakaoPay = async () => {
+  setLoading(true);
+  try {
+    const result = await window.Kakao.Pay.requestPayment({
+      cid: "TC0ONETIME",
+      partner_order_id: orderId,
+      partner_user_id: userId,
+      item_name: orderName,
+      total_amount: amount,
+      // ...
+    });
+    onSuccess(result);
+  } catch (err) {
+    onError(err);
+  } finally {
+    setLoading(false);
+  }
+};
+```
+
+The SDK setup (script load, init) happens at app bootstrap; the button just triggers.
+
+## Code example
+
+```tsx
+function CheckoutFooter({ amount, orderId }: Props) {
+  const [loading, setLoading] = useState<Brand | null>(null);
+
+  const handlePay = async (brand: Brand) => {
+    setLoading(brand);
+    try {
+      const result = await initiatePayment(brand, { amount, orderId });
+      navigate(`/orders/${result.orderId}/success`);
+    } catch (err) {
+      toast.error("결제에 실패했습니다", { description: err.message });
+    } finally {
+      setLoading(null);
+    }
+  };
+
+  return (
+    <FixedFooter className="space-y-2">
+      <PaymentBrandButton
+        brand="kakaopay"
+        amount={amount}
+        size="lg"
+        fullWidth
+        loading={loading === "kakaopay"}
+        disabled={loading !== null}
+        onClick={() => handlePay("kakaopay")}
+      />
+      <PaymentBrandButton
+        brand="naverpay"
+        size="lg"
+        fullWidth
+        loading={loading === "naverpay"}
+        disabled={loading !== null}
+        onClick={() => handlePay("naverpay")}
+      />
+      <Button variant="outline" size="lg" fullWidth onClick={() => navigate("/checkout/card")}>
+        다른 결제 수단
+      </Button>
+    </FixedFooter>
+  );
+}
+```
+
+## Edge cases
+
+- **Brand not available on platform**: Apple Pay only on iOS Safari + WebKit-iOS. Hide the button on unsupported platforms; don't show as "disabled".
+- **Brand SDK fails to load**: log + show non-brand fallback. Don't show a button that won't work.
+- **User dismisses brand modal mid-flow**: button returns to default state, no error toast (user-cancelled, not failure).
+- **Network drops mid-payment**: server-side webhook reconciles; UI shows "결제 처리 중..." until resolved.
+- **A/B testing brand button styles**: don't. Brands require official assets — no creative variants.
+- **Dark mode**: brand assets are designed for light bg. KakaoPay yellow on dark bg is jarring. Some brands publish dark-mode variants; check guidelines.
+
+## Don't
+
+- Don't restyle brand colors / logos / wordmarks.
+- Don't omit the brand logo.
+- Don't combine multiple brand logos in one button (e.g., "KakaoPay or NaverPay" — make them separate buttons).
+- Don't disable the button after loading without showing an error.
+- Don't show 5+ brand buttons on one screen — overwhelming. Group via `PaymentMethodSelector` instead.
+- Don't translate the wordmark ("kakao pay" stays English even on Korean app — that's the brand).
+- Don't use brand buttons for non-payment actions (login, sharing). Different buttons for different purposes.
+
+## References
+
+- KakaoPay Developers: [https://developers.kakaopay.com/](https://developers.kakaopay.com/)
+- NaverPay merchant: [https://developer.pay.naver.com/](https://developer.pay.naver.com/)
+- Toss Payments: [https://docs.tosspayments.com/](https://docs.tosspayments.com/)
+- Apple Pay HIG: [https://developer.apple.com/design/human-interface-guidelines/apple-pay](https://developer.apple.com/design/human-interface-guidelines/apple-pay)
+- Samsung Pay developers: [https://pay.samsung.com/developers](https://pay.samsung.com/developers)
+
+## Cross-reference
+
+- [`examples/component-payment-method-selector.md`](component-payment-method-selector.md) — selector that includes these buttons
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — vendor selection rules
+- [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md) — focus ring contrast on brand-colored buttons

package/examples/component-payment-method-selector.md

@@ -0,0 +1,272 @@
+# `PaymentMethodSelector` (custom — Korean) — spec
+
+> Custom component pattern. The payment method selector is the highest-stakes screen in any e-commerce / fintech checkout. Korean conventions differ significantly from Western ones.
+>
+> Cited knowledge: [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md), [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md)
+
+## Purpose
+
+Lets the user pick how to pay during checkout: cards, wallets (KakaoPay/NaverPay/Toss), bank transfer (무통장입금), carrier billing (휴대폰결제), real-time bank transfer (계좌이체).
+
+The order, grouping, and visual emphasis matter — Korean users have strong expectations.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│ 결제 수단 선택                                     │
+│                                                  │
+│ ─── 간편결제 ─────────────────────────────────── │
+│  ◯ [💛 KakaoPay 로고]                       >    │
+│  ◯ [💚 NaverPay 로고]                        >    │
+│  ◯ [💙 Toss 로고]                             >    │
+│                                                  │
+│ ─── 카드 ─────────────────────────────────────── │
+│  ◯ 신용/체크카드                              >    │
+│      [등록된 카드: 국민카드 ****-1234]              │
+│                                                  │
+│ ─── 기타 ─────────────────────────────────────── │
+│  ◯ 휴대폰 결제                                >    │
+│  ◯ 무통장 입금                                >    │
+└──────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Section header per group | yes | "간편결제", "카드", "기타" |
+| Method row | yes | Radio + brand logo + label + chevron |
+| Saved-method indicator | optional | "등록된 카드: ..." |
+| Selection indicator | yes | Radio (`◯` / `●`) or selected state |
+| Drill-in chevron | optional | When picking opens detail screen (card list, account input) |
+
+## API
+
+```tsx
+<PaymentMethodSelector
+  value={selectedMethod}
+  onValueChange={setSelectedMethod}
+  availableMethods={["kakaopay", "naverpay", "toss", "card", "phone", "vbank"]}
+  savedCards={user.savedCards}
+  audience="consumer"
+  amount={45000}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Method \| null` | — | Selected method |
+| `onValueChange` | `(method) => void` | — | |
+| `availableMethods` | `Method[]` | all | Server-allowed methods |
+| `savedCards` | `Card[]` | `[]` | User's pre-registered cards (display next to "신용카드") |
+| `audience` | `"consumer" \| "b2b" \| "b2b-young"` | `"consumer"` | Drives ordering + emphasis |
+| `amount` | `number` | — | Used to filter (e.g., 휴대폰결제 only for < ₩500K) |
+| `showFees` | `boolean` | `false` | Show per-method fee disclosure |
+| `disabled` | `boolean` | `false` | |
+
+```ts
+type Method =
+  | "kakaopay"      // KakaoPay wallet
+  | "naverpay"      // Naver Pay wallet
+  | "toss"          // Toss wallet
+  | "samsungpay"    // Samsung Pay
+  | "card"          // Credit / debit card
+  | "phone"         // 휴대폰 결제
+  | "vbank"         // 무통장 입금 (virtual account)
+  | "transfer";     // 계좌이체 (real-time)
+```
+
+## Method ordering by audience
+
+Per [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md):
+
+### Consumer (default)
+
+```
+1. KakaoPay         ← top — most-used wallet
+2. NaverPay
+3. Toss
+─── 카드 ───────
+4. Credit/debit card
+─── 기타 ───────
+5. 휴대폰 결제 (if amount eligible)
+6. 무통장 입금
+```
+
+### B2B / Older audience
+
+```
+1. Credit/debit card     ← cards first
+2. 무통장 입금
+3. 계좌이체
+─── 간편결제 ───────
+4. KakaoPay (below the fold)
+5. NaverPay
+```
+
+### Young / fintech-coded
+
+```
+1. Toss              ← Toss-first for young audience
+2. KakaoPay
+3. Card
+4. 무통장 입금
+```
+
+## Brand button design
+
+Each wallet brand has official assets — **don't restyle**:
+
+| Brand | Color | Logo |
+| --- | --- | --- |
+| KakaoPay | Yellow `#FFCD00` | "KakaoPay" wordmark + speech-bubble icon |
+| NaverPay | Green `#00C73C` | "NaverPay" wordmark + N icon |
+| Toss | Blue `#3182F6` | "toss" wordmark + dot icon |
+| Samsung Pay | Black + brand red | "Samsung Pay" wordmark |
+| Apple Pay | Black | "Apple Pay" wordmark per Apple guidelines |
+
+When rendering as a brand button (selected, primary CTA), use the official color as background. When rendering as a list option (radio button), brand logo on left + neutral text label on right.
+
+See `component-payment-brand-button.md` for the brand button itself.
+
+## Behavior
+
+### Selection
+
+- Click a row: select that method.
+- For methods needing more info (card → which card?, vbank → which bank?): drill into a detail screen on selection.
+- For one-tap wallets: just select and let the parent flow proceed.
+
+### Saved card display
+
+If user has saved cards and picks "신용카드":
+- Show the most-recent card inline ("등록된 카드: 국민카드 ****-1234").
+- Drill into card list on tap to choose another or add new.
+
+### Method filtering by amount
+
+Example: 휴대폰결제 typically maxes out at ₩500,000. If `amount > 500000`, hide phone option (or show disabled with "한도 초과" hint).
+
+### Disabled methods
+
+Server might disable certain methods per-merchant or per-user. Disabled methods stay visible but greyed out, with a brief "사용할 수 없습니다" hint.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Method visible, radio empty |
+| Selected | Filled radio + slight bg highlight |
+| Disabled | Muted, no events, hint text |
+| Hover | Bg slightly darker |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated         (selected row bg)
+--color-bg-subtle           (hover)
+--color-primary-default     (selected radio)
+--color-text-primary
+--color-text-secondary       (saved-method indicator)
+--color-text-tertiary        (disabled hint)
+--color-text-disabled
+--color-border-default
+--color-focus-ring
+--space-md, --space-lg
+--radius-md
+```
+
+Brand colors (from each vendor's official guidelines):
+
+```
+--color-kakaopay-yellow:  #FFCD00
+--color-kakaopay-text:    #000000
+--color-naverpay-green:   #00C73C
+--color-naverpay-text:    #FFFFFF
+--color-toss-blue:        #3182F6
+--color-toss-text:        #FFFFFF
+```
+
+## Accessibility
+
+- Radio group: `<fieldset>` + `<legend>결제 수단</legend>`.
+- Each row: `<input type="radio">` + `<label>`.
+- Brand logos: `alt` attribute or `aria-label` (e.g., "KakaoPay 로고").
+- Section headers: `<h3>` (or appropriate) for each group.
+- Disabled rows: `aria-disabled="true"` with `aria-describedby` pointing to the disabled hint.
+- Saved card info: announced as part of the radio label ("Credit card. 등록된 카드: 국민카드 ****-1234").
+
+## Code example
+
+```tsx
+function CheckoutPaymentScreen() {
+  const [method, setMethod] = useState<Method | null>(null);
+  const user = useUser();
+  const { amount } = useCart();
+
+  const handleProceed = () => {
+    if (!method) return;
+    if (method === "card") {
+      navigate("/checkout/select-card");
+    } else if (method === "kakaopay") {
+      initiateKakaoPay({ amount });
+    } else if (method === "naverpay") {
+      initiateNaverPay({ amount });
+    }
+    // ...
+  };
+
+  return (
+    <Page>
+      <PaymentMethodSelector
+        value={method}
+        onValueChange={setMethod}
+        availableMethods={availableMethods}
+        savedCards={user.savedCards}
+        audience="consumer"
+        amount={amount}
+      />
+      <FixedFooter>
+        <p className="font-medium">총 결제 금액: ₩{amount.toLocaleString()}</p>
+        <Button size="lg" disabled={!method} onClick={handleProceed}>
+          결제하기
+        </Button>
+      </FixedFooter>
+    </Page>
+  );
+}
+```
+
+## Edge cases
+
+- **Saved card expired**: show with warning marker, prevent selection or prompt to update.
+- **All methods disabled** (rare server config issue): show error state suggesting contact support.
+- **Method selected but server rejects on attempt** (e.g., card declined): keep selection, show error, suggest different method.
+- **First-time user with no saved data**: all rows show; "신용카드" requires entering card on next screen.
+- **Quick-checkout with one default method**: hide selector entirely; show one row "결제: KakaoPay [변경]".
+- **Multiple saved cards of same type**: show count ("등록된 카드 3장").
+- **International tourist using KR app**: PayPal or 신용카드 (international) — most apps don't support; explain.
+
+## Don't
+
+- Don't restyle brand logos / colors — vendors require official assets.
+- Don't put all methods in one flat list. Group them.
+- Don't reorder by personal preference. Korean conventions are strong.
+- Don't auto-select a default method. Let user choose.
+- Don't show 8+ methods. If you have more, group "기타" with a drill-in.
+- Don't gate the selector behind login. Allow guest checkout where possible (with explicit signup nudge).
+- Don't omit fee disclosure if fees apply (legal in Korea for some categories).
+- Don't make wallets less prominent than cards in consumer flows.
+
+## API rationale
+
+- **`audience` prop**: ordering varies dramatically. A B2B SaaS shouldn't show KakaoPay first.
+- **`availableMethods` server-driven**: not all merchants accept all methods; server is the source of truth.
+- **`amount` prop**: enables method filtering (휴대폰결제 cap, etc.) without consumer logic in the parent.
+
+## Cross-reference
+
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — vendor selection, ordering rules, integration UX
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — Korean payment conventions
+- [`examples/component-payment-brand-button.md`](component-payment-brand-button.md) — the actual brand button rendering
+- [`examples/component-form-controls.md`](component-form-controls.md) — radio group pattern