@teamblind-chorus/ui 1.0.0

package/agents/components/tabs/rounded.md

@@ -0,0 +1,150 @@
+# Rounded
+
+Rounded-rectangle tab row — each tab a self-contained chip with a required leading icon and label. Shares chrome with [Segmented](./segmented.md) and [Filter chip](../chip/filter.md) verbatim; the single divergence is corner radius, which steps from `sys.radius.full` (capsule) to `sys.radius.md` (8) — reads as a soft rounded rectangle, not a pill.
+
+**Reach for this when** the row is a sort/filter switcher inside content. **Skip when** the row anchors content sections — use [Underline](./underline.md) — or when it's an in-place mode change — use [Segmented](./segmented.md).
+
+**Layout inset.** full-bleed — edge-to-edge family. Sits as a direct child of the page shell and stretches edge-to-edge; the row pays its own `16px inline / 8px block` padding via `layout.container.*` — do **not** wrap it in another padding div, or the page rail double-pays. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Bare headline form — labels carry meaning, no glyphs.
+
+```preview
+tabs/rounded/default
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="rounded" value="latest" onChange={setValue} aria-label="Sort">
+  <Tab value="latest">Latest</Tab>
+  <Tab value="popular">Popular</Tab>
+  <Tab value="following">Following</Tab>
+</Tabs>
+```
+
+## Use cases
+
+### With icon
+
+Canonical sort/filter row — each tab pairs a leading glyph (`sys.icon.md`, 16px) with its label. All glyphs draw from `@teamblind-chorus/ui/icons` so the row carries no inline SVG.
+
+```preview
+tabs/rounded/leading-icon
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+import { PulseIcon, StarIcon, HeartIcon, BookmarkIcon } from '@teamblind-chorus/ui/icons';
+
+<Tabs variant="rounded" value="latest" onChange={setValue} aria-label="Sort">
+  <Tab value="latest"    leadingIcon={<PulseIcon />}>Latest</Tab>
+  <Tab value="popular"   leadingIcon={<StarIcon />}>Popular</Tab>
+  <Tab value="favorites" leadingIcon={<HeartIcon />}>Favorites</Tab>
+  <Tab value="saved"     leadingIcon={<BookmarkIcon />}>Saved</Tab>
+</Tabs>
+```
+
+### Icon only
+
+Glyph-only tab — collapses to a clean 32×32 square (inline padding 12 → 8). Requires `aria-label`.
+
+```preview
+tabs/rounded/icon-only
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+import { StarIcon, BookmarkIcon, HeartIcon } from '@teamblind-chorus/ui/icons';
+
+<Tabs variant="rounded" value="featured" onChange={setValue} aria-label="View">
+  <Tab value="featured" leadingIcon={<StarIcon />}     aria-label="Featured" />
+  <Tab value="saved"    leadingIcon={<BookmarkIcon />} aria-label="Saved"    />
+  <Tab value="loved"    leadingIcon={<HeartIcon />}    aria-label="Loved"    />
+</Tabs>
+```
+
+### Overflow
+
+When natural width exceeds the column, the row scrolls horizontally. Trailing edge fade (48px / `ref.space.600`) paints via `mask-image` only while overflow is present.
+
+```preview
+tabs/rounded/overflow
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+import { PulseIcon, StarIcon, HeartIcon, BookmarkIcon, TagIcon, ProfileIcon, MentionIcon } from '@teamblind-chorus/ui/icons';
+
+<Tabs variant="rounded" value="latest" aria-label="Feed">
+  <Tab value="latest"    leadingIcon={<PulseIcon />}>Latest</Tab>
+  <Tab value="popular"   leadingIcon={<StarIcon />}>Popular</Tab>
+  <Tab value="favorites" leadingIcon={<HeartIcon />}>Favorites</Tab>
+  <Tab value="saved"     leadingIcon={<BookmarkIcon />}>Saved</Tab>
+  <Tab value="topics"    leadingIcon={<TagIcon />}>Topics</Tab>
+  <Tab value="people"    leadingIcon={<ProfileIcon />}>People</Tab>
+  <Tab value="mentions"  leadingIcon={<MentionIcon />}>Mentions</Tab>
+</Tabs>
+```
+
+### Focus indicator
+
+Static specimen — pins the focus ring to the selected tab. See top-level [Focus indicator](#focus-indicator).
+
+```preview
+tabs/rounded/focused
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="rounded" value="latest" aria-label="Sort">
+  <Tab value="latest" state="focused">Latest</Tab>
+  <Tab value="popular">Popular</Tab>
+  <Tab value="following">Following</Tab>
+</Tabs>
+```
+
+## Slots
+
+- **label** — accessible name. Single line. Optional only when icon-only — requires `aria-label`.
+- **leadingIcon** (optional) — 16px (`sys.icon.md`) glyph. May carry its own brand/category color.
+
+At least one of `label` / `leadingIcon` must be present.
+
+## Anatomy
+
+Selected/unselected pairs are inherited verbatim from [Filter chip's variants](../chip/filter.md#variants).
+
+| Prop / state           | Container                          | Label color                       | Border (always 1px `sys.borderWidth.hairline`)                          |
+|------------------------|------------------------------------|-----------------------------------|-------------------------------------------------------------------------|
+| **Tab — unselected**   | `transparent`                      | `sys.color.onSurface`             | `sys.color.outlineVariant`                                              |
+| **Tab — selected**     | `sys.color.inverseSurface`         | `sys.color.inverseOnSurface`      | `transparent` — 1px width held so footprint never changes between states |
+
+## Sizes
+
+A single fixed rung. Every dimension other than the corner radius matches [Segmented](./segmented.md#sizes) and [Filter chip](../chip/filter.md#sizes).
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Container background              | transparent          | —                                  |
+| Container padding (block × inline)| 16 × 16              | `sys.layout.container.md` × `sys.layout.container.md` |
+| Min-height                        | 32px                 | `ref.space.400` ‡                  |
+| Padding (block × inline)          | 4 × 12               | `sys.layout.container.2xs` × `sys.layout.container.sm` |
+| Label inset (within label slot)   | 4px (horizontal)     | `sys.layout.container.2xs`         |
+| Slot gap (icon ↔ label)           | 0                    | — †                                |
+| Inter-tab gap                     | 4px                  | `sys.layout.inline.sm`             |
+| Radius                            | **8px**              | `sys.radius.md` ⁂                  |
+| Label                             | 12 / Semibold        | `sys.typo.label.sm`                |
+| Icon                              | 16px (fixed)         | `sys.icon.md`                      |
+
+‡ `min-height` binds raw `ref.space.*` — `sys.*` does not currently expose a 32px step.
+
+† Slot gap is a literal `0` — visible label-to-glyph rhythm comes from the label-slot inset (`padding: 0 4px`), not a sibling `gap`.
+
+⁂ Radius is the only divergence from Segmented (`sys.radius.full` → `sys.radius.md`).
+
+## States
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Container + label at rest.                                                  |
+| `hovered`  | `sys.state.hover` (8%)     | Pointer-driven via `:hover`.                                                |
+| `pressed`  | `sys.state.pressed` (16%)  | Pointer-driven via `:active`.                                               |
+| `selected` | —                          | Swap to inverse-surface pair; hairline stroke goes `transparent` (1px held). |
+| `disabled` | overlay suppressed         | Container at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. |
+
+## Focus indicator
+
+Standard ring (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)). Trigger: `:focus-visible`.

package/agents/components/tabs/rounded.spec.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Tabs",
+  "family": "tabs",
+  "subcomponent": "rounded",
+  "description": "Rounded-rectangle tab row — each tab is a self-contained chip carrying a required leading icon and a label, sharing the Segmented geometry verbatim but swapping the capsule radius for sys.radius.md (8) so the tabs read as soft rounded rectangles instead of pills. Reach for this on feed / list headers where the row of choices should sit as standalone chips with a more contained, card-adjacent silhouette.",
+  "delegatesTo": "chip/filter",
+  "element": "div",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "rounded"
+    },
+    "value": {
+      "type": "string",
+      "description": "The active tab's value."
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Fired with the next value when a tab is selected."
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible name for the tablist."
+    },
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when Tabs is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `tabs.family.json`."
+    }
+  },
+  "tabProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional 16px (sys.icon.md) context glyph rendered before the label. May carry its own brand / category color independent of the label."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": false,
+      "description": "Tab's accessible name. Single line. Omit only when the tab is icon-only (pair with an `aria-label` for assistive tech). At least one of label / leadingIcon must be present.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "16px (sys.icon.md) context glyph before the label. At least one of label / leadingIcon must be present.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.400",
+    "containerPaddingBlock": "sys.layout.container.md",
+    "containerPaddingInline": "sys.layout.container.md",
+    "paddingBlock": "sys.layout.container.2xs",
+    "paddingInline": "sys.layout.container.sm",
+    "labelInset": "sys.layout.container.2xs",
+    "slotGap": "0",
+    "interTabGap": "sys.layout.inline.sm",
+    "radius": "sys.radius.md",
+    "labelTypo": "sys.typo.label.sm",
+    "iconSize": "sys.icon.md",
+    "fadeWidth": "ref.space.600"
+  },
+  "selectionStates": {
+    "unselected": {
+      "background": "transparent",
+      "label": "sys.color.onSurface",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.outlineVariant"
+      },
+      "note": "Transparent fill so the tab adopts whatever surface sits behind it — page, raised card, sheet — without pinning to a fixed neutral step. Inherited from Filter chip's unselected recipe."
+    },
+    "selected": {
+      "background": "sys.color.inverseSurface",
+      "label": "sys.color.inverseOnSurface",
+      "border": null
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "disabled": {
+      "overlay": null,
+      "containerOpacity": "sys.state.disabled",
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the tab is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
+    "composition": "inward",
+    "compositionReason": "The Tabs row is a horizontal scroller; an outward ring would clip at the row's top/bottom edges.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the tab edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the tab edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow on the tab's `::after` overlay. Constrained strictly inside the tab's footprint and never exceeds it."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "rounded tabs given raw <button>/<a> or bare-text children instead of <Tab value=…> elements — the chip chrome (chorus-chip--filter + chorus-chip--rounded), the selected state, and the aria-selected/data-value binding all live on <Tab>; raw children render unstyled with no selected state",
+    "rounded tab radius set to sys.radius.full (pill) — the rounded variant is the sys.radius.md (8) soft-rectangle; reach for Segmented when a capsule row is needed",
+    "active state painted with sys.color.brand — rounded tabs use sys.color.inverseSurface fill + sys.color.inverseOnSurface label in selected state"
+  ]
+}

