@design-ai/cli 4.55.0

package/examples/component-form-controls.md

@@ -0,0 +1,251 @@
+# `Switch` / `Checkbox` / `Radio` — combined spec
+
+> Three sibling controls. They share patterns (binary/boolean inputs with a label) but differ in semantics. Speccing together avoids duplication.
+>
+> Citing Ant Design `Switch`/`Checkbox`/`Radio`, MUI `Switch`/`Checkbox`/`Radio`, shadcn-ui `switch`/`checkbox`/`radio-group`
+
+## Semantic difference
+
+| Control | Semantic | Use |
+| --- | --- | --- |
+| **Switch** | Apply immediately, on/off | Settings (notifications, dark mode) — change takes effect at toggle. |
+| **Checkbox** | Multi-select, deferred | Form fields, tasks, multi-select lists — user toggles, then submits. |
+| **Radio** | Single-select from a group, deferred | Pick one from N — payment method, plan tier. |
+
+**Picking the wrong one is the most common mistake.** A "subscribe to newsletter" checkbox isn't a Switch — its effect is deferred to form submit.
+
+## Anatomy — Switch
+
+```
+Off:                       On:
+┌─────────────┐            ┌─────────────┐
+│ ⚪          │            │          ⚪ │
+└─────────────┘            └─────────────┘
+gray bg                    primary bg
+```
+
+## Anatomy — Checkbox
+
+```
+Unchecked:                 Checked:                Indeterminate:
+┌────┐                     ┌────┐                  ┌────┐
+│    │                     │ ✓  │                  │ ─  │
+└────┘                     └────┘                  └────┘
+```
+
+## Anatomy — Radio
+
+```
+Unselected:                Selected:
+○                          ●
+```
+
+## API
+
+### Switch
+
+```tsx
+<Switch
+  checked={enabled}
+  onCheckedChange={setEnabled}
+  label="알림 받기"
+  description="새 메시지가 오면 푸시 알림을 보냅니다."
+  size="md"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` / `defaultChecked` | `boolean` | — | Controlled / uncontrolled |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Fires on toggle |
+| `label` | `string \| ReactNode` | — | Visible label (right side). Required for accessible name. |
+| `description` | `string \| ReactNode` | — | Help text below label |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `disabled` | `boolean` | `false` | |
+| `name` / `value` | — | — | For native form submission |
+
+### Checkbox
+
+```tsx
+<Checkbox
+  checked={agreed}
+  onCheckedChange={setAgreed}
+  label="이용약관에 동의합니다"
+  required
+/>
+```
+
+Same props as Switch, plus:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `indeterminate` | `boolean` | `false` | Mixed state (some children selected) |
+| `required` | `boolean` | `false` | Required for form |
+| `error` / `errorText` | — | — | Validation state |
+
+### RadioGroup + Radio
+
+Radios always live in a `RadioGroup`:
+
+```tsx
+<RadioGroup
+  value={method}
+  onValueChange={setMethod}
+  label="결제 수단"
+>
+  <Radio value="card" label="신용/체크카드" description="국내 모든 카드 사용 가능" />
+  <Radio value="kakao" label="KakaoPay" description="간편결제" />
+  <Radio value="naver" label="NaverPay" description="간편결제" />
+</RadioGroup>
+```
+
+| Prop (group) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string` | — | Currently selected value |
+| `onValueChange` | `(value: string) => void` | — | |
+| `label` | `string` | — | Group label (`<legend>`) |
+| `description` | `string` | — | |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | |
+| `disabled` | `boolean` | `false` | Disables all radios |
+| `required` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | |
+
+| Prop (radio) | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Required. Matches `RadioGroup.value`. |
+| `label` | `string \| ReactNode` | Required for accessible name. |
+| `description` | `string \| ReactNode` | |
+| `disabled` | `boolean` | |
+
+## Sizes
+
+| Size | Switch (W×H) | Checkbox / Radio | Label font |
+| --- | --- | --- | --- |
+| `sm` | 28 × 16 | 14 | 13px |
+| `md` (default) | 36 × 20 | 16 | 14px |
+| `lg` | 44 × 24 | 20 | 16px |
+
+For mobile primary forms: `md` minimum. The control is small but the **whole row** (control + label) should be the tap target — minimum row height 44px.
+
+## States
+
+| State | Switch | Checkbox / Radio |
+| --- | --- | --- |
+| Default | Gray track | Gray border |
+| Hover | Track darkens | Border darkens |
+| Focus-visible | 2px ring around control | 2px ring |
+| Active (toggled on) | Primary bg | Primary fill + checkmark/dot |
+| Disabled | 50% opacity, no events | 50% opacity, no events |
+| Error | Red border | Red border |
+| Indeterminate (Checkbox only) | N/A | Filled with horizontal bar |
+
+## Tokens consumed
+
+```
+--color-bg-default              (track off, checkbox bg unchecked)
+--color-border-default          (border)
+--color-border-strong           (hover border)
+--color-primary-default         (track on, fill, dot)
+--color-on-primary              (checkmark)
+--color-text-primary            (label)
+--color-text-secondary          (description)
+--color-error                   (error border)
+--color-focus-ring
+--space-sm, --space-md
+--radius-sm                     (checkbox)
+--radius-full                   (switch track, radio)
+--motion-fast, --easing-out     (toggle animation)
+```
+
+## Layout
+
+```
+┌─────────────────────────────────────────────────┐
+│ [control]  Label (clickable to toggle)          │
+│            Description (optional)                │
+└─────────────────────────────────────────────────┘
+   ↑
+   12px gap between control and label
+
+vs.
+
+┌─────────────────────────────────────────────────┐
+│  Label                              [control]   │  ← settings list pattern
+│  Description                                    │
+└─────────────────────────────────────────────────┘
+```
+
+- **Form field pattern**: control on left, label on right. Default for forms.
+- **Settings row pattern**: label on left, control (Switch) on right. Default for `Settings` pages.
+
+## Accessibility
+
+### Native HTML preferred
+
+- Switch: `<input type="checkbox" role="switch">` (or `<button role="switch" aria-checked>` for custom). Prefer the input.
+- Checkbox: `<input type="checkbox">`.
+- Radio: `<input type="radio" name="...">` (group via `name`).
+
+Custom-styled controls hide the input visually but keep it in the DOM for native form submission + a11y.
+
+### ARIA
+
+- `<label htmlFor={id}>` wraps or is paired with the input (clicking label toggles).
+- `aria-describedby` points to the description's id.
+- `aria-required="true"` when `required`.
+- `aria-invalid="true"` on error.
+- Switch: native `type="checkbox"` + `role="switch"` is the AAA pattern.
+- Indeterminate (Checkbox only): set via JavaScript — `el.indeterminate = true`. There's no HTML attribute.
+- RadioGroup: wrap radios in `<fieldset>` + `<legend>`. Or `role="radiogroup"` + `aria-labelledby`.
+
+### Keyboard
+
+| Key | Switch | Checkbox | Radio |
+| --- | --- | --- | --- |
+| `Tab` | Reach | Reach | Reach the **selected** radio (first if none selected) |
+| `Space` | Toggle | Toggle | (selects current radio) |
+| `Enter` | Toggle (custom only) | (forms submit if inside form) | (forms submit) |
+| `↑` `↓` | — | — | Move + select within group (radio behavior) |
+| `←` `→` | — | — | Same as ↑ ↓ (when horizontal) |
+
+### Touch target
+
+The visible control is small (16–24px). The **clickable area** must be ≥ 44×44 — extend via the label/row. The whole `[control + label]` row is the click target.
+
+## Edge cases
+
+- **"Save changes" pattern with Switches**: anti-pattern. Switches mean immediate effect. If you have a Save button, use Checkboxes.
+- **Required Checkbox (e.g., terms-and-conditions)**: must show validation error if unchecked at submit. `aria-invalid` + visible error text.
+- **Multiple Checkboxes acting as a group**: that's fine, but if exactly-one must be picked, use a RadioGroup.
+- **2 options where Radio would work**: usually a Switch reads cleaner if it's binary. "Light/Dark" → Switch (or 3-radio if "System" is also an option). "Yes/No" → Radio if part of a form, Switch if immediate.
+- **Pre-selected radio**: avoid. Let users actively choose. (Exception: settings forms where defaults are explicit.)
+- **Many radios (10+)**: use a Select. Radio groups become unwieldy.
+- **Korean labels**: typically more verbose ("이용약관에 동의합니다" vs "I agree"). Plan label width.
+
+## Don't
+
+- Don't use Checkbox for "this takes effect immediately" — that's a Switch.
+- Don't use Switch for "submit later" — that's a Checkbox.
+- Don't use Radio for binary on/off. Use Switch (immediate) or Checkbox (form).
+- Don't pre-check marketing-consent checkboxes. **Illegal in Korea** (e-commerce law) and bad practice everywhere.
+- Don't use Switch as a destructive confirmation ("Delete account: [Switch]"). Confirmation needs explicit action with a button + modal.
+- Don't make the control's hit area smaller than the label's. Make the entire row clickable.
+- Don't combine indeterminate with disabled — visually confusing.
+
+## References
+
+- Ant Design: `Switch`, `Checkbox`, `Checkbox.Group`, `Radio`, `Radio.Group`, `Radio.Button`. Has `Radio.Button` for segmented-control-style radios.
+- MUI: `Switch`, `Checkbox`, `Radio` + `RadioGroup` + `FormControl` for the wrapper. `FormControlLabel` for label-with-control.
+- shadcn-ui: [`switch.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/switch.tsx), [`checkbox.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/checkbox.tsx), [`radio-group.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/radio-group.tsx). Radix primitives. **Default for new projects.**
+
+API choices made:
+- **`onCheckedChange(checked)` for Switch + Checkbox**, **`onValueChange(value)` for RadioGroup**: matches the actual user intent — Switch/Checkbox is "what's the boolean?", RadioGroup is "what's the value?".
+- **`label` and `description` as props**: 90% of forms use both; props are faster than composition. Composition (`<Switch.Label>`) is the escape hatch.
+- **Three components in one spec**: shared a11y rules and visual language; treating them separately would force triplicate maintenance.
+
+## Cross-reference
+
+- [examples/component-input.md](component-input.md) — also a form input, but text-typed
+- [examples/component-form.md](component-form.md) — orchestration of multiple form controls
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) — keyboard contracts
+- [knowledge/i18n/korean-product-conventions.md](../knowledge/i18n/korean-product-conventions.md) — required marketing-consent split

