@teamblind-chorus/ui 1.0.0

package/agents/components/chip/filter.md

@@ -0,0 +1,212 @@
+# Filter
+
+The selectable chip — a capsule-shaped toggle for refining a set. Unselected is a transparent hairline-outlined pill that adopts whatever surface sits behind it; selected swaps to an inverse fill. Optional leading/trailing icons compose without changing footprint.
+
+**Reach for this when** the user narrows a set by toggling one or more independent criteria — multiple chips can be on at once. **Skip when** the choices are mutually-exclusive view modes — use [Segmented](../tabs/segmented.md) instead.
+
+**Layout inset.** inline — content-sized, inherits its surface's padding; rails compose via gap, not chrome.
+
+## Default
+
+At-rest — transparent fill with a hairline `outlineVariant` stroke so the chip sits on any surface without colliding with the surface ladder.
+
+```preview
+chip/filter/unselected
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<Chip variant="filter">
+  All
+</Chip>
+```
+
+## Use cases
+
+### Selected
+
+Active — inverse-toned fill. Toggle the `selected` flag on the same chip element.
+
+```preview
+chip/filter/selected
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<Chip
+  variant="filter"
+  selected
+>
+  All
+</Chip>
+```
+
+### With icon
+
+Facet glyph before the label — tag for category, magnifier for search, check on selection.
+
+```preview
+chip/filter/leading-icon
+---
+import { Chip } from '@teamblind-chorus/ui';
+import { CheckedIcon } from '@teamblind-chorus/ui/icons';
+
+<Chip
+  variant="filter"
+  leadingIcon={<CheckedIcon />}
+>
+  Selected
+</Chip>
+```
+
+### With trailing icon
+
+Directional/dismiss glyph after the label — chevron-down to expand, *×* to clear.
+
+```preview
+chip/filter/trailing-icon
+---
+import { Chip } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Chip
+  variant="filter"
+  trailingIcon={<XIcon />}
+>
+  Today
+</Chip>
+```
+
+### With trailing action
+
+Pair the chip rail with a trailing accent [Text Button](../button/text.md) (`size='small'`, `appearance='accent'`) for a destination outside the filter axis — managing the set, opening keyword settings. The button is *not* a filter toggle; the chip track scrolls horizontally with a trailing 48px `mask-image` fade painted only while overflowing, and the button stays pinned outside the scroll viewport at `sys.layout.inline.xl` gap.
+
+```preview
+chip/filter/with-trailing-action
+---
+import { Chip, Button } from '@teamblind-chorus/ui';
+import { ArrowDownIcon } from '@teamblind-chorus/ui/icons';
+
+<div
+  style={{
+    display: 'flex',
+    alignItems: 'center',
+    gap: 'var(--sys-layout-inline-xl)',
+    width: '100%',
+    boxSizing: 'border-box',
+  }}
+>
+  <div
+    style={{
+      display: 'flex',
+      alignItems: 'center',
+      gap: 'var(--sys-layout-inline-sm)',
+      flex: '1 1 auto',
+      minWidth: 0,
+      overflowX: 'auto',
+      scrollbarWidth: 'none',
+      WebkitMaskImage: 'linear-gradient(to right, black 0, black calc(100% - 48px), transparent 100%)',
+      maskImage: 'linear-gradient(to right, black 0, black calc(100% - 48px), transparent 100%)',
+    }}
+  >
+    <Chip variant="filter" selected trailingIcon={<ArrowDownIcon />}>
+      All keywords
+    </Chip>
+    <Chip variant="filter" selected trailingIcon={<ArrowDownIcon />}>
+      All channels
+    </Chip>
+    <Chip variant="filter">
+      Label
+    </Chip>
+    <Chip variant="filter">
+      Saved
+    </Chip>
+  </div>
+  <Button variant="text" size="small" appearance="accent" style={{ flex: '0 0 auto' }}>
+    Manage
+  </Button>
+</div>
+```
+
+### Group
+
+Adjacent filter chips share a 4px gap (`sys.layout.inline.sm`), left-to-right; selection is independent per chip — Filter does not enforce single-select.
+
+```preview
+chip/filter/group
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', gap: 4 }}>
+  <Chip variant="filter" selected>
+    All
+  </Chip>
+  <Chip variant="filter">
+    Open
+  </Chip>
+  <Chip variant="filter">
+    Closed
+  </Chip>
+  <Chip variant="filter">
+    Archived
+  </Chip>
+</div>
+```
+
+### Focus indicator
+
+Both selection states take the same standard ring; the case below shows unselected.
+
+```preview
+chip/filter/focused
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<Chip variant="filter" state="focused">
+  All
+</Chip>
+```
+
+## Slots
+
+- **label** — accessible name. Required, single line.
+- **leadingIcon** (optional) — facet glyph before the label.
+- **trailingIcon** (optional) — directional/dismiss glyph after the label.
+
+## Sizes
+
+Single fixed footprint, consistent across breakpoints.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| 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                    | — †                                |
+| Radius                            | pill                 | `sys.radius.full`                  |
+| Label                             | 12 / Semibold        | `sys.typo.label.sm`                |
+| Icon                              | 16px                 | `sys.icon.md`                      |
+
+‡ Footprint shared with [Toolbar button](../button/toolbar.md) and [Tabs segmented](../tabs/segmented.md).
+
+† Visible icon-to-label rhythm comes from the label-slot inset.
+
+## Variants
+
+Single visual variant; the selected/unselected toggle swaps the container/label pair wholesale. On `selected`, the border colour goes transparent but its 1px width is held, so footprint never changes.
+
+| State        | Background                          | Border (1px `sys.borderWidth.hairline`)                 | Label / icon color                |
+|--------------|-------------------------------------|---------------------------------------------------------|-----------------------------------|
+| unselected   | `transparent`                       | `sys.color.outlineVariant`                              | `sys.color.onSurface`             |
+| selected     | `sys.color.inverseSurface`          | `transparent`                                           | `sys.color.inverseOnSurface`      |
+
+## 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`.                                               |
+| `disabled` | overlay suppressed         | Container at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. |
+
+## Focus indicator
+
+Standard outward ring on a `position: absolute` pseudo-element so it never affects layout; inside a [Tabs](../tabs/segmented.md) row the same layer is re-anchored inward. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).