package/agents/components/tabs/segmented.md

@@ -0,0 +1,114 @@
+# Segmented
+
+The inline view-mode toggle — a row of mutually-exclusive selectors for in-place mode changes (List ↔ Grid, Day ↔ Week ↔ Month).
+
+**Reach for this when** the segments swap the *same* content's view or range in place — List ↔ Grid, Day ↔ Week ↔ Month. **Skip when** segments switch between *different* panels ([Underline](./underline.md)), multiple values can co-select ([Filter chip](../chip/filter.md)), or the rung is a single-select picker over a long list ([Radio list](../list/radio.md)).
+
+**Layout inset.** `full-bleed` — **edge-to-edge** family. Sits as a direct child of the page shell (or any surface that pays the gutter) and stretches edge-to-edge. The row pays its own `16px inline / 8px block` padding via `layout.container.*`; do **not** wrap it in another `padding-inline` / `px-*` / `style={{ padding: … }}` div, or the page rail double-pays. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Headline form — 2-segment List / Grid view toggle.
+
+```preview
+tabs/segmented/default
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="segmented" value="list" aria-label="View mode">
+  <Tab value="list">List</Tab>
+  <Tab value="grid">Grid</Tab>
+</Tabs>
+```
+
+## Use cases
+
+### With icon
+
+Leading glyph in each segment — useful when the verb alone could read as anything.
+
+```preview
+tabs/segmented/leading-icon
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+import { CheckedIcon, PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Tabs variant="segmented" value="grid" aria-label="View mode">
+  <Tab value="list" leadingIcon={<CheckedIcon />}>List</Tab>
+  <Tab value="grid" leadingIcon={<PlusIcon />}>Grid</Tab>
+</Tabs>
+```
+
+### Overflow
+
+When natural width exceeds the column, the row scrolls horizontally — no `fullWidth` (equal-width segments would break the shared-density contract with Filter chips). Trailing **Edge fade** (rightmost **48px** / `ref.space.600`) paints via `mask-image` only while overflow is present.
+
+```preview
+tabs/segmented/overflow
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="segmented" value="day" aria-label="Range">
+  <Tab value="day">Day</Tab>
+  <Tab value="week">Week</Tab>
+  <Tab value="month">Month</Tab>
+  <Tab value="quarter">Quarter</Tab>
+  <Tab value="year">Year</Tab>
+  <Tab value="decade">Decade</Tab>
+  <Tab value="century">Century</Tab>
+</Tabs>
+```
+
+### Focus indicator
+
+Static specimen — pins the focus ring to a selected segment. See top-level [Focus indicator](#focus-indicator).
+
+```preview
+tabs/segmented/focused
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="segmented" value="list" aria-label="View">
+  <Tab value="list" state="focused">List</Tab>
+  <Tab value="grid">Grid</Tab>
+</Tabs>
+```
+
+## Slots
+
+- **label** — segment's accessible name. Required, single line.
+- **leadingIcon** (optional) — context glyph before the label.
+
+## Anatomy
+
+Each segment renders with `chorus-chip chorus-chip--filter` — see [Filter chip](../chip/filter.md). Selected swaps from unselected (`transparent` fill + `outlineVariant` border + `onSurface` label) to selected (`inverseSurface` fill + `inverseOnSurface` label, border `transparent` with 1px width held).
+
+Chip behaviour inherited verbatim — except the focus ring, re-anchored as an inset overlay on a `::after` layer (segmented row is a horizontal scroller; the chip's default outward ring would clip).
+
+## Sizes
+
+Row container only — segment-internal sizing (min-height, padding, radius, typo, icon) is delegated to [Filter chip → Sizes](../chip/filter.md#sizes).
+
+| Property                                | Value                | Token                              |
+|-----------------------------------------|----------------------|-------------------------------------|
+| Container background                    | transparent          | —                                  |
+| Container padding (block)               | 16px                 | `sys.layout.container.md`          |
+| Container padding (inline)              | 16px                 | `sys.layout.container.md`          |
+| Inter-segment gap                       | 4px                  | `sys.layout.inline.sm`             |
+| Segment min-height / radius / typo / etc.| (inherited)         | see [Filter chip](../chip/filter.md#sizes) |
+
+## States
+
+Delegates to [Filter chip](../chip/filter.md) — segment chrome composes identically.
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Container + label at rest.                                                  |
+| `hovered`  | `sys.state.hover` (8%)     | Pointer-driven via `:hover`.                                                |
+| `pressed`  | `sys.state.pressed` (16%)  | Pointer-driven via `:active`.                                               |
+| `selected` | —                          | Swap to inverse-surface pair; hairline border goes `transparent` (1px held). |
+| `disabled` | overlay suppressed         | Container at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. |
+
+## Focus indicator
+
+**Composition: Inward** (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)) — row is a horizontal scroller, so an outward ring would clip at top/bottom. Paints as inset shadows inside the segment's bounding box on a `::after` so it never shifts a segment or row. Trigger: `:focus-visible`.

package/agents/components/tabs/segmented.spec.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Tabs",
+  "family": "tabs",
+  "subcomponent": "segmented",
+  "description": "Inline mutually-exclusive selector. Visual chrome delegated to Filter chip — each segment renders with `chorus-chip chorus-chip--filter` classes and inherits the chip's container/label/border/state recipes verbatim. This sub adds only the row container (transparent, horizontal padding, fixed inter-segment gap) and the single-select semantics enforced via Tabs context.",
+  "delegatesTo": "chip/filter",
+  "element": "div",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "segmented"
+    },
+    "value": {
+      "type": "string",
+      "description": "The active segment's value."
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Fired with the next value when a segment is selected."
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible name for the tablist."
+    },
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when Tabs is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `tabs.family.json`."
+    }
+  },
+  "tabProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Same contract as Filter chip's label slot.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "Same contract as Filter chip's leadingIcon slot.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "containerPaddingBlock": "sys.layout.container.md",
+    "containerPaddingInline": "sys.layout.container.md",
+    "interSegmentGap": "sys.layout.inline.sm",
+    "fadeWidth": "ref.space.600"
+  },
+  "selectionStates": {
+    "$ref": "../chip/filter.spec.json#/selectionStates",
+    "note": "Each segment swaps between Filter chip's unselected (surfaceContainerHigh + outlineVariant border) and selected (inverseSurface + inverseOnSurface) recipes."
+  },
+  "states": {
+    "$ref": "../chip/filter.spec.json#/states",
+    "note": "Hover / pressed / focus overlays and the disabled treatment are inherited from Filter chip; same opacities, same focus ring composition."
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the segment is in. Re-anchored inside the segment from Filter chip's default outward composition because the Segmented row is a horizontal scroller.",
+    "composition": "inward",
+    "compositionReason": "The Tabs row is a horizontal scroller; an outward ring would clip at the row's top/bottom edges.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the segment edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the segment edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow on the segment's `::after` overlay. Constrained strictly inside the segment's footprint and never exceeds it."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "segmented control given raw <button>/<a> or bare-text children instead of <Tab value=…> elements — the chip chrome, the selected pill state, and the aria-selected/data-value binding all live on <Tab>; raw children render unstyled with no selected state",
+    "active item painted with sys.color.primary fill — segmented active uses sys.color.surface fill on the selected pill (the rest of the row is surfaceContainer)",
+    "segmented row reflowing on selection — anatomy is no-layout"
+  ]
+}

