@design-ai/cli 4.55.0

package/knowledge/patterns/error-states.md

@@ -0,0 +1,318 @@
+<!-- hand-written -->
+---
+title: Error states
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Error states
+
+Errors are the screens users see when something didn't go right. They're load-bearing: a good error keeps the user in the flow; a bad error makes them leave.
+
+## The seven kinds of error
+
+Different causes need different UIs. Don't conflate them.
+
+| Kind | Cause | UI tier | User can fix? |
+| --- | --- | --- | --- |
+| **Validation** | User input doesn't match rules | Inline (next to field) | Yes — fix input |
+| **Network / connectivity** | No internet, request failed to leave | Full-page or inline banner | Sort of — wait for connection |
+| **Server / 5xx** | Backend crashed, timeout | Full-page or banner | No — retry, escalate |
+| **Permission / 403** | User lacks access | Full-page with explanation | Maybe — request access |
+| **Not found / 404** | Resource doesn't exist | Full-page | No — navigate elsewhere |
+| **Conflict / 409** | Stale data, concurrent edit | Inline modal or banner | Yes — refresh + reapply |
+| **Quota / 429** | Rate limit, plan limit | Banner with upgrade or wait | Yes — wait or upgrade |
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│              [error icon — soft]                 │
+│                                                  │
+│         Title — what happened                    │
+│                                                  │
+│      Description — what to do (1 sentence)       │
+│                                                  │
+│           [Primary action] [Secondary]           │
+│                                                  │
+│        (Optional: Error code · contact)          │
+└──────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Icon | recommended | Matches kind. Soft, not aggressive. |
+| Title | yes | Plain language: "저장할 수 없어요" not "Error 500" |
+| Description | yes | What user can do. 1 sentence. |
+| Primary action | yes | Most likely recovery — "다시 시도", "Refresh", "Sign in" |
+| Secondary action | optional | Alternative path — "Contact support", "Go back" |
+| Error code | dev-mode only | Hide in prod unless support asks |
+
+## Copy guidelines
+
+### Tone — apologetic but not abject
+
+| Korean | English | Use |
+| --- | --- | --- |
+| "오류가 발생했어요. 다시 시도해 주세요." | "Something went wrong. Please try again." | Generic |
+| "잠시 후 다시 시도해 주세요." | "Please try again in a moment." | Server / temporary |
+| "네트워크 연결을 확인해 주세요." | "Check your network connection." | Connectivity |
+| "권한이 없습니다. 관리자에게 문의해 주세요." | "You don't have access. Contact your admin." | Permission |
+| "찾을 수 없는 페이지입니다." | "Page not found." | 404 |
+
+Don't:
+- "Oops!" — twee, content-free.
+- "Error 500" — exposing tech detail. (Optionally show small "Error code: 500" at the bottom for support reference.)
+- "Something terrible happened" — alarming.
+- "User error" — blames the user.
+
+### Error message rules
+
+1. **Specific over generic**: "Email must include @" beats "Invalid email."
+2. **Actionable**: Tell the user what to do, not just what's wrong.
+3. **Don't blame the user**: "This file is too large" is fine. "You uploaded a file that's too large" is not.
+4. **Korean tone**: polite (존댓말), end errors with `~해 주세요` or `~합니다`.
+
+## By error kind
+
+### Validation (inline)
+
+See [`patterns/form-design.md`](form-design.md) — handled at the field level, not as a separate screen.
+
+### Network / connectivity
+
+```
+┌─────────────────────────────────────────┐
+│ ⚠ 인터넷 연결이 불안정합니다             │
+│   잠시 후 다시 시도해 주세요.             │
+│                                          │
+│   [다시 시도]                            │
+└─────────────────────────────────────────┘
+```
+
+- Banner at top OR full-screen if it blocks all interaction.
+- Auto-retry with backoff (1s, 2s, 4s, 8s, then stop).
+- If user is offline (browser detects): show "오프라인 상태" banner that auto-clears when online.
+- Don't aggressive-toast every failed background request — collapse to one persistent indicator.
+
+### Server / 5xx
+
+```
+┌─────────────────────────────────────────┐
+│ ⚠ 일시적인 문제가 발생했어요              │
+│   잠시 후 다시 시도해 주세요. 문제가 계속되면 │
+│   고객센터로 문의해 주세요.                │
+│                                          │
+│   [다시 시도]   [고객센터]                │
+│                                          │
+│   Error: 500 (req: a1b2c3d4)            │  ← small, optional
+└─────────────────────────────────────────┘
+```
+
+- Include a request ID or error code (small text at bottom) so support can trace.
+- Two actions: retry + contact support.
+- For long-running operations (file upload, video processing): preserve user's work if possible. Don't blow away unsaved state on a 500.
+
+### Permission / 403
+
+```
+┌─────────────────────────────────────────┐
+│ 🔒 접근 권한이 없습니다                   │
+│    이 항목을 보려면 관리자 권한이 필요합니다.│
+│                                          │
+│   [관리자에게 권한 요청]   [돌아가기]      │
+└─────────────────────────────────────────┘
+```
+
+- Don't expose what the user **can't** see (security through obscurity).
+- Provide the path to access (request flow, support contact).
+- For SaaS multi-tenant: clarify which org/team they need access in.
+
+### Not found / 404
+
+```
+┌─────────────────────────────────────────┐
+│              [illustration: 🗺 lost]      │
+│                                          │
+│         찾을 수 없는 페이지입니다          │
+│                                          │
+│   주소를 확인하거나 홈으로 돌아가 주세요.   │
+│                                          │
+│   [홈으로]    [검색]                      │
+└─────────────────────────────────────────┘
+```
+
+- Branded 404 (use product personality for consumer apps).
+- Always offer a path forward — home, search, recent activity.
+- Don't show error code "404" prominently — describe in plain language.
+- For deep linking gone bad: detect common patterns and route helpfully ("Did you mean /projects/123?").
+
+### Conflict / 409
+
+```
+┌─────────────────────────────────────────┐
+│ ⓘ 다른 곳에서 이미 수정되었습니다          │
+│   최신 내용을 불러오고 다시 저장해 주세요.   │
+│                                          │
+│   [최신 불러오기]  [내 변경사항 보기]      │
+└─────────────────────────────────────────┘
+```
+
+- Don't silently overwrite. The user must decide.
+- For collaborative editing (Google Docs-style): merge automatically when possible; ask for choice when not.
+- Show what's in conflict if possible (your version vs theirs).
+
+### Quota / 429
+
+```
+┌─────────────────────────────────────────┐
+│ ⓘ 사용 한도에 도달했습니다                 │
+│   1시간 후 다시 사용 가능합니다.            │
+│   더 많이 사용하려면 플랜을 업그레이드하세요.│
+│                                          │
+│   [플랜 업그레이드]   [대기]               │
+└─────────────────────────────────────────┘
+```
+
+- Be specific about the limit (which? when reset?).
+- Offer upgrade path if applicable.
+- Don't block the entire UI — only the rate-limited action.
+
+## Layout
+
+| Pattern | Use |
+| --- | --- |
+| **Inline** (next to field, in card) | Validation, conflict on a specific field |
+| **Banner** (page-top strip) | Network, partial server failure, quota |
+| **Full-page replace** | 404, 500 on critical path, permission |
+| **Modal / overlay** | Conflict during save (must decide) |
+| **Toast** | Background failures with auto-recovery (rare for errors — toast is for success/info) |
+
+For mobile: prefer inline + banner over full-page modal. Full-page consumes valuable vertical space.
+
+## Recovery actions
+
+Every error needs at least one user-actionable recovery. The order of preference:
+
+1. **Retry** — when the operation can be retried (network, server)
+2. **Refresh / Reload** — when the state is stale (conflict)
+3. **Navigate elsewhere** — when the resource isn't recoverable (404, permission)
+4. **Contact support** — last resort, with context preserved
+
+Never just "OK" or "Dismiss" with no path forward.
+
+## Error code visibility
+
+| Audience | Show error code? |
+| --- | --- |
+| End users | No — plain language |
+| Internal users / admin | Yes, in dev mode |
+| Support flow | Yes — copy-to-clipboard affordance |
+
+For support handoff: render a small expandable "Technical details" section:
+```
+> Technical details
+> Code: 500
+> Request ID: a1b2c3d4-e5f6-7890
+> Timestamp: 2026-05-07 14:32:01 KST
+> [Copy details]
+```
+
+## Logging vs displaying
+
+The error message you SHOW to users is different from what you LOG to the server:
+
+- **Log everything** (stack trace, request, user ID, browser).
+- **Show only what helps the user** (cause + recovery).
+
+Don't expose stack traces or technical jargon in user-facing errors.
+
+## Tokens consumed
+
+```
+--color-error             (icon, accent border)
+--color-error-subtle-bg   (banner bg)
+--color-warning           (for 429 / quota — not full error)
+--color-text-primary      (title)
+--color-text-secondary    (description)
+--color-text-tertiary     (technical details, error code)
+--color-bg-default
+--color-bg-elevated
+--space-md, --space-base
+--radius-md
+```
+
+## Accessibility
+
+- Error containers: `role="alert"` (assertive) for blocking errors; `role="status"` (polite) for inline / banner.
+- Title is a heading (`<h2>` or appropriate).
+- Recovery action button: standard accessibility.
+- Don't auto-focus the error icon — focus the recovery button.
+- For form errors: announced via `aria-describedby` linking input to error text. See [`patterns/form-design.md`](form-design.md).
+
+## Korean considerations
+
+Per [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md):
+- Polite (존댓말) tone — "~해 주세요" / "~합니다".
+- "고객센터" (customer center) is the standard term for support.
+- Customer service hours stated when contact is the recommended action.
+- For payment errors: cite [`knowledge/i18n/korean-payments.md`](../i18n/korean-payments.md) — specific failure-mode messages.
+- 1:1 inquiry is a standard expectation: provide that path, not just email.
+
+## Code example
+
+```tsx
+function PageContent() {
+  const { data, error, retry } = useData();
+
+  if (error?.type === "404") {
+    return <NotFoundPage />;
+  }
+  if (error?.type === "permission") {
+    return <PermissionDeniedPage />;
+  }
+  if (error?.type === "network") {
+    return (
+      <Banner intent="warning">
+        <Banner.Title>인터넷 연결이 불안정합니다</Banner.Title>
+        <Banner.Description>잠시 후 다시 시도해 주세요.</Banner.Description>
+        <Banner.Action onClick={retry}>다시 시도</Banner.Action>
+      </Banner>
+    );
+  }
+  if (error) {
+    return (
+      <ErrorState
+        title="일시적인 문제가 발생했어요"
+        description="잠시 후 다시 시도해 주세요."
+        primaryAction={{ label: "다시 시도", onClick: retry }}
+        secondaryAction={{ label: "고객센터", href: "/support" }}
+        errorCode={error.code}
+        requestId={error.requestId}
+      />
+    );
+  }
+
+  return <Content data={data} />;
+}
+```
+
+## Don't
+
+- Don't show "Error 500" to end users.
+- Don't conflate empty states with errors. They're different.
+- Don't provide an "OK" button as the only action — what's "OK" about an error?
+- Don't auto-retry indefinitely without a stop.
+- Don't lose the user's work on a server error mid-action — preserve form state, draft, etc.
+- Don't expose stack traces, internal IDs without copy affordance, or English error messages in Korean apps.
+- Don't blame the user. Don't shout (no all-caps).
+- Don't pop up a modal for every minor failure. Use inline / banner where the failure happens.
+
+## Cross-reference
+
+- [`knowledge/patterns/empty-states.md`](empty-states.md) — when there's no data, but it's not an error
+- [`knowledge/patterns/form-design.md`](form-design.md) — validation errors at the field level
+- [`knowledge/i18n/korean-payments.md`](../i18n/korean-payments.md) — payment-specific error messages
+- [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md) — Korean tone

