@design-ai/cli 4.55.0

package/examples/component-dialog-content.md

@@ -0,0 +1,105 @@
+# `DialogContent` — spec
+
+> Synthesized from MUI `DialogContent`. The body region of a `Dialog`. Holds the descriptive text + any form controls between the title and the action row.
+
+## When to use
+
+- Inside every `Dialog` that has body content beyond a single title.
+- For long forms inside a dialog — but reconsider: long forms usually belong on a page, not a modal.
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────┐
+│ Title (DialogTitle)                        │
+├────────────────────────────────────────────┤
+│ Content (DialogContent)                    │
+│   - DialogContentText (optional)           │
+│   - form controls / list / image           │
+├────────────────────────────────────────────┤
+│ Actions (DialogActions)                    │
+└────────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<DialogContent dividers>
+  <DialogContentText>안내 본문</DialogContentText>
+  <TextField label="이메일" fullWidth />
+</DialogContent>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Body content |
+| `dividers` | `boolean` | `false` | Top + bottom divider lines (use when content scrolls) |
+
+## States
+
+Non-interactive itself. Children own their states.
+
+## Scrolling
+
+When content overflows: `DialogContent` becomes the scrollable region (not the whole dialog). Set `dividers` to add visual cues that more content exists above/below the fold.
+
+For a long-content dialog: `Dialog` with `scroll="paper"` (default) and `dividers` on `DialogContent`.
+
+## Tokens consumed
+
+```
+--color-fg-default
+--color-divider
+--space-md
+```
+
+## Accessibility
+
+- The first descendant text node should provide context — pair with `DialogContentText` whose `id` matches `aria-describedby` on the parent `Dialog`.
+- Focus management: when the dialog opens, focus should move to the first interactive control inside `DialogContent` (or to the cancel button if there's no input). Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Form submission via Enter** — wrap content in `<form>`; `Enter` should trigger the primary action button. Don't auto-submit forms with destructive primary actions.
+- **Korean text density** — leave 24-32px horizontal padding (`space-md`) so Hangul doesn't feel cramped. 16px is too tight for Korean.
+- **Image-only content** — provide alt text or describe via `aria-describedby`.
+
+## Code example
+
+```tsx
+<Dialog open={open} onClose={handleClose} fullWidth maxWidth="sm">
+  <DialogTitle id="invite-title">팀원 초대</DialogTitle>
+  <DialogContent dividers>
+    <DialogContentText id="invite-desc">
+      이메일 주소를 입력하면 초대 링크가 발송돼요.
+    </DialogContentText>
+    <TextField
+      autoFocus
+      margin="dense"
+      label="이메일"
+      type="email"
+      fullWidth
+    />
+  </DialogContent>
+  <DialogActions>
+    <Button onClick={handleClose}>취소</Button>
+    <Button onClick={handleSend} variant="contained">초대 보내기</Button>
+  </DialogActions>
+</Dialog>
+```
+
+## Don't
+
+- Don't pack the dialog with 5+ form fields — split into a multi-step pattern or move to a page.
+- Don't put the primary action *inside* `DialogContent` — it belongs in `DialogActions` for keyboard-traversal predictability.
+
+## References
+
+- MUI: [`DialogContent.d.ts`](../refs/mui/packages/mui-material/src/DialogContent/DialogContent.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-dialog.md`](component-dialog.md)
+- [`component-dialog-title.md`](component-dialog-title.md)
+- [`component-dialog-actions.md`](component-dialog-actions.md)

package/examples/component-dialog-title.md

@@ -0,0 +1,104 @@
+# `DialogTitle` — spec
+
+> Synthesized from MUI `DialogTitle`. The header row of a `Dialog`. Provides the accessible name for the dialog via the `aria-labelledby` association.
+
+## When to use
+
+- Inside every `Dialog` (modal). The accessibility contract requires every modal to have a heading.
+- For sheet / drawer headers, prefer the equivalent `<SheetTitle>` / `<DrawerHeader>` from those primitives — same role, different visual context.
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────┐
+│ Title text                       [close ×] │
+└────────────────────────────────────────────┘
+```
+
+The close button is typically rendered separately (often inside the title row via `position: absolute` or as a sibling); MUI's `DialogTitle` doesn't include one by default.
+
+## API
+
+```tsx
+<Dialog open={open} onClose={handleClose} aria-labelledby="confirm-title">
+  <DialogTitle id="confirm-title">정말 삭제할까요?</DialogTitle>
+  <DialogContent>...</DialogContent>
+  <DialogActions>...</DialogActions>
+</Dialog>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | Required for `aria-labelledby` association on the parent `Dialog` |
+| `children` | `ReactNode` | — | Title text; usually short (≤ 60 chars) |
+
+`DialogTitle` extends `Typography` so all typography props (`variant`, `align`, `noWrap`, etc.) work.
+
+## States
+
+`DialogTitle` is non-interactive. Visual is constant.
+
+## Tokens consumed
+
+```
+--color-fg-default
+--font-size-xl       /* default; h2 equivalent */
+--font-weight-semibold
+--space-md           /* horizontal padding */
+--space-md-y         /* vertical padding */
+```
+
+## Accessibility
+
+- Semantic element: `<h2>` (default; via `Typography component="h2"`).
+- The `id` MUST match the parent `Dialog`'s `aria-labelledby`.
+- If the dialog also needs a description, use `<DialogContentText>` with `id` matching `aria-describedby`.
+- For dialogs without a visible title (rare; e.g., image lightbox), provide an `aria-label` directly on the `Dialog` instead of `DialogTitle`.
+
+## Edge cases
+
+- **Long titles** — wrap to 2 lines max; truncating breaks comprehension. Prefer rephrasing.
+- **Korean honorific level** — match the dialog's purpose. Confirmation: 합쇼체 ("정말 삭제하시겠습니까?"). Friendly action: 해요체 ("삭제할까요?"). Cite [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md).
+- **No title with destructive action** — *don't*. Even simple confirms need a title for screen readers and reading order.
+
+## Code example
+
+```tsx
+<Dialog
+  open={open}
+  onClose={handleClose}
+  aria-labelledby="leave-title"
+  aria-describedby="leave-desc"
+>
+  <DialogTitle id="leave-title">저장하지 않은 변경사항이 있어요</DialogTitle>
+  <DialogContent>
+    <DialogContentText id="leave-desc">
+      페이지를 떠나면 변경사항이 사라져요. 계속할까요?
+    </DialogContentText>
+  </DialogContent>
+  <DialogActions>
+    <Button onClick={handleClose}>머무르기</Button>
+    <Button color="error" onClick={handleLeave} autoFocus>
+      나가기
+    </Button>
+  </DialogActions>
+</Dialog>
+```
+
+## Don't
+
+- Don't omit `id` — without it, the dialog has no accessible name.
+- Don't put a close button as `children` — render it as a sibling or via `position: absolute` so the heading text is the `<h2>` content.
+- Don't write title as a question if the body answers — match cause & effect (title states the situation; body provides detail).
+
+## References
+
+- MUI: [`DialogTitle.d.ts`](../refs/mui/packages/mui-material/src/DialogTitle/DialogTitle.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-dialog.md`](component-dialog.md)
+- [`component-dialog-content.md`](component-dialog-content.md)
+- [`component-dialog-actions.md`](component-dialog-actions.md)
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md)