package/agents/components/tabs/tabs.family.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "tabs",
+  "name": "Tabs",
+  "description": "Tab row family. `underline` is the default content-section switcher (sliding bottom-edge indicator); `rounded` is a soft-rectangle chip row with required leading icons; `segmented` delegates chrome to Filter chip for in-place mode toggles.",
+  "useCases": [
+    "section switcher",
+    "content tabs",
+    "chip tab row",
+    "in-place mode toggle",
+    "list-grid toggle"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns its inline padding internally. Place as a direct child of the page-shell <main> (or any host that pays the gutter once). Do NOT wrap in a padding-inline div, className=\"px-*\", or style={{ padding }} \u2014 the page rail is paid once at the shell, never on the full-bleed child. Inside a bounded surface (Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "compositionModes": {
+    "standalone": {
+      "default": true,
+      "chrome": {
+        "background": "sys.color.surface",
+        "padding": "per-variant container.* inline"
+      },
+      "context": "Direct child of the page shell or any host that pays the page-rail gutter once."
+    },
+    "embedded": {
+      "trigger": "prop `embedded={true}` on <Tabs /> OR direct child of `.chorus-carousel` / `.chorus-feed` (DOM-ancestry safety net).",
+      "chrome": {
+        "background": "transparent",
+        "padding": "0"
+      },
+      "context": "Composed inside another rail-responsible host (e.g. a labelled Section that hosts a stage-tab row). Tabs takes over from the host's content-box edge; the underline indicator and segmented chips still paint correctly because `padding-inline: 0` doesn't change tab geometry, only the rail surround."
+    }
+  },
+  "usage": {
+    "note": "`<Tabs>` selects chrome by the `variant` prop; every tab MUST be a `<Tab value=…>` child (compound) — there is no per-variant tab export and bare text / raw <button> children do not work.",
+    "subs": {
+      "underline": { "variant": "underline", "example": "<Tabs variant=\"underline\" value={v} onChange={setV}><Tab value=\"a\">A</Tab><Tab value=\"b\">B</Tab></Tabs>" }
+    }
+  },
+  "spec": "tabs.md",
+  "subcomponents": [
+    {
+      "slug": "underline",
+      "spec": "underline.spec.json",
+      "md": "underline.md",
+      "default": true
+    },
+    {
+      "slug": "rounded",
+      "spec": "rounded.spec.json",
+      "md": "rounded.md"
+    },
+    {
+      "slug": "segmented",
+      "spec": "segmented.spec.json",
+      "md": "segmented.md"
+    }
+  ]
+}

