@design-ai/cli 4.55.0

package/examples/component-flex.md

@@ -0,0 +1,117 @@
+# `Flex` — spec
+
+> Synthesized from Ant Design `Flex`. A `<div>` with `display: flex` and shorthand props for direction / gap / align / justify. Sibling to `Stack` (MUI) and `HStack`/`VStack` patterns.
+
+## When to use
+
+- Horizontal or vertical row of items with consistent gap.
+- Header layouts (logo + nav + actions).
+- Toolbar / button groups.
+
+When NOT to use:
+- Multi-row wrapping with column constraints — use `Grid`.
+- Single-row with text wrapping — use raw CSS.
+
+## API
+
+```tsx
+<Flex gap={2}>
+  <Avatar />
+  <Text>Name</Text>
+</Flex>
+
+<Flex direction="column" gap={4} align="start">
+  <Heading>Title</Heading>
+  <Text>Body</Text>
+</Flex>
+
+<Flex justify="space-between" align="center">
+  <Logo />
+  <Nav />
+  <Actions />
+</Flex>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `direction` | `"row" \| "column" \| "row-reverse" \| "column-reverse"` | `"row"` | Flex direction |
+| `gap` | spacing-token | `0` | Gap between children |
+| `align` | `"start" \| "center" \| "end" \| "stretch" \| "baseline"` | `"stretch"` | align-items |
+| `justify` | `"start" \| "center" \| "end" \| "space-between" \| "space-around" \| "space-evenly"` | `"start"` | justify-content |
+| `wrap` | `boolean` | `false` | Allow wrapping |
+| `inline` | `boolean` | `false` | inline-flex instead of flex |
+| `as` | element | `"div"` | Render element |
+
+## Common patterns
+
+### Toolbar (justify-between)
+
+```tsx
+<Flex justify="space-between" align="center">
+  <Heading>Title</Heading>
+  <Flex gap={2}>
+    <Button variant="ghost">Cancel</Button>
+    <Button>Save</Button>
+  </Flex>
+</Flex>
+```
+
+### Stack (column with gap)
+
+```tsx
+<Flex direction="column" gap={4}>
+  <Card>...</Card>
+  <Card>...</Card>
+</Flex>
+```
+
+### Centered
+
+```tsx
+<Flex justify="center" align="center" minHeight="100vh">
+  <Card>Centered</Card>
+</Flex>
+```
+
+### Wrapping tag list
+
+```tsx
+<Flex wrap gap={1}>
+  {tags.map(tag => <Tag key={tag}>{tag}</Tag>)}
+</Flex>
+```
+
+## States
+
+Stateless.
+
+## Tokens consumed
+
+```
+--space-{0..n}                     (gap)
+```
+
+## Accessibility
+
+- Flex is presentational. Use `as` for semantic elements (`as="nav"` for nav).
+- For toolbars: wrap with `<div role="toolbar">` if interactive controls.
+- Source order = reading order. Flex visual order can differ via `order` prop, but DOM order is what screen readers read. Avoid `order` for content layout.
+
+## Don't
+
+- Don't use Flex where Stack (MUI) or VStack/HStack (Chakra) is the team convention. Pick one primitive name and stick with it.
+- Don't nest Flex 5+ levels deep. If layout is that complex, use Grid.
+- Don't use Flex with `direction="column"` AND `gap={N}` for content reading flow when a semantic element exists. Use `<article>`, `<section>`, etc.
+
+## References
+
+- Ant: [`Flex`](../refs/ant-design/components/flex)
+- MUI: `Stack` (sibling primitive)
+- Chakra UI: `HStack`, `VStack`, `Flex`
+
+## Cross-reference
+
+- [`examples/component-stack.md`](component-stack.md) — N/A (Stack rendered via similar primitive in some libs)
+- [`examples/component-grid.md`](component-grid.md) — for 2D layout
+- [`examples/component-box.md`](component-box.md) — generic styled wrapper
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md)

package/examples/component-float-button.md

@@ -0,0 +1,214 @@
+# `FloatButton` (FAB — Floating Action Button) — spec
+
+> Citing Ant Design `FloatButton`, MUI `Fab`, shadcn-ui (composition)
+
+## Purpose
+
+A round floating button anchored to the screen edge (typically bottom-right). Used for the **single most important action** on the screen — compose new message, add new item, scroll-to-top.
+
+## When FAB vs alternatives
+
+| Pattern | Use |
+| --- | --- |
+| **FAB** | One primary action, mobile-primary product |
+| **Bottom CTA** (full-width footer button) | Form submit, "Pay" — context-specific |
+| **Header action button** | When the action is contextual to the page header |
+| **Inline button in list** | Per-item actions |
+
+A FAB **must be the single most important action**. Don't use it for navigation. Don't have multiple FABs at the same time.
+
+## Anatomy
+
+```
+[viewport]
+                                   ┌─────┐
+                                   │  +  │   ← FAB
+                                   └─────┘
+                                   ▼ tap
+
+With expand menu:
+                                   ┌────┐
+                                   │ 📷 │  ← child action
+                                   └────┘
+                                   ┌────┐
+                                   │ 📝 │
+                                   └────┘
+                                   ┌─────┐
+                                   │  ✕  │  ← rotated FAB (close)
+                                   └─────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Icon | yes | Single, recognizable (+, 📝, 📷, ↑) |
+| Label | optional | "Extended FAB" — text alongside icon |
+| Child actions | optional | Speed-dial menu when tapped |
+
+## API
+
+```tsx
+<FloatButton
+  icon={<PlusIcon />}
+  onClick={openAddModal}
+  position="bottom-right"
+  label="Add"
+/>
+
+// With expand menu (Speed Dial)
+<FloatButton.Group icon={<PlusIcon />} position="bottom-right">
+  <FloatButton.Item icon={<CameraIcon />} label="사진" onClick={takePhoto} />
+  <FloatButton.Item icon={<PenIcon />} label="메모" onClick={addNote} />
+  <FloatButton.Item icon={<MicIcon />} label="음성" onClick={recordVoice} />
+</FloatButton.Group>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `ReactNode` | — | Required |
+| `label` | `string` | — | Extended-FAB label |
+| `onClick` | `() => void` | — | |
+| `position` | `"bottom-right" \| "bottom-left" \| "bottom-center"` | `"bottom-right"` | Screen-edge anchor |
+| `offset` | `[number, number]` | `[16, 16]` (mobile) / `[24, 24]` (desktop) | px from edge |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `variant` | `"primary" \| "secondary" \| "tonal"` | `"primary"` | |
+| `disabled` | `boolean` | `false` | |
+| `tooltip` | `string` | — | Optional hover hint (desktop) |
+
+## Sizes
+
+| Size | Diameter | Icon | Use |
+| --- | --- | --- | --- |
+| `sm` | 40px | 20px | Inline / dense |
+| `md` (default) | 56px | 24px | Standard mobile FAB |
+| `lg` | 64px | 28px | Tablet / hero |
+
+Material 3's "extended FAB" with label: ~48px height + label text padding.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Resting; raised shadow |
+| Hover | Slight scale up + shadow deepen |
+| Pressed | Scale 0.96 |
+| Focus-visible | 2px ring around |
+| Expanded (Speed Dial open) | Backdrop dim, child actions visible above, FAB rotates to ✕ |
+
+## Tokens consumed
+
+```
+--color-primary-default       (default FAB bg)
+--color-on-primary             (icon)
+--color-bg-elevated           (tonal variant)
+--color-text-primary
+--color-focus-ring
+--space-md, --space-base
+--radius-full                  (circular)
+--radius-lg                    (extended FAB)
+--shadow-3                     (elevation when raised)
+--shadow-4                     (elevation when expanded)
+--motion-fast, --easing-out
+--z-fab                        (above content, below modals)
+```
+
+## Safe area on mobile
+
+iOS / Android devices have safe-area insets (home bar, notches). FAB position must respect them:
+
+```css
+.fab {
+  position: fixed;
+  bottom: max(16px, calc(16px + env(safe-area-inset-bottom)));
+  right: max(16px, calc(16px + env(safe-area-inset-right)));
+}
+```
+
+In RN: use `useSafeAreaInsets()` hook.
+
+## Bottom navigation interplay
+
+If your app has a bottom-tab-bar (per [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md)), the FAB sits **above the tab bar** with `bottom: tabBarHeight + 16`.
+
+For the "center action" tab (elevated tab in middle of tab bar): that's a different pattern — not a FAB, integrated into nav.
+
+## Accessibility
+
+- Render as `<button>` with `aria-label` (icon-only).
+- For Speed Dial: parent button has `aria-haspopup="menu" aria-expanded`. Children are `role="menuitem"`.
+- Focus order: FAB is reachable via Tab.
+- High contrast mode: ensure icon visible against bg color.
+
+### Keyboard
+
+- `Tab` reaches FAB.
+- `Enter` / `Space` activates.
+- For Speed Dial: arrow keys move through children, `Esc` closes.
+
+## Variants
+
+### `primary` (default)
+
+Filled with `--color-primary-default`, on-primary icon. Highest emphasis.
+
+### `secondary`
+
+Filled with secondary brand or neutral elevated. Use when there's a more important primary CTA elsewhere on the page.
+
+### `tonal` (Material 3)
+
+Subtle bg (`--color-primary-subtle-bg`), primary icon. Less emphasis but still elevated.
+
+## Code example
+
+```tsx
+// Standard FAB — add new
+<FloatButton
+  icon={<PlusIcon />}
+  aria-label="새 거래 추가"
+  onClick={openAddTransaction}
+/>
+
+// Extended (label visible)
+<FloatButton
+  icon={<PenIcon />}
+  label="작성"
+  onClick={openCompose}
+/>
+
+// Scroll to top variant
+<FloatButton
+  icon={<ArrowUpIcon />}
+  aria-label="맨 위로"
+  onClick={() => window.scrollTo({ top: 0, behavior: "smooth" })}
+  hidden={scrollY < 200}     // only show when scrolled
+/>
+
+// Speed dial
+<FloatButton.Group icon={<PlusIcon />}>
+  <FloatButton.Item icon={<CameraIcon />} label="사진 촬영" onClick={takePhoto} />
+  <FloatButton.Item icon={<NoteIcon />} label="메모 작성" onClick={addNote} />
+  <FloatButton.Item icon={<MicIcon />} label="음성 녹음" onClick={recordVoice} />
+</FloatButton.Group>
+```
+
+## Don't
+
+- Don't have multiple FABs visible at once.
+- Don't use FAB for navigation — that's a tab.
+- Don't use for destructive actions — too easy to tap accidentally.
+- Don't use FAB on screens where its action wouldn't make sense (settings page, etc.). Show only where the action is contextual.
+- Don't omit `aria-label` for icon-only.
+- Don't ignore safe-area-inset on mobile.
+- Don't put FAB so close to bottom-tab-bar that taps overlap.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/float-button/`](../refs/ant-design/components/float-button/) — `FloatButton`, `FloatButton.Group` (speed dial), `FloatButton.BackTop`. Most flexible.
+- MUI: [`refs/mui/packages/mui-material/src/Fab/`](../refs/mui/packages/mui-material/src/Fab/) — `Fab` with `variant="circular" | "extended"`, color, size. Material-aligned.
+- shadcn-ui: no built-in. Compose with `Button` + Tailwind `fixed bottom-4 right-4 rounded-full`.
+
+## Cross-reference
+
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md) — center-tab variant
+- [`examples/component-button.md`](component-button.md) — for non-FAB buttons
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — touch target sizing