package/examples/component-dialog.md

@@ -0,0 +1,176 @@
+# `Dialog` — spec
+
+> Synthesized from Ant Design `Modal` + MUI `Dialog`. The flagship modal primitive — focus-trapped, esc-closeable, scroll-locked overlay containing structured content (title, body, actions). Used for confirmations, focused tasks, and content too important to dismiss inline.
+
+## When to use
+
+- Confirmations with destructive consequences ("Delete?", "Leave without saving?").
+- Focused short tasks that pull the user out of context (invite, schedule, single-step config).
+- Critical disclosures the user must acknowledge.
+
+## When NOT to use
+
+- Long forms (5+ fields) → use a dedicated page.
+- Optional info → use a Tooltip / Popover / Sheet.
+- Errors that don't block flow → use Toast / Snackbar.
+
+## Anatomy
+
+```
+┌─[scrim]─────────────────────────────────────┐
+│                                             │
+│   ┌──────────────────────────────────┐      │
+│   │ DialogTitle              [✕]     │      │
+│   ├──────────────────────────────────┤      │
+│   │ DialogContent                    │      │
+│   │   DialogContentText (optional)   │      │
+│   │   form fields / list / image     │      │
+│   ├──────────────────────────────────┤      │
+│   │           [Cancel] [Primary]     │      │
+│   └──────────────────────────────────┘      │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Dialog
+  open={open}
+  onClose={handleClose}
+  fullWidth
+  maxWidth="sm"
+  aria-labelledby="dialog-title"
+  aria-describedby="dialog-desc"
+>
+  <DialogTitle id="dialog-title">팀원 초대</DialogTitle>
+  <DialogContent>
+    <DialogContentText id="dialog-desc">
+      이메일로 초대 링크를 보내요.
+    </DialogContentText>
+    <TextField autoFocus fullWidth label="이메일" />
+  </DialogContent>
+  <DialogActions>
+    <Button onClick={handleClose}>취소</Button>
+    <Button onClick={handleSend} variant="contained">보내기</Button>
+  </DialogActions>
+</Dialog>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | required | Controlled open state |
+| `onClose` | `(e, reason) => void` | — | Called on backdrop click / Esc / close button |
+| `fullWidth` | `boolean` | `false` | Stretch to `maxWidth` |
+| `maxWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| false` | `'sm'` | Width cap |
+| `fullScreen` | `boolean` | `false` | Full viewport (mobile) |
+| `scroll` | `'paper' \| 'body'` | `'paper'` | `paper`: content scrolls inside; `body`: page scrolls |
+| `disableEscapeKeyDown` | `boolean` | `false` | Block Esc — use sparingly |
+| `aria-labelledby` | `string` | — | Required; matches DialogTitle's `id` |
+| `aria-describedby` | `string` | — | Required when there's body description; matches DialogContentText's `id` |
+| `TransitionComponent` | `Component` | `Fade` | Custom enter/exit transition |
+| `keepMounted` | `boolean` | `false` | Keep DOM after close (state preservation) |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Not in DOM (or `display: none` if `keepMounted`) |
+| Opening | Scrim fades in (200ms); dialog scales/fades from 90% to 100% |
+| Open | Focus trapped inside; scroll locked on body; backdrop receives Esc |
+| Closing | Reverse of opening; restore focus to opener |
+
+## Tokens consumed
+
+```
+--scrim-bg              /* black/40 light, black/60 dark */
+--dialog-bg             /* surface elevated */
+--dialog-radius
+--dialog-shadow         /* elevation-md */
+--dialog-max-width-sm   /* 444 */
+--dialog-max-width-md   /* 600 */
+--dialog-max-width-lg   /* 900 */
+--space-md              /* internal padding */
+--motion-duration-200
+--motion-easing-out
+```
+
+## Accessibility
+
+- Focus trap: Tab cycles within dialog only. First focus goes to first interactive element (or `autoFocus` button).
+- Escape closes (unless `disableEscapeKeyDown`).
+- Scroll lock: body scroll disabled while dialog open.
+- `role="dialog"` + `aria-modal="true"` (MUI sets these).
+- `aria-labelledby` + `aria-describedby` MUST be set; otherwise screen readers announce just "dialog".
+- On close: focus returns to the element that opened the dialog.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Backdrop click ambiguity** — `onClose` fires with `reason='backdropClick'`. For destructive flows (unsaved changes), confirm before actually closing.
+- **Nested dialogs** — possible but discouraged. If unavoidable: focus trap moves to the inner one, restores correctly on close.
+- **Mobile fullscreen** — set `fullScreen={isMobile}` (e.g., `useMediaQuery('(max-width:600px)')`) so dialogs fill the small viewport instead of cramping.
+- **Korean honorific** — title 합쇼체 for confirmations ("삭제하시겠습니까?"); 해요체 for friendly modals ("초대 보내볼까요?"). Cite [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md).
+- **Long content** — set `scroll="paper"` (default) and pair `dividers` on `DialogContent` to signal scrollability.
+
+## Code example
+
+```tsx
+function DeleteConfirmDialog({ open, onClose, onConfirm, isPending }) {
+  return (
+    <Dialog
+      open={open}
+      onClose={(_, reason) => {
+        if (reason === 'backdropClick' && isPending) return; // block during pending
+        onClose();
+      }}
+      aria-labelledby="del-title"
+      aria-describedby="del-desc"
+      maxWidth="sm"
+      fullWidth
+    >
+      <DialogTitle id="del-title">정말 삭제할까요?</DialogTitle>
+      <DialogContent>
+        <DialogContentText id="del-desc">
+          이 작업은 되돌릴 수 없어요.
+        </DialogContentText>
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={onClose}>취소</Button>
+        <LoadingButton
+          onClick={onConfirm}
+          loading={isPending}
+          color="error"
+          variant="contained"
+        >
+          삭제
+        </LoadingButton>
+      </DialogActions>
+    </Dialog>
+  );
+}
+```
+
+## Don't
+
+- Don't disable Esc unless the flow truly requires explicit confirmation.
+- Don't put 4+ buttons in DialogActions — overflow into a menu or split into steps.
+- Don't open a dialog from a dialog (nested) without strong reason.
+- Don't make the dialog dismissable during a destructive operation that's actually running.
+- Don't omit `aria-labelledby` — the dialog has no accessible name without it.
+
+## References
+
+- Ant Design: [`Modal`](../refs/ant-design/components/modal/) — class API, mask
+- MUI: [`Dialog`](../refs/mui/packages/mui-material/src/Dialog/) — flagship reference
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-dialog-title.md`](component-dialog-title.md)
+- [`component-dialog-content.md`](component-dialog-content.md)
+- [`component-dialog-actions.md`](component-dialog-actions.md)
+- [`component-dialog-content-text.md`](component-dialog-content-text.md)
+- [`component-modal.md`](component-modal.md) — Ant-flavor modal
+- [`knowledge/patterns/empty-states.md`](../knowledge/patterns/empty-states.md) — confirmation patterns
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)

