@design-ai/cli 4.55.0

package/examples/component-alert-title.md

@@ -0,0 +1,77 @@
+# `AlertTitle` — spec
+
+> Synthesized from MUI `AlertTitle`. The header line inside an `Alert`. Use for alerts with both a short title and a longer body — without it, the alert just shows a one-line message.
+
+## When to use
+
+- Multi-line alerts where the first line is a summary and the rest is detail.
+- Alerts that need a strong visual hierarchy ("Something went wrong" + paragraph of detail).
+
+## When NOT to use
+
+- One-line alerts → just use `<Alert>` with text content.
+
+## API
+
+```tsx
+<Alert severity="error">
+  <AlertTitle>저장에 실패했어요</AlertTitle>
+  네트워크 연결을 확인하고 다시 시도해 주세요. 문제가 계속되면{' '}
+  <Link href="/help">도움말</Link>을 참고하세요.
+</Alert>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Title text |
+
+Extends `Typography` — typography props work.
+
+## Tokens consumed
+
+```
+--font-size-heading-sm     /* 16px */
+--font-weight-semibold
+--space-xs                 /* margin-bottom to body */
+```
+
+## Accessibility
+
+- Renders inside the Alert's accessible region.
+- For severity changes, the title color follows (error red, warning amber, etc.).
+- Don't omit the title for severity-error multi-paragraph alerts — title gives quick scan.
+
+## Edge cases
+
+- **Korean honorific** — match the alert severity. Error: 합쇼체 ("저장에 실패하셨습니다"). Info: 해요체 ("저장됐어요").
+- **Long titles** — wrap; for ellipsis, use `noWrap` on Typography.
+
+## Code example
+
+```tsx
+<Alert
+  severity="warning"
+  action={
+    <Button color="inherit" size="small" onClick={handleDismiss}>
+      닫기
+    </Button>
+  }
+>
+  <AlertTitle>저장하지 않은 변경사항이 있어요</AlertTitle>
+  페이지를 떠나면 변경사항이 사라져요. 저장하시겠어요?
+</Alert>
+```
+
+## Don't
+
+- Don't use for one-liner alerts.
+- Don't put interactive elements inside the title — they belong in `action`.
+
+## References
+
+- MUI: [`AlertTitle`](../refs/mui/packages/mui-material/src/AlertTitle/)
+
+## Cross-reference
+
+- [`component-alert.md`](component-alert.md)
+- [`component-snackbar.md`](component-snackbar.md)

package/examples/component-alert.md

@@ -0,0 +1,192 @@
+# `Alert` (Banner) — spec
+
+> Citing Ant Design `Alert`, MUI `Alert`, shadcn-ui `alert`. Different from Toast — Alert is **persistent and inline**, Toast is **transient and floating**.
+
+## Purpose
+
+A persistent in-page message: status info, warnings, errors that the user must see and may need to act on. Sticks until dismissed or until the underlying state changes.
+
+## When Alert vs Toast vs Modal
+
+| Use | Why |
+| --- | --- |
+| **Alert** | The state persists. The user sees it on every render. Inline in the page. |
+| **Toast** | The state is momentary. Auto-dismisses. Floating. |
+| **Modal** | The user must respond before continuing. Blocks interaction. |
+| **InlineError** (form-level) | Single field validation — use form's ErrorText, not Alert. |
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ [icon]  Title                                          [✕]   │
+│         Description (optional)                                │
+│                                                              │
+│         [primary action]  [secondary]                        │  ← actions row (optional)
+└──────────────────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Intent icon | usually | Matches intent: ℹ ✓ ⚠ ✕ — provides redundant cue beyond color |
+| Title | yes | The message; ≤ 80 chars |
+| Description | optional | Detail or remediation hint |
+| Actions | optional | 1–2 buttons (e.g., "Retry", "Learn more") |
+| Close button | optional (always for `error`) | ✕ in top-right |
+
+## API
+
+```tsx
+<Alert
+  intent="warning"
+  title="구독 만료가 임박했습니다"
+  description="2026년 6월 1일까지 결제 정보를 업데이트해 주세요."
+  actions={[
+    { label: "결제 정보 업데이트", onClick: handleUpdate, intent: "primary" },
+    { label: "나중에", onClick: dismiss, variant: "ghost" },
+  ]}
+  dismissible
+  onDismiss={handleDismiss}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intent` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Sets icon + color + ARIA role |
+| `title` | `string \| ReactNode` | — | Required. The message. |
+| `description` | `string \| ReactNode` | — | Detail line(s). |
+| `actions` | `Action[]` | — | Up to 2 buttons. |
+| `dismissible` | `boolean` | `false` | Show ✕ |
+| `onDismiss` | `() => void` | — | Called on dismiss |
+| `iconStart` | `ReactNode` | derived from intent | Override the intent icon |
+| `variant` | `"subtle" \| "outlined" \| "solid"` | `"subtle"` | Visual emphasis |
+
+## Variants — `variant`
+
+| Variant | Background | Border | Use |
+| --- | --- | --- | --- |
+| `subtle` (default) | `--color-<intent>-subtle-bg` | none | In-page, low-emphasis |
+| `outlined` | `--color-bg-default` | `1px --color-<intent>` | Light pages, when subtle bg blends |
+| `solid` | `--color-<intent>` | none | High-emphasis, full-bleed banners |
+
+`subtle` is the right default for 90% of cases. `solid` is for marketing announcements (top-of-page promo banner).
+
+## Intent → token mapping
+
+| Intent | Icon | Subtle bg | Border / solid bg | Title color (subtle) |
+| --- | --- | --- | --- | --- |
+| `info` | ℹ | `--color-info-subtle-bg` | `--color-info` | `--color-text-primary` |
+| `success` | ✓ | `--color-success-subtle-bg` | `--color-success` | `--color-text-primary` |
+| `warning` | ⚠ | `--color-warning-subtle-bg` | `--color-warning` | `--color-text-primary` |
+| `error` | ✕ | `--color-error-subtle-bg` | `--color-error` | `--color-text-primary` |
+
+For `solid` variant: title and body text become white (or near-black for warning's amber, where contrast inverts).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | resting |
+| Action hovered | nested Button states |
+| Dismissed | unmount with 150ms fade-out |
+
+Alerts don't have hover/active themselves — only their nested actions do.
+
+## Tokens consumed
+
+```
+--color-info, --color-info-subtle-bg
+--color-success, --color-success-subtle-bg
+--color-warning, --color-warning-subtle-bg
+--color-error, --color-error-subtle-bg
+--color-text-primary
+--color-text-secondary
+--color-bg-default
+--space-md, --space-base
+--radius-md
+--font-size-sm, --font-size-base
+--font-weight-medium
+```
+
+## Accessibility
+
+- **Role**:
+  - `role="alert"` for `error` intent — assertive, interrupts screen reader.
+  - `role="status"` for `info` / `success` / `warning` — polite.
+- **`aria-live`** matches role implicitly; explicit on the container is fine.
+- **Live region timing**: if the alert is mounted on page load (not in response to action), wrap in a `<div aria-live="off">` initially, then update to live after first paint — otherwise screen readers announce immediately on mount which is jarring.
+- **Dismiss button**: `aria-label="Dismiss alert"`. Focus returns to a logical neighbor (or the next focusable element after the alert) on dismiss.
+- **Color is not the only signal**: every alert has the intent icon — color-blind users see the icon.
+- **For interactive alerts** (with action buttons): they are NOT modals — page content remains tab-reachable around them.
+
+## Code example
+
+```tsx
+// Simple info banner at top of page
+<Alert intent="info" title="새 기능이 추가되었습니다" description="대시보드에서 새 차트를 확인하세요." dismissible />
+
+// Error with retry
+<Alert
+  intent="error"
+  title="저장에 실패했습니다"
+  description="네트워크 연결을 확인하고 다시 시도해 주세요."
+  actions={[
+    { label: "다시 시도", onClick: retry, intent: "primary" },
+  ]}
+/>
+
+// Warning with dismiss
+<Alert
+  intent="warning"
+  title="계정 보안 경고"
+  description="새로운 기기에서 로그인이 감지되었습니다."
+  actions={[
+    { label: "확인하기", onClick: review },
+  ]}
+  dismissible
+/>
+
+// Solid promotional banner (top of page, full-width)
+<Alert
+  intent="info"
+  variant="solid"
+  title="🎉 신규 가입 시 50% 할인"
+  description="6월 30일까지 한정"
+  actions={[{ label: "자세히 보기", onClick: nav }]}
+/>
+```
+
+## Edge cases
+
+- **Multiple alerts stacked**: order by severity (error → warning → info → success). Don't show 5+ alerts simultaneously — collapse to a summary.
+- **Alert with no dismiss + no actions**: legitimate but rare. Make sure the underlying state changes will eventually remove the alert.
+- **Alert that's also a link**: avoid making the entire alert clickable. If it has navigation, use an explicit action button.
+- **Long description that wraps**: title-then-description layout still works; align icon + dismiss to the top, not center.
+- **Inside a modal**: the modal already has assertive-context; Alert inside should use `role="status"` (not `alert`) to avoid double-announcing.
+- **RTL**: dismiss flips to left, actions flow RTL, padding swaps via logical CSS.
+
+## Don't
+
+- Don't use Alert for transient feedback ("Saved!"). Use a Toast — Alert sticks around until dismissed.
+- Don't use Alert for form-field errors. Forms have their own ErrorText.
+- Don't auto-dismiss errors after a timeout. They're persistent on purpose.
+- Don't put more than 2 actions in an Alert. If there are 3+ paths, the choice is a Modal.
+- Don't use solid variant inside a card or section — too punchy. Reserve solid for full-bleed banners.
+- Don't ship Alert with no icon AND color-only intent — fails for color-blind users. Always include the icon.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/alert/`](../refs/ant-design/components/alert/) — `Alert`, `Alert.ErrorBoundary`. Supports `closable`, `banner` variant, `showIcon`, `action`. Has a "banner" mode for full-width top banners.
+- MUI: [`refs/mui/packages/mui-material/src/Alert/`](../refs/mui/packages/mui-material/src/Alert/) — `Alert` + `AlertTitle`. Variants: `standard` (subtle), `filled` (solid), `outlined`. Closest to this spec.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/alert.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/alert.tsx) — primitive (`Alert`, `AlertTitle`, `AlertDescription`). Composition; intent via className variant.
+
+API choices made:
+- **`actions` array prop** rather than children-only: 80% of alerts with actions need exactly 1–2 buttons; the prop is faster than composing.
+- **`variant` (subtle / outlined / solid)** matches MUI's three-tier model. Most universal.
+- **`role` derived from `intent`**: explicit only when overriding (rare).
+
+## Cross-reference
+
+- [examples/component-toast.md](component-toast.md) — transient version
+- [examples/component-modal.md](component-modal.md) — blocking version
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) — focus management on dismiss

