@design-ai/cli 4.55.0

package/examples/component-list-item-button.md

@@ -0,0 +1,139 @@
+# `ListItemButton` — spec
+
+> Synthesized from MUI `ListItemButton`. The clickable variant of `ListItem`. Use this whenever a list row should respond to clicks (settings, nav, picker). Without it, `ListItem` is just a structural container.
+
+## When to use
+
+- Settings rows ("계정 정보", "알림 설정").
+- Nav lists in drawers / sidebars.
+- Picker / chooser rows where the row itself is the selection target.
+- ANY list row with a primary click action.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│ [icon]  Primary text          [trailing icon]    │
+│         Secondary text                           │
+└──────────────────────────────────────────────────┘
+        ─ entire row is the click target ─
+```
+
+For rows with a *separate* trailing action (button), wrap `ListItemButton` inside `ListItem` and put the action in `secondaryAction` (which sits outside the button's hit area).
+
+## API
+
+```tsx
+<List>
+  <ListItem disablePadding>
+    <ListItemButton selected={current === 'profile'} onClick={() => navigate('/profile')}>
+      <ListItemIcon><PersonIcon /></ListItemIcon>
+      <ListItemText primary="프로필" secondary="이름, 이메일, 사진" />
+    </ListItemButton>
+  </ListItem>
+</List>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Usually `ListItemIcon` + `ListItemText` + optional trailing icon |
+| `selected` | `boolean` | `false` | Highlighted (current/active item in nav) |
+| `disabled` | `boolean` | `false` | Non-interactive; greyed |
+| `dense` | `boolean` | `false` | Reduce vertical padding |
+| `divider` | `boolean` | `false` | Bottom divider line |
+| `onClick` | `(e) => void` | — | Click handler |
+| `href` | `string` | — | Renders as `<a>` (use for nav lists) |
+| `component` | `ElementType` | `'div'` | Override element (e.g., `Link` from react-router) |
+| `disableRipple` | `boolean` | `false` | Skip the click-ripple effect |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | transparent bg, fg-default |
+| Hover | bg-subtle |
+| Focus-visible | bg-subtle + 2px focus ring inset |
+| Active | bg-pressed |
+| Selected | bg-selected (~ brand-50/dark mode brand-900-30%), fg-on-selected |
+| Selected + hover | bg-selected-hover (slight shift) |
+| Disabled | reduced opacity, no hover effect |
+
+## Tokens consumed
+
+```
+--list-item-min-height-44      /* default touch target */
+--list-item-min-height-36      /* dense */
+--color-bg-default
+--color-bg-subtle              /* hover */
+--color-bg-pressed             /* active */
+--color-bg-selected            /* selected */
+--color-fg-default
+--color-fg-on-selected
+--space-md                     /* horizontal padding */
+--motion-duration-100          /* hover/active transition */
+```
+
+## Accessibility
+
+- Default semantic: `<div role="button">` with `tabIndex=0`. With `href`: renders `<a>` (preferred for nav).
+- `selected={true}` → `aria-selected="true"`. For nav lists also add `aria-current="page"` when the row matches the current route.
+- Keyboard: Enter / Space activates. Disabled rows skipped in tab order.
+- Touch target: ≥ 44pt mobile (default 48px). Don't use `dense` on mobile primary nav.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Long primary text** — wraps to 2 lines, then ellipsis. For nav rows, prefer concise labels.
+- **`href` + `onClick`** — `onClick` fires before navigation; useful for analytics.
+- **Inside React Router** — pass `component={RouterLink}` + `to="/path"` for SPA-style nav (no full page reload).
+- **Selected without persistence** — `selected` is for the *current* item. For multi-select (checkbox lists), use `Checkbox` inside the row instead of `selected`.
+- **Korean labels** — slightly more vertical padding looks less cramped (Hangul reads taller). Default 48px row height works; resist `dense` for Korean nav.
+
+## Code example
+
+```tsx
+function SettingsNav({ section }: { section: string }) {
+  const items = [
+    { id: 'profile', label: '프로필', icon: <PersonIcon /> },
+    { id: 'notifications', label: '알림 설정', icon: <BellIcon /> },
+    { id: 'privacy', label: '개인정보', icon: <LockIcon /> },
+    { id: 'billing', label: '결제 정보', icon: <CardIcon /> },
+  ];
+
+  return (
+    <List component="nav" aria-label="설정">
+      {items.map((it) => (
+        <ListItem key={it.id} disablePadding>
+          <ListItemButton
+            component={Link}
+            to={`/settings/${it.id}`}
+            selected={section === it.id}
+          >
+            <ListItemIcon>{it.icon}</ListItemIcon>
+            <ListItemText primary={it.label} />
+          </ListItemButton>
+        </ListItem>
+      ))}
+    </List>
+  );
+}
+```
+
+## Don't
+
+- Don't use `ListItemButton` outside a `ListItem` parent — semantics break.
+- Don't make the entire `ListItem` clickable via `onClick` on `ListItem` — wrap the inner content in `ListItemButton` so secondary actions stay separately focusable.
+- Don't combine `ListItemButton` with form controls (Checkbox, Switch) inside the same clickable area — a click on the form control conflicts with the row click.
+- Don't override `selected` styling without keeping enough contrast (`color-bg-selected` should be ≥ 3:1 against `color-bg-default`).
+
+## References
+
+- MUI: [`ListItemButton`](../refs/mui/packages/mui-material/src/ListItemButton/)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-list-item.md`](component-list-item.md) — structural container
+- [`component-list-item-text.md`](component-list-item-text.md)
+- [`component-list-item-icon.md`](component-list-item-icon.md)
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md)

package/examples/component-list-item-icon.md

@@ -0,0 +1,82 @@
+# `ListItemIcon` — spec
+
+> Synthesized from MUI `ListItemIcon`. The leading-icon slot in a `ListItem` — handles consistent sizing, color, and spacing so icons align across rows.
+
+## When to use
+
+- Leading icons in nav lists (settings, drawer menu).
+- Status icons in compact lists (success / warning indicators).
+- For trailing icons (chevrons, badges), use `secondaryAction` on `ListItem` instead.
+
+## API
+
+```tsx
+<ListItem disablePadding>
+  <ListItemButton>
+    <ListItemIcon>
+      <PersonIcon />
+    </ListItemIcon>
+    <ListItemText primary="프로필" />
+  </ListItemButton>
+</ListItem>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | The icon component |
+
+The icon's color and size are controlled by the parent — don't apply explicit `sx={{ color, fontSize }}` unless intentionally diverging.
+
+## States
+
+Inherits from parent button: hover, focus, selected, disabled all cascade. Selected rows get brand-colored icons.
+
+## Tokens consumed
+
+```
+--icon-size-md            /* 24px default */
+--color-fg-muted          /* default icon color */
+--color-fg-on-selected    /* selected state */
+--list-icon-min-width     /* 40-56px reserved column */
+```
+
+## Accessibility
+
+- Decorative icons get `aria-hidden="true"` (default behavior of MUI icons).
+- If the icon is the *only* indicator (no text label), wrap with `<span aria-label="..."/>`.
+- Touch target lives on the parent `ListItemButton`, not the icon itself.
+
+## Edge cases
+
+- **Mixed: some rows have icons, some don't** — use `inset={true}` on `ListItemText` for icon-less rows so text columns align.
+- **Custom icon size** — overriding via `sx={{ minWidth: ... }}` lets compact lists fit more rows; don't go below 32px on touch.
+- **Status icons + text** — pair with `<Stack direction="row" gap={1}>` inside `ListItemText.primary` if both need to be at the text level.
+
+## Code example
+
+```tsx
+// Settings nav with status indicators
+<List component="nav">
+  <ListItem disablePadding>
+    <ListItemButton>
+      <ListItemIcon><BellIcon color="primary" /></ListItemIcon>
+      <ListItemText primary="알림" secondary="3개 안 읽음" />
+    </ListItemButton>
+  </ListItem>
+</List>
+```
+
+## Don't
+
+- Don't put text inside `ListItemIcon` — it's sized for icons only.
+- Don't skip `ListItemIcon` and put icons in `ListItemText.primary` for icon-led rows — alignment breaks.
+
+## References
+
+- MUI: [`ListItemIcon`](../refs/mui/packages/mui-material/src/ListItemIcon/)
+
+## Cross-reference
+
+- [`component-list-item.md`](component-list-item.md)
+- [`component-list-item-text.md`](component-list-item-text.md)
+- [`knowledge/icons/curated-sets.md`](../knowledge/icons/curated-sets.md)

