@design-ai/cli 4.55.0

package/examples/component-table.md

@@ -0,0 +1,202 @@
+# `Table` — spec
+
+> Citing Ant Design `Table`, MUI `DataGrid` / `Table`, shadcn-ui `data-table` (TanStack Table)
+
+## Purpose
+
+Displays multi-column data for comparison and analysis. Optimized for desktop. On mobile, **most tables should become stacked card lists** — see edge cases.
+
+When NOT to use: single-attribute lists (use `List`); items where each row is a self-contained card (use card list).
+
+## Anatomy
+
+```
+[Toolbar?]              search · filter · density · column-toggle · export
+┌──────────────────────────────────────────────────────────────────────┐
+│ ☐  Header 1 ▾    Header 2     Header 3 ▾                  Actions ▾ │  ← sticky
+├──────────────────────────────────────────────────────────────────────┤
+│ ☐  cell 1.1      cell 1.2     cell 1.3                    [...]     │
+│ ☐  cell 2.1      cell 2.2     cell 2.3                    [...]     │
+│ ─────────────────────────────────────────────────────────────────── │
+│   ...                                                                │
+└──────────────────────────────────────────────────────────────────────┘
+[Footer]                  selected count · pagination · summary
+```
+
+## API (TanStack Table-flavored, framework-agnostic)
+
+```tsx
+<Table
+  columns={[
+    { id: "name", header: "이름", accessor: (row) => row.name, sortable: true, width: 180 },
+    { id: "email", header: "이메일", accessor: (row) => row.email, width: 220 },
+    { id: "amount", header: "금액", accessor: (row) => row.amount, sortable: true, align: "right", cell: (v) => formatKRW(v) },
+    { id: "actions", header: "", cell: (_, row) => <ActionsMenu row={row} />, width: 64 },
+  ]}
+  data={data}
+  selectable
+  onSelectionChange={setSelection}
+  sortBy={sort}
+  onSortChange={setSort}
+  pagination={{ pageSize: 20, total, onChange: setPage }}
+  density="md"
+  emptyState={<EmptyState />}
+  loading={isPending}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` | `Column[]` | — | Column definitions |
+| `data` | `T[]` | `[]` | Row data |
+| `selectable` | `boolean` | `false` | Adds checkbox column |
+| `sortable` | per-column | — | Click header to toggle asc/desc/none |
+| `pagination` | `{ pageSize, total, onChange }` | — | Server or client pagination |
+| `density` | `"compact" \| "md" \| "comfortable"` | `"md"` | Row height |
+| `stickyHeader` | `boolean` | `true` | Header pins on scroll |
+| `loading` | `boolean` | `false` | Skeleton rows |
+| `emptyState` | `ReactNode` | default | Replaces tbody when `data.length === 0` |
+| `onRowClick` | `(row) => void` | — | Drill into detail. Doesn't conflict with checkbox. |
+| `getRowId` | `(row) => string` | `row.id` | For React keys + selection |
+
+### Column definition
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | Stable key for sort/visibility |
+| `header` | `ReactNode` | — | Header content |
+| `accessor` | `(row) => any` | `row[id]` | How to extract the value |
+| `cell` | `(value, row) => ReactNode` | `value as string` | How to render |
+| `sortable` | `boolean` | `false` | |
+| `align` | `"left" \| "right" \| "center"` | `"left"` | Right for numbers/amounts |
+| `width` | `number \| string` | auto | Fixed or `min-content`/`1fr` |
+| `sticky` | `"left" \| "right"` | — | Pin column for horizontal scroll (e.g., name on left, actions on right) |
+
+## Density
+
+| Density | Row height | Use |
+| --- | --- | --- |
+| `compact` | 32px | Power user, > 100 rows visible |
+| `md` (default) | 40px | Standard product table |
+| `comfortable` | 48px | Marketing pages, fewer rows |
+
+User-facing density toggle in toolbar is common. Persist preference to localStorage.
+
+## Sort
+
+- Header click cycles: `asc` → `desc` → `none`.
+- Visual: arrow indicator, `▲` asc / `▼` desc / muted both when none.
+- One-column at a time by default. Multi-sort via `Shift+click` (desktop power users). Document in tooltip.
+- Server-side sort: re-fetch on change. Client-side: just re-render.
+
+## Selection
+
+- Checkbox column on far left.
+- "Select all" checkbox in header. Three states: unchecked / partial / checked.
+- "Select all 142" affordance when paginated: "All 20 on this page selected. **[Select all 142]**" — clarifies vs. "select all visible".
+- Bulk actions appear in a contextual bar that **replaces the toolbar** when selection > 0:
+
+  ```
+  ┌─────────────────────────────────────────────────────┐
+  │  3 selected   [Archive] [Delete] [Export] · ✕       │
+  └─────────────────────────────────────────────────────┘
+  ```
+
+## Pagination
+
+See [examples/component-pagination.md](component-pagination.md) for the standalone Pagination spec.
+
+For tables: footer-mounted, right-aligned. Show "1–20 of 142" + page controls + page size selector.
+
+## Empty / loading / error
+
+- **Loading first paint**: render header + 5 skeleton rows.
+- **Loading after data exists** (refetch): show subtle progress in header, keep stale data visible.
+- **Empty**: full-row span: illustration + "데이터가 없어요" + optional CTA.
+- **Error**: full-row span: error icon + message + retry. Cite [knowledge/patterns/list-and-feed.md](../knowledge/patterns/list-and-feed.md).
+
+## Accessibility
+
+- Use semantic `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`. Don't fake with `<div>` unless absolutely necessary (and then use `role="table"` etc.).
+- `<th scope="col">` on column headers, `<th scope="row">` on row labels.
+- For sortable columns: `aria-sort="ascending" | "descending" | "none"` on `<th>`.
+- Keyboard: arrow keys move focus across cells; Enter/Space activates header (sort) or cell (if interactive).
+- Screen reader: announce row/column count on table render. Announce sort change.
+- Selection: each checkbox has a label like "Select row for 김민지".
+- Bulk action bar: `role="region" aria-label="Bulk actions"`.
+
+## Mobile — break to cards
+
+A 5-column table is unusable on a 375px screen. Two approaches:
+
+### 1. Card list
+
+Below `md` breakpoint, render as a card per row:
+
+```
+┌────────────────────────────────────┐
+│ 김민지                              │
+│ minji@example.com                   │
+│                                    │
+│ 결제: ₩45,000                       │
+│ 상태: 완료                           │
+│                                    │
+│              [상세 보기]   [더보기 ⋮] │
+└────────────────────────────────────┘
+```
+
+Each card shows the same data as a row but vertically. The "primary" column (name) becomes the heading.
+
+### 2. Horizontal scroll
+
+Keep the table but enable horizontal scroll. **Pin** the first column (name) so it stays visible.
+
+Pick #1 for product UIs, #2 for power-user data tools.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated         (sticky header background)
+--color-bg-subtle           (zebra rows or hover)
+--color-border-default
+--color-text-primary
+--color-text-secondary
+--color-primary-default     (selected row indicator)
+--space-md, --space-base
+--font-size-sm, --font-size-base
+```
+
+## Edge cases
+
+- **Long text in cells**: truncate to 1 line with `…`, `title` attr for full. Optionally allow row expansion to wrap.
+- **Numeric columns**: right-align, tabular numerals. See [knowledge/patterns/money-and-amount.md](../knowledge/patterns/money-and-amount.md).
+- **Sticky columns + horizontal scroll**: pin the leftmost (name/identifier) and the rightmost (actions). Middle columns scroll.
+- **Frozen header on tall tables**: use CSS `position: sticky` on `<thead>`. Not `<table>` height tricks.
+- **Click row to drill in vs. interactive controls in cells**: `onClick` on the row, but `e.stopPropagation()` on inner buttons (checkbox, menu). Or use the block-link pattern from [examples/component-card.md](component-card.md).
+- **CSV export**: include the export button in the toolbar; prefer client-side generation for ≤ 10K rows, server-generated download for larger.
+
+## Don't
+
+- Don't use a Table for a 1-column list. Use a List.
+- Don't auto-update sort/filter on every keystroke in toolbar inputs — debounce 300ms.
+- Don't paginate to "1, 2, 3, ..., 142, last" as the only nav. Provide page-size + jump-to-page.
+- Don't allow horizontal scroll on mobile by default — user expects vertical-only.
+- Don't put primary CTAs in cells unless the row is the action target (e.g., "Approve" per row in an admin queue).
+
+## References
+
+- Ant Design: [`refs/ant-design/components/table/`](../refs/ant-design/components/table/) — most exhaustive: tree data, expandable rows, virtual scroll, drag-drop column reorder, fixed headers/columns. Heavy but production-grade.
+- MUI: `<Table>` (basic) and `<DataGrid>` (heavy, paid for some features). DataGrid has best DX for filtering/sorting but is a large dep.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/table.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/table.tsx) — primitives only (`<Table>`, `<TableHeader>`, etc.). Pair with TanStack Table for behavior. **Recommended modern pattern.**
+
+API choices made:
+- **TanStack Table as the engine** — headless, framework-agnostic, free, mature. Don't reinvent.
+- **Sort/filter state controlled** by default — server-side pagination is the common case.
+- **Mobile fallback as a designed escape hatch** (card list) rather than horizontal scroll.
+
+## Cross-reference
+
+- [knowledge/patterns/list-and-feed.md](../knowledge/patterns/list-and-feed.md)
+- [knowledge/patterns/money-and-amount.md](../knowledge/patterns/money-and-amount.md) — amount columns
+- [examples/component-pagination.md](component-pagination.md) — table footer pagination

package/examples/component-tabs.md

@@ -0,0 +1,184 @@
+# `Tabs` — spec
+
+> Citing Ant Design `Tabs`, MUI `Tabs`, shadcn-ui `tabs`. Includes mobile bottom-tab variant.
+
+## Purpose
+
+Tabs let users switch between mutually exclusive views without navigating away. Different from navigation — tabs stay on the same screen.
+
+Three variants in one spec, same a11y contract:
+
+| Variant | Use |
+| --- | --- |
+| `tabs` (default) | In-page section switcher (Profile / Activity / Settings) |
+| `segmented` (pill group) | Compact filter switch (오늘 / 이번 주 / 이번 달) |
+| `bottom-tab-bar` (mobile) | App-level top destinations — see [knowledge/patterns/mobile-navigation.md](../knowledge/patterns/mobile-navigation.md) |
+
+## Anatomy — `tabs` and `segmented`
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Profile  │ Activity  │ Settings                     │  ← TabList
+├──────────┴────────────────────────────────────────── │  ← active indicator (underline or pill)
+│                                                      │
+│  TabPanel content for active tab                     │
+│                                                      │
+└─────────────────────────────────────────────────────┘
+```
+
+```tsx
+<Tabs defaultValue="profile">
+  <Tabs.List>
+    <Tabs.Trigger value="profile">Profile</Tabs.Trigger>
+    <Tabs.Trigger value="activity">Activity</Tabs.Trigger>
+    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="profile">...</Tabs.Content>
+  <Tabs.Content value="activity">...</Tabs.Content>
+  <Tabs.Content value="settings">...</Tabs.Content>
+</Tabs>
+```
+
+## API
+
+| Prop (root) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string` | — | Active tab. Controlled / uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Fires on change |
+| `variant` | `"underline" \| "segmented" \| "card" \| "bottom-bar"` | `"underline"` | Visual treatment |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Side-tab pattern with vertical |
+| `activationMode` | `"automatic" \| "manual"` | `"automatic"` | Auto-activate on focus (default) or wait for Enter/Space |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `fullWidth` | `boolean` | `false` | TabList stretches; each trigger gets equal width (segmented only) |
+
+| Prop (trigger) | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Required. Matches `Tabs.Content` value. |
+| `disabled` | `boolean` | |
+| `iconStart` | `ReactNode` | Icon before label |
+| `badge` | `ReactNode` | Count or status indicator |
+
+## Variants
+
+### `underline` (default — Ant / Material style)
+
+Bottom border under active tab. The tab label sits above a shared baseline. Most common for in-page tab switching.
+
+### `segmented` (iOS-native pill)
+
+```
+┌────────────────────────────────────────┐
+│ ┌────────┐ ┌────────┐ ┌────────┐       │
+│ │ Today  │ │  Week  │ │ Month  │       │
+│ └────────┘ └────────┘ └────────┘       │
+└────────────────────────────────────────┘
+```
+
+- All tabs in a single rounded container.
+- Active tab has filled background.
+- Use for: time-period filters, view-mode toggles (List / Grid), 3–5 short labels max.
+- iOS-native segmented control is the visual reference.
+
+### `card` (top-edge tabs)
+
+Each tab is a card with a top border. Active card "merges" into the panel below. Less common; used in tabbed forms or settings panels.
+
+### `bottom-bar` (mobile only)
+
+See [knowledge/patterns/mobile-navigation.md](../knowledge/patterns/mobile-navigation.md). Same a11y contract; visual is fixed at bottom of viewport.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default (inactive) | Muted text, no border/bg |
+| Hover | Slight bg shift |
+| Active | `--color-primary-default` text + indicator (underline or pill bg) |
+| Focus-visible | 2px ring around the trigger |
+| Disabled | 50% opacity, no events |
+
+## Tokens consumed
+
+```
+--color-text-secondary    (inactive)
+--color-text-primary      (hover)
+--color-primary-default   (active)
+--color-bg-subtle         (hover bg, segmented inactive bg)
+--color-bg-default        (segmented active bg)
+--space-md, --space-base
+--radius-md               (segmented pills)
+--motion-fast, --easing-out  (underline indicator slide)
+```
+
+## Sizes
+
+| Size | Trigger height | Font | Padding-x |
+| --- | --- | --- | --- |
+| `sm` | 32px | 13px | 12px |
+| `md` | 40px | 14px | 16px |
+| `lg` | 48px | 16px | 20px |
+
+## Accessibility — WAI-ARIA Tabs Pattern
+
+Critical contract — get this exactly right:
+
+- `Tabs.List` has `role="tablist"`.
+- Each `Tabs.Trigger` has `role="tab"`, `aria-selected="true|false"`, `aria-controls="<panel-id>"`.
+- Each `Tabs.Content` has `role="tabpanel"`, `aria-labelledby="<trigger-id>"`, `tabIndex={0}`.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Moves into the tab list. Inside the list, focus goes to the active trigger. Tabs again to leave the list (NOT cycle through tabs). |
+| `←` / `→` | Move focus between triggers (horizontal) |
+| `↑` / `↓` | Move focus between triggers (vertical) |
+| `Home` / `End` | First / last trigger |
+| `Enter` / `Space` | Activate the focused trigger (manual mode only) |
+
+### `activationMode`
+
+- `"automatic"` (default): focus a trigger → tab activates. Faster scanning. Good for quick browse.
+- `"manual"`: focus moves but tab doesn't activate until Enter/Space. Use when activating is expensive (loads heavy content, makes API call).
+
+### Screen reader
+
+- Active tab announces "selected".
+- TabList reads as "tab list" with N tabs.
+- TabPanel content is announced when activated (via `aria-controls` link).
+- Don't add custom `aria-live` to tab content — switching tabs is user-driven.
+
+## Edge cases
+
+- **Many tabs (> 5–6)**: scroll horizontally with overflow. Add chevrons (`<` `>`) to scroll. **Don't** use a "More" tab as a dropdown — accessibility breaks.
+- **Tab content height varies**: panel height adjusts on switch; consider `min-height` on the container to prevent layout shift between tab activations.
+- **Lazy loading panels**: render only the active panel for performance, but **mount** all on first activation if you need form state preserved across switches. Trade-off: memory vs. data loss on switch.
+- **URL sync**: tab state often syncs to URL hash or query (`?tab=settings`). Use shadcn/Radix `Tabs` with `value` controlled from `useSearchParams`. Browser back/forward then works.
+- **RTL**: arrow keys reverse, indicator direction reverses. Use logical CSS.
+- **Korean labels**: shorter is better for tabs (1–2 syllables). "프로필" (profile), "활동" (activity), "설정" (settings).
+
+## Don't
+
+- Don't put more than 5–6 tabs in a row without scroll. Consider whether a sidebar or different navigation fits better.
+- Don't use tabs as a substitute for navigation. Tabs stay on the same screen; navigation changes URL/screen.
+- Don't add an "All" tab if it shows a union — show "All" by default and let users filter.
+- Don't load all tab content eagerly if any tab is expensive.
+- Don't use bottom-tab-bar variant for in-page switching. It's reserved for app-level navigation.
+- Don't combine tabs + breadcrumbs at the same level — pick one.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/tabs/`](../refs/ant-design/components/tabs/) — `Tabs`, `Tabs.TabPane`, supports `card`/`line`/`editable-card` variants. Most variants out of the box.
+- MUI: [`refs/mui/packages/mui-material/src/Tabs/`](../refs/mui/packages/mui-material/src/Tabs/) — `Tabs` + `Tab` + `TabPanel` (separately). MUI has good `scrollable` props.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/tabs.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/tabs.tsx) — Radix Tabs primitive. Cleanest a11y. **Default for new projects.**
+
+API choices made:
+- **Composition with `Tabs.Trigger` / `Tabs.Content`** matching value strings — Radix pattern, lowest surface area.
+- **`activationMode` exposed** rather than hard-coded — different UIs benefit from different defaults.
+- **`bottom-bar` listed as a variant** rather than a separate component — same WAI-ARIA pattern, just a positioning detail.
+
+## Cross-reference
+
+- [knowledge/patterns/mobile-navigation.md](../knowledge/patterns/mobile-navigation.md) — bottom-tab-bar specifics
+- [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md)