@tailor-platform/app-shell 1.15.0 → 1.16.0

package/skills/app-shell-patterns/references/components/sidebar-layout.md

@@ -0,0 +1,258 @@
+---
+title: SidebarLayout
+description: Default AppShell layout with a built-in sidebar, content header, optional app-wide top bar, and an escape-hatch body slot
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/sidebar-layout.docs.outline.md — do not edit by hand. -->
+
+# SidebarLayout
+
+`SidebarLayout` is the default AppShell layout. By default it renders:
+
+- `SidebarLayout.DefaultSidebar`
+- `SidebarLayout.DefaultHeader`
+- the current route outlet
+
+You can replace the sidebar, replace the content header, add a full-width `topBar` above the whole shell, or take over the entire region beside the sidebar with the `body` slot.
+
+If you want the opinionated "global app header + icon rail" mode, use [`GlobalHeaderLayout`](./global-header-layout.md), which is built on top of `SidebarLayout`.
+
+## Import
+
+```tsx
+import { SidebarLayout } from "@tailor-platform/app-shell";
+```
+
+## Basic usage
+
+```tsx
+import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";
+
+function App() {
+  return (
+    <AppShell modules={modules}>
+      <SidebarLayout />
+    </AppShell>
+  );
+}
+```
+
+This gives you:
+
+- ✅ Responsive sidebar with auto-generated navigation from modules
+- ✅ Breadcrumb navigation
+- ✅ Theme toggle via the built-in header
+- ✅ Mobile-friendly collapse behavior
+
+## Props
+
+### Common props
+
+| Prop          | Type              | Default                            | Description                                                                                                  |
+| ------------- | ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `sidebar`     | `React.ReactNode` | `<SidebarLayout.DefaultSidebar />` | Replaces the entire sidebar region.                                                                          |
+| `defaultOpen` | `boolean`         | `true`                             | Whether the sidebar starts expanded on desktop.                                                              |
+| `collapsible` | `boolean`         | `true`                             | Whether the sidebar can be collapsed. When `false`, toggle controls are hidden and `defaultOpen` is ignored. |
+| `topBar`      | `React.ReactNode` | -                                  | Full-width bar above both the sidebar and the content region.                                                |
+
+### Default content mode
+
+Use this when AppShell should keep owning the content column.
+
+| Prop       | Type                                                            | Default                           | Description                                                 |
+| ---------- | --------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------- |
+| `header`   | `React.ReactNode`                                               | `<SidebarLayout.DefaultHeader />` | Replaces the content header above the main column.          |
+| `children` | `(props: { Outlet: () => React.ReactNode }) => React.ReactNode` | current route outlet              | Custom content renderer that wraps or surrounds the outlet. |
+
+### Body-slot mode
+
+Use this when you need to compose your own columns beside the sidebar.
+
+| Prop   | Type              | Default  | Description                                                                                                   |
+| ------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `body` | `React.ReactNode` | required | Replaces everything to the right of the sidebar. Compose it with `ContentContainer`, `Outlet`, and `Trigger`. |
+
+`body` is mutually exclusive with `header` and `children`, because it replaces the region those props normally describe.
+
+## Extending the built-in header
+
+The supported "small customization" path is to pass `SidebarLayout.DefaultHeader` into the `header` slot and fill its `actions` cluster.
+
+```tsx
+import { AppearanceSwitcher, Button, SidebarLayout } from "@tailor-platform/app-shell";
+import { BellIcon } from "lucide-react";
+
+<SidebarLayout
+  header={
+    <SidebarLayout.DefaultHeader
+      actions={[
+        <Button key="notifications" variant="outline" size="icon" aria-label="Notifications">
+          <BellIcon className="size-4" />
+        </Button>,
+        <AppearanceSwitcher key="appearance" />,
+      ]}
+    />
+  }
+/>;
+```
+
+`actions` replaces the entire right-hand cluster. If you still want the built-in appearance switcher, include `<AppearanceSwitcher />` yourself.
+
+## Replacing the sidebar
+
+Pass `sidebar` to replace the whole left-side region. The built-in component is [`SidebarLayout.DefaultSidebar`](./default-sidebar.md), also exported as `DefaultSidebar`.
+
+```tsx
+import {
+  SidebarGroup,
+  SidebarItem,
+  SidebarLayout,
+  SidebarSeparator,
+} from "@tailor-platform/app-shell";
+
+<SidebarLayout
+  sidebar={
+    <SidebarLayout.DefaultSidebar>
+      <SidebarItem to="/" />
+      <SidebarSeparator />
+      <SidebarGroup title="Main">
+        <SidebarItem to="/dashboard" />
+        <SidebarItem to="/orders" />
+      </SidebarGroup>
+    </SidebarLayout.DefaultSidebar>
+  }
+/>;
+```
+
+## Adding an app-wide top bar
+
+`topBar` renders above the whole shell, spanning both the sidebar and the content region.
+
+```tsx
+<SidebarLayout topBar={<MyGlobalTopBar />} sidebar={<SidebarLayout.DefaultSidebar hideHeader />} />
+```
+
+When `topBar` is present, the fixed sidebar is offset below it. The bar should be `3.5rem` tall (`h-14`) to match the built-in layout.
+
+If you specifically want AppShell's opinionated global-header mode, use [`GlobalHeaderLayout`](./global-header-layout.md), which wires the top bar, icon rail, and matching default sidebar for you.
+
+## Owning the region beside the sidebar
+
+Use `body` when the stock content column is too restrictive and you need your own side columns.
+
+```tsx
+<SidebarLayout
+  body={
+    <>
+      <aside className="w-64 shrink-0 overflow-y-auto border-r">
+        <TableOfContents />
+      </aside>
+      <SidebarLayout.ContentContainer header={<SidebarLayout.DefaultHeader />}>
+        <SidebarLayout.Outlet />
+      </SidebarLayout.ContentContainer>
+      <aside className="w-96 shrink-0 overflow-y-auto border-l">
+        <AssistantPanel />
+      </aside>
+    </>
+  }
+/>
+```
+
+`SidebarLayout.ContentContainer` is the stock main column: inset padding, pinned header slot, scroll region, and `useAppShellScrollContainer()` support. `SidebarLayout.Trigger` exposes the built-in sidebar toggle so custom headers do not need DOM workarounds.
+
+## Reading and controlling the sidebar
+
+Use `useAppShellSidebar()` to read and control the sidebar state instead of observing internal DOM attributes or clicking the trigger through the DOM.
+
+```tsx
+import { useAppShellSidebar } from "@tailor-platform/app-shell";
+
+function CustomHeader() {
+  const { open, isMobile, toggle } = useAppShellSidebar();
+
+  return (
+    <div className="flex items-center justify-between border-b px-4 py-3">
+      <button type="button" onClick={toggle}>
+        {open ? "Hide navigation" : "Show navigation"}
+      </button>
+      <span>{isMobile ? "Mobile" : "Desktop"}</span>
+    </div>
+  );
+}
+```
+
+Outside `SidebarLayout`, the hook returns a safe fallback (`open: true`, `isMobile: false`, no-op setters) rather than throwing.
+
+## Reusing the built-in breadcrumb
+
+`DynamicBreadcrumb` is exported when you want the same route-driven breadcrumb in a custom header or top bar:
+
+```tsx
+import { DynamicBreadcrumb, SidebarLayout } from "@tailor-platform/app-shell";
+
+<header className="flex items-center gap-3 border-b px-4 py-3">
+  <SidebarLayout.Trigger />
+  <DynamicBreadcrumb />
+</header>;
+```
+
+## Accessing the content scroll container
+
+The AppShell is viewport-bounded (`h-svh`), so the **document itself does not scroll** — the content area does. Code that previously relied on `window`/document scroll (reading `window.scrollY`, listening to `window`'s `scroll` event, `window.scrollTo(...)`, or an `IntersectionObserver` with the default viewport root) should target the content scroll container instead.
+
+Use the `useAppShellScrollContainer()` hook to get a ref to that element from any page:
+
+```tsx
+import { useAppShellScrollContainer } from "@tailor-platform/app-shell";
+import { useEffect, useState } from "react";
+
+function ReadingProgress() {
+  const scrollRef = useAppShellScrollContainer();
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const onScroll = () => {
+      const max = el.scrollHeight - el.clientHeight;
+      setProgress(max > 0 ? el.scrollTop / max : 0);
+    };
+    onScroll();
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, [scrollRef]);
+
+  return <progress value={progress} />;
+}
+```
+
+The same element handles imperative scrolling (`scrollRef.current?.scrollTo({ top: 0, behavior: "smooth" })`) and works as an `IntersectionObserver` root (`new IntersectionObserver(cb, { root: scrollRef.current })`).
+
+Notes:
+
+- The element mounts with the layout, above your page, so read `ref.current` inside an effect — it is populated by the time effects run, not during render.
+- On a [`<Layout fill>`](./layout.md#fill-mode) page this element does **not** scroll; its children (for example a `DataTable`) manage their own scrolling.
+- Outside a `SidebarLayout` (a fully custom layout) the returned ref's `current` is always `null` — such layouts own their own scroll region.
+- For non-React access (CSS, tests, plain DOM) the container also carries a `data-appshell-scroll-container` attribute: `document.querySelector("[data-appshell-scroll-container]")`.
+
+## Styling
+
+The sidebar and layout are styled with the library's internal `astw:`-prefixed utilities. Write **plain** Tailwind utilities in your own markup — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components).
+
+## Accessibility
+
+SidebarLayout includes built-in accessibility features:
+
+- **Keyboard navigation** for sidebar interaction
+- **ARIA labels** on built-in controls
+- **Focus management** when the sidebar opens on mobile
+- **Responsive behavior** that works with keyboard, mouse, and touch input
+
+## Related
+
+- [AppShell](./app-shell.md) - root component
+- [DefaultHeader](./default-header.md) - built-in content header (`SidebarLayout.DefaultHeader`)
+- [DefaultSidebar](./default-sidebar.md) - built-in sidebar (`SidebarLayout.DefaultSidebar`)
+- [GlobalHeaderLayout](./global-header-layout.md) - opinionated app-wide header mode built on SidebarLayout
+- [AppearanceSwitcher](./appearance-switcher.md) - color-theme dropdown for header actions
+- [usePageMeta](../api/use-page-meta.md) - route metadata lookup used by sidebar items

package/skills/app-shell-patterns/references/components/spinner.md

@@ -0,0 +1,81 @@
+---
+title: Spinner
+description: Lightweight loading indicator component with accessible defaults and preset sizes
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/spinner.docs.outline.md — do not edit by hand. -->
+
+# Spinner
+
+`Spinner` is AppShell's reusable loading indicator. It renders a small rotating SVG and is used throughout the built-in UI for loading states such as `ActionPanel`, command palette search, and CSV import progress.
+
+## Import
+
+```tsx
+import { Spinner } from "@tailor-platform/app-shell";
+```
+
+## Basic usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return <Spinner aria-label="Loading" />;
+}
+```
+
+## Props
+
+`Spinner` accepts all standard `<svg>` props plus one AppShell prop:
+
+| Prop   | Type                                | Default     | Description                                                                |
+| ------ | ----------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| `size` | `"xs" \| "sm" \| "default" \| "lg"` | `"default"` | Preset square size. Ignored when `width` or `height` is passed explicitly. |
+
+Preset sizes map to:
+
+| `size`      | Pixels |
+| ----------- | ------ |
+| `"xs"`      | `12`   |
+| `"sm"`      | `14`   |
+| `"default"` | `16`   |
+| `"lg"`      | `20`   |
+
+## Accessibility
+
+`Spinner` defaults to decorative output unless you give it an accessible name:
+
+- with `aria-label` or `aria-labelledby`, it renders with `role="status"`
+- with `aria-hidden={true}`, it stays decorative
+- with neither, it is treated as decorative and gets `aria-hidden="true"`
+
+Use a label when the spinner is the primary visible loading affordance:
+
+```tsx
+<Spinner size="sm" aria-label="Loading orders" />
+```
+
+When the surrounding control already has its own accessible name, keep the spinner decorative:
+
+```tsx
+<Button disabled>
+  <Spinner size="sm" aria-hidden />
+  Saving
+</Button>
+```
+
+## Sizing and styling
+
+Pass ordinary Tailwind utilities through `className` for color and layout, or override the dimensions directly with `width` / `height`.
+
+```tsx
+<Spinner className="text-muted-foreground" />
+<Spinner size="lg" className="text-primary" aria-label="Generating report" />
+<Spinner width={24} height={24} aria-label="Loading" />
+```
+
+## Related
+
+- [ActionPanel](./action-panel.md) - uses `Spinner` for per-row loading states
+- [WithGuard](./with-guard.md) - common place to render a loading spinner while guards resolve

package/skills/app-shell-patterns/references/components/table.md

@@ -0,0 +1,188 @@
+---
+title: Table
+description: Semantic HTML table with pre-styled sub-components
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/table.docs.outline.md — do not edit by hand. -->
+
+# Table
+
+The `Table` component provides a set of pre-styled, semantic HTML table sub-components. It wraps a standard `<table>` element in a horizontally scrollable container.
+
+## Import
+
+```tsx
+import { Table } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Table.Root>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Name</Table.Head>
+          <Table.Head>Email</Table.Head>
+          <Table.Head>Role</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Alice</Table.Cell>
+          <Table.Cell>alice@example.com</Table.Cell>
+          <Table.Cell>Admin</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component   | HTML element | Description                            |
+| --------------- | ------------ | -------------------------------------- |
+| `Table.Root`    | `<table>`    | Root element with scrollable container |
+| `Table.Header`  | `<thead>`    | Table header section                   |
+| `Table.Body`    | `<tbody>`    | Table body section                     |
+| `Table.Footer`  | `<tfoot>`    | Table footer section                   |
+| `Table.Row`     | `<tr>`       | Table row (hover and selection styles) |
+| `Table.Head`    | `<th>`       | Header cell                            |
+| `Table.Cell`    | `<td>`       | Data cell                              |
+| `Table.Caption` | `<caption>`  | Table caption                          |
+
+## Props
+
+### Table.Root Props
+
+| Prop                 | Type                        | Default | Description                                                       |
+| -------------------- | --------------------------- | ------- | ----------------------------------------------------------------- |
+| `className`          | `string`                    | -       | Additional CSS classes for the `<table>` element                  |
+| `containerClassName` | `string`                    | -       | Additional CSS classes for the outer scrollable `<div>` container |
+| `containerRef`       | `React.Ref<HTMLDivElement>` | -       | Ref forwarded to the outer scrollable `<div>` container           |
+
+All other standard HTML `<table>` props are accepted.
+
+All other sub-components (`Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`) accept `className` and their corresponding standard HTML element props.
+
+`Table.Head` and `Table.Cell` also accept `align?: "left" | "center" | "right"` for semantic text alignment without relying on utility-class overrides.
+
+## Examples
+
+### With Footer
+
+```tsx
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Product</Table.Head>
+      <Table.Head>Qty</Table.Head>
+      <Table.Head>Price</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Widget A</Table.Cell>
+      <Table.Cell>10</Table.Cell>
+      <Table.Cell>$100.00</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>Widget B</Table.Cell>
+      <Table.Cell>5</Table.Cell>
+      <Table.Cell>$75.00</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+  <Table.Footer>
+    <Table.Row>
+      <Table.Cell colSpan={2}>Total</Table.Cell>
+      <Table.Cell>$175.00</Table.Cell>
+    </Table.Row>
+  </Table.Footer>
+</Table.Root>
+```
+
+### With Caption
+
+```tsx
+<Table.Root>
+  <Table.Caption>Order line items</Table.Caption>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Item</Table.Head>
+      <Table.Head>Status</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Item 1</Table.Cell>
+      <Table.Cell>Shipped</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
+
+### Right-aligned numeric columns
+
+```tsx
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Item</Table.Head>
+      <Table.Head align="right">Amount</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Widget A</Table.Cell>
+      <Table.Cell align="right">123</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
+
+### Center-aligned status column
+
+```tsx
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Item</Table.Head>
+      <Table.Head align="center">Status</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Widget A</Table.Cell>
+      <Table.Cell align="center">Active</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
+
+### Constrained Height with Scroll
+
+```tsx
+<Table.Root containerClassName="max-h-64 overflow-y-auto">
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Name</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    {items.map((item) => (
+      <Table.Row key={item.id}>
+        <Table.Cell>{item.name}</Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+</Table.Root>
+```
+
+## Related Components
+
+- [Badge](./badge.md) - Display status inside table cells
+- [Layout](./layout.md) - Place tables inside page layouts

package/skills/app-shell-patterns/references/components/tabs.md

@@ -0,0 +1,158 @@
+---
+title: Tabs
+description: Tab navigation with a compound component API
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/tabs.docs.outline.md — do not edit by hand. -->
+
+# Tabs
+
+The `Tabs` component provides tab-based navigation for toggling between related panels on the same page. It is backed by Base UI's Tabs primitive.
+
+## Import
+
+```tsx
+import { Tabs } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List>
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="projects">Projects</Tabs.Tab>
+        <Tabs.Tab value="account">Account</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+      <Tabs.Panel value="projects">Projects content</Tabs.Panel>
+      <Tabs.Panel value="account">Account content</Tabs.Panel>
+    </Tabs.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| `Tabs.Root`   | Manages tab selection state                                    |
+| `Tabs.List`   | Groups the individual tab buttons                              |
+| `Tabs.Tab`    | An interactive tab button that toggles the corresponding panel |
+| `Tabs.Panel`  | A panel displayed when the corresponding tab is active         |
+
+## Props
+
+### Tabs.Root Props
+
+| Prop            | Type                                | Default     | Description                                                   |
+| --------------- | ----------------------------------- | ----------- | ------------------------------------------------------------- |
+| `defaultValue`  | `Tabs.Tab.Value`                    | `0`         | Initial active tab value (uncontrolled)                       |
+| `value`         | `Tabs.Tab.Value`                    | -           | Controlled active tab value                                   |
+| `onValueChange` | `(value: any) => void`              | -           | Callback when the active tab changes                          |
+| `variant`       | `'default' \| 'line' \| 'capsule'`  | `'default'` | Visual style of the tabs                                      |
+| `size`          | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Minimum size (`capsule` only) — mirrors Button's height tiers |
+| `className`     | `string`                            | -           | Additional CSS classes for root                               |
+| `children`      | `React.ReactNode`                   | -           | Tabs sub-components                                           |
+
+### Tabs.List Props
+
+Accepts `className` and all standard HTML `<div>` props.
+
+### Tabs.Tab Props
+
+| Prop       | Type             | Default | Description                        |
+| ---------- | ---------------- | ------- | ---------------------------------- |
+| `value`    | `Tabs.Tab.Value` | -       | **Required.** The value of the tab |
+| `disabled` | `boolean`        | -       | Whether the tab is disabled        |
+
+Also accepts `className` and all standard HTML `<button>` props.
+
+### Tabs.Panel Props
+
+| Prop          | Type             | Default | Description                                            |
+| ------------- | ---------------- | ------- | ------------------------------------------------------ |
+| `value`       | `Tabs.Tab.Value` | -       | **Required.** The value matching the corresponding tab |
+| `keepMounted` | `boolean`        | `false` | Whether to keep the panel in the DOM when hidden       |
+
+Also accepts `className` and all standard HTML `<div>` props.
+
+## Controlled Usage
+
+```tsx
+const [activeTab, setActiveTab] = useState("overview");
+
+<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Tab value="overview">Overview</Tabs.Tab>
+    <Tabs.Tab value="details">Details</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel value="details">Details content</Tabs.Panel>
+</Tabs.Root>;
+```
+
+## Examples
+
+### With Disabled Tab
+
+```tsx
+<Tabs.Root defaultValue="active">
+  <Tabs.List>
+    <Tabs.Tab value="active">Active</Tabs.Tab>
+    <Tabs.Tab value="pending">Pending</Tabs.Tab>
+    <Tabs.Tab value="archived" disabled>
+      Archived
+    </Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="active">Active items</Tabs.Panel>
+  <Tabs.Panel value="pending">Pending items</Tabs.Panel>
+  <Tabs.Panel value="archived">Archived items</Tabs.Panel>
+</Tabs.Root>
+```
+
+### Use Icons in Tab
+
+In the `capsule` variant, a tab whose only child is an icon renders **square** —
+its `min-width` matches its `min-height` — making it a natural fit for icon-only
+view toggles (e.g. table/kanban). Use `size` to align the track with a sibling
+`Button`: `size="default"` (36px) matches `Button`'s default height. Unsized
+icons default to `16px`, so the square is consistent regardless of the icon.
+
+> **Accessibility:** an icon-only tab has no visible text, so give each one an
+> `aria-label`. Without it, screen readers announce an unnamed tab.
+
+```tsx
+<Tabs.Root defaultValue="overview" variant="capsule" size="default">
+  <Tabs.List>
+    <Tabs.Tab value="overview" aria-label="Overview">
+      <LayoutDashboardIcon />
+    </Tabs.Tab>
+    <Tabs.Tab value="projects" aria-label="Projects">
+      <FolderKanbanIcon />
+    </Tabs.Tab>
+    <Tabs.Tab value="settings" aria-label="Settings">
+      <SettingsIcon />
+    </Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel value="projects">Projects content</Tabs.Panel>
+  <Tabs.Panel value="settings">Settings content</Tabs.Panel>
+</Tabs.Root>
+```
+
+### Sizing the capsule variant
+
+`size` mirrors `Button`'s height tiers, so a capsule can sit flush next to a
+button. The value sets a **minimum** height — taller content still grows.
+
+| `size`    | Track height | Matches Button |
+| --------- | ------------ | -------------- |
+| `xs`      | 28px         | `size="xs"`    |
+| `sm`      | 32px         | `size="sm"`    |
+| `default` | 36px         | default        |
+| `lg`      | 40px         | `size="lg"`    |