@design-ai/cli 4.55.0

package/knowledge/patterns/settings-page.md

@@ -0,0 +1,325 @@
+<!-- hand-written -->
+---
+title: Settings page patterns
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Settings page patterns
+
+A settings page is a list of toggles, choices, and links. The hard parts: organization, save behavior, and the destructive actions at the bottom.
+
+## Three layouts
+
+| Layout | Use |
+| --- | --- |
+| **Single-page list** | Mobile, simple settings (≤ 20 items) |
+| **Sidebar + content** | Desktop, complex settings (account, billing, integrations, etc.) |
+| **Tabbed** | Medium complexity — 3–5 sections, no need for sidebar |
+
+For Korean consumer mobile: **single-page list** is the convention. Settings sections separated by visual gaps; section headers small and gray.
+
+For B2B SaaS desktop: **sidebar + content** is the convention. The sidebar lists categories; clicking shifts the right panel.
+
+## Anatomy — single-page
+
+```
+[Top app bar: ← 설정]
+
+──── 계정 ────────────────────
+이름                  김민지   >
+이메일       minji@example.com >
+프로필 사진             변경  >
+
+──── 알림 ────────────────────
+푸시 알림                 ●━○
+이메일 수신                ○━●
+   알림 빈도            매일  >
+
+──── 결제 ────────────────────
+결제 수단              KB ****  >
+구독 관리                      >
+
+──── 보안 ────────────────────
+비밀번호 변경                  >
+2단계 인증                ○━●
+
+──── 기타 ────────────────────
+약관                          >
+개인정보처리방침                >
+앱 버전               v1.4.2
+
+──── ─────────────────────────
+로그아웃                  ↗
+계정 삭제                  ⚠
+```
+
+| Element | Notes |
+| --- | --- |
+| Section header | Small (12–13px), `--color-text-tertiary`, uppercase or label-style |
+| Section gap | `--space-2xl` (32px) between sections |
+| Row height | 48px mobile / 40px desktop dense |
+| Trailing chevron `>` | For drill-in (opens detail screen) |
+| Trailing toggle | For boolean settings |
+| Trailing value (e.g., "매일") | When the setting has a current value visible |
+| Destructive at bottom | Logout, delete account |
+
+## Save behavior — three patterns
+
+| Pattern | Save trigger | Use |
+| --- | --- | --- |
+| **Auto-save (per change)** | On toggle, on blur of input | Settings that are clearly individual toggles. Default for most. |
+| **Save bar** | Sticky banner appears when changes exist; user clicks Save | Multi-field forms, billing info, profile editing |
+| **Modal with confirm** | Open detail screen, edit, click Save | Complex changes (password change, payment method) |
+
+**Pick the lowest-friction pattern that's safe.**
+
+For toggles (notifications on/off): auto-save. The user expects immediate effect.
+
+For forms (display name, address): save bar. The user might tweak multiple fields before deciding.
+
+For destructive (delete account, change password): modal with explicit confirm.
+
+### Save bar
+
+```
+┌────────────────────────────────────────────────────┐
+│ Profile                                             │
+│ [name input]                                        │
+│ [email input]                                       │
+│ [bio textarea]                                      │
+│ ...                                                 │
+│                                                     │
+│ [save bar appears as soon as anything changes]      │
+└────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────┐  ← sticky bottom
+│  Unsaved changes        [Discard]    [Save]        │
+└────────────────────────────────────────────────────┘
+```
+
+- Appears when state diverges from saved.
+- Cleanly disappears after successful save (toast confirmation).
+- Disabled save button during validation errors — but tooltip explains why.
+- Discard prompt for unsaved navigation away.
+
+## Korean settings copy
+
+Standard section labels:
+
+| Korean | English |
+| --- | --- |
+| 계정 | Account |
+| 알림 | Notifications |
+| 결제 | Billing / Payments |
+| 구독 | Subscription |
+| 보안 | Security |
+| 개인정보 | Privacy |
+| 약관 | Terms |
+| 도움말 | Help |
+| 앱 정보 | About |
+| 기타 | Other |
+
+Standard row labels:
+
+| Korean | English |
+| --- | --- |
+| 비밀번호 변경 | Change password |
+| 이메일 수신 | Email notifications |
+| 푸시 알림 | Push notifications |
+| 다크 모드 | Dark mode |
+| 언어 | Language |
+| 로그아웃 | Sign out |
+| 계정 삭제 | Delete account |
+
+## Section organization — what goes where
+
+The order matters. Korean consumer apps converge on this rough order:
+
+1. **계정 (Account)** — name, email, photo, basic identity
+2. **알림 (Notifications)** — frequency, channels
+3. **결제 / 구독** — payment methods, current plan
+4. **보안** — password, 2FA, login history
+5. **앱 환경** — language, theme, density
+6. **개인정보** — data, marketing consent
+7. **기타 / 정보** — legal, about, version
+8. **위험한 액션** — sign out, delete (with separator)
+
+Don't:
+- Don't put destructive actions in the middle.
+- Don't bury security under "More" — make it a top-level section.
+- Don't combine billing + payment methods + subscription if they're different concepts.
+
+## Destructive actions at the bottom
+
+```
+──── ─────────────────────────
+로그아웃                       
+계정 삭제 ⚠ 
+```
+
+- Visual gap above (heavier divider or extra space).
+- "Log out" is neutral; "Delete account" is red (`--color-error`).
+- Both require confirmation:
+  - **Log out**: simple Yes/No modal.
+  - **Delete account**: stronger confirm — type the username, plus checkboxes for "I understand this is permanent" + "I understand my data will be deleted".
+- For data export before delete: provide an obvious "Export my data" link first.
+
+## Toggles vs drill-in
+
+| Choice | Use toggle | Use drill-in |
+| --- | --- | --- |
+| Setting has 2 values (on/off) | ✓ | — |
+| Setting has 3+ values | — | ✓ — opens a screen with radios |
+| Setting needs sub-options | — | ✓ |
+| Setting includes input field | — | ✓ |
+
+```
+✓ Push notifications              ●━○      [boolean → toggle]
+✓ Notification frequency    매일  >        [3+ values → drill-in]
+✓ Profile name              민지  >        [text input → drill-in]
+
+✗ Theme                  Light  ●━○        [3 values can't fit a toggle]
+```
+
+## Drill-in screens
+
+When a row drills into a sub-screen:
+
+```
+[← Back] Notification frequency
+
+Choose how often you want notifications:
+
+○  Real-time
+●  Daily summary
+○  Weekly summary
+○  Off
+
+[설명: ...]
+```
+
+- Use radio group for 3+ choices.
+- Use form for free-text input.
+- Save behavior: usually auto-save on selection (radio) OR save button (form).
+- Back button returns to settings list.
+
+## Mobile patterns
+
+- Settings is the canonical use case for the **bottom-tab-bar with no settings tab** — instead, settings is reached via "MY" or "More" tab → drill in.
+- Don't show settings as a top-level tab unless the app is settings-heavy.
+- Header: "← 설정" with no actions.
+- Pull-to-refresh: not applicable (settings don't refresh).
+
+## Desktop patterns — sidebar + content
+
+```
+┌──────────────┬─────────────────────────────────────────┐
+│ ⚙ 설정        │  ── 계정 ─────────────────────         │
+│              │  Profile                                │
+│ ● 계정        │  [name input]                          │
+│ ○ 알림        │  [email input]                         │
+│ ○ 결제        │  ...                                    │
+│ ○ 보안        │                                        │
+│ ○ 정보        │                                        │
+└──────────────┴─────────────────────────────────────────┘
+```
+
+- Sidebar fixed-width 200–280px.
+- Active section highlighted (full row, not just text).
+- Right panel scrolls; sidebar doesn't.
+- URL syncs to section: `/settings/account`, `/settings/notifications`. Refresh preserves.
+
+For very deep settings (organization-level, multi-tenant), nested sub-navigation in sidebar:
+
+```
+계정
+  ▾ 프로필
+    개인 정보
+    공개 설정
+  ▸ 보안
+  ▸ 결제
+```
+
+But avoid > 2 levels — that's too deep.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated         (sidebar bg, card sections)
+--color-bg-subtle           (hover, section bg)
+--color-text-primary
+--color-text-secondary       (helper text)
+--color-text-tertiary        (section labels)
+--color-text-disabled
+--color-error                (destructive)
+--color-border-default       (rows divider)
+--color-focus-ring
+--space-md, --space-base, --space-2xl
+--font-size-sm, --font-size-base
+--font-size-xs               (section labels)
+--radius-md
+```
+
+## Accessibility
+
+- Section headers: `<h2>` (or appropriate); each section a `<section>` with `aria-labelledby`.
+- Each row is keyboard-reachable. Toggles via `Space`. Drill-ins via `Enter`.
+- For drill-in rows: render as `<a href>` (web) or `<Pressable>` (RN), not just clickable divs.
+- Screen reader announces section + row label + current value.
+- Destructive actions: confirmation modal must trap focus + restore on close. See [`examples/component-modal.md`](../../examples/component-modal.md).
+- Form save bar: `aria-live="polite"` so changes announced.
+
+## Common settings page anti-patterns
+
+- **Hiding sign-out** under multiple drill-downs.
+- **No confirmation on destructive actions** (delete account in one tap).
+- **Auto-save on text inputs** (user paused typing → got saved with typo).
+- **Save button without disabled state** (user clicks save with no changes).
+- **Settings everywhere** — every page has its own settings panel. Centralize.
+- **Inconsistent toggle direction** (some "off" is left, some "off" is right).
+- **No breadcrumb on deep settings** (user lost in /settings/account/security/2fa/codes).
+- **Modal stacking** for nested settings drill-ins — should be a screen push, not a modal.
+- **Settings modal that closes on outside click** while editing — user loses unsaved input.
+
+## Code example
+
+```tsx
+function SettingsPage() {
+  return (
+    <Page>
+      <PageHeader>설정</PageHeader>
+
+      <SettingsSection title="계정">
+        <SettingsRow label="이름" value={user.name} onClick={() => nav("/settings/account/name")} />
+        <SettingsRow label="이메일" value={user.email} onClick={() => nav("/settings/account/email")} />
+      </SettingsSection>
+
+      <SettingsSection title="알림">
+        <SettingsRow label="푸시 알림" trailing={<Switch checked={notifyPush} onCheckedChange={setNotifyPush} />} />
+        <SettingsRow label="이메일 수신" trailing={<Switch checked={notifyEmail} onCheckedChange={setNotifyEmail} />} />
+        <SettingsRow label="알림 빈도" value={notifyFreq} onClick={() => nav("/settings/notifications/frequency")} />
+      </SettingsSection>
+
+      <SettingsSection title="기타">
+        <SettingsRow label="약관" onClick={() => nav("/settings/terms")} />
+        <SettingsRow label="앱 버전" trailing={<span>v{APP_VERSION}</span>} />
+      </SettingsSection>
+
+      <SettingsSection>
+        <SettingsRow label="로그아웃" onClick={() => confirmLogout()} />
+        <SettingsRow label="계정 삭제" intent="danger" onClick={() => confirmDelete()} />
+      </SettingsSection>
+    </Page>
+  );
+}
+```
+
+## Cross-reference
+
+- [`knowledge/patterns/form-design.md`](form-design.md) — when settings include forms
+- [`knowledge/patterns/mobile-navigation.md`](mobile-navigation.md) — settings inside MY tab
+- [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md) — Korean labels and conventions
+- [`examples/component-form-controls.md`](../../examples/component-form-controls.md) — Switch / Checkbox / Radio

package/knowledge/patterns/slide-deck-design.md

@@ -0,0 +1,316 @@
+<!-- hand-written -->
+---
+title: Slide deck design
+applies_to: [presentations, slide-decks, pitch-decks, conference-talks]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Slide deck design
+
+Slide decks have their own rules. They're built for **presentation in front of an audience** (not solo reading) — so layout, density, and pacing differ from documents.
+
+If your "deck" is meant to be sent as a PDF and read alone, that's a **document**, not a deck. See [`document-typography.md`](document-typography.md). Many "decks" should be docs.
+
+## Three slide-deck archetypes
+
+| Type | Use | Density |
+| --- | --- | --- |
+| **Talk deck** | Presented live, supports the speaker | Very low (1 idea per slide) |
+| **Sales / pitch deck** | Sent OR presented; persuasion + reading | Medium |
+| **Reading deck (deck-as-document)** | Read solo, structured like slides | High — but consider doc instead |
+
+Don't mix archetypes in one deck. A talk deck sent as PDF reads as confusingly sparse.
+
+## Talk deck rules — the strict ones
+
+### One idea per slide
+
+If a slide has 3 different points, it's 3 slides.
+
+### Big text
+
+Body text on slides: **24pt minimum**. From the back of a room, anything smaller is unreadable. For body content: 32–40pt.
+
+Heading: 60–96pt.
+
+### Few words
+
+Maximum **6 lines × 6 words** rule (rough). If your slide has more, you're reading slides at the audience — bad presenting.
+
+### High contrast
+
+Black on white. Or white on near-black. No gray-on-gray.
+
+### No animations except for purpose
+
+Auto-transitions, fade-ins, "flying text" — kill them all. Animations should:
+- Reveal information progressively (e.g., bullet by bullet during a build-up).
+- Show physical change (a chart updating).
+- Create surprise (rare, intentional).
+
+Default: no animation. Only add when justified.
+
+## Sales/pitch deck rules
+
+Different: this deck stands alone (sent via email) AND gets presented.
+
+### Higher density allowed
+
+Body 18–24pt is fine. Subtitle/caption 14–16pt.
+
+### Each slide self-contained
+
+Sender isn't there to explain. Each slide should communicate without the speaker.
+
+### Strong visual brand
+
+Colors, fonts, illustrations match brand. The deck IS a brand artifact.
+
+### Standard structure (SaaS pitch)
+
+```
+1. Hero — company + tagline
+2. Problem — what's broken in the world
+3. Solution — what we do
+4. Why now — market timing
+5. Product / Demo
+6. Traction — metrics, customers, growth
+7. Business model
+8. Competition / market
+9. Team
+10. Financials / Ask (for fundraising) OR pricing
+```
+
+Variations exist; this is the typical SaaS pitch deck. Keep it ≤ 12 slides for first send.
+
+## Anatomy of a great slide
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                              │
+│                                                              │
+│      Headline — what this slide says                         │  ← center-aligned, bold
+│                                                              │
+│      [Visual / chart / image — main proof]                   │
+│                                                              │
+│      Sub-text or caption (optional)                          │
+│                                                              │
+│                                                              │
+│  [logo]                                  [page #] / [N]      │  ← chrome at bottom
+└─────────────────────────────────────────────────────────────┘
+```
+
+| Slot | Use |
+| --- | --- |
+| Headline | The one thing — prose, not heading |
+| Visual | The proof — chart, image, demo screenshot |
+| Sub-text | Secondary detail (small, low-priority) |
+| Chrome | Logo + page numbers (small, persistent) |
+
+Every slide has these elements. Variation comes from layout (visual top vs left vs bottom) — but the slots are consistent.
+
+## Title-as-message
+
+Bad title (boring): "Revenue".
+Good title (the message): "Revenue tripled in Q4."
+
+The title makes the case. The chart proves it.
+
+If audience reads only the titles, they get the deck's argument. That's the goal.
+
+## Visual hierarchy
+
+Slide audiences scan in seconds. Hierarchy must be unambiguous:
+
+1. **Largest visual element wins.** If your chart is small and the heading is huge, the heading is the message. Verify intent.
+2. **Color contrast wins second.** A red number on a gray slide draws first.
+3. **Position last.** Everything else equal, top-left wins (LTR).
+
+Test: glance at slide for 2 seconds. What do you see?
+
+## Color in decks
+
+| Use | Color |
+| --- | --- |
+| Brand primary | Headlines, key callouts |
+| Neutral dark | Body text |
+| Neutral light | Background |
+| Money / status | One semantic accent (positive trend, etc.) |
+
+Cap palette at **4–6 colors** for the whole deck. More is brand chaos.
+
+For chart slides: use the chart palette rules from [`knowledge/patterns/chart-color-encoding.md`](chart-color-encoding.md).
+
+## Typography in decks
+
+| Slot | Web/screen | Print/PDF |
+| --- | --- | --- |
+| Title | 60–96pt | 36–48pt |
+| Body | 24–32pt | 14–18pt |
+| Caption | 16–20pt | 10–12pt |
+| Code (rare) | 22–28pt monospace | 12–14pt |
+
+Pick **one font**. Maybe two (heading + body if they pair). More is brand inconsistency.
+
+For Korean: Pretendard works at all sizes. Avoid mixing Hangul fonts within one deck.
+
+## Layout templates
+
+### Title slide
+
+```
+┌──────────────────────────────────────┐
+│                                       │
+│  [Big bold title]                     │
+│                                       │
+│  Subtitle / tagline                   │
+│                                       │
+│  Author · Date · Venue                │
+│                                       │
+└──────────────────────────────────────┘
+```
+
+### Section divider
+
+```
+┌──────────────────────────────────────┐
+│                                       │
+│  Part 02                              │
+│  Section name                         │
+│                                       │
+└──────────────────────────────────────┘
+```
+
+Used between major parts of the deck. Helps audience reset.
+
+### Content slide (one image, one message)
+
+```
+┌──────────────────────────────────────┐
+│ Title                                  │
+│                                       │
+│  [Large image / chart]                │
+│                                       │
+│ Caption                               │
+└──────────────────────────────────────┘
+```
+
+### Comparison slide (2-up)
+
+```
+┌──────────────────────────────────────┐
+│ Title — the comparison itself         │
+├─────────────┬───────────────────────┤
+│             │                        │
+│ Option A    │ Option B               │
+│             │                        │
+│ ✓ benefit   │ ✓ benefit              │
+│ ✓ benefit   │ ✗ drawback             │
+│             │                        │
+└─────────────┴───────────────────────┘
+```
+
+Two columns; clearly delineated. Avoid 3+ columns (cramped).
+
+### Quote slide
+
+```
+┌──────────────────────────────────────┐
+│                                       │
+│  "Quote text, large, italic or         │
+│   distinct font."                      │
+│                                       │
+│  — Attribution                        │
+│                                       │
+└──────────────────────────────────────┘
+```
+
+Used for testimonials in sales decks, framing quotes in talks.
+
+## Charts on slides
+
+| Rule | Why |
+| --- | --- |
+| **Headline tells the story** | Audience reads the headline, glances at chart for confirmation |
+| **Drop chart noise** (gridlines, redundant labels) | Slide is glance-only, less is better |
+| **Highlight the takeaway** | Color one bar / line differently to indicate "this is the point" |
+| **Single message per chart** | Don't show 5 series unless the comparison is the point |
+| **No 3D charts** | Always confusing |
+
+Cite [`knowledge/patterns/chart-color-encoding.md`](chart-color-encoding.md).
+
+## Demo / screenshot slides
+
+For product walkthroughs:
+- Screenshot fills most of the slide.
+- Annotate with arrows / circles / numbered callouts.
+- For UI demos: cover sensitive data (use placeholder).
+- Optimize image — slide PDF can balloon to 100MB if uncompressed.
+
+## Tools
+
+| Tool | Best for |
+| --- | --- |
+| **Keynote** (Mac) | Live talks, smooth animations |
+| **Google Slides** | Collaboration, real-time editing |
+| **PowerPoint** | Corporate, advanced layout |
+| **Figma Slides** | Brand-led decks with rich design |
+| **Pitch** | Sales decks, modern collaboration |
+| **Markdown → reveal.js / Slidev** | Engineer-friendly, code-heavy talks |
+
+For consistency with design-ai's design system: Figma Slides + tokens (Phase 9 Figma MCP) is the cleanest path.
+
+## Deck structure decisions
+
+### How long?
+
+| Use | Slide count |
+| --- | --- |
+| 5-min lightning talk | 8–10 slides |
+| 20-min conference talk | 15–25 slides |
+| 30-min keynote | 30–40 slides |
+| Sales pitch (sent) | 10–15 slides |
+| Investor pitch | 12 slides (Sequoia-style) or 8–10 (Y Combinator-style) |
+| Internal team review | 15–25 slides |
+
+More important than count: **rhythm**. A 30-slide deck with 10 dense slides + 20 simple slides reads better than 30 medium-density slides.
+
+### One presenter or several?
+
+Multi-presenter decks need clear handoffs. Add a "next presenter" cue between sections (a slide with the next person's name + topic).
+
+## Korean conventions
+
+Korean business decks (보고서/제안서):
+- Heavier on text than Western (Korean business context expects detail).
+- Hierarchy via numbered sections (1, 1.1, 1.1.1).
+- Polite tone (~합니다).
+- Conservative palette — corporate gray + brand color, less saturation.
+
+Korean talk decks at conferences (PyCon Korea, FEKR, etc.):
+- Lighter, more Western-style.
+- English code samples on Korean explanation slides is standard.
+
+For Korean fintech pitch decks: per Toss-style aesthetic — minimal, single primary color, lots of whitespace, big numbers.
+
+## Common deck design mistakes
+
+- **Walls of bullets** — death by PowerPoint.
+- **Reading slides verbatim** — "I'll let the slide speak for itself" is the slide's failure.
+- **Tiny text** at the back of the room.
+- **Auto-advance** — robs presenter of pacing control.
+- **Stock photography of people pointing at laptops** — instantly cliché.
+- **Pie charts with 8+ slices**.
+- **3D anything**.
+- **Slide numbers in the title** — irrelevant during the talk.
+- **Same template for every slide type** — title slide, section divider, content slide should look distinct.
+
+## Cross-reference
+
+- [`knowledge/patterns/document-typography.md`](document-typography.md) — when "deck" is actually a doc
+- [`knowledge/patterns/chart-color-encoding.md`](chart-color-encoding.md) — chart-on-slide
+- [`knowledge/patterns/information-architecture.md`](information-architecture.md) — structuring sections
+- [`knowledge/colors/color-theory.md`](../colors/color-theory.md) — palette construction
+- [`skills/slide-deck-author/PLAYBOOK.md`](../../skills/slide-deck-author/PLAYBOOK.md) — authoring skill (uses these rules)