@devalok/shilp-sutra 0.40.1 → 0.42.0

package/make-kit/components/select.md

@@ -0,0 +1,148 @@
+# Select
+
+Single-choice picker from a short fixed list. Use instead of `<select>`.
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectGroup,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+} from '@devalok/shilp-sutra/ui/select'
+```
+
+## When to use
+
+- Fixed list under ~15 items, no search needed (status, priority, role).
+- Need typeahead / search across many options? Use `<Combobox>`.
+- Free-text with suggestions? Use `<Autocomplete>`.
+- Multi-select? Use `<MultiSelect>` or `<Combobox multiple>`.
+- Yes/no toggle? Use `<Switch>` or `<RadioGroup>` with 2 options.
+
+## Compound shape
+
+```
+Select (root — value, onValueChange, defaultValue)
+  SelectTrigger              ← variant / color / size go HERE
+    SelectValue (placeholder)
+  SelectContent
+    SelectGroup (optional)
+      SelectLabel            ← non-interactive section header
+      SelectItem (value)     ← REQUIRED value, unique
+    SelectSeparator
+```
+
+## SelectTrigger props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `'default'\|'outline'\|'ghost'` | Default `default`. |
+| `color` | `'default'\|'error'\|'success'\|'warning'` | Default `default`. `error` sets `aria-invalid`. |
+| `size` | `'xs'\|'sm'\|'md'\|'lg'` | Default `md`. |
+
+Styling lives on the **Trigger**, not on `Select` root. Setting `<Select size="lg">` does nothing — TypeScript won't catch it.
+
+## Root state props (Radix passthrough)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` | `string` | Controlled value. |
+| `onValueChange` | `(value: string) => void` | Fires on select. |
+| `defaultValue` | `string` | Uncontrolled. |
+| `open` | `boolean` | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | |
+
+## Examples
+
+**Standard:**
+```tsx
+<Select onValueChange={setStatus}>
+  <SelectTrigger>
+    <SelectValue placeholder="Status" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="todo">To do</SelectItem>
+    <SelectItem value="doing">In progress</SelectItem>
+    <SelectItem value="done">Done</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**With grouped items and a separator:**
+```tsx
+<Select value={assignee} onValueChange={setAssignee}>
+  <SelectTrigger size="sm">
+    <SelectValue placeholder="Assignee" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Team</SelectLabel>
+      <SelectItem value="alice">Alice</SelectItem>
+      <SelectItem value="bob">Bob</SelectItem>
+    </SelectGroup>
+    <SelectSeparator />
+    <SelectGroup>
+      <SelectLabel>External</SelectLabel>
+      <SelectItem value="contractor-1">Contractor 1</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Inside a FormField (manual error wiring):**
+```tsx
+<FormField state={errors.role ? 'error' : 'helper'}>
+  <Label htmlFor="role">Role</Label>
+  <Select value={role} onValueChange={setRole}>
+    <SelectTrigger id="role" color={errors.role ? 'error' : 'default'}>
+      <SelectValue placeholder="Choose a role" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="admin">Admin</SelectItem>
+      <SelectItem value="member">Member</SelectItem>
+      <SelectItem value="viewer">Viewer</SelectItem>
+    </SelectContent>
+  </Select>
+  {errors.role && <FormHelperText>{errors.role}</FormHelperText>}
+</FormField>
+```
+
+Select doesn't auto-consume FormField context (unlike Input / Textarea). Set `color="error"` on `SelectTrigger` manually.
+
+**Ghost variant in a toolbar:**
+```tsx
+<Select value={sort} onValueChange={setSort} defaultValue="recent">
+  <SelectTrigger variant="ghost" size="sm">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="recent">Most recent</SelectItem>
+    <SelectItem value="oldest">Oldest</SelectItem>
+    <SelectItem value="az">A → Z</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Composability
+
+- **Radix Select** underneath — `value` / `onValueChange` / `defaultValue` / `open` / `onOpenChange` standard state.
+- **Portal + z-popover (1400):** SelectContent portals to body, stacks above Dialog / Sheet / other overlays.
+- **SelectItem requires a unique `value`** — duplicates produce undefined selection behavior.
+- **FormField integration is manual** — wire `color="error"` on SelectTrigger from your validation state.
+
+See `foundations/surfaces.md` for the overlay surface, `foundations/color.md` for state colors.
+
+## Rules
+
+- Put `variant` / `color` / `size` on `SelectTrigger`, NOT on `Select` root.
+- Every `SelectItem` needs a unique `value` prop.
+- For lists over ~15 items or when users will scan for a term, switch to `<Combobox>` — Select has no typeahead.
+- Set `color="error"` on `SelectTrigger` for validation failures — Select doesn't auto-consume FormField state.
+- Don't use Select for multi-value capture — use `<MultiSelect>` or `<Combobox multiple>`.
+- Always render `<SelectValue placeholder="..." />` — without it, the trigger renders empty before any selection.
+- Group related items with `<SelectGroup>` + `<SelectLabel>` — flat lists over 8 items get hard to scan.
+- Don't customize the dropdown surface — overlays use `surface-1` per `foundations/surfaces.md`.

package/make-kit/components/stack.md

@@ -0,0 +1,165 @@
+# Stack
+
+Flexbox layout primitive. Use instead of `<div className="flex flex-col gap-4">` everywhere.
+
+```tsx
+import { Stack } from '@devalok/shilp-sutra/ui/stack'
+```
+
+## When to use
+
+- Stacking elements vertically or horizontally with consistent gap.
+- Any time you'd write `flex` + `gap-*` + `items-*` + `justify-*` on a div.
+- Centering + width-capping a page section? Use `<Container>`, then a `<Stack>` inside.
+- Grid layouts (rows × columns)? Use a Tailwind `grid` div directly — Stack is for one-axis layouts.
+
+Server-safe — no hydration, no context.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `direction` | `'vertical'\|'horizontal'\|'row'\|'column'` | Default `vertical`. `row` = `horizontal`, `column` = `vertical` (aliases). |
+| `gap` | `'ds-01'..'ds-13'` \| `0..13` | Design-system spacing token. Numbers map 1:1 to `ds-0N`. |
+| `align` | `'start'\|'center'\|'end'\|'stretch'\|'baseline'` | Cross-axis alignment (`align-items`). |
+| `justify` | `'start'\|'center'\|'end'\|'between'\|'around'\|'evenly'` | Main-axis alignment (`justify-content`). |
+| `wrap` | `boolean` | Enables `flex-wrap`. |
+| `as` | `ElementType` | Default `'div'`. Polymorphic. |
+| `className` | `string` | For overrides — don't reach for raw `flex-*` utilities. |
+
+## Gap cadence
+
+Default to the 3-tier cadence from `foundations/spacing.md`:
+
+| Gap | Use |
+|---|---|
+| `ds-03` (8 px) | Related items inside a group (icon + label, button row). |
+| `ds-05` (16 px) | Grouped sections within a card / form. |
+| `ds-07` (32 px) | Page sections / major regions. |
+
+Don't reach for every adjacent token. If `ds-04` "feels right," it usually means a parent's padding or the section relationship needs a rethink.
+
+## Examples
+
+**Vertical form layout:**
+```tsx
+<Stack gap="ds-05">
+  <FormField>
+    <Label htmlFor="name">Name</Label>
+    <Input id="name" />
+  </FormField>
+  <FormField>
+    <Label htmlFor="email">Email</Label>
+    <Input id="email" />
+  </FormField>
+</Stack>
+```
+
+**Horizontal toolbar:**
+```tsx
+<Stack direction="horizontal" gap="ds-03" align="center">
+  <Button variant="soft" startIcon={IconFilter}>Filter</Button>
+  <Button variant="soft" startIcon={IconSortDescending}>Sort</Button>
+  <Separator orientation="vertical" className="h-6" />
+  <Button variant="solid" startIcon={IconPlus}>New</Button>
+</Stack>
+```
+
+**Avatar + label cluster:**
+```tsx
+<Stack direction="horizontal" gap="ds-03" align="center">
+  <Avatar size="sm" src={user.avatar} alt={user.name} />
+  <Stack gap="ds-01">
+    <Text variant="label-plain-sm">{user.name}</Text>
+    <Text variant="body-xs" className="text-fg-muted">{user.role}</Text>
+  </Stack>
+</Stack>
+```
+
+**Page-section spacing:**
+```tsx
+<Container>
+  <Stack gap="ds-07">
+    <PageHeader title="Projects" description="A workspace for everything you ship." />
+    <Stack gap="ds-05">
+      <SectionHeader title="Active" />
+      <ProjectGrid projects={active} />
+    </Stack>
+    <Stack gap="ds-05">
+      <SectionHeader title="Archived" />
+      <ProjectGrid projects={archived} />
+    </Stack>
+  </Stack>
+</Container>
+```
+
+**Wrap for tag cluster:**
+```tsx
+<Stack direction="horizontal" gap="ds-02" wrap>
+  {tags.map((tag) => <Badge key={tag} color="neutral">{tag}</Badge>)}
+</Stack>
+```
+
+For tag clusters specifically, prefer `<Badge.Group>` — it handles overflow with `+N` automatically.
+
+**Justify-between (label + action):**
+```tsx
+<Stack direction="horizontal" gap="ds-04" align="center" justify="between">
+  <Text variant="heading-md">Team</Text>
+  <Button variant="soft" startIcon={IconPlus} size="sm">Invite</Button>
+</Stack>
+```
+
+**Polymorphic — semantic list:**
+```tsx
+<Stack as="ul" gap="ds-03">
+  {items.map((item) => (
+    <Stack as="li" key={item.id} direction="horizontal" gap="ds-03" align="center">
+      <Icon icon={IconCheck} />
+      <Text variant="body-sm">{item.label}</Text>
+    </Stack>
+  ))}
+</Stack>
+```
+
+**Numeric gap shortcut:**
+```tsx
+<Stack gap={5}>  {/* same as gap="ds-05" */}
+  …
+</Stack>
+```
+
+**Inside Card (no extra padding):**
+```tsx
+<Card>
+  <CardContent>
+    <Stack gap="ds-04">
+      <Text variant="label-sm" className="text-fg-muted">REVENUE</Text>
+      <Text variant="heading-xl">$2.4M</Text>
+      <Text variant="body-sm" className="text-fg-muted">+18% YoY</Text>
+    </Stack>
+  </CardContent>
+</Card>
+```
+
+CardContent already supplies the outer padding. Stack just spaces the children.
+
+## Composability
+
+- **Server-safe.** Nothing to hydrate. Use in RSC trees.
+- **Polymorphic via `as`** — `<Stack as="ul">`, `<Stack as="section">`, `<Stack as="nav">`. Inherits flex behavior on the chosen element.
+- **Compose with Container:** `<Container><Stack>...</Stack></Container>`. Container centers + caps width; Stack arranges children.
+- **No responsive direction prop** — for `flex-col md:flex-row` use a plain div with Tailwind utilities directly, or render two Stacks with display toggling.
+
+See `foundations/spacing.md` for the gap cadence, `foundations/surfaces.md` for layout-on-surfaces context.
+
+## Rules
+
+- Default to the `ds-03 / ds-05 / ds-07` cadence. Reach for other tokens only with a deliberate reason.
+- Use Stack everywhere you'd write `flex` + `gap` on a div. Don't mix Stack and raw flex utilities in the same tree.
+- For grid (2D) layouts, use a plain `grid` div. Stack is one-axis only.
+- For responsive direction changes, drop to a plain div with Tailwind responsive flex utilities. Stack doesn't have a responsive direction prop.
+- Don't add padding to a Stack — wrap it in a Container or Card. Padding lives on containers, not layout primitives.
+- For tag clusters with potential overflow, use `<Badge.Group>` instead of `<Stack wrap>` — it handles `+N` collapsing.
+- Numeric `gap={4}` and string `gap="ds-04"` are equivalent. Pick a convention per file and stick with it.
+- `direction="row"` and `direction="column"` are aliases for `horizontal` / `vertical`. Pick one naming pair per codebase.

package/make-kit/components/table.md

@@ -0,0 +1,215 @@
+# Table
+
+Server-safe semantic wrappers around `<table>`. For static / presentational tables.
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from '@devalok/shilp-sutra/ui/table'
+```
+
+## When to use
+
+- Static or small data displays where you control every row and cell.
+- Marketing / pricing comparison tables.
+- Documentation tables (API references, prop tables).
+- Server-rendered tables (RSC) — Table and sub-components are server-safe.
+- Need sorting / filtering / pagination / selection / virtualization? Use `<DataTable>` from `@devalok/shilp-sutra/ui/data-table` — out of scope for this guide.
+
+## Compound shape
+
+```
+Table (<table>)
+  TableCaption (<caption>)        ← optional summary for screen readers
+  TableHeader (<thead>)
+    TableRow (<tr>)
+      TableHead (<th scope="col">)
+  TableBody (<tbody>)
+    TableRow (<tr>)
+      TableCell (<td>)
+  TableFooter (<tfoot>)
+    TableRow
+      TableCell
+```
+
+Each component is a thin semantic wrapper — no props beyond standard HTML attributes plus `className`.
+
+## Examples
+
+**Standard:**
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+      <TableHead>Owner</TableHead>
+      <TableHead>Updated</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {projects.map((p) => (
+      <TableRow key={p.id}>
+        <TableCell>{p.name}</TableCell>
+        <TableCell>
+          <Badge color={p.status === 'active' ? 'success' : 'neutral'}>
+            {p.status}
+          </Badge>
+        </TableCell>
+        <TableCell>
+          <Stack direction="horizontal" gap="ds-02" align="center">
+            <Avatar size="xs" src={p.owner.avatar} alt={p.owner.name} />
+            <Text variant="body-sm">{p.owner.name}</Text>
+          </Stack>
+        </TableCell>
+        <TableCell>
+          <Text variant="body-sm" className="text-fg-muted">
+            {formatDate(p.updatedAt)}
+          </Text>
+        </TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+**With caption + footer:**
+```tsx
+<Table>
+  <TableCaption>Q4 revenue by region.</TableCaption>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Region</TableHead>
+      <TableHead>Revenue</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow><TableCell>NA</TableCell><TableCell>$1.2M</TableCell></TableRow>
+    <TableRow><TableCell>EU</TableCell><TableCell>$0.8M</TableCell></TableRow>
+    <TableRow><TableCell>APAC</TableCell><TableCell>$0.4M</TableCell></TableRow>
+  </TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell><Text variant="label-sm">Total</Text></TableCell>
+      <TableCell><Text variant="label-sm">$2.4M</Text></TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```
+
+**Row actions (IconButton in last cell):**
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>File</TableHead>
+      <TableHead>Size</TableHead>
+      <TableHead className="w-12" />
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {files.map((f) => (
+      <TableRow key={f.id}>
+        <TableCell>{f.name}</TableCell>
+        <TableCell>{formatFileSize(f.size)}</TableCell>
+        <TableCell>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <IconButton icon={<Icon icon={IconDots} />} variant="ghost" size="sm" aria-label="Actions" />
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuItem onSelect={() => download(f)}>Download</DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem onSelect={() => remove(f)}>Delete</DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+**Inside a Card:**
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team members</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Member</TableHead>
+          <TableHead>Role</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {members.map((m) => (
+          <TableRow key={m.id}>
+            <TableCell>{m.name}</TableCell>
+            <TableCell><Badge color="neutral">{m.role}</Badge></TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  </CardContent>
+</Card>
+```
+
+When inside a `<Card>`, the Table's surrounding padding comes from `CardContent`. Don't add extra padding on the Table.
+
+**Server-rendered table (RSC):**
+```tsx
+// app/projects/page.tsx — no 'use client'
+export default async function ProjectsPage() {
+  const projects = await db.projects.findMany()
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Name</TableHead>
+          <TableHead>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {projects.map((p) => (
+          <TableRow key={p.id}>
+            <TableCell>{p.name}</TableCell>
+            <TableCell><Badge>{p.status}</Badge></TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  )
+}
+```
+
+Table + Badge (server-safe via Badge.Group context — verify per use) + Avatar all render in RSC trees. Skip client components.
+
+## Composability
+
+- **Server-safe:** Table and its sub-components are pure HTML semantic wrappers. No state, no context. Use in RSC trees without `'use client'`.
+- **TableHead scope:** Headers automatically get `scope="col"` for screen-reader navigation. Don't override it.
+- **Composes with primitives:** Drop `<Badge>`, `<Avatar>`, `<IconButton>`, `<StatusDot>` inside cells. Check each component's server-safety if you need RSC compatibility.
+- **TableCaption:** Renders as HTML `<caption>` — screen readers announce it before content. Use it for any non-trivial table.
+
+See `foundations/typography.md` for the body / label variants inside cells, `foundations/surfaces.md` for table-in-card surface guidance.
+
+## Rules
+
+- For anything with sorting / filtering / pagination / selection / virtualization, use `<DataTable>` from `/ui/data-table`. Don't rebuild that machinery on bare Table.
+- Always wrap header cells in `<TableHead>` (renders `<th>`). Don't use `<TableCell>` (`<td>`) in headers — breaks screen-reader column scope.
+- Use `<TableCaption>` for any table that's not self-evident. Renders the HTML `<caption>` which screen readers announce.
+- Inside Card, drop the Table directly in `<CardContent>` — don't add wrapper divs that fight the card's padding cascade.
+- For wide tables on mobile, wrap in an `overflow-x-auto` container. Don't try to make a Table responsive via column stacking — switch to a card list on small viewports.
+- Don't style cell text with raw Tailwind palette utilities. Use `text-fg-muted` from `foundations/color.md`.
+- Compose with Badge for status, Avatar for users, IconButton for row actions. Don't invent new primitives per table.
+- Keep TableCell content single-line where possible — multi-line cells make scanning hard. Use `<Stack>` only when each row genuinely needs two lines.

package/make-kit/components/tabs.md

@@ -0,0 +1,162 @@
+# Tabs
+
+Switch between sibling views inside a single region. Not for top-level navigation.
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@devalok/shilp-sutra/ui/tabs'
+```
+
+## When to use
+
+- Sub-sections of a single page / panel that share context (Overview / Activity / Settings on a project).
+- Filtered views over the same dataset (All / Mine / Archived).
+- Need URL-driven routes per tab? Wire `value` / `onValueChange` to router state.
+- Top-level app navigation? Use `<Sidebar>` / `<TopBar>`, not Tabs.
+- Multi-step flows? Use `<Stepper>` or a wizard pattern.
+
+## Compound shape
+
+```
+Tabs (root — value, defaultValue, onValueChange)
+  TabsList (variant, size, orientation)
+    TabsTrigger (value)         ← inherits variant/size/orientation from TabsList
+  TabsContent (value)           ← rendered inline (not portalled)
+```
+
+## TabsList props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `'line'\|'contained'` | Default `line`. |
+| `size` | `'sm'\|'md'\|'lg'` | Default `md`. |
+| `orientation` | `'horizontal'\|'vertical'` | Default `horizontal`. Vertical also changes keyboard nav to ArrowUp/Down. |
+| `color` | `'accent'\|'neutral'` | Affects the line-variant active indicator. |
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `line` (default) | Underline active indicator. Most common — pairs with section headings. |
+| `contained` | Pill background per active trigger. Use inside cards or compact toolbars. |
+
+## Root state props (Radix passthrough)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` | `string` | Controlled active tab. |
+| `defaultValue` | `string` | Uncontrolled initial tab. |
+| `onValueChange` | `(value: string) => void` | Fires on tab change. |
+
+## TabsTrigger / TabsContent
+
+Both require a `value: string` prop. The values must match between a trigger and its content.
+
+`TabsTrigger` reads `variant` / `size` / `orientation` from `TabsList` via context. Override per-trigger if needed, but normally don't.
+
+## Examples
+
+**Standard line tabs:**
+```tsx
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+    <TabsTrigger value="settings">Settings</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">
+    <ProjectOverview />
+  </TabsContent>
+  <TabsContent value="activity">
+    <ActivityFeed />
+  </TabsContent>
+  <TabsContent value="settings">
+    <ProjectSettings />
+  </TabsContent>
+</Tabs>
+```
+
+**Contained variant inside a card:**
+```tsx
+<Card>
+  <CardContent>
+    <Tabs defaultValue="day">
+      <TabsList variant="contained" size="sm">
+        <TabsTrigger value="day">Day</TabsTrigger>
+        <TabsTrigger value="week">Week</TabsTrigger>
+        <TabsTrigger value="month">Month</TabsTrigger>
+      </TabsList>
+      <TabsContent value="day"><Chart range="day" /></TabsContent>
+      <TabsContent value="week"><Chart range="week" /></TabsContent>
+      <TabsContent value="month"><Chart range="month" /></TabsContent>
+    </Tabs>
+  </CardContent>
+</Card>
+```
+
+**Vertical orientation (settings-style):**
+```tsx
+<Tabs defaultValue="account" orientation="vertical">
+  <Stack direction="horizontal" gap="ds-07" align="start">
+    <TabsList orientation="vertical">
+      <TabsTrigger value="account">Account</TabsTrigger>
+      <TabsTrigger value="billing">Billing</TabsTrigger>
+      <TabsTrigger value="notifications">Notifications</TabsTrigger>
+    </TabsList>
+    <div className="flex-1">
+      <TabsContent value="account"><AccountForm /></TabsContent>
+      <TabsContent value="billing"><BillingForm /></TabsContent>
+      <TabsContent value="notifications"><NotificationsForm /></TabsContent>
+    </div>
+  </Stack>
+</Tabs>
+```
+
+**With icons + badges:**
+```tsx
+<Tabs defaultValue="inbox">
+  <TabsList>
+    <TabsTrigger value="inbox">
+      <Icon icon={IconInbox} /> Inbox
+      <Badge size="xs" color="accent">12</Badge>
+    </TabsTrigger>
+    <TabsTrigger value="sent">
+      <Icon icon={IconSend} /> Sent
+    </TabsTrigger>
+  </TabsList>
+  <TabsContent value="inbox"><InboxList /></TabsContent>
+  <TabsContent value="sent"><SentList /></TabsContent>
+</Tabs>
+```
+
+**Router-driven (Next.js App Router):**
+```tsx
+'use client'
+const router = useRouter()
+const pathname = usePathname()
+const tab = pathname.split('/').pop() ?? 'overview'
+
+<Tabs value={tab} onValueChange={(v) => router.push(`/projects/${id}/${v}`)}>
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+</Tabs>
+```
+
+## Composability
+
+- **Context cascade:** `TabsList` propagates `variant` / `size` / `orientation` to every child `TabsTrigger`. Don't repeat those props on each trigger.
+- **Inline content:** `TabsContent` renders inline (not portalled). Container-scoped queries in tests work.
+- **Keyboard:** Roving tabindex via Radix — ArrowLeft/Right (horizontal) or ArrowUp/Down (vertical). Home / End jump to first / last. Don't re-implement.
+
+See `foundations/spacing.md` for the gap between TabsList and TabsContent, `foundations/icons.md` for icon sizing inside triggers.
+
+## Rules
+
+- Put `variant` / `size` / `orientation` on `TabsList`, NOT on `Tabs` root or `TabsTrigger`.
+- Every `TabsTrigger` and `TabsContent` needs a `value` — the values must match.
+- For top-level app navigation use Sidebar / TopBar, not Tabs.
+- Don't stack two Tabs inside the same region — pick one. Nested tabs confuse keyboard nav and section structure.
+- For router-bound tabs, keep `value` controlled — don't mix `defaultValue` with router-driven URLs.
+- For 5+ tabs that overflow on mobile, consider a Select dropdown on small viewports or wrap in a horizontally scrollable container.
+- Icons in TabsTrigger don't auto-size via IconProvider — set explicit `<Icon icon={...} size="sm" />` when the trigger feels off.