package/knowledge/patterns/form-design.md

@@ -0,0 +1,237 @@
+<!-- hand-written -->
+---
+title: Form design patterns
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Form design patterns
+
+Forms are where users do real work. Bad forms cost real conversions and real frustration. This is the floor for any form longer than two fields.
+
+## Layout
+
+### Single column over multi-column
+
+Single column is faster to fill, faster to scan, simpler on mobile. Use multi-column **only** for genuine pairs (first/last name — though for Korean, this is a single field; address line 1/2; city/state/zip).
+
+```
+✗ multi-column scattering related fields:
+  [Name      ]  [Email     ]
+  [Phone     ]  [Birthday  ]
+  [Address   ]  [Postal    ]
+
+✓ single-column logical flow:
+  [Name      ]
+  [Email     ]
+  [Phone     ]
+  [Birthday  ]
+  [Address              ]
+  [Postal   ]
+```
+
+### Label position
+
+| Position | Use |
+| --- | --- |
+| **Above the field** (default) | Always — fastest scan, accommodates long labels, RTL-safe, mobile-friendly |
+| Inline left | Only for dense desktop forms with predictable short labels (admin tools, settings) |
+| Floating label (Material) | Avoid — animation distracts, label disappears as users start typing, accessibility tooling struggles |
+| Placeholder-as-label | **Never** — vanishes on input, fails contrast, fails screen readers |
+
+For Korean labels (often longer than English), above-field is required.
+
+### Group with visual grouping, not boxes
+
+Use whitespace + section headings to group related fields. Heavy borders or shaded card backgrounds for each section make the form feel like a tax document.
+
+## Field anatomy
+
+```
+┌──────────────────────────────────┐
+│ Label                            │ ← always above
+│ ┌──────────────────────────────┐ │
+│ │ optional placeholder hint    │ │ ← shows the format, NOT the label
+│ └──────────────────────────────┘ │
+│ Help text — explains what or why │ ← grey, below
+│ ⚠ Error: be specific             │ ← red, replaces help text on error
+└──────────────────────────────────┘
+```
+
+### Required vs optional
+
+Mark **optional** with `(optional)`, not required with `*`. Reasoning: most fields in a well-designed form are required; visually marking the few exceptions is less noisy than marking the majority.
+
+```
+✓ Email
+✓ Phone (optional)
+✓ Company
+
+✗ Email *
+✗ Phone
+✗ Company *
+```
+
+For forms where most fields ARE optional (e.g., "complete your profile" type pages), reverse: mark required with `Required` text label, not `*`.
+
+`*` alone fails accessibility — screen readers read it as "asterisk", not "required". Use `aria-required="true"` plus visible text.
+
+### Help text vs placeholder
+
+| Type | Use | Example |
+| --- | --- | --- |
+| **Label** | What this field is | `Email address` |
+| **Help text** (under field) | Why or how (constraints, format hints) | `We'll only use this for password recovery.` |
+| **Placeholder** | Optional, format example only | `name@company.com` |
+| **Error** (replaces help text on error) | What's wrong, how to fix | `Email must include @` |
+
+Help text is the single most underused affordance. If you're tempted to add a tooltip — make it help text instead.
+
+## Validation
+
+### When to validate
+
+| Trigger | Use |
+| --- | --- |
+| **On blur** (after user leaves the field) | Default for most fields. Don't yell while user is typing. |
+| **On change** (every keystroke) | After the first error has shown — gives real-time feedback once user knows what's wrong. |
+| **On submit** | Always — final pass. Catches anything missed. |
+| **Async (server-side)** | Username availability, email taken, etc. Show a spinner/icon at the field, not a global loader. |
+
+**Never** validate on focus (when user lands in field) — there's no input to validate.
+
+### Error message rules
+
+1. **Be specific**: `Password must be 8+ characters` not `Invalid password`.
+2. **Be actionable**: tell them what to do, not just what's wrong. `Use a different email — this one's already registered.` is better than `Email taken`.
+3. **Don't blame**: avoid "you failed to" or "you must". `This field is required` is fine.
+4. **Korean tone**: be polite/apologetic. `이메일 형식이 올바르지 않습니다` not `잘못된 이메일`.
+5. **Position next to the field**: never just at the top. Users miss top-level error summaries on mobile.
+6. **Plus a top summary on submit-fail** (with anchor links to each field) — for users with screen readers and for forms longer than ~5 fields.
+
+### Inline success affirmation
+
+For fields with non-obvious correctness (strong password, valid coupon, available username), show a positive checkmark or message:
+
+```
+✓ Password is strong
+✓ "username123" is available
+✓ Coupon applied — 20% off
+```
+
+Use sparingly — confirming every field reads as patronizing.
+
+## Specific field types
+
+### Email
+
+- `<input type="email">` — gets correct mobile keyboard, native validation.
+- `inputmode="email"` for older browsers.
+- `autocomplete="email"` always — saves users typing it again.
+- Validate format on blur with regex, but **don't be strict** — RFC-compliant emails are weirder than your regex thinks. Better to send a verification email than to reject `user+tag@subdomain.example.co.kr`.
+
+### Password
+
+- `<input type="password">` with a **show/hide toggle** (eye icon).
+- `autocomplete="new-password"` for sign-up, `autocomplete="current-password"` for sign-in. This determines whether the password manager prompts to save vs autofill.
+- Strength meter: yes for sign-up, no for sign-in.
+- Show requirements **before** the user types, not as red errors. `Use 8+ chars with a number` listed under the field.
+- Don't mask password length. `••••••••` of fixed width regardless of actual length is harmful — users lose track.
+
+### Phone
+
+- `<input type="tel">` for mobile keyboard.
+- `inputmode="tel"`.
+- `autocomplete="tel"`.
+- Auto-format as user types: `010-1234-5678` (Korea), `(415) 555-1234` (US).
+- For international, use a country-code dropdown + national number input. Don't ask users to type `+82` manually.
+
+### Date
+
+- For dates the user knows (birthdate, expiry) — text input + format hint, OR three dropdowns. Calendar pickers are slow for known dates.
+- For dates the user is choosing (appointment, travel) — calendar picker.
+- Format: localize. Korean default `YYYY.MM.DD`, US `MM/DD/YYYY`, ISO `YYYY-MM-DD` for technical.
+
+### Address (Korea-specific)
+
+- **Always use postcode lookup** (Daum Postcode API). Never free-form.
+- Two-line address structure: 도로명/지번 (lookup) + 상세주소 (detail, free text).
+- See [knowledge/i18n/korean-product-conventions.md](../i18n/korean-product-conventions.md).
+
+### Numbers / currency
+
+- `<input type="number">` only when free integer input is fine.
+- For currency: `<input type="text" inputmode="decimal">` + format on blur. (`type="number"` strips leading zeros and rejects formatting.)
+- Show the unit (`₩`, `$`, `kg`) inside or beside the field — don't force the user to type it.
+- For Korean currency: comma-separator on display, bare on submit.
+
+### File upload
+
+- Drag-and-drop **plus** a button — both modalities. Drag-only excludes mobile.
+- Show file name and size after select. Allow remove.
+- State limits clearly **before** upload: `Max 10 MB. JPG, PNG, PDF.`
+- For images, show preview after upload.
+
+## Multi-step forms
+
+Use multi-step when:
+- Form has > 8 logically separable fields.
+- Steps have completion incentive (progressive disclosure).
+- You can save progress between steps.
+
+Don't use multi-step when:
+- All fields could fit on one page comfortably.
+- Steps are arbitrary chunks (no logical grouping).
+
+Required affordances:
+- **Progress indicator**: dots, numbered steps, or progress bar.
+- **Back button** on every step except the first.
+- **Save progress** if the form takes > 2 minutes.
+- **Don't reset** on back navigation.
+- **Allow non-linear navigation** if steps are independent.
+
+## Submit button
+
+- Action-specific label: `Create account` not `Submit`. `Send password reset email` not `Send`.
+- Always one primary submit per form. Multiple primary buttons confuse.
+- Disable while submitting (loading state).
+- After submit, show toast/banner with next-step guidance — don't just clear the form silently.
+- For destructive submits (delete, remove): require confirmation, use red intent.
+
+## Mobile considerations
+
+- All fields full-width on mobile — no left/right padding wasted.
+- Field height ≥ 44 px for tap target.
+- Spacing between fields ≥ 16 px (so the field above doesn't get accidentally tapped).
+- Use the right `inputmode` for every field — gets users the right keyboard.
+- Submit button at the bottom, sticky if form is long.
+- Avoid datepickers that take over the screen — system native is better.
+
+## Accessibility
+
+- Every field has a `<label for>` linking to its `id`. (Or `aria-labelledby` for non-label cases.)
+- Required fields: `aria-required="true"` AND visible "required" indicator.
+- Errors: `aria-invalid="true"` on the field + `aria-describedby` pointing to the error message.
+- Error messages live in `role="alert"` or `aria-live="polite"` — announced by screen reader.
+- Group related fields with `<fieldset>` and `<legend>`.
+- For multi-step: announce step changes via live region.
+- Cite [knowledge/a11y/keyboard-and-focus.md](../a11y/keyboard-and-focus.md) for keyboard handling.
+
+## Common form anti-patterns
+
+- **Reset button**: nobody wants to reset by accident; remove it.
+- **CAPTCHA at the end of a long form**: blocks valid users; use invisible reCAPTCHA or hCaptcha.
+- **Confirm-email field**: just have one. Email validation + verification covers it.
+- **Confirm-password field**: redundant if there's a show/hide toggle. Skip.
+- **Fields that aren't actually used**: cut. Every field is friction.
+- **Asking for info you can derive**: don't ask for "country" if you have IP. Don't ask for "age" if you have DOB.
+- **Soft-disabled submit until "all valid"**: confusing — users can't tell why. Better: let them click, then surface specific errors.
+- **Error summary on top of long form, no anchor links**: users have to scroll to find the field.
+
+## Cross-reference
+
+- [knowledge/patterns/ux-guidelines.md](ux-guidelines.md) — broader UX rules
+- [knowledge/i18n/korean-product-conventions.md](../i18n/korean-product-conventions.md) — Korean form expectations (phone, address, terms)
+- [knowledge/a11y/keyboard-and-focus.md](../a11y/keyboard-and-focus.md) — keyboard navigation contract