@design-ai/cli 4.55.0

package/examples/component-table-footer.md

@@ -0,0 +1,72 @@
+# `TableFooter` — spec
+
+> Synthesized from MUI `TableFooter`. The container for footer rows in a `Table` — totals, summaries, or pagination. Renders `<tfoot>`.
+
+## When to use
+
+- Tables with totals/subtotals row (sum of an amount column).
+- Tables with `TablePagination` rendered inside the table (rather than below).
+
+## API
+
+```tsx
+<Table>
+  <TableHead>...</TableHead>
+  <TableBody>...</TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell colSpan={2}>합계</TableCell>
+      <TableCell align="right">{total.toLocaleString('ko-KR')}원</TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | `TableRow` (typically one) |
+| `component` | `ElementType` | `'tfoot'` | Override |
+
+## Accessibility
+
+- `<tfoot>` semantics communicate "summary row" to screen readers.
+- For totals: the row label cell uses `scope="row"` so the total cell is properly associated.
+
+## Edge cases
+
+- **Multiple footer rows** — fine; common for layered summaries (subtotal, tax, total).
+- **Korean total labels** — "합계", "총액", "소계 / 부가세 / 합계" — keep in 합쇼체 or noun-form.
+
+## Code example
+
+```tsx
+<TableFooter>
+  <TableRow>
+    <TableCell colSpan={2} scope="row">소계</TableCell>
+    <TableCell align="right" sx={{ fontVariantNumeric: 'tabular-nums' }}>
+      {subtotal.toLocaleString('ko-KR')}원
+    </TableCell>
+  </TableRow>
+  <TableRow>
+    <TableCell colSpan={2} scope="row">부가세 (10%)</TableCell>
+    <TableCell align="right">{tax.toLocaleString('ko-KR')}원</TableCell>
+  </TableRow>
+  <TableRow sx={{ '& td': { fontWeight: 600 } }}>
+    <TableCell colSpan={2} scope="row">합계</TableCell>
+    <TableCell align="right">{total.toLocaleString('ko-KR')}원</TableCell>
+  </TableRow>
+</TableFooter>
+```
+
+## Don't
+
+- Don't use as a wrapper for non-summary rows (filters, etc.) — that's a sibling component, not the footer.
+
+## References
+
+- MUI: [`TableFooter`](../refs/mui/packages/mui-material/src/TableFooter/)
+
+## Cross-reference
+
+- [`component-table.md`](component-table.md)
+- [`component-table-row.md`](component-table-row.md)

package/examples/component-table-head.md

@@ -0,0 +1,78 @@
+# `TableHead` — spec
+
+> Synthesized from MUI `TableHead`. The container for header rows in a `Table`. Renders `<thead>` with semibold cell text and `<th>` semantics on inner `TableCell`s.
+
+## When to use
+
+- Every `Table` with column labels (almost all of them).
+- For tables with sortable columns, header cells contain `TableSortLabel`.
+
+## API
+
+```tsx
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableCell scope="col">이름</TableCell>
+      <TableCell scope="col" align="right">금액</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>...</TableBody>
+</Table>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | `TableRow` (typically one) |
+| `component` | `ElementType` | `'thead'` | Override |
+
+## Accessibility
+
+- `TableCell` children inside `TableHead` automatically render as `<th>`.
+- Add `scope="col"` to each header cell — required for screen readers to associate columns with body cells.
+- For multi-row headers, use `<TableRow>` siblings inside `TableHead` and `colspan` / `rowspan` on cells.
+
+## Edge cases
+
+- **Sticky header** — set `<TableContainer sx={{ maxHeight: 400 }}>` + `<Table stickyHeader>` to keep headers visible during scroll.
+- **Mobile narrow viewport** — Tables don't scale well; switch to card-list layout. Cite [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md).
+- **Korean column labels** — keep short (1-3 words). Long labels wrap or truncate; truncated headers are confusing.
+
+## Code example
+
+```tsx
+<TableContainer component={Paper} sx={{ maxHeight: 480 }}>
+  <Table stickyHeader>
+    <TableHead>
+      <TableRow>
+        <TableCell scope="col">이름</TableCell>
+        <TableCell scope="col">부서</TableCell>
+        <TableCell scope="col" align="right">
+          <TableSortLabel active direction="asc" onClick={onSort}>
+            입사일
+          </TableSortLabel>
+        </TableCell>
+      </TableRow>
+    </TableHead>
+    <TableBody>
+      {employees.map((emp) => <EmployeeRow key={emp.id} {...emp} />)}
+    </TableBody>
+  </Table>
+</TableContainer>
+```
+
+## Don't
+
+- Don't omit `scope="col"` — accessibility miss.
+- Don't put body rows inside `TableHead`.
+- Don't style header cells with body-cell typography — keep semibold semantic distinction.
+
+## References
+
+- MUI: [`TableHead`](../refs/mui/packages/mui-material/src/TableHead/)
+
+## Cross-reference
+
+- [`component-table.md`](component-table.md)
+- [`component-table-cell.md`](component-table-cell.md)
+- [`component-table-sort-label.md`](component-table-sort-label.md)