package/examples/component-form-group.md

@@ -0,0 +1,86 @@
+# `FormGroup` — spec
+
+> Synthesized from MUI `FormGroup`. A wrapper for grouping multiple `FormControlLabel`-wrapped checkboxes. Provides spacing + optional row layout. Doesn't enforce mutual exclusivity (use `RadioGroup` for that).
+
+## When to use
+
+- Multi-select checkbox groups (filter options, consent checkboxes, multi-day picker).
+- Inside `FormControl` to group related toggles under one label.
+
+## API
+
+```tsx
+<FormControl>
+  <FormLabel>관심 도메인 (복수 선택)</FormLabel>
+  <FormGroup>
+    <FormControlLabel control={<Checkbox />} label="UI/UX" />
+    <FormControlLabel control={<Checkbox />} label="브랜드" />
+    <FormControlLabel control={<Checkbox />} label="모션" />
+  </FormGroup>
+</FormControl>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | `FormControlLabel` children |
+| `row` | `boolean` | `false` | Layout horizontally (default vertical) |
+
+## States
+
+Layout primitive — no interactive state of its own.
+
+## Tokens consumed
+
+```
+--space-xs   /* gap between rows */
+--space-md   /* gap between columns when row */
+```
+
+## Accessibility
+
+- Wrap inside `FormControl` with `FormLabel` to give the group an accessible name.
+- For required groups: `FormControl required` propagates to the FormLabel asterisk.
+- Don't rely on FormGroup alone for labeling — screen readers won't announce the group purpose without a parent label.
+
+## Edge cases
+
+- **Many options (10+)** — switch to a multi-select Autocomplete or a search-filtered list.
+- **`row` with long labels** — wraps to next line; check at narrow viewports (320px).
+- **Mixing checkboxes + switches** — possible but visually inconsistent; prefer one control type per group.
+
+## Code example
+
+```tsx
+<FormControl required component="fieldset">
+  <FormLabel component="legend">법적 동의 사항</FormLabel>
+  <FormGroup>
+    <FormControlLabel
+      control={<Checkbox required name="terms" />}
+      label="이용약관에 동의해요"
+    />
+    <FormControlLabel
+      control={<Checkbox required name="privacy" />}
+      label="개인정보 수집·이용에 동의해요"
+    />
+    <FormControlLabel
+      control={<Checkbox name="marketing" />}
+      label="마케팅 수신에 동의해요 (선택)"
+    />
+  </FormGroup>
+</FormControl>
+```
+
+## Don't
+
+- Don't use for radio groups — use `RadioGroup` (handles `name` + mutual exclusivity).
+- Don't omit the parent label — the group needs an accessible name.
+
+## References
+
+- MUI: [`FormGroup`](../refs/mui/packages/mui-material/src/FormGroup/)
+
+## Cross-reference
+
+- [`component-form-control.md`](component-form-control.md)
+- [`component-form-control-label.md`](component-form-control-label.md)
+- [`component-checkbox.md`](component-checkbox.md)

package/examples/component-form-helper-text.md

@@ -0,0 +1,95 @@
+# `FormHelperText` — spec
+
+> Synthesized from MUI `FormHelperText`. The helper / error text below an input. Inherits `error` and `disabled` state from the parent `FormControl` so consumers don't conditionally style.
+
+## When to use
+
+- Below every input that needs guidance ("회사 이메일을 입력해 주세요").
+- Below every input that can show validation errors.
+- Skip when an input is fully self-explanatory (rare for a sound design).
+
+## API
+
+```tsx
+<FormControl error={!!emailError} required>
+  <FormLabel htmlFor="email">이메일</FormLabel>
+  <OutlinedInput id="email" />
+  <FormHelperText id="email-help">
+    {emailError ?? "회사 도메인 이메일을 입력해 주세요"}
+  </FormHelperText>
+</FormControl>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | The helper / error text |
+| `disabled` | `boolean` | inherited | Mute when disabled |
+| `error` | `boolean` | inherited | Color as error |
+| `filled` | `boolean` | inherited | Match Filled variant spacing |
+| `focused` | `boolean` | inherited | Color when input focused |
+| `margin` | `'dense' \| 'normal' \| 'none'` | `'normal'` | Top spacing |
+| `required` | `boolean` | inherited | (Not visualized; from FormControl) |
+
+## States
+
+| State | Color |
+| --- | --- |
+| Default | `fg-muted` |
+| Focused | `fg-primary` |
+| Error | `fg-error` |
+| Disabled | reduced opacity |
+
+## Tokens consumed
+
+```
+--font-size-caption   /* 12px */
+--color-fg-muted
+--color-fg-primary
+--color-fg-error
+--space-xs            /* margin-top */
+```
+
+## Accessibility
+
+- Pair with input via `aria-describedby` matching this element's `id`.
+- For error states, also set `aria-invalid="true"` on the input.
+- Avoid putting links inside helper text — they're hard to spot at this size and easy to miss.
+
+## Edge cases
+
+- **Switching between helper and error** — keep the same `id`; switch text content. Don't unmount/remount (the screen reader association breaks).
+- **Multi-line helper** — wraps; for long text, consider moving to a Tooltip or below-block info instead.
+- **Korean honorific** — match the form's overall register. Onboarding: 해요체 ("입력해 주세요"). Legal/contracts: 합쇼체 ("입력하시기 바랍니다").
+
+## Code example
+
+```tsx
+<FormControl error={!!errors.email} fullWidth>
+  <FormLabel htmlFor="email">이메일</FormLabel>
+  <OutlinedInput
+    id="email"
+    type="email"
+    aria-invalid={!!errors.email}
+    aria-describedby="email-help"
+  />
+  <FormHelperText id="email-help">
+    {errors.email ?? "회사 도메인 이메일을 입력해 주세요"}
+  </FormHelperText>
+</FormControl>
+```
+
+## Don't
+
+- Don't use raw `<p>` for helper text — `error` state won't auto-propagate.
+- Don't conditionally hide the helper element when there's no error and there used to be — the layout shifts and screen readers lose the association.
+- Don't pile multiple FormHelperText siblings — combine into one node.
+
+## References
+
+- MUI: [`FormHelperText`](../refs/mui/packages/mui-material/src/FormHelperText/)
+
+## Cross-reference
+
+- [`component-form-control.md`](component-form-control.md)
+- [`component-form-label.md`](component-form-label.md)
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md)