package/examples/component-form-control-label.md

@@ -0,0 +1,134 @@
+# `FormControlLabel` — spec
+
+> Synthesized from MUI `FormControlLabel`. The label-wraps-control pattern for `Checkbox` / `Radio` / `Switch` — the entire label area becomes the click target. Without it, users have to click the tiny check/radio circle directly (poor touch UX).
+
+## When to use
+
+- Any standalone `Checkbox` / `Radio` / `Switch` with a visible label.
+- Inside `FormGroup` for grouped checkboxes.
+- Inside `RadioGroup` for radio sets (RadioGroup wires up `name` automatically).
+
+## Anatomy
+
+```
+[control]   Label text
+   └─────── click target spans both ────────┘
+```
+
+## API
+
+```tsx
+<FormControlLabel
+  control={<Checkbox checked={agreed} onChange={(e) => setAgreed(e.target.checked)} />}
+  label="개인정보 수집 및 이용에 동의해요"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `control` | `ReactElement` | required | The Checkbox/Radio/Switch |
+| `label` | `ReactNode` | — | Label text or component |
+| `labelPlacement` | `'start' \| 'end' \| 'top' \| 'bottom'` | `'end'` | Label position relative to control |
+| `disabled` | `boolean` | inherited | Disable the entire label+control |
+| `required` | `boolean` | `false` | Visual asterisk (label only) |
+| `value` | `any` | — | When inside RadioGroup |
+| `componentsProps` | `{ typography?: TypographyProps }` | — | Customize label typography |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Control + label fg-default |
+| Hover | Subtle bg ripple from control |
+| Focus | Control's focus ring; label color unchanged |
+| Disabled | Both control + label muted |
+| Checked / unchecked | Driven by inner control |
+
+## Tokens consumed
+
+```
+--font-size-body
+--color-fg-default
+--color-fg-muted          /* disabled */
+--space-sm                /* gap between control and label */
+```
+
+## Accessibility
+
+- Label is implicitly associated via the wrapping `<label>` element — no explicit `htmlFor` needed when `control` is a child.
+- For long labels with HTML inside (links, **bold**), screen readers read the entire label as the control's name.
+- Don't put interactive elements (other buttons/links) inside the label — they conflict with the click target.
+- For consent checkboxes with required-acceptance, also set `aria-required="true"` on the inner Checkbox.
+
+## Edge cases
+
+- **Long label wrapping** — wraps cleanly; the click target stays aligned with the control on the first line.
+- **Korean labels with embedded link** — "이용약관에 동의해요" with link on "이용약관". Use `<Link onClick={(e) => e.stopPropagation()}>` to prevent toggling the checkbox when the link is clicked.
+- **labelPlacement="start"** — useful for settings rows where the label is the question and the Switch is the answer.
+- **Inside Stack with multiple labels** — `Stack gap={0}` — don't add extra gap; FormControlLabel has its own.
+
+## Code example
+
+```tsx
+function ConsentCheckboxes() {
+  const [consents, setConsents] = useState({
+    terms: false,
+    privacy: false,
+    marketing: false,
+  });
+
+  return (
+    <FormGroup>
+      <FormControlLabel
+        control={
+          <Checkbox
+            checked={consents.terms}
+            onChange={(e) => setConsents({ ...consents, terms: e.target.checked })}
+          />
+        }
+        label={
+          <>
+            <Link
+              href="/terms"
+              target="_blank"
+              onClick={(e) => e.stopPropagation()}
+            >
+              이용약관
+            </Link>
+            에 동의해요 <span style={{ color: 'red' }}>*</span>
+          </>
+        }
+        required
+      />
+      <FormControlLabel
+        control={<Checkbox checked={consents.privacy} onChange={...} />}
+        label="개인정보 수집 동의"
+        required
+      />
+      <FormControlLabel
+        control={<Checkbox checked={consents.marketing} onChange={...} />}
+        label="마케팅 수신 동의 (선택)"
+      />
+    </FormGroup>
+  );
+}
+```
+
+## Don't
+
+- Don't put a button inside `label` — clicking the button toggles the control, confusing users.
+- Don't use it without a visible label — for icon-only toggles, use `IconButton` with `aria-label`.
+- Don't place the control too far from the label visually (`labelPlacement="bottom"` with extra gap) — the connection becomes unclear.
+
+## References
+
+- MUI: [`FormControlLabel`](../refs/mui/packages/mui-material/src/FormControlLabel/)
+
+## Cross-reference
+
+- [`component-form-control.md`](component-form-control.md)
+- [`component-form-group.md`](component-form-group.md)
+- [`component-checkbox.md`](component-checkbox.md)
+- [`component-radio.md`](component-radio.md)
+- [`component-switch.md`](component-switch.md)
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md)

package/examples/component-form-control.md

@@ -0,0 +1,113 @@
+# `FormControl` — spec
+
+> Synthesized from MUI `FormControl`. The wrapper that groups a label + input + helper-text + error message together, so they share state (focused, error, disabled, required).
+
+## When to use
+
+- Around every form input that has a label or helper text. Skip when wrapping a single uncontrolled `TextField` (which already provides its own FormControl internally).
+- Around custom composed inputs where you want consistent error/required state propagation.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────┐
+│ Label *                              │  ← FormLabel
+│ ┌──────────────────────────────────┐ │
+│ │ Input                            │ │  ← OutlinedInput / Select / etc.
+│ └──────────────────────────────────┘ │
+│ Helper text or error                 │  ← FormHelperText
+└──────────────────────────────────────┘
+```
+
+The visual gap between input and helper text is part of the FormControl's owned spacing.
+
+## API
+
+```tsx
+<FormControl error={hasError} required disabled={!editable}>
+  <FormLabel htmlFor="email">이메일</FormLabel>
+  <OutlinedInput id="email" value={email} onChange={...} />
+  <FormHelperText>{hasError ? errorMsg : '회사 이메일을 입력해 주세요'}</FormHelperText>
+</FormControl>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Label + input + helper |
+| `error` | `boolean` | `false` | Propagates error styling to label, input, and helper |
+| `disabled` | `boolean` | `false` | Propagates disabled to all children |
+| `required` | `boolean` | `false` | Propagates required (visual asterisk on label) |
+| `fullWidth` | `boolean` | `false` | 100% width |
+| `variant` | `'outlined' \| 'filled' \| 'standard'` | `'outlined'` | Inherited by child input |
+| `size` | `'small' \| 'medium'` | `'medium'` | Inherited by child input |
+| `focused` | `boolean` | — | Force-focused styling (rarely needed; auto from input focus) |
+| `margin` | `'dense' \| 'normal' \| 'none'` | `'none'` | Vertical margin |
+
+## States
+
+| State | Visual (cascades to children) |
+| --- | --- |
+| Default | Standard label + input |
+| Focused | Label color = primary; input border = primary |
+| Error | Label color = error; input border = error; helper text = error |
+| Disabled | All elements muted; no hover effects |
+
+## Tokens consumed
+
+```
+--color-fg-default
+--color-fg-error
+--color-fg-primary
+--space-sm        /* helper-text margin-top */
+--space-md
+```
+
+## Accessibility
+
+- The `FormLabel`'s `htmlFor` MUST match the input's `id` — without it, label clicks don't focus the input AND screen readers don't read the label.
+- For required fields, the visual `*` is decorative; pair with `aria-required="true"` on the input itself.
+- For error state: `aria-invalid="true"` on the input, and the FormHelperText's `id` should match `aria-describedby` so screen readers announce the error.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) and [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md).
+
+## Edge cases
+
+- **Multiple FormControls in a row** — group them with `Stack` or `Grid`; don't try to nest one FormControl with multiple labels.
+- **Validation message switching** — when toggling between helper text and error message, animate the color change but not the text swap (no flicker).
+- **Korean field labels** — keep labels short (1-3 words) plus optional helper text. "이메일" not "이메일 주소를 입력해 주세요" as the label.
+
+## Code example
+
+```tsx
+<FormControl error={!!errors.email} required disabled={isSubmitting} fullWidth>
+  <FormLabel htmlFor="email">이메일</FormLabel>
+  <OutlinedInput
+    id="email"
+    type="email"
+    value={values.email}
+    onChange={handleChange}
+    aria-invalid={!!errors.email}
+    aria-describedby={errors.email ? "email-error" : "email-help"}
+  />
+  <FormHelperText id={errors.email ? "email-error" : "email-help"}>
+    {errors.email ?? '회사 이메일을 입력해 주세요'}
+  </FormHelperText>
+</FormControl>
+```
+
+## Don't
+
+- Don't omit `FormLabel` for a labeled field — visual placeholder text isn't a substitute (placeholders disappear on focus).
+- Don't put the helper text in a separate paragraph outside `FormControl` — error state won't propagate.
+- Don't toggle `required` based on user input — set it once based on schema.
+
+## References
+
+- MUI: [`FormControl.d.ts`](../refs/mui/packages/mui-material/src/FormControl/FormControl.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-form-label.md`](component-form-label.md)
+- [`component-form-helper-text.md`](component-form-helper-text.md)
+- [`component-form-control-label.md`](component-form-control-label.md)
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md)