package/examples/component-table-pagination.md

@@ -0,0 +1,137 @@
+# `TablePagination` — spec
+
+> Synthesized from MUI `TablePagination`. The pagination controls for a `Table` — page size selector + page navigation + total count display. Sits in `TableFooter` or below the table container.
+
+## When to use
+
+- Tables with > 25 rows where users need to navigate pages.
+- For client-side pagination of small datasets, prefer `Pagination` component (decoupled from Table).
+
+## When NOT to use
+
+- Infinite-scroll feeds → use `Load More` button or auto-load on scroll. Cite [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md).
+- Single-page tables → no pagination control.
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────────────────┐
+│  Rows per page: [10 ▼]   1-10 of 234   [<] [>] [>>]    │
+└────────────────────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<TablePagination
+  component="div"
+  count={total}
+  page={page}
+  onPageChange={(_, newPage) => setPage(newPage)}
+  rowsPerPage={pageSize}
+  onRowsPerPageChange={(e) => {
+    setPageSize(parseInt(e.target.value, 10));
+    setPage(0);
+  }}
+  rowsPerPageOptions={[10, 25, 50, 100]}
+  labelRowsPerPage="페이지당 행"
+  labelDisplayedRows={({ from, to, count }) => `${from}-${to} / 전체 ${count}`}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `count` | `number` | required | Total row count |
+| `page` | `number` | required | Current page (0-indexed) |
+| `onPageChange` | `(e, page) => void` | required | Page change handler |
+| `rowsPerPage` | `number` | required | Current page size |
+| `onRowsPerPageChange` | `(e) => void` | — | Page-size change handler |
+| `rowsPerPageOptions` | `number[]` | `[10, 25, 50, 100]` | Page-size options (or `[]` to hide selector) |
+| `labelRowsPerPage` | `ReactNode` | `'Rows per page:'` | Selector label |
+| `labelDisplayedRows` | `({ from, to, count }) => ReactNode` | — | Range label formatter |
+| `showFirstButton` / `showLastButton` | `boolean` | `false` | Show first/last page jumps |
+| `component` | `ElementType` | `'td'` | Override (use `'div'` outside Table footer) |
+| `SelectProps` | `SelectProps` | — | Customize the page-size Select |
+| `getItemAriaLabel` | `(type) => string` | — | Customize button aria-labels |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| First page | Previous button disabled |
+| Last page | Next button disabled |
+| All pages fit on one | Pagination collapses; only count shows |
+
+## Tokens consumed
+
+```
+--table-pagination-min-height-52
+--font-size-body
+--space-md
+```
+
+## Accessibility
+
+- Buttons have `aria-label` (Previous/Next/First/Last). Localize via `getItemAriaLabel`.
+- The page-size Select needs an associated label — `labelRowsPerPage` provides it.
+- Korean: provide `labelDisplayedRows` formatter that uses Korean range syntax: `1-10 / 전체 234`.
+- Announce page changes via `aria-live="polite"` if context requires (e.g., screen reader users navigating large tables).
+
+## Edge cases
+
+- **`count={-1}` (unknown total)** — pagination shows "1-10 of more than 10" (with `labelDisplayedRows` returning that string). Useful for cursor-based APIs.
+- **Korean pluralization** — there's none in Korean; "1 결과" and "234 결과" both fine. Don't try to pluralize.
+- **Mobile narrow** — buttons + Select can wrap awkwardly. Consider hiding `rowsPerPageOptions` on mobile (`rowsPerPageOptions={[]}`).
+
+## Code example
+
+```tsx
+function EmployeesTable() {
+  const [page, setPage] = useState(0);
+  const [pageSize, setPageSize] = useState(25);
+  const { data, total } = useEmployees({ page, pageSize });
+
+  return (
+    <Paper>
+      <TableContainer>
+        <Table>
+          <TableHead>...</TableHead>
+          <TableBody>
+            {data.map((emp) => <EmployeeRow key={emp.id} {...emp} />)}
+          </TableBody>
+        </Table>
+      </TableContainer>
+      <TablePagination
+        component="div"
+        count={total}
+        page={page}
+        onPageChange={(_, p) => setPage(p)}
+        rowsPerPage={pageSize}
+        onRowsPerPageChange={(e) => {
+          setPageSize(parseInt(e.target.value, 10));
+          setPage(0);
+        }}
+        rowsPerPageOptions={[10, 25, 50, 100]}
+        labelRowsPerPage="페이지당 행"
+        labelDisplayedRows={({ from, to, count }) => `${from}-${to} / 전체 ${count}`}
+      />
+    </Paper>
+  );
+}
+```
+
+## Don't
+
+- Don't reset `page` to 0 implicitly when filters change without surfacing the reset to the user (sudden page jumps confuse).
+- Don't put 1000+ rows on one page — slow render + bad UX.
+- Don't use English labels in a Korean UI.
+
+## References
+
+- MUI: [`TablePagination`](../refs/mui/packages/mui-material/src/TablePagination/)
+
+## Cross-reference
+
+- [`component-table.md`](component-table.md)
+- [`component-pagination.md`](component-pagination.md)
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md)