package/agents/components/chip/filter.spec.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Chip",
+  "family": "chip",
+  "subcomponent": "filter",
+  "description": "Selectable chip. Capsule-shaped toggle. Unselected = transparent fill + hairline outline so the chip adopts whatever surface it sits on; selected = inverse fill.",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "filter"
+    },
+    "selected": {
+      "type": "boolean",
+      "default": false
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Required, single line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "Facet glyph before label.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Directional / dismiss glyph after label.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.400",
+    "paddingBlock": "sys.layout.container.2xs",
+    "paddingInline": "sys.layout.container.sm",
+    "labelInset": "sys.layout.container.2xs",
+    "slotGap": "0",
+    "radius": "sys.radius.full",
+    "labelTypo": "sys.typo.label.sm",
+    "iconSize": "sys.icon.md"
+  },
+  "selectionStates": {
+    "unselected": {
+      "background": "transparent",
+      "label": "sys.color.onSurface",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.outlineVariant"
+      },
+      "note": "Transparent fill so the chip adopts whatever surface sits behind it (page, raised card, sheet) without pinning to a fixed neutral step."
+    },
+    "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 chip is in. The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
+    "composition": "outward",
+    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "radius below sys.radius.full — filter chip is always a fully-rounded pill",
+    "filled gray rest state with no `selected` semantics — rest carries hairline outline + onSurface label; selected carries inverseSurface fill + inverseOnSurface label",
+    "border declared via `border:` instead of inset box-shadow stroke",
+    "trailing chevron / icon as a separate hit area — the entire chip is the click target"
+  ]
+}

package/agents/components/chip/tag.md

