@design-ai/cli 4.55.0

package/knowledge/i18n/korean-payments.md

@@ -0,0 +1,211 @@
+<!-- hand-written -->
+---
+title: Korean payments — vendor selection and integration UX
+applies_to: [korean-market, fintech, e-commerce, payments]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Korean payments
+
+Designing for Korean payments means choosing among a unique vendor landscape, then integrating each correctly. This is a decision document — pick a path, document why, ship.
+
+## The vendor landscape
+
+| Vendor | Type | Strengths | Notes |
+| --- | --- | --- | --- |
+| **Toss Payments** | PG (payment gateway) | Modern API, best DX, default for new fintech/SaaS | Toss the company, widely trusted brand |
+| **NHN KCP** | PG | Enterprise-grade, deep B2B presence | Older API; more setup |
+| **INICIS** (이니시스) | PG | Largest market share for traditional commerce | Legacy patterns; many Korean stores still default |
+| **NICE Payments** | PG | Deep ESCROW + identity infrastructure | Common in finance, 본인인증 |
+| **KakaoPay** | Wallet (간편결제) | Massive adoption (Kakao ecosystem) | Customer pays via KakaoPay app — UX shift |
+| **NaverPay** | Wallet | Strong in commerce, Naver shopping | Similar UX shift |
+| **Toss** (the wallet, not Toss Payments) | Wallet | Younger demographic, finance-first | Increasingly used as a payment method, separate from Toss Payments PG |
+| **Samsung Pay** | Wallet | OEM card-on-device | Less common in standalone apps; embedded in Samsung phones |
+| **PayPal Korea** | International gateway | When you need to accept overseas cards | Niche |
+| **휴대폰결제 (Carrier billing)** | Telco-billed | Quick small-amount, no card needed | Mobile-game / digital-content category |
+| **무통장입금 (Bank transfer)** | Direct deposit | Older demographics, distrust of cards | Shows virtual account; user transfers from bank app |
+| **계좌이체 (Real-time bank transfer)** | Direct ACH | Lower fees than cards, common in B2B/large amounts | Friction: bank app handoff |
+
+## Decision tree — which to integrate
+
+```
+Is the product:
+├── Consumer mobile app (B2C)?
+│   └── Required: Toss Payments PG (cards) + KakaoPay + NaverPay
+│       Optional: Toss wallet, Samsung Pay
+├── B2B / Enterprise?
+│   └── Required: NHN KCP or NICE (legacy PG) + 무통장입금
+│       Optional: 계좌이체 for invoiced amounts
+├── Subscription SaaS?
+│   └── Required: Toss Payments PG (best subscription API)
+│       Optional: KakaoPay (recurring), NaverPay
+├── Digital content / Game?
+│   └── Required: 휴대폰결제 + Toss Payments PG
+│       Optional: KakaoPay
+├── E-commerce?
+│   └── Required: Toss Payments + KakaoPay + NaverPay + 무통장입금
+│       Optional: 계좌이체 for high-value, ESCROW for marketplace
+└── Cross-border / Tourism?
+    └── Required: PayPal + Toss Payments
+        Optional: Alipay+ (for Chinese visitors)
+```
+
+**Rule of thumb for new B2C apps**: Toss Payments PG as the foundation (handles cards, subscriptions, virtual accounts). Add KakaoPay and NaverPay as one-tap shortcuts. That's ~95% of the market.
+
+## Integration UX patterns
+
+### The payment method selector
+
+The order of payment methods on the selector screen carries weight in Korea:
+
+```
+[ ─ Recommended order for B2C consumer ─ ]
+1. KakaoPay (yellow brand button)        ← top — most-used wallet
+2. NaverPay (green brand button)         ← second wallet
+3. Toss (blue)                           ← if your audience skews younger
+─────────────────────
+4. 신용/체크카드 (credit/debit card)       ← break, then cards
+5. 휴대폰결제                              ← if applicable
+6. 무통장입금                              ← always last for B2C
+```
+
+For older / B2B audiences:
+```
+1. 신용/체크카드
+2. 무통장입금
+3. 계좌이체
+4. 휴대폰결제 (if applicable)
+5. KakaoPay / NaverPay (below the fold)
+```
+
+Brand buttons (KakaoPay yellow, NaverPay green, Toss blue) carry recognition. Use the official assets — vendors require it as part of their brand guidelines.
+
+### One-tap wallets vs card form
+
+When a user picks KakaoPay/NaverPay:
+- **Don't show a card form afterwards.** They've already chosen the wallet — switch to the wallet handoff immediately.
+- Wallet flow: SDK opens an in-app browser or native wallet app → user authenticates → returns to your app with success/fail.
+- Loading state while waiting on wallet callback: spinner + "결제 진행 중…" (do not show "Loading…" English).
+
+When a user picks "신용/체크카드":
+- Show card form: 카드번호, 유효기간, CVC, 카드명의자명.
+- Toss Payments offers `requestPayment` SDK that renders this form with their UX — recommended over building it yourself.
+- For first-time entry, ask for `이름` (cardholder name) per regulation.
+- Save card option: present **after** successful first payment, not before. Korean users are wary of pre-checked save-card.
+
+### Subscription disclosure (legal requirement)
+
+E-commerce law mandates clear disclosure **before** the subscribe button:
+
+```
+┌─────────────────────────────────────┐
+│ 구독 정보 (subscription details)     │
+│                                     │
+│ 월 ₩9,900 자동 결제                  │
+│ 매월 7일에 결제됩니다                │
+│ 카드: KB국민카드 ****-1234           │
+│                                     │
+│ [언제든 해지 가능 · 해지 방법 보기]    │
+│                                     │
+│ □ 위 내용에 동의합니다                │
+│                                     │
+│   [구독 시작]                        │
+└─────────────────────────────────────┘
+```
+
+- Price in ₩, period explicit.
+- Next billing date shown.
+- Cancellation method explicitly stated and linked.
+- **Consent checkbox required** — pre-checked is illegal under e-commerce law.
+- After subscription, send a confirmation email (legal requirement) summarizing the same info.
+
+### Refund / 청약철회
+
+Korean e-commerce law gives consumers a **7-day cooldown** for digital goods (with caveats — opened software, used services may be excluded). UX must:
+- Disclose this period at point of purchase.
+- Provide an in-app refund/cancel path.
+- Document exclusions clearly (e.g., "이미 다운로드한 콘텐츠는 환불 불가").
+
+### Failed payment
+
+Common Korean failure modes and the right error message:
+
+| Cause | English equivalent | Korean message |
+| --- | --- | --- |
+| Card declined by issuer | Card declined | "카드사에서 거절되었습니다. 다른 카드를 시도해 주세요." |
+| Insufficient funds | Insufficient funds | "잔액이 부족합니다." |
+| Daily limit exceeded | Over daily limit | "1일 결제 한도를 초과했습니다." |
+| Foreign card not allowed | International card blocked | "해외 카드는 이 결제에서 사용할 수 없습니다." |
+| Wallet auth timeout | KakaoPay/NaverPay timed out | "인증 시간이 만료되었습니다. 다시 시도해 주세요." |
+| Network | Connection lost | "네트워크 연결이 불안정합니다." |
+| 본인인증 mismatch | Identity check failed | "본인 정보가 일치하지 않습니다. 입력 정보를 확인해 주세요." |
+
+**Always provide a "다시 시도" (retry) button**, except for `본인인증` failures (which require user to fix the underlying data).
+
+## 본인인증 (Identity verification)
+
+Required for:
+- Financial transactions over ~₩500,000 (varies by use case)
+- Age-gated content
+- Account creation in some categories (mobile carriers, securities)
+- Real-name verified accounts (실명인증)
+
+Vendors:
+- **PASS app** — most modern, used by all 3 carriers (SKT/KT/LGU+). Native app handoff.
+- **NICE 본인인증** — SMS-based or PASS-based, integrated into NICE's PG.
+- **KCB 본인인증** — alternative to NICE.
+
+**Never roll your own.** It requires real-name database integration only available via licensed vendors.
+
+UX flow:
+```
+[현재 화면: 본인인증 필요]
+
+  본인인증이 필요합니다
+  안전한 결제를 위해 본인인증을 진행해주세요.
+
+  [PASS 앱으로 인증]
+  [SMS로 인증]
+  [공동인증서로 인증]   ← rare, falling out of use
+
+  > 본인인증은 약 1분 소요됩니다.
+```
+
+After success, return to the payment flow with `verificationToken` in the user's session.
+
+## ESCROW (필수 in some categories)
+
+Marketplaces (peer-to-peer commerce) and certain product categories legally require ESCROW — payment held by a 3rd party until the buyer confirms receipt.
+
+- Vendor: NICE Payments, KCP, INICIS all offer ESCROW APIs.
+- UX: buyer pays → ESCROW holds → seller ships → buyer confirms (or auto-confirms after N days) → ESCROW releases.
+- Display "ESCROW 보호 거래" badge on listing/payment screen — Korean buyers look for it.
+
+## Cost structure (high-level)
+
+| Method | Typical fee | Notes |
+| --- | --- | --- |
+| Cards (PG) | 2.5–3.5% | Negotiable at scale; chargebacks possible |
+| KakaoPay | 2.5–3.0% | Some products have lower wallet fees |
+| NaverPay | 2.5–3.0% | |
+| Bank transfer (계좌이체) | 0.5–1.0% | Cheapest; friction higher |
+| 휴대폰결제 | 5–7% | Highest fee but trivial UX for small amounts |
+| 무통장입금 | ~₩400 / transaction | Flat, near-zero percentage; manual reconciliation overhead |
+| 본인인증 | ~₩70–200 / verification | Per-call vendor fee |
+
+For a typical B2C consumer app with ~3% blended payment cost: assume **2.8%** as a planning number after KakaoPay/NaverPay/card mix.
+
+## What designers (not just engineers) need to know
+
+- Brand button colors and shapes are **regulated by the wallet vendors**. KakaoPay's button must be yellow with the official KakaoPay logo at the official aspect ratio. NaverPay must be green with the N. Don't restyle.
+- The wallet handoff flow (in-app browser or native app) takes ~3–10 seconds. Design a clear loading state.
+- "결제 완료" confirmation screens are expected — don't auto-navigate away. Show order/payment ID, copy-to-clipboard affordance, and a primary "내역 보기" / "주문 확인" CTA.
+- For subscriptions, design the **cancel flow** as a first-class UI. Korean users expect to find "구독 해지" within 2 taps from settings.
+
+## Cross-reference
+
+- [knowledge/i18n/korean-product-conventions.md](korean-product-conventions.md) — broader Korean UX conventions
+- [knowledge/i18n/korean-publishing.md](korean-publishing.md) — store submission requirements (privacy, marketing consent)
+- [knowledge/patterns/form-design.md](../patterns/form-design.md) — payment form patterns (card, address)