package/examples/component-list-item-text.md

@@ -0,0 +1,98 @@
+# `ListItemText` — spec
+
+> Synthesized from MUI `ListItemText`. The text block inside a `ListItem` — primary line plus optional secondary line. Handles typography, ellipsis, and screen-reader semantics so consumers don't reimplement.
+
+## When to use
+
+- Inside every `ListItem` that has text content (almost all of them).
+- For text-only rows (no icon, no secondary action), `ListItemText` is the entire body.
+
+## Anatomy
+
+```
+[Primary text — 14px medium / fg-default]
+[Secondary text — 12px regular / fg-muted]
+```
+
+## API
+
+```tsx
+<ListItemText
+  primary="홍길동"
+  secondary="개발팀 · 2026-05-01 입사"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `primary` | `ReactNode` | — | Primary line (label) |
+| `secondary` | `ReactNode` | — | Secondary line (sub-label) |
+| `inset` | `boolean` | `false` | Indent left to align with rows that have a leading icon |
+| `disableTypography` | `boolean` | `false` | Skip wrapping in `<Typography>`; renders raw children |
+| `primaryTypographyProps` | `TypographyProps` | — | Override primary line typography |
+| `secondaryTypographyProps` | `TypographyProps` | — | Override secondary line typography |
+
+## States
+
+`ListItemText` is structural — no interactive states. Inherits color from parent (`ListItemButton`'s selected/disabled states cascade).
+
+## Tokens consumed
+
+```
+--font-size-body         /* primary */
+--font-size-caption      /* secondary */
+--font-weight-medium     /* primary */
+--font-weight-regular    /* secondary */
+--color-fg-default       /* primary */
+--color-fg-muted         /* secondary */
+--line-height-body       /* KR-bumped 1.65 */
+--space-xs               /* gap between primary and secondary */
+```
+
+## Accessibility
+
+- Semantic: primary renders as `<span>` (or override). Secondary renders as `<p>`.
+- For screen readers, both lines are announced together as "primary, secondary".
+- For LONG primary text that wraps, ensure `aria-label` provides a short summary if needed.
+- `inset={true}` keeps text alignment consistent with sibling rows that have icons — don't drop it.
+
+## Edge cases
+
+- **Long primary text** — wraps; if multi-line wrap is undesired, set `primaryTypographyProps={{ noWrap: true }}` for ellipsis.
+- **Empty secondary** — omit the prop; don't pass empty string (creates extra spacing).
+- **React node as primary** — primary can be a `<Stack>` for inline badges next to the label. `disableTypography` lets you control the wrapper.
+- **Korean text density** — Hangul reads slightly taller; default line-height (1.65 KR-bumped) should not be reduced.
+
+## Code example
+
+```tsx
+// Settings row with switch
+<ListItem
+  secondaryAction={<Switch onChange={toggle} checked={pushEnabled} />}
+>
+  <ListItemText
+    primary="푸시 알림"
+    secondary="새 메시지가 오면 알림을 받아요"
+  />
+</ListItem>
+
+// Inset variant — aligns with rows that have icons
+<ListItemText inset primary="섹션 헤더 없음" secondary="아이콘 자리만큼 들여 써요" />
+```
+
+## Don't
+
+- Don't pass JSX trees as `secondary` that reimplement Typography — use `secondaryTypographyProps` overrides.
+- Don't omit `inset` selectively — once any sibling row uses `ListItemIcon`, all icon-less siblings should `inset` for visual rhythm.
+- Don't rely on `secondary` for critical info screen reader users need quickly — they hear it as continuation of primary.
+
+## References
+
+- MUI: [`ListItemText`](../refs/mui/packages/mui-material/src/ListItemText/)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-list-item.md`](component-list-item.md)
+- [`component-list-item-button.md`](component-list-item-button.md)
+- [`knowledge/typography/type-scale-fundamentals.md`](../knowledge/typography/type-scale-fundamentals.md)