@@ -0,0 +1,137 @@
+# Tag
+
+The informational chip — square-cornered label naming attached metadata (categories, statuses, content labels). Shorter than Filter (24 vs 32 min-height) with `sys.radius.sm` corners. Two appearances: `default` paints a translucent `sys.color.scrimSubtle` overlay (~8% inverse-tone, adopts whatever surface sits behind it); `accent` paints a tonal pale-primary container with primary label.
+
+**Reach for this when** you're naming attached metadata on rows, cards, or profiles. **Skip when** the marker signals unread / new activity on a host rather than describing it — use [Badge](../badge/badge.md) instead.
+
+**Layout inset.** inline — Tag ships no padding outside its own pill chrome; the host row pays the surrounding gap and column padding. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), the host already owns the inset — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Translucent overlay fill, label-only — the overlay tints the surface one step darker (light) or lighter (dark) rather than locking to a single container tone. Omit `appearance` or pass `appearance="default"`.
+
+```preview
+chip/tag/default
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<Chip variant="tag">
+  Design
+</Chip>
+```
+
+## Use cases
+
+### Accent
+
+Tonal pale-primary fill — `sys.color.primaryContainer` background, `sys.color.primary` label. Use when the tag should pop against the surface (Popular Tags in compose, highlighted hashtags); the default overlay is too quiet there.
+
+```preview
+chip/tag/accent
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<Chip variant="tag" appearance="accent">
+  #sellside
+</Chip>
+```
+
+### Dismissable
+
+Opt-out — same chip with a trailing *×* to remove the tag. Trailing icon inherits label color via `currentColor`.
+
+```preview
+chip/tag/dismissable
+---
+import { Chip } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Chip
+  variant="tag"
+  trailingIcon={<XIcon />}
+>
+  Newsletter
+</Chip>
+```
+
+### Group
+
+Adjacent tag chips share a 4px gap on both axes — `sys.layout.inline.sm` between siblings, `sys.layout.stack.2xs` between rows on wrap. Mixing with Filter is allowed — Tag's square + sunken tone vs Filter's pill + raised tone keeps roles legible. Tags are passive metadata, so collections exceeding the container's width **wrap** rather than scroll or truncate (set `display: flex; flex-wrap: wrap` on the container; do not use `overflow-x: auto` — horizontal scrolling belongs to tappable affordances).
+
+```preview
+chip/tag/group
+---
+import { Chip } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', flexWrap: 'wrap', gap: 4, maxWidth: 320 }}>
+  <Chip variant="tag">Design</Chip>
+  <Chip variant="tag">Engineering</Chip>
+  <Chip variant="tag">Research</Chip>
+  <Chip variant="tag">Product</Chip>
+  <Chip variant="tag">Marketing</Chip>
+  <Chip variant="tag">Operations</Chip>
+  <Chip variant="tag">Customer success</Chip>
+</div>
+```
+
+### Focus indicator
+
+Only the dismissable tag is focusable; the case below shows that form. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+```preview
+chip/tag/focused
+---
+import { Chip } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Chip variant="tag" state="focused" trailingIcon={<XIcon />}>
+  Newsletter
+</Chip>
+```
+
+## Slots
+
+- **label** — accessible name. Required, single line.
+- **trailingIcon** (optional) — dismiss/opt-out glyph after the label (typically *×*). Tag does not carry a leading icon.
+
+## Sizes
+
+Same min-height, vertical padding, label rung, and label-slot inset as Filter, but horizontal outer padding tightens from 12 to 8 (label-only Tag clears 12px each side; dismissable Tag reads 4px label-to-glyph then 8px to edge).
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Min-height                        | 24px                 | `ref.space.300` ‡                  |
+| Padding (block × inline)          | 4 × 8                | `sys.layout.container.2xs` × `sys.layout.container.xs` |
+| Label inset (within label slot)   | 4px (horizontal)     | `sys.layout.container.2xs`         |
+| Slot gap (icon ↔ label)           | 0                    | — †                                |
+| Radius                            | 4px                  | `sys.radius.sm`                    |
+| Label                             | 12 / Semibold        | `sys.typo.label.sm`                |
+| Icon                              | 16px                 | `sys.icon.md`                      |
+
+‡ `min-height` binds to raw `ref.space.*` — `sys.*` does not expose a 24px step.
+
+† Slot gap is `0` — see [Filter → Sizes](./filter.md#sizes).
+
+## Appearance
+
+Two appearances; Tag never toggles.
+
+| Appearance | Background                                                                                  | Label / icon color           |
+|------------|---------------------------------------------------------------------------------------------|------------------------------|
+| `default`  | `sys.color.scrimSubtle` (translucent inverse-tone overlay — black 8% light / white 8% dark) | `sys.color.onSurface`        |
+| `accent`   | `sys.color.primaryContainer` (theme-aware)                                                  | `sys.color.primary`          |
+
+## States
+
+Tag is interactive only when `trailingIcon` carries a click target; otherwise the chip is presentational and the chip body takes no state.
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Container + label at rest.                                                  |
+| `hovered`  | `sys.state.hover` (8%)     | Pointer-driven via `:hover` when the chip is interactive.                   |
+| `pressed`  | `sys.state.pressed` (16%)  | Pointer-driven via `:active` when the chip is interactive.                  |
+| `disabled` | overlay suppressed         | Container at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. |
+
+## Focus indicator
+
+Standard ring on the dismissable form only. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).

