@design-ai/cli 4.55.0

package/examples/component-input-otp.md

@@ -0,0 +1,271 @@
+# `InputOTP` (one-time password input) — spec
+
+> Citing Ant Design `Input.OTP`, MUI (no built-in), shadcn-ui `input-otp`
+
+## Purpose
+
+A multi-cell input for one-time passwords / verification codes. Each digit lives in its own visual cell. Used for: SMS verification, 2FA codes, app verification (KakaoTalk login auth).
+
+In Korean fintech: **mandatory** for SMS-based 본인인증 verification flows.
+
+## Anatomy
+
+```
+┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐
+│ 1│ │ 2│ │ 3│ │ 4│ │ 5│ │ 6│   ← 6-digit code (Korean SMS standard)
+└──┘ └──┘ └──┘ └──┘ └──┘ └──┘
+                                    [Resend] in 30s
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Cells | yes | One per digit, square boxes |
+| Active cell indicator | yes | Cursor / border emphasis on current input |
+| Resend button | optional | Below the input — re-request the code |
+
+## API
+
+```tsx
+<InputOTP
+  length={6}
+  value={code}
+  onValueChange={setCode}
+  onComplete={(code) => verify(code)}
+  autoFocus
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `length` | `number` | `6` | Number of cells |
+| `value` | `string` | — | Current value |
+| `onValueChange` | `(value: string) => void` | — | Fires on each cell change |
+| `onComplete` | `(value: string) => void` | — | Fires when all cells filled |
+| `autoFocus` | `boolean` | `false` | Focus first cell on mount |
+| `disabled` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | |
+| `pattern` | `"numeric" \| "alphanumeric"` | `"numeric"` | Allowed chars per cell |
+| `mask` | `boolean` | `false` | Mask digits as ` • ` (security; rare for SMS codes) |
+| `separator` | `ReactNode` | — | Visual separator after N cells (e.g., `-` after 3) |
+
+## Behavior
+
+### Per-cell typing
+
+- User types in cell 1: digit appears, focus auto-advances to cell 2.
+- Continues until all cells filled.
+- On complete: `onComplete` fires.
+
+### Backspace
+
+- Backspace in an empty cell: focus moves back, deletes previous cell's digit.
+- Backspace in a filled cell: deletes that digit, focus stays.
+
+### Paste
+
+User pastes a 6-digit code (e.g., from SMS). Distribute across cells:
+- "123456" → cells become 1, 2, 3, 4, 5, 6.
+- "12 34 56" → strip spaces, distribute.
+- "123-456" → strip non-digits, distribute.
+- Mid-paste: cursor lands on the last filled cell or after.
+
+This is the most-tested path — get it right.
+
+### Auto-fill (mobile)
+
+iOS / Android can auto-fill SMS codes from the most recent text message. Set `autoComplete="one-time-code"` on the input:
+
+```tsx
+<input
+  type="text"
+  inputMode="numeric"
+  autoComplete="one-time-code"
+  pattern="[0-9]*"
+  maxLength={1}
+/>
+```
+
+iOS reads the SMS notification, extracts the code, and offers to autofill.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty | Cells empty, first cell focus ring |
+| Active cell | Border highlighted (primary), cursor visible |
+| Filled cell | Digit visible, border default |
+| Complete | All filled; `onComplete` fired |
+| Error | All cells red border |
+| Disabled | Muted, no events |
+| Loading (verifying) | Cells dimmed, spinner overlay |
+
+## Sizes
+
+| Size | Cell | Font | Gap |
+| --- | --- | --- | --- |
+| `sm` | 32×40 | 16px | 4px |
+| `md` (default) | 40×48 | 20px | 8px |
+| `lg` | 48×56 | 24px | 12px |
+
+For mobile primary auth: `lg` is right (large touch targets, clear digits).
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-border-default       (cell border)
+--color-border-strong         (hover)
+--color-primary-default       (active cell, complete state)
+--color-text-primary
+--color-error                 (error state)
+--color-focus-ring
+--space-xs, --space-sm
+--radius-md
+--font-size-xl                (digit display)
+--font-feature-amount: 'tnum' 1   (tabular numerals — digits align)
+```
+
+## Accessibility
+
+- Container: `<fieldset>` with `<legend>` ("인증번호 입력").
+- Each cell: `<input type="text" inputMode="numeric" maxLength={1}>` with `aria-label="N번째 자리"`.
+- Group: `role="group"` for screen reader awareness.
+- Error: `role="alert"` on errorText.
+
+```html
+<fieldset>
+  <legend class="sr-only">인증번호 입력</legend>
+  <div role="group">
+    <input aria-label="1번째 자리" maxlength="1" inputmode="numeric" autocomplete="one-time-code" />
+    <input aria-label="2번째 자리" maxlength="1" inputmode="numeric" />
+    ...
+  </div>
+</fieldset>
+```
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach first cell |
+| Type digit | Auto-advance to next |
+| `Backspace` | Delete + go back |
+| `←` / `→` | Move between cells |
+| `Home` / `End` | First / last cell |
+| `Cmd+V` / `Ctrl+V` | Paste full code |
+
+## Korean SMS verification flow
+
+Standard pattern in Korean fintech / banking:
+
+1. User enters phone number.
+2. App sends SMS via vendor (NICE, KCB, Toss).
+3. SMS arrives: `[XXX 인증번호] 123456 입력해주세요.`
+4. User enters code in InputOTP.
+5. App verifies via vendor API.
+6. Either: success → proceed; OR: 3+ failures → reset.
+
+### Resend timer
+
+Always include a "재전송" (resend) button with a 30–60s cooldown:
+
+```tsx
+<div>
+  <InputOTP length={6} onComplete={verify} />
+  <ResendButton cooldown={30} onResend={requestNewCode} />
+  {/* Shows: "30초 후 재전송" → "재전송하기" after countdown */}
+</div>
+```
+
+Rate-limit re-sends server-side (max 5/hour typical).
+
+## Error states
+
+| Cause | Message |
+| --- | --- |
+| Wrong code | "인증번호가 올바르지 않습니다." |
+| Expired code | "인증번호가 만료되었습니다. 다시 발급해 주세요." |
+| Too many attempts | "인증 시도 횟수를 초과했습니다. 잠시 후 다시 시도해 주세요." |
+| Network | "네트워크 연결을 확인해 주세요." |
+
+Clear the input on error so user can re-type.
+
+## Code example
+
+```tsx
+function VerifyPhoneScreen({ phone }: Props) {
+  const [code, setCode] = useState("");
+  const [error, setError] = useState<string>();
+  const [verifying, setVerifying] = useState(false);
+  const [cooldown, setCooldown] = useCountdown(30);
+
+  const handleVerify = async (otpCode: string) => {
+    setVerifying(true);
+    try {
+      await api.verifyCode({ phone, code: otpCode });
+      navigation.navigate("Success");
+    } catch (err) {
+      setError(err.message);
+      setCode("");
+    } finally {
+      setVerifying(false);
+    }
+  };
+
+  return (
+    <Page>
+      <h1>인증번호 입력</h1>
+      <p>{phone}로 보낸 6자리 인증번호를 입력해 주세요.</p>
+
+      <InputOTP
+        length={6}
+        value={code}
+        onValueChange={setCode}
+        onComplete={handleVerify}
+        autoFocus
+        disabled={verifying}
+        errorText={error}
+      />
+
+      <Button
+        variant="link"
+        onClick={() => { resendCode(); setCooldown(30); }}
+        disabled={cooldown > 0}
+      >
+        {cooldown > 0 ? `${cooldown}초 후 재전송` : "재전송하기"}
+      </Button>
+    </Page>
+  );
+}
+```
+
+## Edge cases
+
+- **Paste includes non-digits**: filter to digits only, distribute remaining across cells.
+- **Paste shorter than length**: fill from start, leave rest empty.
+- **Paste longer than length**: take first N digits.
+- **User types fast**: each cell may flicker — make sure auto-advance doesn't skip.
+- **Auto-fill replaces manual entry**: respect user's intent — auto-fill once if user hasn't typed yet; don't override mid-typing.
+- **Lost focus**: when user dismisses keyboard then returns, focus the next empty cell.
+
+## Don't
+
+- Don't omit `autoComplete="one-time-code"` — auto-fill is a major UX win.
+- Don't allow non-digit input (unless `pattern="alphanumeric"` for special cases).
+- Don't reset entire input on error — let user just fix the wrong cells.
+- Don't skip the resend cooldown — user-initiated DoS risk.
+- Don't show the digits as plaintext in screen readers if `mask=true` was requested.
+- Don't make cells too small to tap reliably (≥ 40px on mobile).
+
+## References
+
+- Ant Design: [`refs/ant-design/components/input/`](../refs/ant-design/components/input/) — `Input.OTP`. Length, formatting, paste handling.
+- MUI: no built-in. Compose individual `<TextField>` cells.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/input-otp.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/input-otp.tsx) — wraps `input-otp` library. **Default for new projects.**
+
+## Cross-reference
+
+- [`examples/component-input.md`](component-input.md) — base Input
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — phone-first auth + 본인인증
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — payment-related verification
+- [`examples/component-biometric-gate.md`](component-biometric-gate.md) — biometric fallback path

package/examples/component-input.md

@@ -0,0 +1,213 @@
+# `Input` — spec
+
+> Status: example artifact for `component-spec-writer` skill
+> Generated by: `skills/component-spec-writer`, citing Ant Design `Input`, MUI `TextField`, shadcn-ui `input` + `label`
+
+## Purpose
+
+A single-line text input. The most-used form control. Must compose with labels, help text, and errors; must accept controlled and uncontrolled values; must clear WCAG AA in every state.
+
+## Anatomy
+
+```
+Field (the row)
+├── Label                  (above input)
+├── Input
+│   ├── [iconStart]?       prefix slot
+│   ├── input element
+│   ├── [iconEnd]?         suffix slot (status icon, clear button, password toggle, etc.)
+│   └── [addonStart/End]?  text/button addon (e.g., `https://`, `/page`)
+├── HelpText               (below — neutral hint)
+└── ErrorText              (below — replaces HelpText in error state)
+```
+
+| Part | Purpose | Required |
+| --- | --- | --- |
+| Label | What this field is | yes (visible OR `aria-label`) |
+| Input | The control | yes |
+| HelpText | Why or how (constraints, format) | optional |
+| ErrorText | What's wrong, how to fix | required when `error` |
+| iconStart/End | Icon affordance inside the field | optional |
+| addonStart/End | Text or control attached to the side | optional |
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Controlled value. |
+| `defaultValue` | `string` | — | Uncontrolled initial value. |
+| `onChange` | `(value: string, e: ChangeEvent) => void` | — | Fires per keystroke. First arg is value (most-used), event second. |
+| `onBlur` | `(e: FocusEvent) => void` | — | Fires when input loses focus. Use to trigger validation. |
+| `label` | `string \| ReactNode` | — | Visible label. If omitted, **`aria-label` is required**. |
+| `placeholder` | `string` | — | Format hint. Never the label. Disappears on input. |
+| `helpText` | `string \| ReactNode` | — | Below-field hint. Always visible until error replaces it. |
+| `errorText` | `string` | — | Below-field error. Setting non-empty implies `error={true}`. |
+| `error` | `boolean` | inferred from `errorText` | Force error styling without text. |
+| `required` | `boolean` | `false` | Marks visually + sets `aria-required`. Visible label gets `(optional)` on others. |
+| `disabled` | `boolean` | `false` | Removes interactivity. |
+| `readOnly` | `boolean` | `false` | Value visible but not editable. Different from disabled — focus/copy still work. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `type` | `"text" \| "email" \| "password" \| "tel" \| "url" \| "search"` | `"text"` | Drives mobile keyboard via native attr. |
+| `inputMode` | `HTMLAttributes['inputMode']` | derived from `type` | Override mobile keyboard. |
+| `autoComplete` | `string` | — | `"email"`, `"new-password"`, `"current-password"`, `"tel"`, etc. **Always set** for known semantic fields. |
+| `iconStart` | `ReactNode` | — | Icon inside left side of input. |
+| `iconEnd` | `ReactNode` | — | Icon inside right side. Auto-rendered for password toggle, clear button, status. |
+| `addonStart` | `ReactNode` | — | Attached element outside the input on the left (e.g., `https://`). |
+| `addonEnd` | `ReactNode` | — | Attached element outside the input on the right. |
+| `clearable` | `boolean` | `false` | Renders an `×` clear button when value is non-empty. |
+| `showPasswordToggle` | `boolean` | `true` for `type="password"` | Eye icon to show/hide. |
+| `maxLength` | `number` | — | Hard limit. If set, render counter `0/100`. |
+| `name` | `string` | — | Form name. Required for native form submission. |
+| `id` | `string` | auto-generated | Used by `<label htmlFor>`. |
+| `fullWidth` | `boolean` | `true` | Inputs default full-width within their parent. |
+
+## States
+
+| State | Trigger | Visual |
+| --- | --- | --- |
+| Default | resting | 1px border `--color-border-default`, bg `--color-bg-default` |
+| Hover | mouse-over | border `--color-border-strong` |
+| Focus-visible | keyboard tab | 2px ring `--color-focus-ring`, 2px offset; border `--color-primary-default` |
+| Filled | `value` non-empty | unchanged (don't darken) |
+| Error | `error` | border `--color-error`, focus ring `--color-error/40`, errorText shown |
+| Disabled | `disabled` | bg `--color-bg-subtle`, text `--color-text-disabled`, no border emphasis |
+| Read-only | `readOnly` | bg `--color-bg-subtle`, no border emphasis, cursor `text` |
+| Loading (async validation) | `loading` (custom prop) | spinner in iconEnd slot |
+
+## Sizes
+
+| Size | Height | Font | Padding-x | Icon size | Use |
+| --- | --- | --- | --- | --- | --- |
+| `sm` | 32px | 13px | 8px | 14px | dense forms, compact UIs |
+| `md` | 40px | 14px | 12px | 16px | default |
+| `lg` | 48px | 16px | 16px | 20px | mobile-priority forms |
+
+## Tokens consumed
+
+```
+--color-border-default
+--color-border-strong
+--color-bg-default
+--color-bg-subtle
+--color-text-primary
+--color-text-secondary
+--color-text-tertiary
+--color-text-disabled
+--color-primary-default
+--color-error
+--color-focus-ring
+--space-sm
+--space-md
+--radius-md
+--font-size-sm
+--font-size-base
+--font-size-lg
+--transition-fast
+```
+
+## Accessibility
+
+- **Semantic**: native `<input>`. Always paired with `<label>` (visible) or `aria-label`.
+- `<label htmlFor={id}>` is the strongest pattern — clicking the label focuses the input.
+- **Required**:
+  - `required` attribute (HTML).
+  - `aria-required="true"` (explicit for AT).
+  - Visible "Required" indicator (or `(optional)` on optionals — see [knowledge/patterns/form-design.md](../knowledge/patterns/form-design.md)).
+- **Error**:
+  - `aria-invalid="true"` when `error`.
+  - `aria-describedby` pointing to the error text element's id.
+  - Error text in `role="alert"` for assertive announcement, or `aria-live="polite"` for non-blocking.
+- **Help text**: `aria-describedby` pointing to the help element (in addition to error when present, both ids).
+- **Password show/hide**: the toggle button needs its own `aria-label="Show password"` / `"Hide password"`.
+- **Clear button**: `aria-label="Clear"`.
+- **Touch target**: input height ≥ 40px for mobile. `sm` (32px) is too small for touch primary forms.
+- **Keyboard**:
+  - `Tab` reaches.
+  - `Esc` clears search-type inputs (convention, not native).
+  - For comboboxes built on top of input, follow [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+- **Autofill**: `autoComplete` attribute is required for password manager and browser autofill. Skipping it is a real friction cost.
+
+## Code example
+
+```tsx
+// Default — labeled, with help text
+<Input
+  label="Email"
+  type="email"
+  placeholder="name@company.com"
+  helpText="We'll only use this for password recovery."
+  autoComplete="email"
+  value={email}
+  onChange={setEmail}
+  required
+/>
+
+// Error state
+<Input
+  label="Password"
+  type="password"
+  value={password}
+  onChange={setPassword}
+  errorText="Password must include a number."
+  autoComplete="new-password"
+  required
+/>
+
+// With icon and clearable
+<Input
+  label="Search"
+  type="search"
+  iconStart={<SearchIcon />}
+  clearable
+  value={query}
+  onChange={setQuery}
+/>
+
+// With addon (URL prefix)
+<Input
+  label="Site URL"
+  addonStart="https://"
+  placeholder="example.com"
+  value={url}
+  onChange={setUrl}
+/>
+
+// Read-only display
+<Input label="Account ID" value="acc_8f2k...3jq" readOnly />
+```
+
+## Edge cases
+
+- **Pasting overflows `maxLength`**: native truncates. Surface the behavior with the counter going red and a help-text update.
+- **`type="number"` quirks**: avoid for currency/decimals — strips leading zeros, rejects formatting, scrolls on accidental wheel. Use `type="text" inputMode="decimal"` and parse on blur.
+- **Password manager covering iconEnd**: 1Password and similar overlay over the right side of password fields. Don't put critical UI there for `type="password"`.
+- **iOS auto-zoom on font-size < 16px**: focusing an input with smaller font triggers Safari zoom. Either set `font-size: 16px` or add `<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">` (the latter is debated for a11y).
+- **RTL**: `iconStart` mirrors right, `iconEnd` mirrors left, padding swaps. Use logical CSS properties.
+- **Korean input**: IME (input method editor) generates intermediate states (조합 중). Don't validate per-keystroke during composition. Listen to `compositionstart`/`compositionend` and skip validation between them.
+
+## Don't
+
+- Don't use `placeholder` as the only label.
+- Don't make `label` the only error indicator (color alone fails contrast for color-blind users — always have `errorText`).
+- Don't disable submit until "valid" without showing why each field is invalid.
+- Don't validate on every keystroke before user has had a chance to finish typing — validate on blur for the first error, then on change after.
+- Don't mask password length with fixed-width dots — show actual length in the bullet count.
+- Don't put `iconStart` and `addonStart` together — pick one to indicate the leading affordance.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/input/`](../refs/ant-design/components/input/) — `Input`, `Input.Search`, `Input.Password`, `Input.TextArea`, `Input.Group`, `Input.OTP`. Most exhaustive split-by-purpose API.
+- MUI: [`refs/mui/packages/mui-material/src/Input/Input.tsx`](../refs/mui/packages/mui-material/src/Input/) and [`TextField/TextField.tsx`](../refs/mui/packages/mui-material/src/TextField/) — separates `Input` (raw) from `TextField` (Input + label + helper). MUI's split is cleaner conceptually.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/input.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/input.tsx) — minimal styling layer over native `<input>`. Pairs with separate `label.tsx`. Composition over configuration.
+
+API choices made:
+- **`label`/`helpText`/`errorText` as props** rather than separate components: 80% of inputs need all three; props keep usage compact. Composition (`<Field><Label/>...`) for the 20% that need finer control.
+- **`onChange(value, e)` ordering**: value-first since that's what 95% of consumers want. Event is escape hatch.
+- **`autoComplete` is documented as critical**: ant-design and shadcn don't emphasize it; skipping is a real loss for forms.
+- **`clearable` and `showPasswordToggle` as props**: ant-design has them, MUI doesn't. They're worth the surface area — every product UI re-implements them otherwise.
+
+## Cross-reference
+
+- [knowledge/patterns/form-design.md](../knowledge/patterns/form-design.md)
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md)
+- [knowledge/a11y/contrast.md](../knowledge/a11y/contrast.md)