package/examples/component-list-item.md

@@ -0,0 +1,116 @@
+# `ListItem` — spec
+
+> Synthesized from MUI `ListItem`. The single-row primitive used inside `List`. For interactive rows that respond to clicks, use [`component-list-item-button.md`](component-list-item-button.md) — `ListItem` itself is the structural container.
+
+## When to use
+
+- One row inside a `<List>`.
+- Pure-display rows (text + secondary action button on the right).
+- For *clickable rows* (the common case in settings / nav lists), use `ListItemButton` as the child.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│ [icon/avatar]  Primary text          [secondary] │
+│                Secondary text                    │
+└──────────────────────────────────────────────────┘
+```
+
+Slots: leading icon/avatar (optional), text block (`ListItemText`), trailing secondary action (`ListItemSecondaryAction`).
+
+## API
+
+```tsx
+<List>
+  <ListItem secondaryAction={<IconButton><DeleteIcon /></IconButton>}>
+    <ListItemAvatar><Avatar /></ListItemAvatar>
+    <ListItemText primary="이름" secondary="설명" />
+  </ListItem>
+</List>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Primary content; usually `ListItemText` + optional avatar/icon |
+| `disablePadding` | `boolean` | `false` | Remove default vertical padding (use when child is `ListItemButton`) |
+| `secondaryAction` | `ReactNode` | — | Right-anchored action area; not part of the row's clickable surface |
+| `disableGutters` | `boolean` | `false` | Remove horizontal padding |
+| `dense` | `boolean` | `false` | Reduce vertical padding (settings / dense nav lists) |
+| `divider` | `boolean` | `false` | Bottom divider line |
+
+## States
+
+`ListItem` itself is non-interactive. Interactivity comes from a `ListItemButton` child:
+
+| State (on inner button) | Visual |
+| --- | --- |
+| Default | transparent bg, fg-default |
+| Hover | bg-subtle |
+| Focus-visible | 2px focus ring inset; cite [keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) |
+| Active | bg-pressed |
+| Selected | bg-selected, fg-on-selected |
+| Disabled | reduced opacity |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-fg-default
+--space-sm        /* dense */
+--space-md        /* default */
+--list-row-min-height-44
+--color-divider
+```
+
+## Accessibility
+
+- Semantic element: `<li>` (default).
+- For navigable list with selection, use `role="list"` on the parent and `aria-current="page"` on the selected item.
+- `secondaryAction` must be a separately-focusable control with its own accessible name (otherwise it merges into the row's tab stop and is unreachable).
+- Touch target: ≥ 44pt for mobile lists.
+
+## Edge cases
+
+- **Long primary text** — wraps to 2 lines, then ellipsis.
+- **`ListItemButton` child + `secondaryAction`** — the secondary action is OUTSIDE the button's hit area. Functionally critical for screen-reader nav.
+- **Korean text density** — Hangul reads ~10% wider than Latin. Test with realistic Korean copy.
+
+## Code example
+
+```tsx
+<List>
+  {users.map((u) => (
+    <ListItem
+      key={u.id}
+      secondaryAction={
+        <IconButton edge="end" aria-label={`${u.name} 삭제`}>
+          <DeleteIcon />
+        </IconButton>
+      }
+      disablePadding
+    >
+      <ListItemButton onClick={() => select(u.id)}>
+        <ListItemAvatar><Avatar src={u.avatarUrl} /></ListItemAvatar>
+        <ListItemText primary={u.name} secondary={u.role} />
+      </ListItemButton>
+    </ListItem>
+  ))}
+</List>
+```
+
+## Don't
+
+- Don't make the entire `ListItem` clickable via `onClick`; wrap inner content in `ListItemButton` so secondary action stays separately focusable.
+- Don't put 3+ controls inside `secondaryAction` — overflow into a menu.
+
+## References
+
+- MUI: [`ListItem.d.ts`](../refs/mui/packages/mui-material/src/ListItem/ListItem.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-list-item-button.md`](component-list-item-button.md)
+- [`component-list-item-text.md`](component-list-item-text.md)
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md)

