@design-ai/cli 4.55.0

package/examples/component-switch.md

@@ -0,0 +1,99 @@
+# `Switch` — spec
+
+> Synthesized from Ant Design `Switch`, MUI `Switch`, shadcn-ui `switch`. iOS-style toggle for binary on/off settings. See [`component-form-controls.md`](component-form-controls.md) for Switch + Checkbox + Radio comparison.
+
+## Switch vs Checkbox
+
+> **Switch = immediate effect setting. Checkbox = form input.**
+
+- Settings page: `Switch` ("Enable notifications" — toggles immediately).
+- Signup form: `Checkbox` ("I agree to terms" — submitted with form).
+
+## Anatomy
+
+```
+Off:     ◯━━ ━━━━━           On:     ━━━━━ ━━●
+```
+
+Track + thumb. Thumb slides from left to right when toggled.
+
+## API
+
+```tsx
+<Switch
+  checked={enabled}
+  onCheckedChange={setEnabled}
+  id="notifications"
+/>
+
+<Switch checked={loading ? enabled : ...} disabled={loading} />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | controlled | State |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled initial |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Callback |
+| `disabled` | `boolean` | `false` | — |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | — |
+| `name` / `value` | `string` | — | Form attributes |
+
+## Sizes
+
+| Size | Track w×h | Thumb |
+| --- | --- | --- |
+| sm | 28×16 | 12 |
+| md (default) | 44×24 | 20 |
+| lg | 56×32 | 28 |
+
+Touch target ≥ 44pt regardless via padding.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Off | Track: muted gray; thumb left |
+| On | Track: brand color; thumb right |
+| Hover | Subtle track color shift |
+| Focus-visible | Ring around track |
+| Disabled | Reduced opacity |
+| Loading (optional) | Spinner replaces thumb |
+
+## Tokens consumed
+
+```
+--switch-track-off
+--switch-track-on               (brand)
+--switch-thumb
+--switch-thumb-disabled
+--motion-fast                   (200ms slide)
+--ease-out
+```
+
+## Accessibility
+
+- `<button role="switch" aria-checked="true|false">`.
+- `aria-label` if no visible label.
+- Keyboard: Space toggles; Enter doesn't (per WAI-ARIA Switch).
+
+## Korean conventions
+
+- 알림 받기, 다크 모드, 자동 저장 — typical settings labels (해요체).
+- For 마케팅 정보 수신: use Checkbox (form), not Switch (immediate effect).
+
+## Don't
+
+- Don't use Switch in forms with Submit. That's Checkbox.
+- Don't make Switch < 28px wide. Touch / readability.
+- Don't lazy-render label state ("On" / "Off") — let the visual track show state.
+
+## References
+
+- Ant: [`Switch`](../refs/ant-design/components/switch)
+- MUI: [`Switch`](../refs/mui/packages/mui-material/src/Switch)
+- shadcn-ui: [`switch`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/switch.tsx)
+
+## Cross-reference
+
+- [`examples/component-form-controls.md`](component-form-controls.md)
+- [`examples/component-checkbox.md`](component-checkbox.md)

package/examples/component-tab-scroll-button.md

@@ -0,0 +1,180 @@
+# `TabScrollButton` - spec
+
+> Direct upstream component: MUI `TabScrollButton`. Parent pattern references: Ant Design `Tabs`, MUI `Tabs`, shadcn-ui `tabs`.
+
+## Purpose
+
+`TabScrollButton` is the overflow affordance used by scrollable tab lists. It moves the tab strip left/right or up/down when there are more tabs than fit in the available space.
+
+It is a supporting control for `Tabs`, not a tab and not page navigation.
+
+## Anatomy
+
+```
+Tabs
+├── Start TabScrollButton    optional; appears when content can scroll backward
+├── TabList
+│   ├── Tab
+│   ├── Tab
+│   └── Tab
+└── End TabScrollButton      optional; appears when content can scroll forward
+```
+
+| Part | Required | Purpose |
+| --- | --- | --- |
+| Root | yes | Scroll command container. |
+| Direction icon | yes | Communicates scroll direction. |
+| Start/end slot | optional | Allows custom icons while preserving behavior. |
+
+## API
+
+```tsx
+<TabScrollButton
+  direction="right"
+  orientation="horizontal"
+  disabled={!canScrollForward}
+  aria-label="다음 탭 보기"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | - | Optional custom content. Usually omit and use icon slots. |
+| `classes` | `Partial<TabScrollButtonClasses>` | - | Style override hooks for MUI-style implementations. |
+| `direction` | `"left" \| "right"` | required | Visual/behavioral scroll direction. |
+| `disabled` | `boolean` | `false` | Disabled when the tab strip cannot scroll further in that direction. |
+| `orientation` | `"horizontal" \| "vertical"` | required | Tab list orientation. |
+| `slots` | `{ StartScrollButtonIcon?, EndScrollButtonIcon? }` | `{}` | Custom start/end icon components. |
+| `slotProps` | `{ startScrollButtonIcon?, endScrollButtonIcon? }` | `{}` | Props forwarded to icon slots. |
+| `sx` | `SxProps<Theme>` | - | MUI system override. Prefer tokens for shared design-system code. |
+
+Inherits most `ButtonBase` props in MUI, except native button behavior is intentionally customized.
+
+## API choices made
+
+- Keep `direction` and `orientation` required because icon rotation and scroll behavior depend on both.
+- Keep `disabled` explicit so first/last scroll limits are represented in DOM and visuals.
+- Do not expose `onScrollTabs` in this spec; the parent `Tabs` component should own scroll position and click handlers.
+- Do not treat `TabScrollButton` as a `Tabs.Trigger`. It must stay outside the tab roving-focus model.
+
+## States
+
+| State | Trigger | Visual rule |
+| --- | --- | --- |
+| Hidden | No overflow in that direction | Do not render, or render with zero interaction and no layout jump depending on parent Tabs strategy. |
+| Default | Overflow available | Icon uses secondary text color; fixed control width/height. |
+| Hover | Pointer over enabled control | Subtle background. |
+| Focus-visible | Keyboard focus if implemented as a real button | 2px focus ring with at least 3:1 contrast. |
+| Active | Press | Pressed background; scroll distance remains deterministic. |
+| Disabled | At scroll limit | Muted or transparent; no activation. |
+| Vertical | `orientation="vertical"` | Icon rotates to indicate up/down movement. |
+| RTL | Directional context | Horizontal start/end behavior mirrors with text direction. |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle
+--color-text-secondary
+--color-text-disabled
+--color-focus-ring
+--space-xs
+--space-sm
+--tabs-scroll-button-size
+--icon-size-sm
+--radius-sm
+--motion-fast
+```
+
+If `--tabs-scroll-button-size` does not exist, map it to the tab trigger height for the current size.
+
+## Accessibility
+
+- The control must not be part of the `role="tablist"` roving focus sequence.
+- If your implementation makes it user-clickable, render a real `<button type="button">` with labels such as `aria-label="이전 탭 보기"` and `aria-label="다음 탭 보기"`.
+- If matching MUI's internal presentational pattern, ensure the same scroll action is available through pointer drag/trackpad scroll and tab-list arrow-key navigation.
+- Disabled controls need native `disabled` or `aria-disabled="true"` plus suppressed activation.
+- Touch target must be at least 44x44 on mobile.
+- Icons are decorative when the button has an accessible label; set icon `aria-hidden="true"`.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Enters active tab, not every tab and not hidden scroll controls, unless scroll controls are implemented as visible buttons. |
+| `Enter` / `Space` | Activates the scroll button only when it is a focusable real button. |
+| Arrow keys | Move between tabs through the parent Tabs pattern. |
+
+## Layout rules
+
+| Rule | Value |
+| --- | --- |
+| Horizontal size | Fixed inline size matching the parent density; commonly 40px equivalent. |
+| Vertical size | Full tab-list width with fixed block size. |
+| Position | At the start/end edge of the scroll container. |
+| Overlay | Avoid covering tab labels; reserve space or use gradient mask plus button. |
+| Motion | Smooth scroll is allowed, but disable it for `prefers-reduced-motion`. |
+
+## Code example
+
+```tsx
+function ScrollableTabsHeader({ tabs, value, onValueChange }: Props) {
+  return (
+    <Tabs value={value} onValueChange={onValueChange} variant="underline">
+      <TabScrollButton
+        direction="left"
+        orientation="horizontal"
+        disabled={!canScrollBack}
+        aria-label="이전 탭 보기"
+        onClick={scrollBack}
+      />
+      <Tabs.List>
+        {tabs.map((tab) => (
+          <Tabs.Trigger key={tab.value} value={tab.value}>
+            {tab.label}
+          </Tabs.Trigger>
+        ))}
+      </Tabs.List>
+      <TabScrollButton
+        direction="right"
+        orientation="horizontal"
+        disabled={!canScrollForward}
+        aria-label="다음 탭 보기"
+        onClick={scrollForward}
+      />
+    </Tabs>
+  );
+}
+```
+
+## Edge cases
+
+- **No overflow**: hide both controls or keep reserved space consistently. Do not show disabled arrows forever in compact mobile UIs.
+- **RTL**: visual arrows and scroll math must be tested together; browser `scrollLeft` behavior differs by engine.
+- **Vertical tabs**: rotate or swap icons so the control reads as up/down, not left/right.
+- **Touch devices**: horizontal swipe/drag should work even when scroll buttons are hidden.
+- **Many tabs**: keep arrow-key navigation functional for all tabs, including off-screen tabs.
+- **Reduced motion**: use instant scroll instead of smooth scrolling.
+- **High contrast mode**: do not rely on opacity alone for disabled state; pair with `disabled` semantics.
+
+## Don't
+
+- Don't render scroll buttons as tabs.
+- Don't include scroll buttons in the tab count announced to screen readers.
+- Don't use a "More" dropdown as the first solution for overflowed tabs.
+- Don't hide off-screen tabs from the accessibility tree if they are still part of the tab set.
+
+## References
+
+- MUI direct source: [`refs/mui/packages/mui-material/src/TabScrollButton/TabScrollButton.d.ts`](../refs/mui/packages/mui-material/src/TabScrollButton/TabScrollButton.d.ts)
+- MUI implementation: [`refs/mui/packages/mui-material/src/TabScrollButton/TabScrollButton.js`](../refs/mui/packages/mui-material/src/TabScrollButton/TabScrollButton.js)
+- MUI tabs source: [`refs/mui/packages/mui-material/src/Tabs/`](../refs/mui/packages/mui-material/src/Tabs/)
+- Ant Design parent pattern: [`refs/ant-design/components/tabs/`](../refs/ant-design/components/tabs/)
+- shadcn-ui parent pattern: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/tabs.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/tabs.tsx)
+- Accessibility baseline: [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)
+
+## Cross-reference
+
+- [examples/component-tabs.md](component-tabs.md)
+- [examples/component-tab.md](component-tab.md)
+- [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)

package/examples/component-tab.md

@@ -0,0 +1,120 @@
+# `Tab` — spec
+
+> Synthesized from MUI `Tab`. A single tab inside a `Tabs` set. Used for top-level navigation within a section ("개요 / 활동 / 멤버") and for bottom navigation patterns.
+
+## When to use
+
+- Mutually exclusive views of the same context (account → profile / security / billing).
+- Switching between datasets in a dashboard.
+- For top-level app navigation, prefer dedicated nav (drawer, top bar) — Tabs are within-page.
+
+## When NOT to use
+
+- 2 options → use `ToggleButtonGroup` or `Radio`.
+- 7+ options → switch to a dropdown or a sidebar.
+
+## Anatomy
+
+```
+[Tab1]  [Tab2]  [Tab3]
+─────  ─────  ─────
+        ▔▔▔        ← indicator under selected
+```
+
+## API
+
+```tsx
+<Tabs value={tab} onChange={(_, v) => setTab(v)} aria-label="account sections">
+  <Tab label="프로필" value="profile" />
+  <Tab label="보안" value="security" />
+  <Tab label="결제" value="billing" disabled />
+</Tabs>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | — | Tab label |
+| `value` | `any` | — | Identifies tab; matched against parent `Tabs.value` |
+| `icon` | `ReactNode` | — | Leading icon (above label by default) |
+| `iconPosition` | `'top' \| 'bottom' \| 'start' \| 'end'` | `'top'` | Icon placement |
+| `disabled` | `boolean` | `false` | Non-interactive |
+| `wrapped` | `boolean` | `false` | Allow text to wrap to 2 lines |
+| `href` | `string` | — | Render as link (use for tabs that map to routes) |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | fg-muted, no underline |
+| Hover | fg-default |
+| Focus-visible | fg-default + ring |
+| Selected | fg-primary, underline indicator |
+| Disabled | reduced opacity |
+
+## Tokens consumed
+
+```
+--tab-fg-default          /* fg-muted */
+--tab-fg-selected         /* fg-primary OR fg-default — design-system choice */
+--tab-indicator-color     /* brand */
+--tab-indicator-height    /* 2px */
+--tab-min-width-72        /* default min */
+--tab-min-height-48       /* touch */
+```
+
+## Accessibility
+
+- Renders `role="tab"` inside `role="tablist"`. Selected = `aria-selected="true"`.
+- Keyboard: ArrowLeft/Right cycle between tabs. Home/End jump.
+- For tabs with associated panels: `aria-controls="panel-id"` + matching `role="tabpanel"` + `aria-labelledby="tab-id"`.
+- Disabled tabs are skipped in keyboard nav by default.
+
+## Edge cases
+
+- **Long labels in Korean** — Hangul is wider; expect tabs to overflow. Use `<Tabs variant="scrollable">` for horizontal scroll on overflow.
+- **Mobile narrow viewport** — `variant="fullWidth"` distributes tabs evenly; OK for ≤ 4 tabs. For 5+, switch to scrollable.
+- **Icon + label** — label first then icon-only on narrow → use `useMediaQuery` to switch `iconPosition`.
+- **Nested tabs** — discouraged but possible. Aria gets confusing; consider a sub-nav pattern instead.
+
+## Code example
+
+```tsx
+function AccountTabs() {
+  const [tab, setTab] = useState('profile');
+  const navigate = useNavigate();
+
+  return (
+    <Box sx={{ borderBottom: 1, borderColor: 'divider' }}>
+      <Tabs
+        value={tab}
+        onChange={(_, v) => { setTab(v); navigate(`/account/${v}`); }}
+        aria-label="계정 설정"
+        variant="scrollable"
+        scrollButtons="auto"
+      >
+        <Tab label="프로필" value="profile" />
+        <Tab label="보안" value="security" />
+        <Tab label="결제" value="billing" />
+        <Tab label="알림" value="notifications" />
+        <Tab label="개인정보" value="privacy" />
+      </Tabs>
+    </Box>
+  );
+}
+```
+
+## Don't
+
+- Don't use Tabs for binary on/off — use `Switch` or `ToggleButton`.
+- Don't put 2 separate Tabs sets on the same screen — confuses keyboard navigation.
+- Don't use Tab text as the page heading — they have separate semantics.
+
+## References
+
+- MUI: [`Tab`](../refs/mui/packages/mui-material/src/Tab/) + [`Tabs`](../refs/mui/packages/mui-material/src/Tabs/)
+
+## Cross-reference
+
+- [`component-tabs.md`](component-tabs.md)
+- [`component-bottom-navigation.md`](component-bottom-navigation.md)
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md)

