@design-ai/cli 4.55.0

package/examples/component-qr-code.md

@@ -0,0 +1,201 @@
+# `QRCode` — spec
+
+> Citing Ant Design `QRCode`, MUI (no built-in), shadcn-ui (no built-in)
+
+## Purpose
+
+Renders a QR code from a string (URL, payment ID, contact info). Used in Korean fintech (계좌이체 QR, KakaoPay QR), authentication flows, content sharing.
+
+## Anatomy
+
+```
+┌─────────────────────┐
+│ ▣ ▢ ▣ ▢ ▢ ▣ ▢ ▣    │
+│ ▢ ▢ ▣ ▣ ▢ ▢ ▣ ▢    │
+│ ▣ ▢ ▢ ▣ ▣ ▢ ▢ ▣    │  ← QR matrix
+│ ▢ ▣ ▣ ▢ ▢ ▣ ▣ ▢    │
+│ ▣ ▢ ▣ ▢ ▣ ▢ ▣ ▢    │
+└─────────────────────┘
+       [logo]                ← optional center logo
+```
+
+## API
+
+```tsx
+<QRCode
+  value="https://app.example.com/pay/abc123"
+  size={200}
+  errorLevel="M"
+  iconSrc="/logo.png"
+  bgColor="#ffffff"
+  fgColor="#000000"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | URL or text to encode |
+| `size` | `number` | `160` | Pixel size (square) |
+| `errorLevel` | `"L" \| "M" \| "Q" \| "H"` | `"M"` | Error correction; H tolerates more damage / supports center logo better |
+| `bgColor` | `string` | `"#FFFFFF"` | |
+| `fgColor` | `string` | `"#000000"` | |
+| `iconSrc` | `string` | — | Center logo URL |
+| `iconSize` | `number` | `40` | |
+| `padding` | `number` | `16` | Quiet zone around code |
+| `loading` | `boolean` | `false` | |
+| `errorState` | `boolean` | `false` | Show error placeholder |
+
+## Error correction levels
+
+QR codes can recover from damage. Higher levels tolerate more but require more dense matrix:
+
+| Level | Recovery | Use |
+| --- | --- | --- |
+| `L` | 7% | Print, small QRs without logos |
+| `M` (default) | 15% | Most cases |
+| `Q` | 25% | Outdoor / damaged contexts |
+| `H` | 30% | Required if you put a center logo (logo replaces QR data) |
+
+## Sizes
+
+| Use | Size (px) |
+| --- | --- |
+| Inline (in a card) | 120–160 |
+| Standard | 200–240 |
+| Modal / dedicated screen | 280–320 |
+| Full-screen sharing | 400+ |
+
+Always render at integer pixel sizes (no fractional) — fractional pixels blur.
+
+## Color customization
+
+- **High contrast required**: `fg` and `bg` need ~7:1+ contrast for scanning reliability.
+- **Brand colors**: tempting but risky. Black-on-white is most reliable. If using brand color: dark navy or deep purple work; avoid yellows / pastels.
+- **Inverted (light fg on dark bg)**: scannable but less reliable on older devices.
+
+## Center logo
+
+Adding a center logo (brand mark) replaces some of the QR data. Requires error level `H` (30% recovery) for reliable scanning.
+
+```tsx
+<QRCode
+  value="..."
+  errorLevel="H"
+  iconSrc="/logo.png"
+  iconSize={size * 0.2}        // ~20% of total size
+/>
+```
+
+Don't make the logo too large — exceeds QR's recovery capacity, fails to scan.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | QR rendered |
+| Loading | Skeleton or spinner |
+| Error (failed to encode) | Placeholder + retry |
+| Refreshing | Brief fade (for time-limited QRs) |
+
+For time-limited QRs (e.g., KakaoPay session-based codes): show a countdown OR auto-refresh before expiration.
+
+## Tokens consumed
+
+```
+--color-bg-default            (default QR bg)
+--color-text-primary          (default QR fg)
+--color-bg-subtle             (loading skeleton)
+--color-error                  (error state)
+--space-md
+--radius-md                    (around the QR container, not the QR itself)
+```
+
+## Accessibility
+
+- Wrap in a labeled container: `<div role="img" aria-label="QR 코드: payment session abc123">`.
+- Provide a **text alternative** as a fallback:
+  ```tsx
+  <QRCode value={url} />
+  <p>또는 직접 방문: <a href={url}>{url}</a></p>
+  ```
+- For session-based QRs (KakaoPay, banking): provide an alternative input method (manual code entry).
+
+## Korean fintech use cases
+
+- **계좌이체 QR**: 송금자가 받는 계좌의 QR을 스캔 → 계좌번호 자동 입력
+- **결제 QR**: 사장님 화면에 QR → 손님이 KakaoPay/NaverPay로 스캔 → 결제
+- **인증 QR**: 본인인증 / 로그인 — 모바일 앱이 QR을 보여주고 데스크톱이 스캔 (또는 반대)
+- **공유 QR**: 가게 정보, 친구 추천 코드 등
+
+For 결제 QR: the QR usually encodes a session token + payment URL, refreshing every ~60s for security. Implement with `key={refreshKey}` to force re-render on refresh.
+
+## Code example
+
+```tsx
+// Static URL
+<QRCode value="https://example.com/me" size={200} />
+
+// Payment QR with logo and time limit
+function PaymentQRScreen({ session }) {
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      session.refresh();
+      setRefreshKey(k => k + 1);
+    }, 60_000);
+    return () => clearInterval(timer);
+  }, [session]);
+
+  return (
+    <div className="flex flex-col items-center">
+      <QRCode
+        key={refreshKey}
+        value={session.paymentUrl}
+        size={280}
+        errorLevel="H"
+        iconSrc="/brand.png"
+        iconSize={56}
+      />
+      <p className="text-sm text-text-secondary">
+        QR이 자동 갱신됩니다 · 60초 후 갱신
+      </p>
+      <p className="mt-2">
+        결제 금액: <strong>₩{amount.toLocaleString()}</strong>
+      </p>
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+- **Very long URL** encoded: QR matrix becomes dense. Cap to ~500 chars; for longer, shorten via your own URL shortener service.
+- **No internet** at scan time: pre-encode locally; don't rely on online encoding service.
+- **Color-blind users**: don't use red/green for QR — black or dark navy on white.
+- **Print at small size**: use error level `Q` or `H` and minimum 25mm physical size.
+- **Encoding errors**: if `value` is unencodable (rare), show fallback with the text URL plain.
+
+## Don't
+
+- Don't restyle a QR with very low contrast — defeats the purpose.
+- Don't put logo without error level `H`.
+- Don't omit text alternative — assistive tech can't read QRs.
+- Don't make the user wait > 1s for QR to render. Pre-compute when possible.
+- Don't use animated QR (rotating, color-changing). It's a static identifier — animation breaks scans.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/qr-code/`](../refs/ant-design/components/qr-code/) — `QRCode` with all options.
+- MUI: no built-in. Use libraries like `qrcode.react` or `react-qr-code`.
+- shadcn-ui: no built-in. Use libraries.
+
+Common libraries:
+- `qrcode` (Node-style, can run in browser)
+- `qrcode.react` (React component)
+- `react-qr-code` (lightweight)
+
+## Cross-reference
+
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — KakaoPay/NaverPay QR contexts
+- [`examples/component-payment-method-selector.md`](component-payment-method-selector.md) — QR as a payment option

package/examples/component-radio.md

@@ -0,0 +1,167 @@
+# `Radio` (and `RadioGroup`) — spec
+
+> Synthesized from Ant Design `Radio`, MUI `Radio`/`RadioGroup`, shadcn-ui `radio-group`. Mutually exclusive choice control. See also [`component-form-controls.md`](component-form-controls.md).
+
+## Radio vs Select
+
+> Radio for **2-5 visible options**. Select / Combobox for **6+** OR when space is constrained.
+
+| | Radio | Select |
+| --- | --- | --- |
+| All options visible | Yes | No (one at a time) |
+| Use | Few visible options; explicit choice | Many options; chosen value visible |
+| Visual | Each option as a row | Compact dropdown |
+
+## Anatomy
+
+```
+Pick payment method:
+
+○ Credit card
+●  KakaoPay
+○ Toss
+○ Bank transfer
+```
+
+## API
+
+```tsx
+<RadioGroup value={method} onValueChange={setMethod}>
+  <RadioGroup.Item value="card" id="card" />
+  <label htmlFor="card">Credit card</label>
+
+  <RadioGroup.Item value="kakao" id="kakao" />
+  <label htmlFor="kakao">KakaoPay</label>
+
+  <RadioGroup.Item value="toss" id="toss" />
+  <label htmlFor="toss">Toss</label>
+</RadioGroup>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | controlled | Selected value |
+| `defaultValue` | `string` | — | Uncontrolled initial |
+| `onValueChange` | `(value: string) => void` | — | Callback |
+| `disabled` | `boolean` | `false` | Disable all items |
+| `required` | `boolean` | `false` | One must be selected |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Unselected | Empty circle with border |
+| Selected | Filled circle with brand-color dot inside |
+| Hover | Border color shift |
+| Focus-visible | Ring around the focused item |
+| Disabled | Reduced opacity |
+
+## Layouts
+
+### Vertical (default)
+
+```
+○ Option 1
+○ Option 2
+● Option 3
+```
+
+### Horizontal
+
+```
+○ Option 1   ○ Option 2   ● Option 3
+```
+
+For 2-3 short options.
+
+### Card-style (visual-rich)
+
+```
+┌─────────────────────┐ ┌─────────────────────┐
+│ ●  KakaoPay         │ │ ○  Toss             │
+│    No fees          │ │    1.5% fee         │
+└─────────────────────┘ └─────────────────────┘
+```
+
+Whole card clickable; radio dot in corner OR replaced by border highlight.
+
+## Tokens consumed
+
+```
+--radio-bg-unchecked
+--radio-bg-checked-dot             (brand color dot inside)
+--radio-border
+--radio-border-checked
+--radio-error-border
+--radio-size                       (typically 16-20px)
+--space-sm                         (item gap)
+--motion-fast
+```
+
+## Accessibility
+
+- `RadioGroup`: `role="radiogroup"` + `aria-labelledby` (often referencing a heading).
+- `Radio.Item`: `role="radio"` + `aria-checked`.
+- Keyboard:
+  - Tab moves into the group (focuses the selected one or first if none).
+  - Arrow keys navigate within the group AND change selection.
+  - Space activates if not already activated.
+- For required: `aria-required="true"` on group; show error if no selection on submit.
+- Label every radio with linked `<label htmlFor>`.
+
+## Code example — Korean fintech payment method
+
+```tsx
+function PaymentMethodPicker({ value, onChange }: Props) {
+  return (
+    <fieldset>
+      <legend>결제 수단</legend>
+      <RadioGroup value={value} onValueChange={onChange}>
+        <div className="radio-row">
+          <RadioGroup.Item value="kakao" id="pay-kakao" />
+          <label htmlFor="pay-kakao">
+            <Image src="/kakaopay-logo.svg" alt="KakaoPay" />
+            카카오페이
+          </label>
+        </div>
+        <div className="radio-row">
+          <RadioGroup.Item value="naver" id="pay-naver" />
+          <label htmlFor="pay-naver">
+            <Image src="/naverpay-logo.svg" alt="NaverPay" />
+            네이버페이
+          </label>
+        </div>
+        <div className="radio-row">
+          <RadioGroup.Item value="toss" id="pay-toss" />
+          <label htmlFor="pay-toss">
+            <Image src="/toss-logo.svg" alt="Toss" />
+            토스페이
+          </label>
+        </div>
+      </RadioGroup>
+    </fieldset>
+  );
+}
+```
+
+## Don't
+
+- Don't use Radio for binary on/off — use Switch (immediate effect) or Checkbox (form).
+- Don't allow zero selection in a required group. Validation must catch it.
+- Don't make the visual circle smaller than 16x16. Touch target ≥ 44pt via padding.
+- Don't omit `<fieldset>` + `<legend>` for the group context.
+- Don't have only one radio in a group. That's a Checkbox or just a single button.
+
+## References
+
+- Ant: [`Radio`](../refs/ant-design/components/radio)
+- MUI: [`Radio`](../refs/mui/packages/mui-material/src/Radio)
+- shadcn-ui: [`radio-group`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/radio-group.tsx)
+- WAI-ARIA: [Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
+
+## Cross-reference
+
+- [`examples/component-form-controls.md`](component-form-controls.md) — combined with Switch + Checkbox
+- [`examples/component-checkbox.md`](component-checkbox.md)
+- [`examples/component-payment-method-selector.md`](component-payment-method-selector.md) — KR payment specialization

package/examples/component-rate.md

@@ -0,0 +1,202 @@
+# `Rate` (Rating) — spec
+
+> Citing Ant Design `Rate`, MUI `Rating`, shadcn-ui (composed)
+
+## Purpose
+
+A row of star (or other) icons for capturing or displaying a rating. Used for: product reviews, satisfaction scoring, content quality feedback.
+
+## Two distinct uses
+
+| Use | Mode | Example |
+| --- | --- | --- |
+| **Input rating** | Interactive | "Rate your experience" |
+| **Display rating** | Read-only | "4.3 ★ (1,247 reviews)" |
+
+The component is the same; the props differ. Always implement input behavior accessibly.
+
+## Anatomy
+
+```
+Input mode (hover state):
+☆ ☆ ☆ ☆ ☆           ← empty (default)
+★ ★ ★ ☆ ☆           ← user picked 3
+★ ★ ★ ⭑ ☆           ← user hovering 4 (preview)
+
+With half-star precision:
+★ ★ ⯨ ☆ ☆           ← 2.5 stars
+
+Display mode:
+★ ★ ★ ★ ⯨  4.5     (1,247)
+
+Other shapes:
+😡 😞 😐 🙂 😍     emoji-based scale
+👎 👍               binary
+1 2 3 4 5          numeric scale (NPS-style 0-10 also)
+```
+
+## API
+
+```tsx
+<Rate value={rating} onValueChange={setRating} />
+<Rate value={4.3} readOnly count={5} />
+<Rate value={3} max={10} />     {/* 10-point scale */}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number` | `0` | Current value |
+| `onValueChange` | `(value: number) => void` | — | (Input mode only) |
+| `defaultValue` | `number` | — | Uncontrolled |
+| `count` | `number` | `5` | Number of icons (rating max) |
+| `precision` | `number` | `1` | Smallest increment (0.5 for half-star, 0.1 for finer) |
+| `readOnly` | `boolean` | `false` | Display only — no hover/click |
+| `disabled` | `boolean` | `false` | |
+| `allowClear` | `boolean` | `true` | Click on the active value to clear (input mode only) |
+| `icon` | `ReactNode \| ((index, value) => ReactNode)` | star | Custom icon |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `label` | `string` | — | Accessible label |
+| `tooltips` | `string[]` | — | Per-rating tooltip ("나쁨", "보통", "좋음", "아주 좋음", "최고") |
+
+## Sizes
+
+| Size | Icon size |
+| --- | --- |
+| `sm` | 16px |
+| `md` (default) | 20px |
+| `lg` | 28px |
+
+For input mode on mobile: `lg`. The hit area extends ~8px around each icon.
+
+## Behavior
+
+### Input mode
+
+- Hover over an icon: preview that rating (and lower stars filled).
+- Click: commit value.
+- If `allowClear`: clicking on the currently-selected icon clears.
+- Half-star: clicking the left half of an icon = `n - 0.5`, right half = `n`.
+
+### Display mode
+
+- Renders the value as filled icons (with partial fill for fractional values).
+- No hover effects.
+- Often paired with numeric value + count.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty | All icons in `--color-text-tertiary` |
+| Hovered | Preview rating in primary or yellow |
+| Selected | Filled icons in `--color-warning` (yellow stars) or brand color |
+| Half | Filled half + empty half |
+| Disabled | Muted, no events |
+| Read-only | Non-interactive, no hover |
+
+## Tokens consumed
+
+```
+--color-warning             (default star color — yellow)
+OR
+--color-primary-default     (when brand-aligned)
+--color-text-tertiary       (empty icons)
+--color-text-secondary      (numeric value beside)
+--color-focus-ring
+--space-xs
+--motion-fast               (hover transition)
+```
+
+## Accessibility — WAI-ARIA Slider pattern (input)
+
+For input mode, use `role="slider"`:
+
+- `role="slider"`
+- `aria-valuenow={value}`
+- `aria-valuemin={0}`
+- `aria-valuemax={count}`
+- `aria-valuetext={tooltip[value-1]}` if tooltips defined (more descriptive than just the number)
+- `aria-label="Rating"`
+- `tabIndex={0}` to be keyboard-reachable
+
+For display mode (readOnly):
+- `aria-label="Rating: 4.3 out of 5"`
+- No interactive role needed — it's text equivalent
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach the rating control (single tab stop) |
+| `←` / `↓` | Decrement by `precision` |
+| `→` / `↑` | Increment by `precision` |
+| `Home` | 0 |
+| `End` | max |
+| `Enter` (with focus) | (no-op or commit, depending on UX) |
+| `Esc` | (Input form context) cancel |
+| `0`–`9` | Jump to that rating value |
+
+## Code example
+
+```tsx
+// Standard 5-star input with tooltips
+<Rate
+  value={rating}
+  onValueChange={setRating}
+  tooltips={["나쁨", "보통", "좋음", "아주 좋음", "최고"]}
+  label="만족도"
+  size="lg"
+/>
+
+// Half-star precision
+<Rate value={rating} onValueChange={setRating} precision={0.5} />
+
+// Display mode with details
+<div className="flex items-center gap-2">
+  <Rate value={4.3} readOnly />
+  <span className="font-medium">4.3</span>
+  <span className="text-text-secondary">(1,247 리뷰)</span>
+</div>
+
+// Custom icon (heart for favorite)
+<Rate value={1} count={1} icon={(i, v) => v === 0 ? <HeartIcon /> : <HeartFilled />} />
+
+// Emoji-based satisfaction
+<Rate
+  value={mood}
+  onValueChange={setMood}
+  count={5}
+  icon={(i, v) => <span>{["😡", "😞", "😐", "🙂", "😍"][i]}</span>}
+  tooltips={["아주 별로", "별로", "보통", "좋음", "최고"]}
+/>
+```
+
+## Edge cases
+
+- **Fractional displays**: `value=4.3` renders 4 full + a partial 5th. CSS clip-path or width-based fill.
+- **Hover then click outside**: revert to actual value.
+- **`allowClear` with hover preview**: hovering the current value should NOT preview clear. Clear only on click.
+- **Touch devices**: no hover. Click-only commits. Drag-to-rate is uncommon — stick to tap.
+- **Very large counts (10+)**: stars become small/cramped. Switch to numeric input or NPS-style 0–10 number row.
+- **Required rating in form**: render error state if value=0 on submit.
+- **Localized labels**: tooltips ("나쁨" / "Bad") matching locale.
+
+## Don't
+
+- Don't show stars without numeric value when display mode — users want both.
+- Don't auto-submit a form on rating click.
+- Don't use 5-star for binary feedback (helpful / not helpful). Use thumbs.
+- Don't disable arrow keys — rating is a slider semantically.
+- Don't use yellow stars on yellow backgrounds. Pick a contrasting color.
+- Don't omit tooltips for input ratings — without them, the rating values are abstract.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/rate/`](../refs/ant-design/components/rate/) — `Rate` with `count`, `allowHalf`, `tooltips`, custom `character`. Most flexible.
+- MUI: [`refs/mui/packages/mui-material/src/Rating/`](../refs/mui/packages/mui-material/src/Rating/) — `Rating` with `precision`, `IconContainerComponent`, `getLabelText` for a11y. Solid impl.
+- shadcn-ui: no built-in. Compose from icons + state.
+
+## Cross-reference
+
+- [`examples/component-slider.md`](component-slider.md) — Rate is essentially a discrete-step slider
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — slider keyboard contract