package/examples/component-table-row.md

@@ -0,0 +1,113 @@
+# `TableRow` — spec
+
+> Synthesized from MUI `TableRow`. A row inside a `Table`. Handles selection state, hover styling, zebra striping. Used for both `<tbody>` rows and `<thead>` header rows.
+
+## When to use
+
+- Inside any `Table` body or head.
+- For non-tabular data (cards, lists), don't use TableRow.
+
+## API
+
+```tsx
+<TableRow hover selected={isSelected} onClick={() => onSelect(row.id)}>
+  <TableCell padding="checkbox">
+    <Checkbox checked={isSelected} />
+  </TableCell>
+  <TableCell>{row.name}</TableCell>
+  <TableCell align="right">{row.amount.toLocaleString('ko-KR')}원</TableCell>
+</TableRow>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | TableCell children |
+| `hover` | `boolean` | `false` | Enable hover bg |
+| `selected` | `boolean` | `false` | Selected styling (bg-selected) |
+| `onClick` | `(e) => void` | — | Row click handler |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | transparent / zebra |
+| Hover (with `hover`) | bg-subtle |
+| Selected | bg-selected (brand-tinted) |
+| Focus-visible | 2px ring inset |
+
+## Tokens consumed
+
+```
+--table-row-bg
+--table-row-bg-zebra
+--table-row-bg-hover
+--table-row-bg-selected
+--table-row-min-height-48
+--color-divider
+```
+
+## Accessibility
+
+- Renders as `<tr>`. Native semantics handle row/column relationships.
+- For selectable rows with `onClick`, also support keyboard (Enter/Space). MUI doesn't add this automatically — wrap in `tabIndex={0}` + onKeyDown handler.
+- For selected rows, screen readers announce based on the inner Checkbox state, not `selected` prop.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Whole-row click** — convenient but can conflict with cell-level clicks (link inside, button). Use `e.stopPropagation()` on inner interactives.
+- **Korean amount alignment** — `align="right"` on numeric cells; use `font-variant-numeric: tabular-nums` for clean column alignment.
+- **Long cell content** — wraps by default; use `noWrap` on Typography or `overflow: hidden` for ellipsis.
+
+## Code example
+
+```tsx
+<TableContainer>
+  <Table>
+    <TableHead>
+      <TableRow>
+        <TableCell padding="checkbox">
+          <Checkbox checked={allSelected} onChange={toggleAll} />
+        </TableCell>
+        <TableCell>이름</TableCell>
+        <TableCell>부서</TableCell>
+        <TableCell align="right">입사일</TableCell>
+      </TableRow>
+    </TableHead>
+    <TableBody>
+      {employees.map((emp) => (
+        <TableRow
+          key={emp.id}
+          hover
+          selected={selected.has(emp.id)}
+          onClick={() => toggleSelect(emp.id)}
+        >
+          <TableCell padding="checkbox">
+            <Checkbox checked={selected.has(emp.id)} />
+          </TableCell>
+          <TableCell>{emp.name}</TableCell>
+          <TableCell>{emp.department}</TableCell>
+          <TableCell align="right">{formatDate(emp.hireDate)}</TableCell>
+        </TableRow>
+      ))}
+    </TableBody>
+  </Table>
+</TableContainer>
+```
+
+## Don't
+
+- Don't put TableRow outside a Table — semantics break.
+- Don't use TableRow for card layouts — use Stack / Grid.
+- Don't omit a key when mapping.
+
+## References
+
+- MUI: [`TableRow`](../refs/mui/packages/mui-material/src/TableRow/)
+
+## Cross-reference
+
+- [`component-table.md`](component-table.md)
+- [`component-table-cell.md`](component-table-cell.md)
+- [`component-table-body.md`](component-table-body.md)
+- [`component-table-head.md`](component-table-head.md)

package/examples/component-table-sort-label.md

@@ -0,0 +1,109 @@
+# `TableSortLabel` — spec
+
+> Synthesized from MUI `TableSortLabel`. The clickable sort indicator inside a header `TableCell`. Shows the current sort direction (ascending / descending) + click handler to toggle.
+
+## When to use
+
+- Inside header `TableCell`s of sortable columns.
+- For non-sortable columns, render plain text in the TableCell.
+
+## API
+
+```tsx
+<TableCell sortDirection={orderBy === 'name' ? order : false}>
+  <TableSortLabel
+    active={orderBy === 'name'}
+    direction={orderBy === 'name' ? order : 'asc'}
+    onClick={() => handleSort('name')}
+  >
+    이름
+  </TableSortLabel>
+</TableCell>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` | `false` | This column is currently sorted |
+| `direction` | `'asc' \| 'desc'` | `'asc'` | Sort direction (ignored when not active) |
+| `hideSortIcon` | `boolean` | `false` | Hide arrow when not active (cleaner default; arrow appears on hover) |
+| `IconComponent` | `ElementType` | `ArrowDownwardIcon` | Custom sort icon |
+| `onClick` | `(e) => void` | — | Toggle handler |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default (not active) | Label only; no arrow (or arrow on hover if `hideSortIcon=false`) |
+| Active asc | Label + up arrow |
+| Active desc | Label + down arrow |
+| Hover (any) | Subtle bg + arrow visible |
+| Focus-visible | 2px focus ring |
+
+## Tokens consumed
+
+```
+--icon-size-sm           /* sort arrow */
+--color-fg-default
+--color-fg-muted         /* inactive arrow */
+--motion-duration-100    /* arrow rotation */
+```
+
+## Accessibility
+
+- Renders as `<button>` — keyboard activates with Enter/Space.
+- Pair with `TableCell sortDirection={...}` to set `aria-sort` correctly. MUI handles the cell side automatically.
+- Korean: arrow direction is universal; the label localizes naturally.
+
+## Edge cases
+
+- **Tri-state sort** (asc → desc → unsorted → asc...) — implement in your `onClick`. MUI doesn't enforce tri-state by default; common is asc ↔ desc.
+- **Multi-column sort** — possible but UX-confusing for most adopters. Stick to single-column unless data work warrants it.
+- **Default sort** — set initial `orderBy` + `order` state on mount; first render shows the active arrow.
+
+## Code example
+
+```tsx
+function SortableHeader({ orderBy, order, onSort }) {
+  const cell = (key, label, align = 'left') => (
+    <TableCell
+      align={align}
+      sortDirection={orderBy === key ? order : false}
+      scope="col"
+    >
+      <TableSortLabel
+        active={orderBy === key}
+        direction={orderBy === key ? order : 'asc'}
+        onClick={() => onSort(key)}
+      >
+        {label}
+      </TableSortLabel>
+    </TableCell>
+  );
+
+  return (
+    <TableHead>
+      <TableRow>
+        {cell('name', '이름')}
+        {cell('department', '부서')}
+        {cell('hireDate', '입사일', 'right')}
+        {cell('salary', '급여', 'right')}
+      </TableRow>
+    </TableHead>
+  );
+}
+```
+
+## Don't
+
+- Don't put `TableSortLabel` outside a `TableCell` — `aria-sort` won't propagate.
+- Don't use for non-sortable columns — confuses users when clicking does nothing.
+- Don't omit `aria-label` if the column header is icon-only (pair with `aria-label="정렬: 이름"` or similar).
+
+## References
+
+- MUI: [`TableSortLabel`](../refs/mui/packages/mui-material/src/TableSortLabel/)
+
+## Cross-reference
+
+- [`component-table-cell.md`](component-table-cell.md)
+- [`component-table-head.md`](component-table-head.md)