package/knowledge/i18n/korean-product-conventions.md

@@ -0,0 +1,96 @@
+<!-- hand-written -->
+---
+title: Korean product UX conventions
+applies_to: [korean-market, mobile, web, payments]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Korean product UX conventions
+
+Patterns Korean users expect from local apps. Designs that ignore these read as "translated foreign apps" and lose trust.
+
+## Authentication
+
+| Pattern | Korean expectation |
+| --- | --- |
+| Phone-first signup | Most consumer apps require **phone number + SMS verification** as the primary identity. Email is secondary or optional. |
+| KakaoTalk login | The dominant social login in Korea. Treat it like Apple/Google ID elsewhere. Place above email login. |
+| Naver login | Second most common. Used in news/portal/shopping. |
+| Apple/Google login | Required for app store policy compliance, but place below Kakao/Naver in the visual order for Korean apps. |
+| 본인인증 (Identity verification) | Real-name verification via PASS app or SMS. Required for finance, ticketing, certain age-gated content. **Never implement this yourself** — use a vendor (KCB, NICE, Toss). |
+
+## Payments
+
+| Pattern | Korean expectation |
+| --- | --- |
+| **Toss / KakaoPay / NaverPay** | One-tap payment apps. Most consumer flows show these as primary tabs in the payment selector. |
+| Credit card | Local cards (BC, Shinhan, KB, etc.). Stripe ≠ payment processor here — use Toss Payments, NHN KCP, INICIS, KakaoPay for Business. |
+| 무통장입금 (Bank transfer) | Still common for older demographics, certain B2C. Provide a virtual account. |
+| 휴대폰결제 (Mobile carrier billing) | Small-amount purchases (< ~₩500K). Common in mobile gaming, digital content. |
+| Subscription disclosures | Korea's e-commerce law requires explicit recurring charge disclosure with all prices in ₩, before the subscribe button. |
+| 청약철회 (Right to withdraw) | 7-day cooldown for digital goods is legally required to be disclosed. |
+
+## Forms
+
+- **Address**: Korean addresses use postal-code lookup (도로명주소 / 지번주소) — never free-form. Use the **Daum Postcode API** (free, ubiquitous). Never ask the user to type their full address.
+- **Birth date**: 6-digit `YYMMDD` with regional/gender suffix (resident registration number) — **don't ever ask for the full RRN**. For age, ask for birth year only or full DOB.
+- **Name**: single field "이름". Do not split first/last — Korean names are written 성 + 이름 (family-given) without space. Don't apply Western "first/last" splitting.
+- **Phone**: 11-digit mobile (`010-####-####`). Validate with regex `/^01[0-9]-?\d{3,4}-?\d{4}$/`.
+- **Email**: standard. Korean users frequently use Naver (`@naver.com`) and Daum (`@hanmail.net`); make sure your validator accepts both common patterns.
+
+## Navigation patterns
+
+- **Bottom tab bar (mobile)**: 4–5 tabs. Korean apps frequently use **icon + Korean label** — labels are not optional.
+- **Hamburger menu**: less common as a primary nav in Korean consumer apps. Korean users prefer visible tabs.
+- **Back button**: respect device-native back. Custom back buttons in headers are still common (left-positioned chevron) but don't replace the system gesture.
+- **Search**: prominent, often as a top-bar icon or persistent input. Korean users search more than browse compared to Western patterns.
+
+## Content density
+
+Korean consumer apps tend toward **higher density** than Western apps:
+- More items per screen (lists, feeds, dashboards).
+- Smaller padding between elements.
+- More text per card.
+
+This is not "cluttered design" — it matches reading pace and screen-time habits. When porting a Western design, be prepared to reduce padding by 15–25% and increase items-per-fold.
+
+Reference: see how Coupang, Naver, KakaoTalk, Toss differ from Amazon, Google, WhatsApp, Robinhood.
+
+## Color associations
+
+Different from Western color symbolism:
+
+| Color | Korean association | Use for |
+| --- | --- | --- |
+| Red | Risk, sale, **but not death** | error, sale price, urgency. Korean ecommerce "할인" (sale) badges are red. |
+| Blue | Trust, finance | primary CTAs, fintech, banking |
+| Green | Growth, "go" | success, environmental, **not money** (unlike US green=$) |
+| Yellow | KakaoTalk-coded | branded only — most users associate yellow with Kakao. Use cautiously as a primary brand color. |
+| Black + gold | Luxury, premium | high-end shopping, premium tiers |
+| Pink / coral | Beauty, fashion, K-beauty | cosmetics, lifestyle apps |
+
+## Error and empty states
+
+- Tone: be apologetic, not casual. "오류가 발생했습니다" (an error occurred) over "Oops!"
+- Provide a recovery action — Korean users expect a "다시 시도" (retry) button or contact path.
+- "Empty cart" / "no results" should suggest next steps (popular items, recommendations).
+
+## Customer service expectations
+
+- 1:1 inquiry (1:1 문의) is a standard pattern — a chat or form within the app.
+- Phone customer service hours (KST) are commonly displayed.
+- "고객센터" (customer center) is the standard term for support.
+
+## Compliance notes
+
+- **개인정보처리방침 (Privacy policy)** — required link, often in app settings.
+- **이용약관 (Terms of service)** — required, must be agreed at signup with separate checkboxes for required vs marketing-opt-in items.
+- **마케팅 수신 동의** (Marketing consent) — must be a separate opt-in from required terms. Pre-checked is illegal.
+- **앱 권한 안내** (App permissions disclosure) — Google Play Korea requires a clear in-app disclosure of why each permission is requested.
+
+## Cross-reference
+
+- [knowledge/i18n/korean-typography.md](korean-typography.md)
+- (TODO) [knowledge/i18n/korean-publishing.md](korean-publishing.md) — store-listing rules