package/examples/component-table-body.md

@@ -0,0 +1,82 @@
+# `TableBody` — spec
+
+> Synthesized from MUI `TableBody`. The container for data rows in a `Table`. Equivalent to `<tbody>` with consistent styling defaults.
+
+## When to use
+
+- Inside every `Table` that displays data rows.
+- For tables with no body (header-only summary), omit.
+
+## API
+
+```tsx
+<Table>
+  <TableHead>...</TableHead>
+  <TableBody>
+    {rows.map((row) => (
+      <TableRow key={row.id}>
+        <TableCell>{row.name}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | `TableRow` children |
+| `component` | `ElementType` | `'tbody'` | Override |
+
+## Accessibility
+
+Renders `<tbody>` — semantic role for table body comes for free. No additional ARIA needed.
+
+## Edge cases
+
+- **Empty state** — when `rows.length === 0`, render a single `TableRow` with one `TableCell` spanning all columns containing the empty-state message. Cite [`knowledge/patterns/empty-states.md`](../knowledge/patterns/empty-states.md).
+- **Loading state** — show skeleton rows or a single overlay. Don't leave the body empty during fetch — users see a flash.
+- **Virtualization** — for 100+ rows, use a virtualized table library (TanStack Virtual + MUI Table). MUI's `TableBody` doesn't virtualize automatically.
+
+## Code example
+
+```tsx
+{isLoading ? (
+  <TableBody>
+    {Array.from({ length: 5 }).map((_, i) => (
+      <TableRow key={i}>
+        {columns.map((col) => (
+          <TableCell key={col.key}><Skeleton /></TableCell>
+        ))}
+      </TableRow>
+    ))}
+  </TableBody>
+) : rows.length === 0 ? (
+  <TableBody>
+    <TableRow>
+      <TableCell colSpan={columns.length} align="center" sx={{ py: 8 }}>
+        결과가 없어요
+      </TableCell>
+    </TableRow>
+  </TableBody>
+) : (
+  <TableBody>
+    {rows.map((row) => <TableRow key={row.id}>...</TableRow>)}
+  </TableBody>
+)}
+```
+
+## Don't
+
+- Don't render rows outside `TableBody` (or `TableHead` / `TableFooter`).
+- Don't use for content that isn't tabular — Cards / Stacks fit better.
+
+## References
+
+- MUI: [`TableBody`](../refs/mui/packages/mui-material/src/TableBody/)
+
+## Cross-reference
+
+- [`component-table.md`](component-table.md)
+- [`component-table-row.md`](component-table-row.md)
+- [`component-table-cell.md`](component-table-cell.md)
+- [`knowledge/patterns/empty-states.md`](../knowledge/patterns/empty-states.md)

package/examples/component-table-cell.md

@@ -0,0 +1,118 @@
+# `TableCell` — spec
+
+> Synthesized from MUI `TableCell`. The single cell inside a `TableRow`. Handles padding density, alignment (number columns right-aligned by convention), header/body semantics via `component`.
+
+## When to use
+
+- Inside every `TableRow` (head, body, footer).
+- For every column of tabular data.
+
+## API
+
+```tsx
+<TableCell align="right" component="td" padding="normal">
+  {row.amount.toLocaleString('ko-KR')}원
+</TableCell>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'left' \| 'right' \| 'center' \| 'justify' \| 'inherit'` | `'inherit'` | Text alignment |
+| `padding` | `'normal' \| 'checkbox' \| 'none'` | `'normal'` | Padding profile (`checkbox` is narrow for selection columns) |
+| `size` | `'small' \| 'medium'` | inherited | Density |
+| `component` | `ElementType` | `'td'` (body) / `'th'` (head) | Override |
+| `scope` | `'col' \| 'row' \| 'colgroup' \| 'rowgroup'` | — | Header scope (use on `<th>` cells) |
+| `sortDirection` | `'asc' \| 'desc' \| false` | `false` | Sort indicator |
+| `variant` | `'head' \| 'body' \| 'footer'` | derived | Cell role |
+
+## States
+
+`TableCell` itself has no states. Selection / hover / active live on `TableRow`.
+
+## Tokens consumed
+
+```
+--table-cell-padding-x-normal   /* 16px */
+--table-cell-padding-x-checkbox /* 0 */
+--table-cell-padding-y          /* 16px (medium) / 8px (small) */
+--color-fg-default
+--color-fg-muted               /* head cells */
+--color-divider                /* bottom border */
+--font-size-body
+--font-size-small
+--font-weight-semibold         /* head cells */
+```
+
+## Accessibility
+
+- Header cells render as `<th>` automatically when inside `<TableHead>`. Add `scope="col"` for column headers (or `scope="row"` for row headers in side-headed tables).
+- For sort indicators, use `TableSortLabel` inside the cell — it provides keyboard activation + `aria-sort` on the cell.
+- Right-aligned numeric columns: `align="right"` is visual only. Screen readers still read in DOM order.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Alignment conventions
+
+- **Text columns** → `align="left"` (default in LTR locales).
+- **Numeric columns** → `align="right"`.
+- **Status / icon columns** → `align="center"`.
+- **Action columns (last)** → `align="right"`.
+- For Korean tables: same conventions; Korean reads left-to-right.
+
+## Edge cases
+
+- **Long text** — wraps. For ellipsis: wrap inner content in a `Box` with `noWrap` styling, AND set `Tooltip` to surface full text on hover.
+- **Numeric tabular alignment** — pair `align="right"` with `font-variant-numeric: tabular-nums` for clean column alignment regardless of digit width.
+- **Korean amount cells** — append `원` directly: `12,345원`. Don't put `원` in a separate column (creates layout waste).
+- **Empty cells** — render `—` (em-dash) rather than empty; signals "intentionally empty" vs "data not loaded".
+
+## Code example
+
+```tsx
+<TableHead>
+  <TableRow>
+    <TableCell scope="col">이름</TableCell>
+    <TableCell scope="col">부서</TableCell>
+    <TableCell scope="col" align="right">
+      <TableSortLabel
+        active={orderBy === 'amount'}
+        direction={order}
+        onClick={() => handleSort('amount')}
+      >
+        급여
+      </TableSortLabel>
+    </TableCell>
+    <TableCell scope="col" align="right">상태</TableCell>
+  </TableRow>
+</TableHead>
+<TableBody>
+  {employees.map((emp) => (
+    <TableRow key={emp.id} hover>
+      <TableCell>{emp.name}</TableCell>
+      <TableCell>{emp.department}</TableCell>
+      <TableCell align="right" sx={{ fontVariantNumeric: 'tabular-nums' }}>
+        {emp.salary.toLocaleString('ko-KR')}원
+      </TableCell>
+      <TableCell align="right">
+        <Chip label={emp.status} size="small" />
+      </TableCell>
+    </TableRow>
+  ))}
+</TableBody>
+```
+
+## Don't
+
+- Don't omit `scope` on header cells — accessibility miss.
+- Don't put block-level content (`Card`, full forms) inside cells — Tables aren't grid layouts.
+- Don't mix `padding="checkbox"` with non-checkbox content — use `padding="none"` for tighter control.
+
+## References
+
+- MUI: [`TableCell`](../refs/mui/packages/mui-material/src/TableCell/)
+
+## Cross-reference
+
+- [`component-table.md`](component-table.md)
+- [`component-table-row.md`](component-table-row.md)
+- [`component-table-sort-label.md`](component-table-sort-label.md)
+- [`component-table-head.md`](component-table-head.md)

package/examples/component-table-container.md

@@ -0,0 +1,75 @@
+# `TableContainer` — spec
+
+> Synthesized from MUI `TableContainer`. Wraps a `Table` to provide horizontal scroll, fixed height (with sticky header), and Paper styling. Without it, wide tables overflow the viewport ungracefully.
+
+## When to use
+
+- Every `Table` that might exceed viewport width on narrow screens.
+- Tables inside Cards/Papers where you want consistent elevation.
+- Tables with `stickyHeader` (requires `maxHeight` on container).
+
+## API
+
+```tsx
+<TableContainer component={Paper} sx={{ maxHeight: 480 }}>
+  <Table stickyHeader>
+    <TableHead>...</TableHead>
+    <TableBody>...</TableBody>
+  </Table>
+</TableContainer>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | A `Table` |
+| `component` | `ElementType` | `'div'` | Wrap as `Paper` for elevation |
+
+## Tokens consumed
+
+```
+--paper-bg
+--paper-shadow-1
+--paper-radius
+```
+
+## Accessibility
+
+- The container itself adds no a11y semantics.
+- For very wide tables that scroll horizontally, ensure keyboard users can navigate (the table itself stays focusable; arrow keys move within cells).
+- Set `tabIndex={0}` + `role="region"` + `aria-label` on the container to make scrolling discoverable to screen readers.
+
+## Edge cases
+
+- **`stickyHeader` without `maxHeight`** — header doesn't stick (needs a scrollable parent).
+- **Mobile pivot to card-list** — for very narrow viewports, breaking out of TableContainer entirely and rendering `<Stack><Card /></Stack>` reads better than horizontal scroll. Cite [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md).
+
+## Code example
+
+```tsx
+<TableContainer
+  component={Paper}
+  sx={{ maxHeight: 480 }}
+  tabIndex={0}
+  role="region"
+  aria-label="직원 명단"
+>
+  <Table stickyHeader>
+    <TableHead>...</TableHead>
+    <TableBody>...</TableBody>
+  </Table>
+</TableContainer>
+```
+
+## Don't
+
+- Don't use without a `Table` child.
+- Don't apply both `maxHeight` and `height: 100%` — unpredictable layout.
+
+## References
+
+- MUI: [`TableContainer`](../refs/mui/packages/mui-material/src/TableContainer/)
+
+## Cross-reference
+
+- [`component-table.md`](component-table.md)
+- [`component-table-pagination.md`](component-table-pagination.md)