@design-ai/cli 4.55.0

package/knowledge/patterns/money-and-amount.md

@@ -0,0 +1,301 @@
+<!-- hand-written -->
+---
+title: Money and amount — display, input, color semantics
+applies_to: [fintech, e-commerce, all-money-aware-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Money and amount
+
+Designing UIs that display and accept money has its own rules. Get them wrong and users misread their balance, miscount their cart, or miss-key a transfer. This is the floor for any product where money is on screen.
+
+## Currency display rules
+
+### Format
+
+| Locale | Recommended | Examples |
+| --- | --- | --- |
+| Korea (consumer) | `1,200,000원` (suffix style) | `12,500원` `1,234,567원` |
+| Korea (fintech / Western-coded) | `₩1,200,000` (prefix style) | `₩12,500` `₩1,234,567` |
+| US | `$1,234.56` | `$25.00` `$1,234.56` |
+| Japan | `¥1,234` (no decimal) | `¥250` `¥1,234,567` |
+| EU | `1.234,56 €` (varies) | `25,00 €` `1.234.567,89 €` |
+
+For Korean apps:
+- **Suffix `원`** reads as consumer/local — coffee shops, e-commerce, 가계부.
+- **Prefix `₩`** reads as fintech/professional — investment apps, banking, B2B.
+- **Pick one and stay consistent throughout the product.**
+
+### Thousands separator
+
+Always show. `1234567` is unreadable; `1,234,567` is parseable at a glance.
+
+In Korean: comma every 3 digits is the universal convention for the **arabic-numeral** form. The Korean-number form (`123만 4,567`) is used in display contexts (charts, summaries) but not in transactional contexts.
+
+### Decimals
+
+KRW has no sub-unit (no jeon in modern usage). **Always integer.**
+- Don't display `.00` for KRW. `12,500원`, not `12,500.00원`.
+- For currencies with subunits (USD, JPY without decimals, EUR with), display 2 decimals consistently (or 0 for JPY).
+
+### Tabular numerals
+
+When amounts appear in lists or tables, use `font-feature-settings: 'tnum' 1` (or a font with built-in tabular figures). This makes digits the same width — `1,234,567` aligns with `1,000,000` cleanly:
+
+```
+proportional:        tabular:
+₩1,234,567           ₩1,234,567
+₩  100,000           ₩  100,000
+₩    9,500           ₩    9,500
+```
+
+The tabular column is scannable; the proportional one looks staggered.
+
+Pretendard supports `tnum` natively (set via CSS). Most variable fonts do.
+
+### Korean number names (만, 억) for display contexts
+
+For very large amounts in summaries / hero displays, Korean readers parse `1.2억` faster than `120,000,000`. Common for:
+- Real estate (price)
+- Investment account totals
+- Large transactions
+
+Format: `<truncated number>억`, `<truncated number>만`, or full form. Examples:
+
+| Raw | Compact | Use |
+| --- | --- | --- |
+| `1,234,567` | `123만 4,567원` | rarely worth the verbosity |
+| `12,345,678` | `1,234만원` | compact display |
+| `123,456,789` | `1억 2,345만원` | hero |
+| `1,234,567,890` | `12억 3,457만원` | hero |
+
+**Don't use this format for transactional amounts** (cart totals, transfer amounts) — only for high-level summary displays. Transactional needs full digits for accuracy.
+
+## Color semantics for money
+
+This is its own axis, **separate from primary/accent/error**.
+
+```
+✓ Money colors (semantic):
+  --color-money-positive   (income, deposit, balance increase)
+  --color-money-negative   (expense, withdrawal, balance decrease)
+  --color-money-neutral    (transfer, unchanged)
+```
+
+| Color | Convention | Example |
+| --- | --- | --- |
+| Positive (Korean) | **Red `#DC2626`** for stock gains (Korean reads red as "rising") OR green `#16A34A` for income/deposit | Korean stock apps: red gain, blue loss. Korean banking: green deposit, red withdrawal. |
+| Positive (US/Western) | Green | Standard everywhere except KR/JP/CN stocks |
+| Negative (Korean) | **Blue `#2563EB`** for stock losses OR red `#DC2626` for expenses/withdrawals | Korean stock apps: blue. Korean banking: red. |
+| Negative (US/Western) | Red | Standard |
+| Neutral | Neutral text color (`--color-text-primary`) | Transfer, account balance display |
+
+### The Korean stock convention is INVERTED from the West
+
+Korean stock apps (and Japanese, Chinese):
+- 🔴 **Red = up / gain / 상승**
+- 🔵 **Blue = down / loss / 하락**
+
+This comes from cultural color associations (red = celebration, blue = somber). Western traders working in Korean apps often misread.
+
+If your app handles stocks/crypto for Korean users: **use the Korean convention by default**. Provide a settings toggle for "Western color scheme" but don't default-flip.
+
+If your app is Korean banking/fintech (NOT stocks): use the universal expense-red, income-green convention. KakaoBank, Toss show deposit-green, withdrawal-red.
+
+### Don't use `--color-error` for negative amounts
+
+`--color-error` means **something went wrong**. A negative balance, an outgoing payment, a stock loss — none of those are errors. They're values that happen to be negative. Use `--color-money-negative`.
+
+A user who paid for groceries didn't make an error. Coloring the expense as `--color-error` reads as "this expense was a mistake."
+
+### Don't use `--color-success` for positive amounts
+
+Same reasoning. Income isn't a "success state" of the system; it's a fact about a number.
+
+## Display patterns
+
+### Hero balance display
+
+```
+┌─────────────────────────────────┐
+│ 사용 가능 금액                    │
+│                                 │
+│   ₩2,847,500                    │   ← display variant, 38px+, semibold, tnum
+│                                 │
+│ +12,500원 이번 달                │   ← caption, money-positive color
+└─────────────────────────────────┘
+```
+
+- The amount is the largest text on the screen.
+- Sub-line (delta, period, label) immediately below — small caption with semantic color.
+- Optional comparison ("이번 달 +12,500원" or "+0.4% 어제 대비").
+
+### Transaction row
+
+```
+┌──────────────────────────────────────────────┐
+│ 🍽 점심 식사                          -12,500원 │   ← right-aligned tabular num
+│    스타벅스 강남점 · 12:34            ─2,832,500원 │   ← post-transaction balance
+└──────────────────────────────────────────────┘
+```
+
+- Icon (category emoji or icon) on the left.
+- Amount and post-balance on the right, right-aligned.
+- Use tabular numerals so the column is clean across many rows.
+- Sign convention: `-12,500원` for outflow, `+12,500원` for inflow, no sign for neutral. Don't use parentheses `(12,500원)` — Korean readers parse `-` more naturally.
+
+### Cart / order summary
+
+```
+상품 합계         ₩45,000
+배송비            ₩3,000
+할인             -₩5,000        ← negative (discount), money-positive color (it's good for the user)
+─────────────────────────
+총 결제 금액      ₩43,000        ← bolder, larger, hero tier
+```
+
+The convention here is interesting: discount is a **negative number** in the math but a **positive event** for the user. Color it as `--color-money-positive` (green/blue) — the discount is a benefit, not a charge. Then the final total uses neutral / heavy text.
+
+### Account balance breakdown
+
+```
+┌───────────────────────────────┐
+│ 자유적금                       │
+│ 신한은행 ****-321              │
+│                               │
+│ ₩5,200,000                    │ ← amount in display tier
+│                               │
+│ 매월 ₩100,000 자동이체          │ ← caption, neutral
+└───────────────────────────────┘
+```
+
+## Amount input patterns
+
+### Auto-format on input
+
+User types `1234567`; field shows `1,234,567`. Caret position must NOT jump.
+
+Implementation note: format on every keystroke, then carefully restore caret position. Most amount-input libraries (Cleave.js, react-number-format) handle this.
+
+### Suffix inside the field
+
+```
+┌─────────────────────────────┐
+│ 1,234,567                원  │
+└─────────────────────────────┘
+```
+
+Or prefix:
+```
+┌─────────────────────────────┐
+│ ₩    1,234,567              │
+└─────────────────────────────┘
+```
+
+The suffix/prefix is **not editable** — it's a visual affordance. User types only digits.
+
+### Accepting paste
+
+User pastes `12,500.00`. The field should:
+1. Strip non-digits except the decimal point.
+2. For KRW (no decimals), strip the decimal point and following digits.
+3. Re-format with thousands separators.
+4. Land on `12,500`.
+
+Pasting `₩12,500` or `$12.50` should work too — strip currency symbols.
+
+### Quick-amount chips
+
+For common amounts, offer chips above the input:
+
+```
+[+1만]  [+5만]  [+10만]  [+100만]
+┌─────────────────────────────┐
+│ 0                       원   │
+└─────────────────────────────┘
+```
+
+Tapping `+5만` adds 50,000 to the current value. This is universal in Korean transfer/송금 apps.
+
+### Maximum amount affordance
+
+For "send all balance" actions:
+
+```
+┌─────────────────────────────┐
+│ 1,000,000             원  ✕ │
+└─────────────────────────────┘
+잔액 ₩1,234,567   [전액 보내기]
+```
+
+The "전액" (all) button populates the full balance. Common in transfer/send-money apps.
+
+### Input mode
+
+```html
+<input type="text" inputmode="numeric" autocomplete="transaction-amount" />
+```
+
+`type="number"` is wrong for currency — strips leading zeros, rejects `,` formatting, scrolls on accidental wheel.
+
+`type="text" inputmode="numeric"` triggers the numeric keypad on mobile while letting you control formatting.
+
+For RN: `<TextInput keyboardType="number-pad" />`.
+
+### Validation timing
+
+- **On input**: format only. Don't show errors yet.
+- **On blur**: validate (min/max, balance sufficient). Show error.
+- **On submit**: re-validate, including server-side balance check.
+
+## Edge cases
+
+### Zero
+`0원` (not `₩0` for consumer; `₩0` for fintech). Don't render the amount line at all if it would be zero AND the line is decorative ("you saved ₩0 this month").
+
+### Negative balance
+Allow display, but with care:
+- `-₩5,000` (overdraft) — color `--color-money-negative`, not `--color-error`.
+- Add an explicit annotation: "마이너스 통장 사용 중" or "(overdraft)".
+
+### Very large numbers
+Beyond `999조` (999 trillion), Korean number names break down for most users. Don't try to format these prettily — it's a corner case (tax authority, central bank). Display as `1,000,000,000,000,000원` and accept readability tradeoff.
+
+### Foreign currency in Korean app
+Display the foreign amount + KRW equivalent:
+```
+$25.00 (약 ₩33,300)
+```
+- Foreign first if the source is foreign (international purchase).
+- KRW first if source is KRW (overseas trip planning, conversion display).
+- "약" (approximately) is required when the conversion is approximate.
+
+### Rounding
+- KRW: always integer. Round at the **point of computation**, not display.
+- Foreign currency display: round to the currency's natural precision (USD: 2 decimals).
+- Tax: separate line, use the country's rounding rule (Korean VAT rounds down per item but up on total — server-side concern, designer just shows the line).
+
+### Comma vs period locale issues
+A user pastes a number with `.` as thousands separator (German format, `1.234.567`). Strip and reformat.
+
+## Don't
+
+- Don't color expenses with `--color-error`. Negative ≠ error.
+- Don't show `.00` for KRW.
+- Don't use `type="number"` for currency input.
+- Don't auto-fill the suffix `원` into the value — keep the raw value as digits only.
+- Don't truncate digits silently for "very large" amounts. Display fully, accept aesthetics.
+- Don't use parentheses for negatives (`(₩12,500)`) in Korean apps. Use `-`.
+- Don't mix `원` and `₩` styles in the same product.
+- Don't right-align amounts with proportional numerals — use tabular.
+- Don't show currency conversions without "약" (approx) annotation when the rate is not real-time.
+- Don't display balance updates with disruptive animation (number-tick animation is fine; flash/shake is not).
+
+## Cross-reference
+
+- [knowledge/typography/type-scale-fundamentals.md](../typography/type-scale-fundamentals.md) — tabular numerals
+- [knowledge/colors/color-theory.md](../colors/color-theory.md) — semantic naming
+- [knowledge/i18n/korean-payments.md](../i18n/korean-payments.md) — payment-specific UX
+- [knowledge/patterns/form-design.md](form-design.md) — number input patterns

package/knowledge/patterns/onboarding.md

@@ -0,0 +1,300 @@
+<!-- hand-written -->
+---
+title: Onboarding patterns
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Onboarding patterns
+
+The user's first ~30 seconds with your product. Done well, they understand the value and complete a first action. Done badly, they bounce.
+
+## The four onboarding moments
+
+| Moment | Trigger | Goal |
+| --- | --- | --- |
+| **Account setup** | After signup, before first feature use | Account complete, profile filled, key permissions granted |
+| **First-run** | First time the app opens | Understand the value, see the core action, complete a first task |
+| **Feature discovery** | First time a feature is encountered | Understand what this feature does without leaving the screen |
+| **Re-engagement** | After absence (≥ 7 days) | Show what's new, restore context |
+
+These are NOT all "onboarding". Each needs different patterns.
+
+## When you don't need onboarding
+
+- Single-purpose tools (search engine, calculator)
+- Apps where the UI explains itself in 2 seconds
+- Returning users on familiar flows
+
+If you can show the value within 2 seconds of opening the app, **don't gate it with onboarding**. Onboarding is a tax — pay it only when necessary.
+
+## Account setup
+
+Post-signup, pre-first-use. Goal: get the minimum necessary data to make the product work for this user.
+
+### The Steve Krug rule for account setup
+
+**Cut every field that isn't immediately necessary.** You can ask for more later.
+
+| Don't ask now | Ask later |
+| --- | --- |
+| Full address (only at first checkout) | Phone number "for security" (only when 2FA setup) |
+| Birthday (unless legally required) | Profile photo (after first action) |
+| Bio / about | Notification preferences (when first relevant notification) |
+
+### Multi-step wizard
+
+For genuinely multi-step setup (e.g., onboarding to a fintech with bank connection):
+
+```
+[1. 본인인증]    [2. 계좌 연결]    [3. 카테고리 선택]    [4. 완료]
+   ●               ○                ○                    ○
+```
+
+- Progress indicator (numbered or dots).
+- Back button always available except on step 1.
+- Skip option for non-essential steps with a note ("나중에 설정")
+- Save progress between steps (localStorage).
+- Total step count visible at start ("3분 소요").
+
+Don't:
+- Don't show 8+ steps. The user thinks "ugh" at step 4.
+- Don't reset progress on back.
+- Don't make every step required for entry.
+
+### Smart defaults > asking
+
+For each field, ask: "Can I derive this instead of asking?"
+
+| Field | Derive from |
+| --- | --- |
+| Time zone | Browser / device |
+| Language | Browser locale |
+| Country | IP location (with prompt to confirm) |
+| Currency | Country (KRW for KR, USD for US) |
+| Notification frequency | Sensible default; let user adjust later |
+
+### Korean account setup
+
+Per [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md):
+
+- **Phone-first**: phone + SMS verification is the canonical primary identity.
+- **KakaoTalk login** as a one-tap shortcut (above email).
+- **Address** via Daum Postcode lookup, NOT free-form.
+- **Marketing consent** as a separate, opt-in checkbox (legal — see [`korean-publishing.md`](../i18n/korean-publishing.md)).
+- **본인인증** if required (financial / age-gated): use PASS or NICE, not roll-your-own.
+- **DOB**: ask year only when possible; full DOB when legally required.
+
+## First-run
+
+User opens the app for the first time. Goal: aha moment + first action.
+
+### The three patterns
+
+| Pattern | Best for | Friction |
+| --- | --- | --- |
+| **Activation flow** (set up demo data, walk through one task) | Productivity, content tools | Medium |
+| **Empty state with prompt** (drop into the main UI, empty state shows the path) | Most consumer apps | Low |
+| **Tour with overlays** (highlights UI elements one at a time) | Complex products with non-obvious UI | High |
+
+**Pick the lowest-friction pattern that achieves the goal.** Tours are the highest tax — use only when the UI genuinely needs explaining and an empty-state CTA can't carry the weight.
+
+### Activation flow
+
+For tools where the user genuinely needs setup before they can do anything:
+
+1. Welcome screen (one screen, value prop, one CTA).
+2. Connect / configure (1–3 screens).
+3. Sample data or first action prompt.
+4. Land in the populated main UI.
+
+Don't:
+- Don't make activation a 10-screen wall.
+- Don't ask for permissions / payment before the user's seen the value.
+- Don't skip the "completed" celebration — confirm "you're all set" before dropping into the UI.
+
+### Empty state with prompt (recommended default)
+
+Drop the user into the main UI. The empty state IS the onboarding:
+
+```
+[main UI chrome — nav, header]
+┌────────────────────────────────────────┐
+│       Welcome! Let's get started.       │
+│                                          │
+│            [illustration]                │
+│                                          │
+│       Add your first transaction.        │
+│                                          │
+│           [거래 추가]                     │
+└────────────────────────────────────────┘
+```
+
+See [`empty-states.md`](empty-states.md) for the empty-state pattern. The first-time empty IS the first-run.
+
+### Tour with overlays
+
+Coachmark-style highlights pointing at UI elements:
+
+```
+[main UI in background]
+[overlay dim except a callout area]
+   ┌──────────────────┐
+   │ 1/4              │
+   │ 여기서 거래를      │
+   │ 추가할 수 있어요    │
+   │           [Next]  │
+   └──────────────────┘
+       ▼
+   [Add button]
+```
+
+Rules:
+- ≤ 5 steps. More than that, you're explaining the manual.
+- "Skip" button always available.
+- Don't dim the entire screen black — fades the user out of the product.
+- Each step focuses on **one** UI element with a clear action.
+- Don't tour features the user might never use — tour the core path.
+
+For complex products (Figma, Linear, AfterEffects), tours can run 6–8 steps but with clear "you can come back later" affordances.
+
+### The "skip" question
+
+Always allow skipping onboarding. The user has already committed to opening your app — don't make them work harder.
+
+```
+[Skip]    [Next]
+```
+
+For users who skip:
+- Drop into the empty state (which then carries the "first action" prompt).
+- Don't force the tour back onto them.
+- Optionally: a small `?` button in the header that reopens the tour.
+
+## Feature discovery (in-context)
+
+When a user encounters a feature for the first time **inside** the app:
+
+| Pattern | Use |
+| --- | --- |
+| **Inline tooltip** (one-time, dismissable) | Small affordance — "여기에서 정렬할 수 있어요" |
+| **Coachmark dot** | Indicates "new" without text until clicked |
+| **What's new banner** | Top of page, dismissable |
+| **Spotlight modal** | Major feature — dedicated screen, bigger ask |
+
+Don't:
+- Don't show 3 tooltips at once.
+- Don't auto-show on every visit. Show once, dismiss, never again.
+- Don't gate the feature behind the tooltip — let the user use it without reading.
+
+Persistence: store dismissals in user state (server-side or localStorage). A returning user shouldn't see the same coachmark forever.
+
+## Re-engagement
+
+User has been away for ≥ 7 days. They open the app. What changed?
+
+```
+┌────────────────────────────────────────┐
+│ 오랜만이에요!                            │
+│                                          │
+│ 그동안 새로 추가된 기능을 확인해 보세요.   │
+│   • 새 차트 (지난 주 추가)                │
+│   • 다크모드 지원                         │
+│                                          │
+│ [확인]                                    │
+└────────────────────────────────────────┘
+```
+
+- Brief, not a tour.
+- Optionally: restore last-viewed context ("계속하기: Aurora 프로젝트").
+- Don't force them to read every release note.
+
+For absences > 30 days:
+- Show "what's new" banner persistently for the session.
+- Optionally: re-introduce key flows that may have changed.
+
+## Sample data vs blank slate
+
+For products where the user creates content (note-taking, project management):
+
+| Approach | Pro | Con |
+| --- | --- | --- |
+| **Blank slate** | Authentic — user owns from day 1 | Empty feels intimidating |
+| **Sample data** | Demonstrates value, easy to explore | User has to delete it; "demo project" residue |
+| **Templated start** | Halfway — pre-filled structure, user adds real content | Best for productivity tools |
+
+Best practice for most consumer tools: **blank slate** with a strong empty state. The empty state's CTA is the first action.
+
+For tools where the value lives in seeing data populated (analytics, dashboards): **sample data** with clear labels ("Demo data — replace with yours").
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated         (modal / coachmark bg)
+--color-bg-overlay          (dim overlay for tour)
+--color-text-primary
+--color-primary-default     (coachmark accent, CTAs)
+--space-lg, --space-xl
+--radius-lg
+--shadow-modal              (coachmarks elevated above page)
+```
+
+## Accessibility
+
+- All onboarding content is keyboard-reachable. Tab through every step.
+- Tour overlays: focus moves into the coachmark on appearance. Escape dismisses.
+- Skip is reachable in tab order.
+- Coachmark text is announced via `role="dialog" aria-labelledby`.
+- Don't trap focus indefinitely — there must always be an escape.
+
+## Korean considerations
+
+- Polite tone ("~해 주세요") in instructions.
+- "환영합니다" / "오랜만이에요" common openers.
+- Length: Korean is more verbose; budget more vertical space.
+- Tour text typically 1–2 lines max per step.
+
+## Code example
+
+```tsx
+function App() {
+  const user = useUser();
+  const onboardingState = useOnboardingState(user.id);
+
+  if (!user.isVerified) return <AccountVerification />;
+  if (!user.isProfileComplete) return <ProfileSetupWizard />;
+
+  return (
+    <>
+      <MainApp />
+      {onboardingState.shouldShowFirstRun && (
+        <FirstRunTour onComplete={onboardingState.markFirstRunDone} onSkip={onboardingState.markFirstRunDone} />
+      )}
+      {onboardingState.unseenFeatures.map(f => (
+        <FeatureCoachmark key={f.id} feature={f} onDismiss={() => onboardingState.markFeatureSeen(f.id)} />
+      ))}
+    </>
+  );
+}
+```
+
+## Don't
+
+- Don't ask for everything upfront. Defer everything you can.
+- Don't gate the product behind multi-screen tutorials before showing value.
+- Don't show onboarding to returning users.
+- Don't tour every feature. Tour the core path; let discovery happen inline.
+- Don't auto-show notification permission prompt on app open. Wait for the moment it's relevant.
+- Don't force email verification before user can use the product (allow limited use, escalate later).
+- Don't assume the user remembers your last release. They don't.
+- Don't use marketing language during functional onboarding ("Revolutionary new way to...").
+
+## Cross-reference
+
+- [`knowledge/patterns/empty-states.md`](empty-states.md) — first-time empty IS first-run for most apps
+- [`knowledge/patterns/form-design.md`](form-design.md) — multi-step form pattern
+- [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md) — Korean account-setup expectations
+- [`knowledge/i18n/korean-publishing.md`](../i18n/korean-publishing.md) — required permission disclosures (Android)