package/examples/component-form-label.md

@@ -0,0 +1,98 @@
+# `FormLabel` — spec
+
+> Synthesized from MUI `FormLabel`. The label of a form input — handles required-asterisk, focused color, error color via parent `FormControl`. Use this OR `<label htmlFor>` directly; FormLabel adds the design-system styling.
+
+## When to use
+
+- Label for any `OutlinedInput` / `Select` / custom input inside `FormControl`.
+- For `Checkbox` / `Radio` / `Switch`, prefer `FormControlLabel` (label-wraps-control pattern).
+
+## API
+
+```tsx
+<FormControl required error={!!emailError}>
+  <FormLabel htmlFor="email">이메일</FormLabel>
+  <OutlinedInput id="email" />
+  <FormHelperText>...</FormHelperText>
+</FormControl>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `htmlFor` | `string` | — | Match the input's `id` (REQUIRED for click-to-focus + screen-reader association) |
+| `children` | `ReactNode` | — | Label text |
+| `required` | `boolean` | inherited | Visual asterisk |
+| `error` | `boolean` | inherited | Color as error |
+| `focused` | `boolean` | inherited | Color when input focused |
+| `disabled` | `boolean` | inherited | Mute when disabled |
+| `component` | `ElementType` | `'label'` | Override (use `'legend'` inside `<fieldset>`) |
+| `filled` | `boolean` | inherited | Match Filled variant spacing |
+
+## States
+
+| State | Color |
+| --- | --- |
+| Default | `fg-default` |
+| Focused | `fg-primary` |
+| Error | `fg-error` |
+| Disabled | `fg-muted` |
+| Required | Same color + `*` suffix |
+
+## Tokens consumed
+
+```
+--font-size-body
+--font-weight-medium
+--color-fg-default
+--color-fg-primary       /* focused */
+--color-fg-error
+--color-fg-muted         /* disabled */
+--space-xs               /* margin-bottom to input */
+```
+
+## Accessibility
+
+- `htmlFor` MUST match the input's `id`. Without it, click-on-label-focuses-input doesn't work AND screen readers don't announce the label.
+- For groups (RadioGroup, FormGroup), use `component="legend"` inside a `<fieldset>` (FormControl handles fieldset for you when you set `component="fieldset"`).
+- Required asterisk: visual decoration; pair with `aria-required="true"` on the input for screen readers.
+- Korean labels: keep short (1-3 words). Avoid "을/를" particles in label form ("이메일" not "이메일을").
+
+## Edge cases
+
+- **Optional indicator** — for forms where most fields are optional, label *required* fields visually rather than the inverse. Per [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md).
+- **Long label** — wraps; check at narrow viewports.
+- **Tooltip on label** — wrap label content in a Tooltip for hint-on-hover; ensure focus-visible on label still triggers the tooltip.
+
+## Code example
+
+```tsx
+<FormControl required error={!!errors.password} fullWidth>
+  <FormLabel htmlFor="password">비밀번호</FormLabel>
+  <OutlinedInput
+    id="password"
+    type="password"
+    aria-required="true"
+    aria-invalid={!!errors.password}
+    aria-describedby="password-help"
+  />
+  <FormHelperText id="password-help">
+    {errors.password ?? "8자 이상, 영문 + 숫자 + 특수문자"}
+  </FormHelperText>
+</FormControl>
+```
+
+## Don't
+
+- Don't omit `htmlFor` — biggest a11y miss in real codebases.
+- Don't put placeholder text instead of a label — placeholders disappear on focus.
+- Don't use multiple `FormLabel` per input.
+
+## References
+
+- MUI: [`FormLabel`](../refs/mui/packages/mui-material/src/FormLabel/)
+
+## Cross-reference
+
+- [`component-form-control.md`](component-form-control.md)
+- [`component-form-helper-text.md`](component-form-helper-text.md)
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md)