package/agents/components/tabs/tabs.md

@@ -0,0 +1,18 @@
+# Tabs
+
+A horizontal row of mutually-exclusive selections — exactly one tab is active, and selecting one swaps the surrounding panel. Sub-flavors: **Underline** is the canonical content-section switcher; **Segmented** is the inline view-mode toggle whose chrome delegates to [Filter chip](../chip/filter.md).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell (or any surface that pays the gutter) and stretches edge-to-edge inside it. The tabs rail pays its own internal padding via `layout.container.*`; do **not** wrap it in another `padding-inline` / `px-*` / `style={{ padding: … }}` div, or the page rail double-pays. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Cross-sub contract
+
+- **Selection model.** Single-select. `Tabs` owns the controlled `value`; selecting fires `onChange(value)`. For multi-select, use [Filter chips](../chip/filter.md).
+- **Slots.** Each Tab has a required **label** and an optional **leadingIcon** sized to the active sub's icon rung. No trailing slot.
+- **Selected as a state, not a variant.** Same element flips in/out as the parent's `value` changes.
+- **Accessibility.** Container exposes `role="tablist"` with caller-supplied `aria-label`; each Tab has `role="tab"` + `aria-selected`. Keyboard nav (←/→, Home/End) handled by container.
+
+## Sub-components
+
+- **[Underline](./underline.md)** — Tab row with a single 2px (`sys.borderWidth.thin`) `onSurface` indicator that slides along the active tab's bottom edge. Default for switching content panels.
+- **[Rounded](./rounded.md)** — Rounded-rectangle tab row, each tab a self-contained chip with a required leading icon and label. Shares Segmented's geometry, but corner radius steps from `full` to `sys.radius.md` (8).
+- **[Segmented](./segmented.md)** — Row of inline mode toggles whose chrome delegates to [Filter chip](../chip/filter.md). For in-place view-mode changes (List ↔ Grid, Day ↔ Week ↔ Month).