package/knowledge/i18n/korean-publishing.md

@@ -0,0 +1,139 @@
+<!-- hand-written -->
+---
+title: Korean app store & publishing requirements
+applies_to: [korean-market, ios, android, app-store-connect, google-play, onestore]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Korean app store & publishing requirements
+
+What designers need to know to ship into the Korean market without rejections or last-minute scrambles. This is a pre-flight checklist, not legal advice.
+
+## The three Korean stores
+
+| Store | Why it exists | Designer impact |
+| --- | --- | --- |
+| **App Store (iOS)** | Required for iPhone | Korean metadata in App Store Connect; KCC age rating |
+| **Google Play Korea** | Default for Android | Korean store listing, KOPECO age rating, in-app permission disclosure popup |
+| **ONE store (원스토어)** | KT/SKT/LG U+ joint platform; required for some carrier promotions and game/finance categories | Separate store listing, separate APK, separate review queue |
+
+Most consumer apps publish to App Store + Google Play. Games + finance + telecom-bundled apps add ONE store.
+
+## Mandatory metadata (Korean store listings)
+
+### Names and descriptions
+- **App name**: ≤ 30 characters Korean. Trademark-safe (Korea's trademark database is hostile to generic English names).
+- **Subtitle / Promo text**: must be in Korean.
+- **Description**: write Korean-native, not machine-translated. Include 5–7 keywords naturally for App Store search.
+
+### Screenshots
+| Spec | iPhone 6.5" / 6.7" / 6.9" | Android |
+| --- | --- | --- |
+| Resolution | 1290×2796, 1284×2778, 1242×2688 | 1080×1920+ |
+| Count | 3–10, **first 3 are critical** (visible without scroll) | 2–8 |
+| Korean text | **Required.** Translated screenshots only — do not ship English-text screenshots to Korean storefront. |
+| Density | High — Korean stores expect 50–70% of screen area to be feature copy + UI, not blank backgrounds. |
+
+Korean screenshot conventions:
+- Bold, high-contrast typography.
+- 1–2 lines of bold benefit copy per screenshot.
+- App UI partially shown (cropped) under the copy.
+- Often with a phone-frame mockup.
+
+### App icon
+- 1024×1024 master.
+- Test at 60×60 — Korean store grids are dense; the icon must read at thumbnail size.
+- Hangul "글자" inside icon is acceptable and common (e.g., 토스 = "T", 카카오톡 = "톡"). Use only when the brand is the letter.
+- Avoid: photos, gradients with text overlay, complex illustrations.
+
+## Age ratings (필수)
+
+### iOS — App Store Connect
+- Standard 4+ / 9+ / 12+ / 17+ ratings apply.
+- Korea also enforces the **GRAC (게임물관리위원회)** rating for **games specifically**. If your app is categorized as a game, it must have a separate Korean GRAC rating displayed.
+
+### Android — Google Play
+- Uses **KOPECO** (한국게임정책자율기구) rating for games or **KMRB (영상물등급위원회)** for video content.
+- Non-game apps use Google's standard IARC rating.
+
+For games:
+- Get the GRAC rating before submission. The number must appear in the listing.
+- Categories: 전체이용가 (All), 12세이용가, 15세이용가, 청소년이용불가 (18+).
+
+## In-app required disclosures
+
+Korean law and store policy require these to be **in-app**, not just in store:
+
+### Privacy
+- Privacy policy link in **app settings or sign-up flow**, not just the store listing.
+- 개인정보처리방침 (privacy policy) must be Korean and disclose: data types collected, purpose, retention period, third-party sharing.
+
+### Terms
+- 이용약관 must be agreed at sign-up via a checkbox. Can be a single combined agreement, but marketing consent must be a **separate, opt-in** checkbox.
+
+### Permissions (Android, Google Play Korea-specific)
+- Before requesting any sensitive permission (location, camera, mic, contacts, storage), show an in-app dialog explaining:
+  - Which permission is being requested.
+  - Why it's needed for which feature.
+  - Whether it's required vs optional.
+- This is in addition to the OS prompt. Google Play Korea will reject without this in-app disclosure.
+
+### Subscriptions / IAP
+- Show price in ₩ before purchase.
+- Show recurring schedule (월 / 연 / 회).
+- Show cancellation method explicitly: "구독은 [iOS Settings / Google Play] 에서 해지할 수 있습니다."
+
+## Common rejection reasons (App Store, KR)
+
+1. **Missing Korean screenshots** — English screenshots in Korean storefront.
+2. **Missing Korean privacy policy URL** — must resolve to a Korean-language page.
+3. **Permission requested without in-app explanation** — Apple's "Why does your app need this?" string is per-permission and must be Korean.
+4. **Login required to demo without test credentials** — provide test account for review team.
+5. **Subscription without restore-purchase** — required for paid apps.
+6. **External payment links** — apps targeting Korea got an exemption (2023+) but still must use approved alternative-payment flow if not using Apple IAP.
+
+## Common rejection reasons (Google Play, KR)
+
+1. **No in-app permission explanation popup** before requesting sensitive permissions.
+2. **Sensitive content without age gate** — even text/article apps with adult content need explicit age verification.
+3. **Misleading screenshots** — Korean store reviewers check screenshots match actual UI more strictly than US.
+4. **Inadequate Korean translation** — partial Korean (some screens English, some Korean) is grounds for rejection.
+
+## ONE store specifics (원스토어)
+
+If publishing to ONE store:
+- Separate APK signing (different signing key allowed; many devs use the same as Play).
+- Separate app icon (same asset acceptable).
+- ONE store has its own in-app billing SDK — separate from Google Play Billing.
+- Smaller share of market but required for some carrier-bundled placements.
+- Approval queue is 5–7 business days; typically less strict than Google Play KR.
+
+## Localization reminders
+
+- **Currency**: ₩ everywhere. Localize prices for KRW market — `$1.99` → `₩2,500` (round to natural Korean price tiers, not direct conversion).
+- **Date / time**: Korea Standard Time (KST, UTC+9). No DST.
+- **Phone**: 010-####-####.
+- **Address**: Daum Postcode API for forms.
+- **Customer service**: business hours stated on contact pages, in KST.
+
+## Pre-submission checklist
+
+- [ ] App name reserved on App Store Connect / Play Console / ONE store.
+- [ ] Korean app description (not machine-translated).
+- [ ] All screenshots include Korean text overlays.
+- [ ] Privacy policy URL resolves to Korean-language page.
+- [ ] Terms of service in-app, separate marketing-consent checkbox.
+- [ ] Permission rationale strings localized to Korean.
+- [ ] In-app permission disclosure popup (Android).
+- [ ] GRAC age rating obtained (games only).
+- [ ] Test account credentials provided to reviewer.
+- [ ] All currency formatted ₩ with comma separator.
+- [ ] Subscription cancellation path stated in-app.
+- [ ] Customer service contact path in-app (1:1 inquiry, email, or phone).
+
+## Cross-reference
+
+- [knowledge/i18n/korean-typography.md](korean-typography.md)
+- [knowledge/i18n/korean-product-conventions.md](korean-product-conventions.md)

package/knowledge/i18n/korean-typography.md

@@ -0,0 +1,123 @@
+<!-- hand-written -->
+---
+title: Korean (Hangul) typography for product UI
+applies_to: [korean-market, hangul, cjk, web, mobile]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Korean (Hangul) typography for product UI
+
+Designing for Korean users requires deliberate adjustments. Latin defaults from MUI, Ant Design, or Tailwind do not translate. This is the floor.
+
+## Why Hangul is different
+
+- **Glyph shape**: Hangul is composed of jamo blocks stacked in roughly square cells. Latin glyphs sit on a baseline; Hangul fills the cell.
+- **Vertical metrics**: descenders (받침, batchim) reach noticeably lower than Latin descenders. Default Latin `line-height` truncates them or makes adjacent lines feel cramped.
+- **Optical weight**: Korean fonts at the same numeric weight (e.g., 400) read **lighter** than Latin sans-serif. A "regular" Hangul body looks thin next to "regular" Inter.
+- **Width**: Hangul characters are roughly fixed-width per syllable block. Reading speed depends more on line length than on tracking.
+- **No italics**: traditional Hangul has no italic form. Italicized Hangul looks broken and is non-idiomatic. Use weight or color for emphasis instead.
+
+## Type scale adjustments
+
+Start from your Latin scale, then apply:
+
+| Property | Latin default | Korean adjustment |
+| --- | --- | --- |
+| `line-height` (body) | 1.5 | **1.6–1.7** |
+| `line-height` (headings 24+px) | 1.3 | **1.4** |
+| `letter-spacing` (body) | `0` or `-0.005em` | **`0`** (don't tighten) |
+| `letter-spacing` (caps/labels) | `0.05em` | **`0`** — no all-caps in Hangul anyway |
+| `font-weight` (body emphasis) | 500 (Medium) | **600** (SemiBold) — 500 reads too light |
+| `font-weight` (UI labels) | 500 | **500–600** depending on font |
+
+## Recommended typefaces
+
+### Free / open-source (Korean-only)
+
+| Font | License | Best for | Notes |
+| --- | --- | --- | --- |
+| **Pretendard** | OFL | Universal — body, UI, headings | De facto Korean Inter. Excellent variable. Pairs with itself for Latin (Pretendard mixes Inter glyphs). **Default recommendation.** |
+| **Noto Sans Korean** (Noto Sans KR) | OFL | Body, system fallback | Google's pan-CJK. Heavy file size in static; use variable. |
+| **Spoqa Han Sans Neo** | OFL | UI, formal product | Spoqa's UI-focused face. 7 weights. Slightly more rigid than Pretendard. |
+| **Apple SD Gothic Neo** | system | iOS / macOS only | iOS native. Use for native apps only. |
+
+### Free fonts to avoid for product UI
+
+- **Nanum Gothic** — designed for print legibility, lower x-height, looks dated in product UIs.
+- **Malgun Gothic** — Windows system. Renders inconsistently across platforms.
+- **Black Han Sans** etc. — display-only, not for body.
+
+### Pairing strategy
+
+For Korean-primary products with English secondary content:
+
+```css
+font-family: 'Pretendard', -apple-system, BlinkMacSystemFont, 'Segoe UI',
+             'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif;
+```
+
+Pretendard's design covers Latin and Hangul in matched proportions, so a single stack handles both. **Do not** pair `Inter` (Latin) + `Spoqa Han Sans` (Hangul) — the Latin x-heights mismatch.
+
+For Korean-secondary products (English-primary with KR locale):
+
+```css
+font-family: Inter, -apple-system, 'Apple SD Gothic Neo',
+             'Noto Sans KR', sans-serif;
+```
+
+Inter is Latin-only. The OS / Noto fallback handles Hangul. This is acceptable but the size-mismatch between Inter and Noto KR will be visible — tune `font-size-adjust: 0.5` (browser support 2024+) or accept the small inconsistency.
+
+## Numerical readout
+
+Korean readers expect:
+- **Numbers in Latin glyphs** (`1234`), not Hangul number words.
+- **Comma thousands separator** (`1,234,567`) — same as US.
+- **Won symbol**: `₩` prefix or `원` suffix. `₩1,200` is more "fintech/Western"; `1,200원` is more "consumer/local". Pick one and be consistent.
+- **Date format**: `2026년 5월 7일` (formal), `2026.05.07` (compact), `2026-05-07` (technical). Default to `YYYY.MM.DD` for most product UIs.
+- **Phone**: `010-1234-5678` (mobile), `02-1234-5678` (Seoul landline). Hyphenated, never spaces.
+
+## Common product UI strings — bar for tone
+
+| Action | Casual / friendly | Polite / formal |
+| --- | --- | --- |
+| Save | 저장 | 저장하기 |
+| Delete | 삭제 | 삭제하기 |
+| Cancel | 취소 | 취소 |
+| Confirm | 확인 | 확인 |
+| Sign in | 로그인 | 로그인 |
+| Sign out | 로그아웃 | 로그아웃 |
+| Sign up | 가입 | 회원가입 |
+| Submit | 제출 | 제출하기 |
+| Loading | 로딩 중 | 불러오는 중 |
+| Error | 오류 | 오류가 발생했습니다 |
+
+Casual tone fits B2C, social, fintech consumer apps. Polite/formal fits enterprise, healthcare, finance B2B.
+
+Avoid:
+- Mixing tones within a screen.
+- Direct translation of "Submit" (use 등록/저장 depending on context, rarely 제출 outside formal forms).
+- Loanword preference where a clean Korean exists (저장 over 세이브).
+
+## Layout adjustments
+
+- **Form labels**: above inputs (not beside) — Korean labels often run longer than English equivalents.
+- **Button width**: minimum padding inline 16px. Korean labels like "회원가입하기" need width; tight buttons crop awkwardly.
+- **Truncation**: Korean truncation with `…` reads cleanly per syllable; mid-word break is rare. CSS `text-overflow: ellipsis` works.
+- **Word break**: avoid `word-break: break-all` for Hangul — it breaks mid-syllable. Use `word-break: keep-all` (browser-supported, prevents breaking inside a Hangul syllable cluster).
+- **Justified text**: `text-align: justify` rarely looks good with Hangul; whitespace gaps are jarring. Stick to `left`.
+
+## Readability check
+
+A Korean body paragraph is readable when:
+- 14–16 px font-size on web, 15–17 pt on mobile native.
+- Line length ≈ 35–40 Hangul characters per line (vs ~70 Latin characters).
+- 1.6+ line-height.
+- Sufficient `paragraph-spacing` (≥ 1em) — Hangul paragraphs blur together without it.
+
+## Cross-reference
+
+- [knowledge/typography/type-scale-fundamentals.md](../typography/type-scale-fundamentals.md) — base scale knowledge
+- [knowledge/typography/font-pairings.md](../typography/font-pairings.md) — Latin pairings (apply Korean adjustments on top)
+- [knowledge/i18n/korean-publishing.md](korean-publishing.md) — store-listing / submission considerations