package/agents/components/chip/tag.spec.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Chip",
+  "family": "chip",
+  "subcomponent": "tag",
+  "description": "Informational chip. Square-cornered metadata label. Passive (or dismissable via trailing ×). No leading icon. Two appearances: `default` paints the translucent `sys.color.scrimSubtle` scrim (~8% inverse-tone overlay — black in light, white in dark) so the tag adopts whatever surface sits behind it; `accent` paints a tonal pale-primary container (`sys.color.primaryContainer`) with primary label for tags that need to pop against the surface.",
+  "element": "span",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "tag"
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Dismiss glyph (×); when present, chip becomes interactive."
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Required, single line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "Dismiss / opt-out glyph after the label.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.300",
+    "paddingBlock": "sys.layout.container.2xs",
+    "paddingInline": "sys.layout.container.xs",
+    "labelInset": "sys.layout.container.2xs",
+    "slotGap": "0",
+    "radius": "sys.radius.sm",
+    "labelTypo": "sys.typo.label.sm",
+    "iconSize": "sys.icon.md"
+  },
+  "appearances": {
+    "default": {
+      "background": "sys.color.scrimSubtle",
+      "label": "sys.color.onSurface",
+      "border": null,
+      "default": true,
+      "note": "Background is the translucent inverse-tone scrim (`sys.color.scrimSubtle` — black 8% in light mode, white 8% in dark) so the tag harmonises with whatever surface sits behind it — body, raised card, BottomSheet — instead of pinning to a fixed neutral step. Same Banner-style fill used by Progress track, StatusTag neutral, and Skeleton; sys-color is theme-aware so a single token resolves correctly in both modes."
+    },
+    "accent": {
+      "background": "sys.color.primaryContainer",
+      "label": "sys.color.primary",
+      "border": null,
+      "note": "Tonal accent: pale primary container background with primary label. Sys-color tokens are theme-aware, so no separate dark binding is needed — the resolved tokens pick the right values per theme. Use for tags that should pop against the surface (e.g. Popular Tags in compose, highlighted hashtags) where the default overlay is too quiet."
+    }
+  },
+  "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 chip is in. Applies only when the chip is interactive (a dismiss trailingIcon is present). The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
+    "composition": "outward",
+    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "radius set to sys.radius.full (pill) — tag is a sys.radius.sm square-cornered metadata pill, not a capsule chip",
+    "tag rendered as a clickable commit — tag is a metadata pill, not an action; the click target lives on the surrounding card / row",
+    "raw color override on a tag — tone is the surrounding container's secondary text color"
+  ]
+}

package/agents/components/dialog/dialog.family.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "dialog",
+  "name": "Dialog",
+  "description": "Centered modal surface used for confirmations, short forms, and image-led prompts that demand a focused commit. Single-spec family.",
+  "useCases": [
+    "confirmation",
+    "destructive confirmation",
+    "image-led prompt",
+    "centred modal",
+    "short form"
+  ],
+  "visualReuse": "locked",
+  "layoutInset": "bounded-surface",
+  "wrapperGuidance": "Renders into a body portal (or owns its own surface chrome). Place the call as a sibling of the page shell \u2014 do NOT wrap in a layout container, padding div, or className=\"px-*\". Full-bleed children inside the surface body get the negative-margin opt-out \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "usage": {
+    "note": "Actions are `primaryAction` / `secondaryAction` descriptor objects ({ label, onClick }) — there are NO Button children.",
+    "example": "<Dialog open={open} onClose={() => setOpen(false)} title=\"…\" body=\"…\" primaryAction={{ label, onClick }} secondaryAction={{ label, onClick }} />"
+  },
+  "spec": "dialog.md",
+  "subcomponents": [
+    {
+      "slug": "dialog",
+      "spec": "dialog.spec.json",
+      "md": "dialog.md",
+      "default": true
+    }
+  ]
+}