@teamblind-chorus/ui 1.0.0

package/agents/components/button/fab.md

@@ -0,0 +1,161 @@
+# FAB
+
+Floating action button — surface-elevated commit anchored to the canvas, reachable while content scrolls. Single fixed rung with a pill geometry (`sys.radius.full`) and floating elevation (`sys.elevation.floating`); label and icon both optional, at least one present.
+
+**Reach for this when** the canvas needs a single headline action that survives scroll — Compose, Add, Create. **Skip when** the action lives inline with content (use [Standard Button](./standard.md)) or the row is a dense toolbar ([Toolbar Button](./toolbar.md)).
+
+**Layout inset.** inline — ships no padding outside its own pill chrome. Sits inside an overlay container anchoring it to the canvas (fixed positioner, bottom-right docked layer) with the host paying the offset to the page rail and safe-area inset. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), the host already owns the inset — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Brand-red fill anchoring the canvas's headline action — `appearance="primary"`. One per scrollable canvas.
+
+```preview
+button/fab/primary
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  variant="fab"
+  appearance="primary"
+  icon={<PlusIcon />}
+>
+  Compose
+</Button>
+```
+
+## Use cases
+
+### Secondary
+
+Theme-toned FAB that defers to the canvas's surface tones. Reach for it when a brand-red FAB would over-claim the page hierarchy (filtered map, image-rich feed).
+
+```preview
+button/fab/secondary
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  variant="fab"
+  appearance="secondary"
+  icon={<PlusIcon />}
+>
+  Compose
+</Button>
+```
+
+### Icon
+
+Icon-only — 48 × 48 circle with a 24px glyph. For universally legible actions (`+`, pencil). **Requires `aria-label`.**
+
+```preview
+button/fab/icon
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  variant="fab"
+  appearance="primary"
+  icon={<PlusIcon />}
+  aria-label="Add"
+/>
+```
+
+### Text
+
+Label-only pill. For multi-word actions or verbs without an obvious glyph (*Save draft*).
+
+```preview
+button/fab/text
+---
+import { Button } from '@teamblind-chorus/ui';
+
+<Button variant="fab" appearance="primary">
+  Compose
+</Button>
+```
+
+### Extended
+
+Icon + label. Default for primary canvas commits where space allows (desktop canvases, mobile sheets).
+
+```preview
+button/fab/extended
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button
+  variant="fab"
+  appearance="primary"
+  icon={<PlusIcon />}
+>
+  Add item
+</Button>
+```
+
+### Focus indicator
+
+Standard ring with the FAB's floating elevation stacked underneath. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+```preview
+button/fab/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+import { PlusIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="fab" appearance="primary" state="focused" icon={<PlusIcon />}>
+  Compose
+</Button>
+```
+
+## Slots
+
+- **icon** (optional) — 24px glyph. Inherits foreground via `currentColor` per the [family rule](./button.md#icon-colour-inheritance-family-wide).
+- **label** (optional) — short verb phrase. Internally padded so the glyph never crowds the rounded ends.
+
+At least one must be present — combinations: [Icon](#icon), [Text](#text), [Extended](#extended).
+
+## Appearance
+
+Two appearances on the standard [Button](./button.md) emphasis ladder — `primary` for the canvas headline commit, `secondary` for the quieter alternative. FAB wears `brand` (red) rather than `color.primary` (blue) — the screen's single high-attention moment.
+
+| Appearance  | Background                       | Label / icon color   | When to reach for it                                                                              |
+|-------------|----------------------------------|----------------------|---------------------------------------------------------------------------------------------------|
+| `primary`   | `sys.color.brand`                | `sys.color.onBrand`  | Brand-red commit anchoring the canvas's next step (Compose, Add, Create). |
+| `secondary` | `sys.color.surfaceContainerHigh` | `sys.color.onSurface` | Theme-toned alternative on dense/chromatic canvases where brand-red would over-claim. |
+
+## Sizes
+
+Single fixed rung — no size axis; same control on every viewport.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Min-height                        | 48px                 | `ref.space.600` ‡                  |
+| Padding (all sides)               | 12px                 | `sys.layout.container.sm`          |
+| Icon size                         | 24px                 | `sys.icon.lg`                      |
+| Slot gap (icon ↔ label)           | 0                    | —                                  |
+| Label inset (within label slot)   | 4px (all sides)      | `sys.layout.container.2xs`         |
+| Radius                            | pill / circle        | `sys.radius.full`                  |
+| Elevation                         | floating             | `sys.elevation.floating`           |
+
+‡ **min-height** binds to raw `ref.space.*` — `sys.*` does not expose a 48px step.
+
+**Label-slot 4px inset.** Outer 12px padding alone would crowd the rounded ends; the label slot adds another `container.2xs` only when text is present:
+
+- **Text-only** — clears 16px each side (12 + 4).
+- **Icon-only** — clean 48 × 48 (12 + 24 + 12).
+- **Icon + text** — icon flush at 12px, label with 4px inset, trailing 12px padding.
+
+## States
+
+The focus ring is a `position: absolute` pseudo-element stacked above the FAB's `box-shadow` so the floating elevation survives focus.
+
+**No disabled state.** If the action isn't available, hide the FAB rather than render it dimmed.
+
+## Focus indicator
+
+Standard outward ring on a `::after` overlay above the FAB's `box-shadow`. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).

package/agents/components/button/fab.spec.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Fab",
+  "family": "button",
+  "subcomponent": "fab",
+  "description": "Floating action button. Single fixed sizing rung, pill geometry, floating elevation. No disabled state.",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "fab"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "primary",
+        "secondary"
+      ],
+      "default": "primary"
+    },
+    "icon": {
+      "type": "node",
+      "optional": true
+    },
+    "label": {
+      "type": "node",
+      "optional": true,
+      "note": "Provide as children. At least one of icon/label required."
+    }
+  },
+  "slots": {
+    "icon": {
+      "required": false,
+      "description": "24px (sys.icon.lg) glyph naming the action. Optional but at least one of icon/label required.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "label": {
+      "required": false,
+      "description": "Short verb phrase. When present, padded internally so glyph never crowds the pill ends.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.600",
+    "padding": "sys.layout.container.sm",
+    "iconSize": "sys.icon.lg",
+    "slotGap": "0",
+    "labelInset": "sys.layout.container.2xs",
+    "radius": "sys.radius.full",
+    "elevation": "sys.elevation.floating",
+    "labelTypo": "sys.typo.label.lg"
+  },
+  "appearances": {
+    "primary": {
+      "background": "sys.color.brand",
+      "label": "sys.color.onBrand"
+    },
+    "secondary": {
+      "background": "sys.color.surfaceContainerHigh",
+      "label": "sys.color.onSurface"
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the FAB is in. The ring stacks above the FAB's floating elevation so the lift survives focus. 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": [
+    "more than one fab per screen — the FAB is the single canonical commit",
+    "fab styled with sys.color.primary fill — the FAB carries sys.color.brand by anatomy contract",
+    "destructive flavor on a FAB — destructive commits live inside Dialog / BottomSheet, never a floating commit",
+    "fab placed inline in flow — it floats over content, anchored bottom-right by the page shell"
+  ]
+}

package/agents/components/button/icon.md

@@ -0,0 +1,141 @@
+# Icon
+
+The icon-only commit surface — circular transparent target carrying a single glyph. Two rungs: `large` (40 × 40 / 24-glyph) for page chrome, `medium` (32 × 32 / 16-glyph) for inside-control density.
+
+**Reach for this when** the control's identity is the glyph and the action is reversible — [Navigation bar](../navigation-bar/navigation-bar.md) search/chat, [Dialog](../dialog/dialog.md) dismiss, feed-row "⋯". **Skip when** the action is destructive or one-shot — use standard [Button](./button.md) with a visible verb.
+
+**Layout inset.** inline — ships no padding outside its own circular target. Sits inside a host slot (NavigationBar trailing rail, Dialog header, feed-row action cluster) with the host paying surrounding rhythm. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), the host already owns the inset — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Transparent capsule with a single glyph in `onSurface`. `large` is the default; flip to `medium` for inside-control density.
+
+```preview
+button/icon/default
+---
+import { Button } from '@teamblind-chorus/ui';
+import { SearchIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="icon" size="large" icon={<SearchIcon />} aria-label="Search" />
+```
+
+## Use cases
+
+### Inverse
+
+Mirror for inverse hosts (Toast dismiss, coach-mark close). Glyph paints in `inverseOnSurface` against the host's `inverseSurface` fill; state overlays mix from the same token.
+
+```preview
+button/icon/inverse
+---
+import { Button } from '@teamblind-chorus/ui';
+import { XIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="icon" size="medium" appearance="inverse" icon={<XIcon />} aria-label="Dismiss" />
+```
+
+### Custom palette colours
+
+Outside the named appearances, the glyph inherits `currentColor` — any Chorus icon-paint token works. Reach for a custom colour when the glyph carries semantic weight (favorite star → `sys.color.icon.yellow`, success check → `sys.color.success`, warning bolt, channel-branded glyph in a brand-tinted host). Apply via inline `color` so state overlays still mix from the same token at standard `sys.state.*` opacities — never override `background` or wrap in another element to recolour.
+
+```preview
+button/icon/custom-color
+---
+import { Button } from '@teamblind-chorus/ui';
+import { StarFillIcon } from '@teamblind-chorus/ui/icons';
+
+<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-xl)' }}>
+  <Button variant="icon" icon={<StarFillIcon />} aria-label="Favorite — inactive" style={{ color: 'var(--sys-color-icon-muted)' }} />
+  <Button variant="icon" icon={<StarFillIcon />} aria-label="Favorite — active"   style={{ color: 'var(--sys-color-icon-yellow)' }} />
+</div>
+```
+
+Pick from `sys.color.*` — semantic roles (`primary` / `success` / `error` / …) for status pairs that also carry a background, and the dedicated `sys.color.icon.*` palette (`muted` / `yellow` / `red` / `blue` / `green` / `purple`) for standalone semantic glyphs. Reaching past sys into `ref.palette.*`, hardcoded hex, and Tailwind colour utilities are all forbidden.
+
+### Group
+
+Three Icon Buttons in a row — common shape on the [Navigation bar](../navigation-bar/navigation-bar.md) Main trailing slot. Adjacent buttons sit 16px apart (`sys.layout.inline.xl`); with optical alignment on, that gap *is* the visible glyph-to-glyph distance.
+
+```preview
+button/icon/group
+---
+import { Button } from '@teamblind-chorus/ui';
+import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-xl)' }}>
+  <Button variant="icon" icon={<SearchIcon />}  aria-label="Search" />
+  <Button variant="icon" icon={<ChatIcon />}    aria-label="Messages" />
+  <Button variant="icon" icon={<ProfileIcon />} aria-label="Profile" />
+</div>
+```
+
+### Focus indicator
+
+Standard ring (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)).
+
+```preview
+button/icon/focused
+---
+import { Button } from '@teamblind-chorus/ui';
+import { SearchIcon } from '@teamblind-chorus/ui/icons';
+
+<Button variant="icon" icon={<SearchIcon />} aria-label="Search" state="focused" />
+```
+
+## Slots
+
+- **icon** — required glyph, sized at the rung's icon token. Inherits foreground via `currentColor` per the [family icon-colour rule](./button.md#icon-colour-inheritance-family-wide).
+- **aria-label** — required accessible name; Icon Button has no visible text.
+
+## Anatomy
+
+| Property              | Token                                                          |
+|-----------------------|----------------------------------------------------------------|
+| Background (rest)     | `transparent`                                                  |
+| Border                | none                                                           |
+| Icon color            | per appearance (`onSurface` / `inverseOnSurface`)              |
+| Hover background      | icon color at `sys.state.hover` (8%) opacity                   |
+| Pressed background    | icon color at `sys.state.pressed` (16%) opacity                |
+
+## Appearance
+
+Two named appearances; geometry identical, only the glyph colour pair flips.
+
+| Appearance  | Background    | Border | Icon color                       | When to reach for it |
+|-------------|---------------|--------|----------------------------------|----------------------|
+| `default`   | `transparent` | none   | `sys.color.onSurface`            | Every regular page surface. |
+| `inverse`   | `transparent` | none   | `sys.color.inverseOnSurface`     | For use inside an inverse host (Toast dismiss, coach-mark close). |
+
+## Sizes
+
+Two rungs. Padding is the single sizing token — `sys.layout.container.xs` (8px) on every edge — so footprint falls out of the icon scale without explicit `width`/`height`. Default is `large`; reach for `medium` only inside another control's chrome, since it falls below the WCAG 24 × 24 floor for top-level commits.
+
+| Rung      | Capsule footprint   | Padding (all sides)              | Icon                | Radius            |
+|-----------|---------------------|----------------------------------|---------------------|-------------------|
+| `large`   | 40 × 40 (implicit)  | `sys.layout.container.xs` (8)    | `sys.icon.lg` (24)  | `sys.radius.full` |
+| `medium`  | 32 × 32 (implicit)  | `sys.layout.container.xs` (8)    | `sys.icon.md` (16)  | `sys.radius.full` |
+
+## States
+
+The overlay paints the **icon color** over the transparent container at the state's opacity.
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Transparent capsule, glyph at `onSurface`.                                  |
+| `hovered`  | `sys.state.hover` (8%)     | Pointer-driven via `:hover`.                                                |
+| `pressed`  | `sys.state.pressed` (16%)  | Pointer-driven via `:active`.                                               |
+| `disabled` | overlay suppressed         | Glyph 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`.
+
+## Optical alignment
+
+Transparent at rest — the eye lands on the glyph. Default rendering applies `margin: calc(-1 × sys.layout.container.xs)` on every side so the **glyph is the layout box**. Not opt-in.
+
+| Where it lands | Effect |
+|---|---|
+| At a row / header / toolbar edge | Glyph flush with the content rail; hover capsule bleeds into the gutter. |
+| In a flush row of adjacent Icon Buttons | Capsule edges touch chrome-to-chrome without phantom padding. |
+| Inside another control's chrome | Glyph occupies only its own footprint. |

package/agents/components/button/icon.spec.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Button",
+  "family": "button",
+  "subcomponent": "icon",
+  "description": "Icon-only commit surface — a circular, transparent target carrying a single glyph. Reach for this whenever a control's identity is the glyph itself and a text label would be redundant: leading menu / trailing actions on the Navigation Bar, the dismiss '×' on a Dialog header, the '⋯' more affordance on a feed row footer. The capsule is transparent at rest and paints the standard state overlays on hover / pressed.",
+  "element": "button",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "icon"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "large",
+        "medium"
+      ],
+      "default": "large"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "inverse"
+      ],
+      "default": "default"
+    },
+    "icon": {
+      "type": "node",
+      "required": true,
+      "description": "The glyph. Required."
+    },
+    "aria-label": {
+      "type": "string",
+      "required": true,
+      "description": "Accessible name — required because Icon Button carries no visible text."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "icon": {
+      "required": true,
+      "description": "The glyph. Sized at the rung's icon token — `sys.icon.lg` (24) on `large`, `sys.icon.md` (16) on `medium`.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "aria-label": {
+      "required": true,
+      "description": "Accessible name. Required — screen readers and keyboard users rely on it to identify the action.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "sizes": {
+    "large": {
+      "padding": "sys.layout.container.xs",
+      "iconSize": "sys.icon.lg",
+      "radius": "sys.radius.full",
+      "footprint": "40 × 40 (implicit, from 8 + 24 + 8)"
+    },
+    "medium": {
+      "padding": "sys.layout.container.xs",
+      "iconSize": "sys.icon.md",
+      "radius": "sys.radius.full",
+      "footprint": "32 × 32 (implicit, from 8 + 16 + 8)"
+    }
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "border": null,
+      "icon": "sys.color.onSurface",
+      "note": "Transparent capsule with the glyph in `onSurface`. The canonical Icon Button chrome, used on every regular page surface."
+    },
+    "inverse": {
+      "background": "transparent",
+      "border": null,
+      "icon": "sys.color.inverseOnSurface",
+      "note": "Mirror of `default` for use inside an inverse host (Toast, coach-mark, snackbar). Glyph paints in `inverseOnSurface` so it reads against the host's `inverseSurface` fill; state overlays mix from the same token so the recipe carries over without per-host tuning."
+    }
+  },
+  "customGlyphColor": {
+    "allowed": true,
+    "description": "Outside the named `default` / `inverse` appearances, the glyph colour is open — the icon inherits `currentColor`, so any Chorus icon-paint token can be applied via inline `color` (e.g. `style={{ color: 'var(--sys-color-icon-yellow)' }}` for an active favorite star, `var(--sys-color-success)` for a confirm check, `var(--sys-color-icon-muted)` for the unpressed partner). State overlays still mix from the same token at the standard `hovered`/`pressed`/`focused` state opacities, so hover / pressed / focus carry over without per-host tuning.",
+    "constraints": [
+      "Pick a Chorus colour token. Two valid sources: (a) a status-pair role (`sys.color.primary`, `sys.color.success`, `sys.color.error`, etc.) when the glyph travels with its own background; (b) the dedicated icon palette (`sys.color.icon.muted`, `sys.color.icon.yellow`, `sys.color.icon.red`, `sys.color.icon.blue`, `sys.color.icon.green`, `sys.color.icon.purple`) for standalone semantic glyphs. Reaching past sys into the raw palette (`ref.palette.yellow.500` etc.), raw hex, and Tailwind colour utilities are all forbidden.",
+      "Override the icon's `color` only — never `background`, never wrap in another element to restyle.",
+      "Reach for a custom colour when the glyph itself carries semantic weight (favorite, success, warning, brand-tinted host). Otherwise stick to `default` / `inverse`.",
+      "The `destructive` flavor (`sys.color.error`) is a named convenience for the same pattern."
+    ]
+  },
+  "flavors": {
+    "destructive": {
+      "description": "Swaps the glyph color to the error family. Reserved for irreversible commits (a 'Remove' trash glyph, a 'Discard' close on a destructive sheet header).",
+      "appearances": {
+        "default": {
+          "background": "transparent",
+          "border": null,
+          "icon": "sys.color.error"
+        },
+        "inverse": {
+          "background": "transparent",
+          "border": null,
+          "icon": "sys.color.error"
+        }
+      }
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "icon",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "icon",
+        "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 button 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": "icon",
+      "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)"
+  },
+  "behavior": {
+    "footprint": "Content-sized — no explicit width / height. The 40 (large) / 32 (medium) falls out of padding + icon + padding.",
+    "group": "Horizontally-grouped Icon Buttons share a row gap of `sys.layout.inline.xl` (16) on both rungs. Because Icon Button applies optical alignment by default (each capsule's chrome bleeds outward by its 8px padding so the visible glyph is the layout box), the chrome-to-chrome gap IS the visible glyph-to-glyph distance — no per-capsule padding to add on top. The hover capsules of adjacent buttons each extend 8px beyond their glyph; with a 16px row gap, two hover capsules touch chrome-to-chrome but never collide.",
+    "opticalAlignmentDefault": "Icon Button applies optical alignment as the **default** rendering rule, on all four sides: the capsule is transparent at rest, so the visible glyph (not the padded chrome) defines the button's layout edges. Implemented as a base `margin: calc(-1 × sys.layout.container.xs)` on `.chorus-button--icon`. Hover capsule still paints on every side — the chrome becomes a hover-only affordance, doubling as a hit-zone enlargement. Consumers do not opt in; alignment with the surrounding content rail just works."
+  },
+  "forbidden": [
+    "Icon button without aria-label",
+    "raw <button> with a chorus-icon class inside instead of the chorus-button--icon chrome",
+    "icon size below sys.icon.md (20px) — small icon buttons fail touch-target minima"
+  ]
+}