package/examples/component-divider.md

@@ -0,0 +1,182 @@
+# `Divider` (Separator) — spec
+
+> Citing Ant Design `Divider`, MUI `Divider`, shadcn-ui `separator`
+
+## Purpose
+
+A visual line that separates content. Smaller than headings or whitespace gaps; lighter weight than borders.
+
+Use sparingly. **Whitespace is usually a better separator than a line.** A divider says "these are related but distinct"; whitespace says "these are unrelated, period."
+
+## When to use
+
+- Inside a card or list to separate items of similar visual weight.
+- Between sections in a settings page (with section heading above).
+- Between toolbar items.
+- Inside menus to group related actions.
+
+## When NOT to use
+
+- Between paragraphs in body content (use whitespace + paragraph spacing).
+- Around a card or section that already has a border or background contrast.
+- As decoration. Dividers should mean something.
+
+## Anatomy
+
+```
+Horizontal:                            Vertical:
+─────────────────────────              │
+                                       │
+With label:                            With margin in toolbar:
+──── Section title ────                Item 1  │  Item 2  │  Item 3
+```
+
+## API
+
+```tsx
+<Divider />                              {/* default: horizontal hairline */}
+<Divider orientation="vertical" />
+<Divider>Section</Divider>               {/* with label */}
+<Divider variant="dashed" />
+<Divider spacing="lg" />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | |
+| `variant` | `"solid" \| "dashed" \| "dotted"` | `"solid"` | Line style |
+| `children` | `ReactNode` | — | Optional label inline (horizontal only) |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Position of label along the line |
+| `spacing` | `"sm" \| "md" \| "lg"` | `"md"` | Vertical/horizontal margin around the divider |
+| `inset` | `number \| string` | `0` | Indent from the start (e.g., to skip an icon column in a list) |
+| `decorative` | `boolean` | `true` | If true, `aria-hidden`. If false, `role="separator"`. |
+
+## Spacing guidance
+
+| Spacing | Margin |
+| --- | --- |
+| `sm` | 8px above + below |
+| `md` (default) | 16px above + below |
+| `lg` | 24px above + below |
+
+For dividers between items in a tight list (transactions, chats): use a 1px bottom border on each row instead of a separate divider element. It's the same visual but cleaner DOM.
+
+## Inset
+
+For a list with leading icons / avatars:
+
+```
+[icon]  Name 1
+─────── (inset 48px to skip the 40px icon + 8px gap)
+[icon]  Name 2
+```
+
+The inset divider doesn't extend over the icon column — visually unifies the icons.
+
+## States
+
+A divider doesn't have states. Static.
+
+## Tokens consumed
+
+```
+--color-divider             (preferred — usually lighter than border)
+OR
+--color-border-default      (when divider should match other borders)
+```
+
+For dark mode: same token; the value is recomputed in dark.
+
+The divider color is typically:
+- 1 step lighter than `--color-border-default`
+- Often `rgba(0, 0, 0, 0.06)` or `rgba(255, 255, 255, 0.08)` depending on mode
+
+## Sizes / thickness
+
+| Thickness | Use |
+| --- | --- |
+| 1px (default) | Universal |
+| 2px | Heavier section breaks |
+| 0.5px (Retina-only) | Very subtle (Apple-style); pairs with `.5px` `transform: scaleY(0.5)` hack on non-Retina |
+
+For most product UIs: 1px. Going thicker without intent reads as a heavy mistake.
+
+## Accessibility
+
+- **Decorative dividers** (the default): `aria-hidden="true"` so screen readers skip.
+- **Semantic dividers** (rare — when the line genuinely separates regions of meaning): `role="separator"` with `aria-orientation`. Use `<hr>` for full-width semantic horizontal dividers.
+
+```html
+<!-- Decorative (default) -->
+<div className="divider" aria-hidden="true"></div>
+
+<!-- Semantic -->
+<hr role="separator" aria-orientation="horizontal" />
+<div role="separator" aria-orientation="vertical"></div>
+```
+
+Most dividers in product UIs should be `aria-hidden`. The structure is conveyed by surrounding semantic elements (headings, regions).
+
+## Code examples
+
+```tsx
+// Between sections in a settings page
+<SettingsSection title="알림">
+  ...
+</SettingsSection>
+<Divider spacing="lg" />
+<SettingsSection title="결제">
+  ...
+</SettingsSection>
+
+// With label
+<Divider>또는</Divider>      {/* "Or" between social login and email login */}
+<Button>이메일로 가입</Button>
+
+// Vertical in a toolbar
+<Toolbar>
+  <Button>저장</Button>
+  <Divider orientation="vertical" />
+  <Button>되돌리기</Button>
+  <Divider orientation="vertical" />
+  <Button>다음 단계</Button>
+</Toolbar>
+
+// Inset in a list with avatars
+<List>
+  {users.map(u => (
+    <ListItem key={u.id}>
+      <Avatar src={u.photoUrl} />
+      <span>{u.name}</span>
+    </ListItem>
+  ))}
+</List>
+{/* Each ListItem has its own bottom border with inset 48px — preferred over <Divider /> elements */}
+```
+
+## Edge cases
+
+- **Divider at the end of a list**: don't render. The last item's bottom is the natural end.
+- **Divider immediately after a heading**: redundant. The heading's bottom margin is the divider.
+- **Vertical divider that needs to match the parent's height**: stretch with `align-self: stretch` in flex parent.
+- **Dashed/dotted on small spans**: doesn't render cleanly under 8px; use solid for short dividers.
+
+## Don't
+
+- Don't put a divider inside another divider (e.g., divider above and below the same divider).
+- Don't use heavy dividers (4px+) — they read as accidental.
+- Don't color a divider the same as text. Subtle is the point.
+- Don't use a divider where a heading would be clearer.
+- Don't use vertical dividers for vertical lists. Use horizontal.
+- Don't combine inset divider with full-width divider in the same list — pick one.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/divider/`](../refs/ant-design/components/divider/) — `Divider` with `type="horizontal" | "vertical"`, `dashed`, optional inline text. Mature.
+- MUI: [`refs/mui/packages/mui-material/src/Divider/`](../refs/mui/packages/mui-material/src/Divider/) — `Divider` with `orientation`, `variant="fullWidth" | "inset" | "middle"`, `textAlign`. Most variants.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/separator.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/separator.tsx) — Radix Separator. Minimal primitive. `decorative` prop drives `aria-hidden` vs `role="separator"`.
+
+## Cross-reference
+
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md) — when whitespace is the better separator
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md) — list-row dividers via per-item border