package/examples/component-amount-input.md

@@ -0,0 +1,278 @@
+# `AmountInput` (custom) — spec
+
+> Status: example artifact for **custom components** — not derived from Ant/MUI/shadcn. This is the kind of spec the system produces for product-specific components that don't exist upstream.
+>
+> Cited knowledge: [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md), [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md), [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md)
+
+## Purpose
+
+A specialized text input for entering currency amounts — the most-used input in any fintech / 가계부 / e-commerce product. Critical to get right because:
+
+- Auto-formatting must not break caret position.
+- Pasting and IME composition must work cleanly.
+- Korean conventions differ from Latin (no decimals for KRW, suffix `원` vs prefix `₩`, comma separator).
+- Validation (positive only, balance ceiling, max amount) is per-context.
+
+This is **not a Slider, not a stepper** — it's a text input optimized for amounts.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│  1,234,567                          원   │   ← suffix style (consumer)
+└─────────────────────────────────────────┘
+
+┌─────────────────────────────────────────┐
+│  ₩    1,234,567                          │   ← prefix style (fintech)
+└─────────────────────────────────────────┘
+
+[+1만]  [+5만]  [+10만]  [+100만]              ← optional quick chips
+┌─────────────────────────────────────────┐
+│  0                              원   ✕   │
+└─────────────────────────────────────────┘
+잔액 ₩2,500,000   [전액 사용]                 ← optional balance + max button
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Input field | yes | Numeric-only via `inputmode="numeric"` |
+| Affix (₩ prefix or 원 suffix) | yes | Decorative — visually inside the input but not editable |
+| Clear button | optional | ✕ when value > 0 |
+| Quick chips | optional | Pre-fill amounts (`+1만`, `+5만`, `+10만`, `+100만`) |
+| Max affordance | optional | "전액" / "전액 사용" — populates with full balance |
+| Balance display | optional | "잔액 ₩X" beside or below |
+| Help / error text | optional | Standard Input pattern |
+
+## API
+
+```tsx
+<AmountInput
+  value={amount}
+  onValueChange={setAmount}
+  currency="KRW"
+  affixStyle="suffix"
+  max={balance}
+  showBalance
+  balance={balance}
+  showQuickChips
+  quickChipAmounts={[10000, 50000, 100000, 1000000]}
+  showMaxButton
+  errorText={amount > balance ? "잔액이 부족합니다" : undefined}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number \| null` | — | Numeric value (in smallest unit — won for KRW). |
+| `onValueChange` | `(value: number \| null) => void` | — | Numeric, not formatted string |
+| `currency` | `"KRW" \| "USD" \| "JPY" \| "EUR" \| "CNY"` | `"KRW"` | Drives format + decimal precision |
+| `affixStyle` | `"prefix" \| "suffix"` | `"suffix"` (KRW consumer) / `"prefix"` (other) | |
+| `min` | `number` | `0` | Smallest allowed |
+| `max` | `number` | — | Largest (e.g., balance) |
+| `step` | `number` | `1` (KRW) / `0.01` (USD) | Smallest increment |
+| `placeholder` | `string` | `"0"` | |
+| `showBalance` | `boolean` | `false` | Render balance below |
+| `balance` | `number` | — | The user's balance (for display + validation) |
+| `showQuickChips` | `boolean` | `false` | Render add-amount chips above |
+| `quickChipAmounts` | `number[]` | `[10000, 50000, 100000, 1000000]` (KRW) | Chip amounts (added to current value) |
+| `showMaxButton` | `boolean` | `false` | "전액 사용" affordance |
+| `disabled` / `readOnly` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | Validation state |
+| `label` / `helpText` | — | — | Inherited from Input |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `autoFocus` | `boolean` | `false` | |
+
+## Currency-driven format
+
+| Currency | Decimal | Separator | Default affix | Example |
+| --- | --- | --- | --- | --- |
+| KRW (₩) | 0 | `,` | `원` suffix (consumer) / `₩` prefix (fintech) | `1,234,567원` / `₩1,234,567` |
+| USD ($) | 2 | `,` decimal `.` | `$` prefix | `$1,234.56` |
+| JPY (¥) | 0 | `,` | `¥` prefix | `¥1,234` |
+| EUR (€) | 2 | `.` decimal `,` | `€` suffix or prefix (locale-dependent) | `1.234,56 €` |
+| CNY (¥) | 2 | `,` decimal `.` | `¥` prefix | `¥1,234.56` |
+
+Per [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md).
+
+## Behavior
+
+### Auto-format
+
+- User types `1234567` → field shows `1,234,567`. Caret position must not jump.
+- Implementation: format-on-input, with caret restored to the equivalent visual position.
+- Use `react-number-format` or similar; don't roll from scratch (caret bugs).
+
+### Pasting
+
+User pastes `12,500.00` (or `₩12,500`, or `$12.50`). The input must:
+
+1. Strip all non-digits except decimal separator.
+2. For KRW (no decimals): strip everything after the decimal too.
+3. Re-format with thousands separators.
+4. Land on `12,500`.
+
+For input mode in Korean apps, paste handling is the most common bug area — test with locale-formatted clipboard content.
+
+### Quick chips
+
+Tapping `+5만` adds 50,000 to the current value. Adds, doesn't replace:
+
+```
+Current: 12,000
+After tap on [+5만]: 62,000
+```
+
+This is canonical in Korean transfer / 송금 apps.
+
+### Max affordance
+
+For "send all balance":
+- "전액" or "전액 사용" button populates the field with the full balance.
+- Useful in transfer flows.
+- Validate that balance is fresh — don't overflow.
+
+### IME composition
+
+For Korean apps where Hangul keyboard is default:
+- Hangul keys produce non-numeric input that should be filtered.
+- Don't crash on weird character; just ignore non-digit keystrokes.
+- `inputmode="numeric"` on mobile triggers numeric keypad — bypassing Hangul entry.
+
+### Validation timing
+
+| Trigger | What |
+| --- | --- |
+| Typing | Format only. No errors yet. |
+| Blur | Validate (>= min, <= max). Show error. |
+| Quick chip | Re-validate immediately. If exceeds max, cap or show error. |
+
+For "send transfer" flows: server-side validation also runs at submit (balance might have changed).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty | Placeholder (`0`), affix in muted color |
+| Typing | Live formatting with caret preserved |
+| Filled | Value formatted, affix prominent |
+| Focus-visible | 2px ring (matches Input spec) |
+| Error | Border red, `errorText` shown |
+| Disabled | Muted, no events |
+| Over balance | Amber border + warning text "잔액이 부족합니다" |
+
+## Sizes
+
+Inherited from Input. `lg` is most common for primary amount inputs (transfer screens, payment) — large touch target + readable digits.
+
+| Size | Height | Font | Suggested affix size |
+| --- | --- | --- | --- |
+| `sm` | 32px | 14px | 13px |
+| `md` (default) | 40px | 16px | 15px |
+| `lg` | 56px | 24px (numerals) | 18px |
+
+For amounts in primary CTAs: bump font to `display` size — 28–32px tabular numerals.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-border-default
+--color-border-strong
+--color-text-primary
+--color-text-secondary       (affix when not focused)
+--color-text-tertiary
+--color-error
+--color-warning              (over-balance state)
+--color-focus-ring
+--color-primary-default      (chip active state)
+--color-primary-subtle-bg    (chip bg)
+--space-md, --space-base
+--radius-md
+--font-feature-amount: 'tnum' 1   (tabular numerals — critical)
+--font-size-base, --font-size-xl, --font-size-2xl
+--motion-fast
+```
+
+## Accessibility
+
+- Input role: standard `<input type="text" inputmode="numeric">` (not `type="number"` — see [`patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md)).
+- `aria-label` if no visible label. For a transfer screen, "Amount to send".
+- `aria-describedby` linking to balance / error / help text.
+- `aria-invalid="true"` on error.
+- For `step` semantics: not strictly needed (text input), but `aria-valuemin` / `aria-valuemax` can be added for assistive tech.
+- Quick chips and max button: standard `<button>` with `aria-label` describing what they do.
+
+## Code example
+
+```tsx
+function TransferScreen() {
+  const [amount, setAmount] = useState<number | null>(null);
+  const balance = useBalance();
+  const isOverBalance = amount && amount > balance;
+
+  return (
+    <div>
+      <AmountInput
+        label="보낼 금액"
+        value={amount}
+        onValueChange={setAmount}
+        currency="KRW"
+        affixStyle="suffix"
+        max={balance}
+        size="lg"
+        showQuickChips
+        showMaxButton
+        showBalance
+        balance={balance}
+        errorText={isOverBalance ? "잔액이 부족합니다" : undefined}
+        autoFocus
+      />
+
+      <Button
+        size="lg"
+        disabled={!amount || isOverBalance}
+        loading={isTransferring}
+        onClick={() => transfer(amount)}
+      >
+        {amount ? `${formatKRW(amount)}원 보내기` : "금액을 입력하세요"}
+      </Button>
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+- **Pasted negative**: strip the `-`. Use `min` validation, don't allow negative entry.
+- **Decimal in KRW**: strip. KRW is integer.
+- **Very large numbers** (≥ 100조 / 100 trillion): allowed but may not format prettily (Korean number names break down). Display as comma-separated digits.
+- **Amount equal to balance** (sending all): allow if `max=balance`; balance becomes 0 after.
+- **Balance changes mid-edit** (background sync updates): re-validate on next blur. Don't reset typed amount.
+- **Multi-currency conversion display**: outside this component's scope. Pair with a separate display.
+- **Max button when balance not loaded**: disable until balance arrives.
+- **Auto-fill leaves bad format**: most browsers don't autofill amount inputs. If they do, re-format on detection.
+- **0 as a valid value**: usually invalid for transfers (can't send 0). For 가계부, 0 might be valid (record a free meal). Pass `min={0}` as appropriate.
+
+## Don't
+
+- Don't use `type="number"` — strips formatting, scrolls on wheel, rejects commas.
+- Don't render the affix as an editable character.
+- Don't auto-submit on Enter without confirmation modal for transfer-type actions.
+- Don't show currency conversion approximation without "약" annotation.
+- Don't display the value formatted in a way the user didn't type (e.g., user types `100`, you display `100원`, then on blur convert to `1만`). Stay literal.
+- Don't allow negative amounts via input.
+- Don't fire validation on every keystroke. Wait for blur.
+
+## API rationale
+
+- **`value: number` (not formatted string)**: the source of truth is the integer. Formatting is presentation. Always pass numbers between AmountInput and the rest of the app.
+- **`currency` prop drives format**: avoids passing 5 separate format props (decimals, separator, affix). One declarative prop.
+- **Quick chips + max button as opt-in**: not all amount inputs need them. Form-field amount in a 가계부 receipt doesn't need quick chips.
+
+## Cross-reference
+
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — comprehensive money-display rules
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — payment UX context
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — IME composition handling
+- [`examples/component-input.md`](component-input.md) — base Input spec this extends
+- [`examples/component-form.md`](component-form.md) — form orchestration