package/examples/component-list-subheader.md

@@ -0,0 +1,70 @@
+# `ListSubheader` — spec
+
+> Synthesized from MUI `ListSubheader`. A section header inside a `List`. Use for grouping related rows under a label ("최근", "즐겨찾기", "전체").
+
+## When to use
+
+- Grouped lists (categories of settings, sections of nav).
+- Date-grouped feeds ("오늘", "어제", "이번 주").
+- Avoid for short lists (<5 rows) — header overhead isn't worth it.
+
+## API
+
+```tsx
+<List subheader={<ListSubheader>최근 검색</ListSubheader>}>
+  <ListItemButton>...</ListItemButton>
+  <ListItemButton>...</ListItemButton>
+</List>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Header text |
+| `disableSticky` | `boolean` | `false` | Skip sticky-on-scroll behavior |
+| `inset` | `boolean` | `false` | Indent to align with icon-led rows |
+| `disableGutters` | `boolean` | `false` | Remove horizontal padding |
+
+## Tokens consumed
+
+```
+--font-size-caption       /* 12px */
+--font-weight-semibold
+--color-fg-muted          /* default */
+--space-md                /* horizontal padding */
+--list-subheader-height   /* 32px */
+```
+
+## Accessibility
+
+- Renders as `<li>` by default. For semantic headers, override `component="h3"` or wrap content with appropriate heading.
+- Don't use as the *only* visual cue for grouping — pair with `Divider` or distinct background for low-vision users.
+
+## Edge cases
+
+- **Sticky on scroll** — default behavior keeps the subheader visible while its rows scroll past. Disable for short lists.
+- **Korean labels** — short and noun-form ("최근", "즐겨찾기"). Avoid sentence-form labels here.
+
+## Code example
+
+```tsx
+<List>
+  <ListSubheader>최근</ListSubheader>
+  {recent.map((it) => <ListItemButton key={it.id}>{it.title}</ListItemButton>)}
+  <ListSubheader>즐겨찾기</ListSubheader>
+  {favs.map((it) => <ListItemButton key={it.id}>{it.title}</ListItemButton>)}
+</List>
+```
+
+## Don't
+
+- Don't nest subheaders.
+- Don't use for sublabels under a single row — that's `ListItemText.secondary`.
+
+## References
+
+- MUI: [`ListSubheader`](../refs/mui/packages/mui-material/src/ListSubheader/)
+
+## Cross-reference
+
+- [`component-list-item.md`](component-list-item.md)
+- [`component-list-item-button.md`](component-list-item-button.md)