@design-ai/cli 4.55.0

package/knowledge/patterns/information-architecture.md

@@ -0,0 +1,341 @@
+<!-- hand-written -->
+---
+title: Information architecture for documents
+applies_to: [docs, knowledge-base, technical-docs, product-docs]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Information architecture
+
+Information architecture (IA) is the structure of content. For documentation: how docs are grouped, navigated, named, cross-linked. Get IA right and users find what they need; get it wrong and they bounce to Google.
+
+## The four-types model (Diátaxis)
+
+The most useful IA framework for technical docs. Different content has different purposes:
+
+| Type | Purpose | Audience state | Example |
+| --- | --- | --- | --- |
+| **Tutorial** | Learning by doing | New user | "Build your first chart" |
+| **How-to guide** | Solving a specific problem | Experienced user with goal | "How to deploy to staging" |
+| **Reference** | Looking up specifics | Implementing | "API endpoint reference" |
+| **Explanation** | Understanding (background) | Curious / debugging | "Why we chose Kafka" |
+
+Each type has different writing style, structure, length. Mixing them in one doc confuses readers.
+
+```
+Tutorial: step-by-step, success-driven, hand-holding
+How-to: numbered list, problem→solution, no fluff
+Reference: tables, exhaustive, no narrative
+Explanation: prose, motivation, "why"
+```
+
+Most docs sites should have all four types **separated**, not interleaved.
+
+## Top-level IA — three options
+
+### A. By type (Diátaxis canonical)
+
+```
+docs/
+├── tutorials/
+├── how-to/
+├── reference/
+└── explanation/
+```
+
+Pure but rare in practice — users don't always know what type they need.
+
+### B. By topic, type within
+
+```
+docs/
+├── components/
+│   ├── overview.md            (explanation)
+│   ├── getting-started.md     (tutorial)
+│   ├── how-to-customize.md    (how-to)
+│   └── api-reference.md       (reference)
+├── tokens/
+│   └── ...
+└── workflows/
+    └── ...
+```
+
+Most common. Topic is the entry point; type is the second level.
+
+### C. By user journey
+
+```
+docs/
+├── new-here/                  (onboarding tutorials)
+├── building-with-design-ai/   (how-tos)
+├── reference/                 (everything for lookup)
+└── concepts/                  (explanations)
+```
+
+Optimized for new vs experienced split.
+
+For most projects: **(B) by topic** is the right default.
+
+## Navigation hierarchy
+
+Users navigate by:
+1. **Sidebar** — visible always, lists everything.
+2. **In-page TOC** (right rail) — current page sections.
+3. **Search** — keyword based.
+4. **Cross-links** — from one page to related.
+5. **Breadcrumbs** — show current position in hierarchy.
+
+A docs site needs **at least 3 of 5** working well.
+
+### Sidebar depth
+
+Cap at 3 levels:
+```
+✓ Components > Button > API
+✗ Components > Forms > Inputs > Text > Variants > API
+```
+
+Past 3 levels, users get lost. If your structure needs deeper: rethink categorization.
+
+### Sidebar width
+
+200–280px typical. Fixed (sticky on scroll). Collapsible on mobile.
+
+## Page anatomy — the canonical doc page
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ [logo]                                              [Search] [GitHub] │  ← top app bar
+├──────────────┬─────────────────────────────────────────┬─────────────┤
+│              │                                          │              │
+│ Components   │ # Button                                 │ ## Anatomy   │  ← right TOC
+│ ▸ Button     │ A short description of what it does.     │ ## API       │
+│ ▸ Card       │                                          │ ## States    │
+│ ▸ Input      │ ## Anatomy                               │ ## Examples  │
+│ ▸ Modal      │ [diagram]                                │ ## See also  │
+│              │                                          │              │
+│ Tokens       │ ## API                                   │              │
+│ ▸ Color      │ <prop table>                             │              │
+│ ▸ Spacing    │                                          │              │
+│              │ ## States                                │              │
+│              │ ...                                      │              │
+│              │                                          │              │
+│              │ ## See also                              │              │
+│              │ - [Card](../card)                        │              │
+│              │ - [Form](../form)                        │              │
+└──────────────┴─────────────────────────────────────────┴─────────────┘
+```
+
+| Region | Purpose |
+| --- | --- |
+| Top app bar | Brand + search + external links |
+| Sidebar (left) | Site-wide navigation |
+| Main content | The doc itself |
+| TOC (right) | Within-page navigation |
+| Footer (below content) | "See also", prev/next, edit on GitHub |
+
+## Page metadata
+
+Every doc page should have, in roughly this order:
+
+1. **Title** (h1)
+2. **Brief summary / lede** (1–2 sentences, what this is about)
+3. **Status** (stable / beta / deprecated / experimental) — if applicable
+4. **Last updated date** — small, in metadata strip
+5. **Edit on GitHub** link — for community contributions
+
+Optional:
+- Reading time estimate
+- Audience (beginner / intermediate / advanced)
+- Prerequisites
+- Related pages
+
+## Naming conventions
+
+Page URLs and titles matter for searchability + memorability:
+
+| Good | Bad |
+| --- | --- |
+| `/components/button` | `/d/c/button-comp` |
+| "Build your first chart" | "Tutorial 1" |
+| "How to deploy" | "Deployment guide" (too generic) |
+| "API: Authentication" | "Auth docs" |
+
+Rules:
+- **Lowercase, kebab-case** URLs.
+- **Verb-led titles for tutorials/how-tos** ("How to deploy", not "Deployment").
+- **Noun-led titles for reference/explanation** ("Authentication API", "Why Kafka").
+- **No version numbers in URLs** (use a separate domain or path: `v2.docs.example.com`).
+
+## Cross-linking strategy
+
+Documents shouldn't be islands. Link liberally:
+
+- **Inline links** when concept is mentioned: `...uses [tokens](../tokens) to...`
+- **See also section** at the bottom of each page: 3–5 related pages.
+- **Prerequisites** at the top: `This guide assumes familiarity with [tokens](../tokens).`
+- **Next step / Continue** at the bottom for sequential content.
+
+Don't:
+- Link the same word multiple times in a paragraph.
+- Link generic words ("the documentation says...") without context.
+- Use "click here" / "this link" — bad for accessibility (screen readers read the link text alone).
+
+## Search strategy
+
+Most users search before browse. Good search needs:
+
+- **Full-text search** of all docs (Algolia, MeiliSearch, Pagefind).
+- **Search-as-you-type** with results dropdown.
+- **Keyboard shortcut** (Cmd+K / Ctrl+K).
+- **Result preview** with matched substring highlighted.
+- **Categories** — "Component" vs "Tutorial" vs "API" labels.
+
+Cite [`knowledge/patterns/search-ux.md`](search-ux.md) for the input UX. The IA piece is what gets indexed:
+
+- All page text.
+- Page titles (highest weight).
+- Headings.
+- Code samples (sometimes — depends on if your audience searches by code).
+- Skip: nav text, footer, repeated chrome.
+
+## Versioning
+
+When the documented thing has versions (API v1 / v2, library 3.x / 4.x):
+
+| Strategy | Use |
+| --- | --- |
+| **Latest only** | When version stability is high (Stripe API). |
+| **Latest + previous** | Most common. Older versions accessible but not default. |
+| **All versions** | When users span many versions (Django). |
+
+URL strategies:
+- `docs.example.com` (latest) + `docs-v1.example.com` (legacy)
+- `docs.example.com/v2/` + `docs.example.com/v1/`
+- Banner at top of older-version pages: "You're viewing v1. v2 docs are at..."
+
+## Korean documentation
+
+Per [`knowledge/i18n/korean-document-style.md`](../i18n/korean-document-style.md):
+
+- Polite (`~합니다`) tone for technical docs.
+- Casual (`~해요`) for getting-started / tutorials in consumer-facing products.
+- Section headings in Korean, code in English (don't translate API names).
+- 영문 약어 (acronyms) typically NOT translated: "API", "URL", "JSON" stay English.
+- Long technical terms: provide Korean + English on first use, English thereafter ("애플리케이션 프로그래밍 인터페이스(API)").
+
+## Migration / refactoring IA
+
+When you rename a page:
+1. **Don't break URLs.** Add a 301 redirect from old to new.
+2. Update all internal links to the new URL.
+3. Mention the rename in the changelog.
+
+When you delete a page:
+1. Add a 301 to the closest equivalent.
+2. If no equivalent: redirect to the parent section.
+3. Don't 404 — frustrates users.
+
+When you reorganize the sidebar:
+1. Rare. Big-bang reorgs disorient users with bookmarks.
+2. If necessary: do it once, communicate clearly, accept the cost.
+3. Don't reorganize quarterly.
+
+## Templates per doc type
+
+Each Diátaxis type has a canonical template:
+
+### Tutorial template
+
+```markdown
+# Build your first <thing>
+
+> Time: 15 minutes · Audience: New users
+
+## What you'll build
+[Screenshot / GIF of the end result]
+
+## Prerequisites
+- ...
+
+## Step 1 — ...
+[do this]
+[expected result]
+
+## Step 2 — ...
+...
+
+## What's next
+- Try [related tutorial]
+- Read [reference] for full API
+```
+
+### How-to template
+
+```markdown
+# How to <verb a goal>
+
+When you need to: <use case>.
+
+## TL;DR
+[1-2 sentences with the core command/code]
+
+## Steps
+1. ...
+2. ...
+
+## Variations
+- ...
+
+## Common pitfalls
+- ...
+```
+
+### Reference template
+
+```markdown
+# <Thing> API
+
+| Method | Returns | Description |
+|---|---|---|
+| `getX()` | `X` | Get the X. |
+| `setX(v)` | void | Set the X to v. |
+
+## getX()
+### Signature
+### Parameters
+### Returns
+### Throws
+### Examples
+```
+
+### Explanation template
+
+```markdown
+# Why <design decision>
+
+## The problem
+...
+
+## What we considered
+- Option A: ...
+- Option B: ...
+
+## What we chose
+...
+
+## Tradeoffs
+...
+```
+
+Use these templates as starting points. They're not laws — adapt.
+
+## Cross-reference
+
+- [`knowledge/patterns/document-typography.md`](document-typography.md) — visual styling
+- [`knowledge/patterns/technical-writing.md`](technical-writing.md) — voice and structure
+- [`knowledge/patterns/search-ux.md`](search-ux.md) — search input pattern
+- [`knowledge/i18n/korean-document-style.md`](../i18n/korean-document-style.md)
+- [Diátaxis framework](https://diataxis.fr/) (the canonical reference)

package/knowledge/patterns/landing-hero-design.md

@@ -0,0 +1,283 @@
+<!-- hand-written -->
+---
+title: Landing hero design (variants and rationale)
+applies_to: [landing, marketing, hero]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Landing hero design
+
+The hero is the first thing visitors see. It's the most-iterated section on any product website and the highest-leverage design surface. This file covers variants, rationale, and decision rules.
+
+For the component spec: [`examples/component-hero-block.md`](../../examples/component-hero-block.md). This file covers **strategy** — which variant to pick, what to put in the headline, when to use video.
+
+## What the hero must do
+
+In 5 seconds, a visitor must understand:
+1. **What the product does** (in their words)
+2. **Why it matters** (problem solved)
+3. **What to do next** (one obvious CTA)
+
+Failure to communicate any of these = bounce.
+
+## Six hero archetypes
+
+### 1. Text-led hero (default)
+
+```
+Headline (large)
+Sub-headline
+[CTA] [Secondary]
+
+[Hero visual on right or below]
+```
+
+When: most products. Easy to A/B test. Headline carries the message.
+
+Pros: fast to load, accessible, testable.
+Cons: less "wow factor" for brand-led products.
+
+### 2. Visual-led hero
+
+```
+[Large product screenshot / mockup]
+
+Caption underneath
+[CTA]
+```
+
+When: product is visual (design tool, photo app, dashboard product). User needs to "see" it to understand.
+
+Pros: shows the product immediately.
+Cons: harder for accessibility (alt text only); larger file → slower load.
+
+### 3. Video hero
+
+```
+[Background video — autoplay, muted, looped]
+Overlay headline + CTA
+```
+
+When: product is dynamic (productivity tool with motion, communication app, anything that "comes alive" in motion).
+
+Pros: high engagement when right.
+Cons: bandwidth, accessibility, mobile battery drain. Many users hate auto-play.
+
+### 4. Split-screen / 50-50
+
+```
+[Text / CTA]    |    [Visual]
+```
+
+When: balanced messaging — product is visual but you also have a strong tagline.
+
+### 5. Single-message brutalist
+
+```
+                  Big headline.
+                  That's it.
+
+                  [CTA]
+```
+
+Centered, minimal. Famous for: Stripe, Linear, Vercel.
+
+Pros: confident, brand-led.
+Cons: doesn't differentiate (lots of products use this now).
+
+### 6. Storyteller hero
+
+```
+Quote from a customer (large)
+"Headline"
+— Author
+
+[CTA]
+```
+
+When: testimonial-driven, social-proof central to the brand.
+
+Pros: trust on first impression.
+Cons: depends on having a great quote. Most don't.
+
+## Headline construction
+
+### The "what + how" formula
+
+```
+[What the product does], [how it differs].
+```
+
+Examples:
+- "가계부, 자동으로 채워줘요. 30개 은행 자동 연동."
+- "Slack, but for designers. Real-time canvas."
+- "Code reviews in 30 seconds. Powered by AI."
+
+### The "outcome" formula
+
+```
+[Outcome the user gets]. [Optional: scale/proof].
+```
+
+Examples:
+- "더 좋은 코드, 빨리 배포. 1만 개 팀이 사용 중."
+- "Save 4 hours a week. Trusted by 10,000+ teams."
+
+### The "transformation" formula
+
+```
+[Old way] is over. [New way] is here.
+```
+
+Examples:
+- "은행 앱 30번씩 보지 마세요. 가계부가 알아서 합니다."
+- "No more spreadsheets. Just answers."
+
+### Anti-formulas (don't)
+
+- "[Company name]. [Generic descriptor]." — "Toss. The future of finance." — content-free.
+- "Welcome to [name]" — wastes the headline.
+- "Revolutionary [thing] for the [industry]" — cliché-free zone.
+- Ironic / clever / poetic without context — confusing.
+
+### Korean-specific headlines
+
+Korean consumer apps trend toward **declarative + colloquial**:
+- "가계부, 자동으로 채워줘요" (declarative)
+- "30초 만에 가입" (factual)
+- "은행 앱은 그만!" (colloquial-imperative)
+
+Avoid direct translation from English ("Welcome to..." → "환영합니다..." reads unnatural).
+
+For B2B Korean: more formal — "팀의 생산성을 높입니다" / "AI로 더 빠르게".
+
+## Sub-headline construction
+
+The sub-headline supports the headline. ~20-30 words. One sentence.
+
+| Pattern | Example |
+| --- | --- |
+| Problem + solution | "은행 앱을 30번씩 보지 않아도 가계부가 자동으로 채워집니다." |
+| Differentiation | "수동 입력 없이, 첫 달 무료로 시작." |
+| Social proof + result | "100만 명이 매달 평균 12만 원을 절약했어요." |
+| Concrete capability | "30개 은행 자동 연동 + AI 카테고리 분류." |
+
+Cut hedging:
+- ✗ "가계부를 도와드릴 수 있습니다." (might help)
+- ✓ "가계부가 자동으로 채워집니다." (does)
+
+## CTA choice
+
+Primary CTA: 1 word verb + value proposition
+
+| Bad | Good |
+| --- | --- |
+| "Click here" | "무료 시작" |
+| "Submit" | "Pro 시작" |
+| "Sign up" | "지금 가입" |
+| "Get started" | "30일 무료 체험" |
+
+Secondary CTA: lower commitment
+
+| Pattern | Example |
+| --- | --- |
+| "Learn more" | "기능 살펴보기" |
+| "Watch demo" | "데모 보기" |
+| "Login" | "로그인" |
+| "Pricing" | "요금제 보기" |
+
+## Background choices
+
+| Style | Conversion impact (typical) |
+| --- | --- |
+| Plain white / off-white | Highest perceived trust, fastest load |
+| Subtle brand tint (5–10% saturation) | Slight brand boost, no real downside |
+| Solid brand color (full saturation) | Strong brand, but limits visual contrast |
+| Gradient | Modern feel; risk of poor text contrast |
+| Hero image (full-bleed) | Strong emotion; harder accessibility |
+| Hero video | Highest engagement; bandwidth + a11y cost |
+
+For Korean fintech: subtle tint or plain white dominates. Toss / KakaoBank style.
+
+## Video heroes — when to use
+
+Use video hero only if:
+1. Product has clear motion benefit (Linear's keyboard demo, Cron's calendar interactions).
+2. You have budget for: 4K source, multiple aspect ratios, mobile-optimized export, fallback poster image.
+3. You'll respect `prefers-reduced-motion`.
+
+Don't use video hero for:
+- Static products (form builder, CMS, etc.)
+- Mobile-primary audiences (battery drain)
+- Slow-network audiences (Korean / SEA / EMEA)
+
+If you do use video:
+- Auto-play muted only (browser policy).
+- Loop, no audio.
+- 5–15 second loop.
+- Fallback poster image for slow connections + reduced-motion.
+- Total < 5MB optimized.
+
+## Mobile considerations
+
+- Hero stacks vertically (headline + sub-headline + CTA + visual stacked).
+- Visual moves below text or hides on mobile.
+- Headline drops to 32–40px (from 48–60).
+- CTA full-width.
+- Trust signal compresses to one line.
+
+For Korean mobile: most landing traffic is mobile. Design mobile-first; desktop is the variant.
+
+## Performance
+
+Hero is above-the-fold. Performance matters disproportionately:
+
+- **LCP target**: < 2.5s (the hero visual usually IS the LCP).
+- **Image format**: WebP / AVIF, with PNG fallback.
+- **Image dimensions**: serve 2x for retina, 1x for standard. Use `srcset`.
+- **Font loading**: subset hero font; preload.
+- **No render-blocking JavaScript** above the fold.
+
+For Korean CDN: use Naver Cloud / KT CDN for KR-edge serving. AWS CloudFront's KR edge is decent but slower than Korean CDNs.
+
+## A/B testing the hero
+
+Most-tested variables:
+1. **Headline copy** (highest impact)
+2. **Primary CTA copy + color**
+3. **Hero visual** (image vs video vs illustration)
+4. **Layout** (text-left vs centered)
+5. **Background** (white vs tinted vs image)
+
+Common testing tools: Optimizely, VWO, Google Optimize (deprecated 2023, alternatives: PostHog, Mixpanel).
+
+Test with traffic ≥ 1,000 visitors / variant. Below that, statistical significance is unreliable.
+
+## Korean landing-page conventions
+
+- **Big number + benefit**: "100만 명이 사용하는 가계부" / "30초 만에 등록 완료"
+- **Trust signals dense**: stars, user count, awards stacked.
+- **Less whitespace** than Western Toss/Linear-style minimalism (some Korean B2C apps lean dense).
+- **Hangul + English mixed**: brand name in English, headline in Korean.
+- **Bottom-of-fold scroll cue** common — arrow / "더 알아보기 ↓" — Korean users scroll less than expected without the cue.
+
+## Anti-patterns
+
+- **Vague headline**: "Better way to do X" doesn't say what X is or why better.
+- **Multiple primary CTAs**: 4 buttons in the hero = nothing chosen.
+- **Hero image of people pointing at laptops**: stock-photo cliché.
+- **Auto-play video with sound**: instant unsubscribe.
+- **Hero CTA doesn't lead to product**: clicks land on a marketing form.
+- **Headline in image, not text**: bad for SEO + screen readers + responsive.
+- **Background video without poster fallback**: blank screen on slow networks.
+- **CTA below the fold**: most users won't scroll.
+
+## Cross-reference
+
+- [`examples/component-hero-block.md`](../../examples/component-hero-block.md) — component spec
+- [`knowledge/patterns/landing-page-patterns.md`](landing-page-patterns.md) — full landing structure
+- [`knowledge/patterns/brand-identity.md`](brand-identity.md) — voice + visual brand
+- [`knowledge/patterns/pricing-page-design.md`](pricing-page-design.md) — pricing on landing
+- [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md) — Korean design conventions