srcdev-nuxt-components 9.6.0 → 9.6.2

package/.claude/skills/component-compliance-checklist.md

@@ -98,6 +98,13 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
    name directly. A component whose layout responds to its container gets the `CanvasSwitcher`
    decorator (see `PageRow.stories.ts` or `GoogleReviews.stories.ts`, which also shows a per-story
    starting canvas via `parameters.initialCanvas`) rather than a hand-sized wrapper or a width arg.
+   If other components render this one inside them (it's a child or building block of theirs),
+   each story gets a short note that explains the relationship and links to the parent's story
+   (`storybook-add-story.md`, "Link to the stories of components that use this one").
+   Sample copy in stories, and examples in the skill doc, use placeholders (a name like "Alex
+   Morgan", a town like "Northtown"), never a real client's name, town, business or site: the
+   stories and docs ship in the public package. **Existing component:** check for, and replace, any
+   copy lifted from a consumer app (`ProfileSection` had both).
 6a. **Storybook Controls-panel reactivity** — check every story `Template`/`render` function in
     the component's `stories/*.stories.ts` files for this bug: `@storybook/vue3` mounts the story
     component **once** and, on every Controls-panel change, mutates the same reactive `args`
@@ -131,12 +138,17 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
     descriptions, body text) a line-clamp token, `--<component>-<element>-line-clamp`, which
     covers ellipsis too (`1` is single-line ellipsis). Default it to `none` unless the layout
     clearly needs a cap, and never clamp text that must stay readable (legal or attribution text,
-    link text that names its destination). Shape and rules: `theming-component-token-pattern.md`,
+    link text that names its destination). Only text the component renders itself (props and data) needs a token: text that arrives
+    through a slot is the consumer's own markup, so they clamp it directly and the component adds
+    no token for it (`ProfileSection` is all slots and has none). Shape and rules: `theming-component-token-pattern.md`,
     "Line-clamp tokens". Give each line-clamp token a Controls-panel select in the stories (set on
     a wrapper `:style`, stripped from the component's args), labelled as a story-only CSS token so
     nobody mistakes it for a prop: `storybook-add-story.md`, "Label token controls as story-only".
-    Add a unit test for any logic fix. A component that takes no data or copy
-    (e.g. a pure layout wrapper) still gets one with oversized slot content.
+    Add a unit test for any logic fix. A grid or layout component still gets one with oversized
+    slot content (an unbroken string in one cell finds `min-inline-size` overflow bugs). Components
+    with nothing to stress (animation wrappers, decorative containers that only take a slot and
+    tag/variant props, Storybook tooling) are exempt: they are listed in `stressStoryExempt` in
+    `.claude/component-ledger/build.mjs`; add a new one there rather than writing a padding story.
 7. **Skill doc** — create or update `.claude/skills/components/<component-name>.md`, following the
    pattern of an existing one. A labelled `<Name>Field` wrapper (or any other wrapper) is documented
    in its control's doc under a "Variants" section, not in a doc of its own
@@ -216,3 +228,10 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
     - `NuxtImg` gets explicit `width` and `height`; a `<video>` uses a `<source :src>` child with
       `:key` and `.load()` (pitfall #12).
     - No `#components` import (breaks Storybook); use `resolveComponent()`.
+    - Layout breakpoints respond to the component's own width (`container: <name> / inline-size` on the
+      root, `@container <name> (min-width: …)`), not the viewport, so it still works in a narrow
+      column. **Existing component:** when converting a viewport `@media` breakpoint, grep consumer
+      repos for `@media` overrides of the same element (they now switch at a different point) and list
+      the edits in private memory. Note that an inline-size container can't size itself from its
+      content: say so in `CONSUMER-STYLING.md` (`ProfileSection`).
+    - Grid tracks that hold text are `minmax(0, …)` so an unbroken string can't widen the grid.

package/.claude/skills/component-dynamic-slots.md

@@ -92,7 +92,7 @@ predictable pattern (`item-0`, `item-1`, …).
 
 |---|---|
 | Multiple slot types per item must be grouped into one rendered element | `AccordianCore` — `summary`/`icon`/`content` per `<ExpandingPanel>` |
-| Two parallel loops must stay in sync for aria linking | `TabsCore` — nav `<li>` loop + content `<div>` loop linked by id |
+| Two parallel loops must stay in sync for aria linking | `TabbedContent` — trigger `<button>` loop + panel `<div>` loop linked by id |
 | `itemCount` drives non-slot logic (z-index, CSS scope, counters) | `WipeAwayVertical` — `z-index: itemCount - key`, `timelineScope` computed |
 | `$slots` inspection per iteration is needed to conditionally render | `StepperList` — checks `$slots[indicator-N]` to toggle class per `<li>` |
 
@@ -119,7 +119,7 @@ const props = defineProps<Props>();
 
 ### Multi-type indexed slots
 
-Some components pair multiple slot types per index (e.g. TabsCore):
+Some components pair multiple slot types per index (e.g. TabbedContent):
 
 ```vue
 <template v-for="index in itemCount" :key="index">
@@ -130,7 +130,7 @@ Some components pair multiple slot types per index (e.g. TabsCore):
 
 ### Reference components (indexed dynamic slots)
 
-- `app/components/01.atoms/navigation/tabs/TabsCore.vue`
+- `app/components/01.atoms/tabbed-content/TabbedContent.vue`
 - `app/components/accordian/AccordianCore.vue`
 - `app/components/02.molecules/stepper-list/StepperList.vue`
 - `app/components/01.atoms/animations/view-timeline/WipeAwayVertical.vue`

package/.claude/skills/component-export-types.md

@@ -11,17 +11,12 @@ Types defined inline in a `.vue` component file are not easily importable by con
 Create `app/types/components/<component-name>.d.ts` with the exported interfaces:
 
 ```ts
-// app/types/components/nav-item.d.ts
-export interface NavItem {
-  text: string;
-  href?: string;
-  isExternal?: boolean;
-  iconName?: string;
-  cssName?: string;
-}
-
-export interface NavItemData {
-  [key: string]: NavItem[];
+// app/types/components/select-menu.d.ts
+export interface SelectMenuOption {
+  value: string | number;
+  label: string;
+  icon?: string;
+  dotColor?: string;
 }
 ```
 
@@ -30,7 +25,7 @@ export interface NavItemData {
 In `app/types/components/index.ts`, add an export line:
 
 ```ts
-export * from "./nav-item.d"
+export * from "./select-menu.d"
 ```
 
 ### 3. Update the component
@@ -39,11 +34,10 @@ Replace the inline `export interface` blocks in the `.vue` file with an import f
 
 ```ts
 // Before
-export interface NavItem { ... }
-export interface NavItemData { ... }
+export interface SelectMenuOption { ... }
 
 // After
-import type { NavItem, NavItemData } from "~/types/components/nav-item.d";
+import type { SelectMenuOption } from "~/types/components/select-menu";
 ```
 
 ## Consuming app usage
@@ -60,7 +54,7 @@ app/types/components/<component>.d.ts
 `types.d.ts` is the `"types"` entry point in `package.json`, so once a type is added to the barrel it is importable directly from the package name:
 
 ```ts
-import type { NavItem, NavItemData } from "srcdev-nuxt-components";
+import type { SelectMenuOption } from "srcdev-nuxt-components";
 ```
 
 ## Notes

package/.claude/skills/component-naming.md

@@ -101,7 +101,7 @@ external consumer, free to rename. Run `/check-component-usage` for the current
 | AlertMaskCore | `AlertMask` | - |
 | CardCore | **decide**: `Card` is single-word and collision-prone; prefer a prefixed name (`Display*`, `Content*`) | yes |
 | AccordianCore | **decide**: also fixes the "Accordian" misspelling; bare `Accordion` is single-word and collision-prone, and it is built on `<details>`/`<summary>` | yes |
-| TabsCore | **decide**: `Tabs` is single-word and collision-prone | - |
+| ~~TabsCore~~ | ✅ `TabbedContent` (2026-10-07) | - |
 
 The `input-checkbox` family also has `MultipleCheckboxes`/`SingleCheckbox` on top of the Core; look
 at how the four relate before choosing names there.

package/.claude/skills/components/alert-content.md

@@ -14,6 +14,10 @@ wrappers. Don't use `AlertContentInner` directly in pages.
 
 **Location**: `app/components/02.molecules/alert-content/AlertContent.vue`, `AlertContentInner.vue`
 
+> **Changed 2026-10-08**: added `styleClassPassthrough` to `AlertContent`, line-clamp tokens for the
+> title and message, and wrapping for long unbroken text and long `InputButton` labels in `#actions`.
+> `StressTest` story added.
+
 > **Changed 2026-09-27**: skill doc renamed from `alert-content-inner.md`. Added the `showIcon` prop
 > and `#actions` slot, public `--alert-content-*` tokens for the previously hardcoded values, and
 > renamed `.title`/`.content` to `.alert-content-title`/`.alert-content-text`.
@@ -30,6 +34,7 @@ Same on `AlertContent`, `AlertContentInner` and `AlertMaskedContent`:
 | `dismissible` | `boolean` | `false` | Shows the dismiss button, which emits `dismiss`. |
 | `contentId` | `string` | `undefined` | `id` on `.alert-content-body`, for `aria-describedby` wiring. |
 | `ariaLive` | `"polite" \| "assertive" \| "off"` | `undefined` | `aria-live` on `.alert-content-body`. Leave unset for static content (e.g. a banner present on page load). |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | `AlertContent` only. Extra classes on the root `.alert-content`. |
 
 ## Slots
 
@@ -96,7 +101,8 @@ slot always wins over app.config.
 Full token list in `CONSUMER-STYLING.md` next to the component. Outer shape (`AlertContent` only):
 `--alert-content-accent`, `-accent-width`, `-border`, `-border-radius-start`/`-end`. Inside (applies to
 `AlertMaskedContent` too): `--alert-content-inner-background`, `-gap`, `-padding`, `-text-colour`,
-`-icon-colour`, `-icon-size`, `-title-font-size`, `-text-font-size`, `-body-gap`,
+`-icon-colour`, `-icon-size`, `-title-font-size`, `-text-font-size`, `-title-line-clamp`,
+`-text-line-clamp` (both default `none`), `-body-gap`,
 `-actions-spacing`, `-actions-gap`, `-actions-justify` (default `flex-end`, right-aligned), and the `-dismiss-*` tokens.
 
 ## Notes
@@ -105,6 +111,8 @@ Full token list in `CONSUMER-STYLING.md` next to the component. Outer shape (`Al
   SVG mask shows through; change its fill with `--alert-masked-content-background` instead.
 - `AlertContent`'s root is `display: grid` so the inner stretches to the root's height (e.g. in a
   stretched row next to a taller alert) instead of showing the accent colour below it.
+- Long unbroken text in the title or message wraps (`overflow-wrap: anywhere`). The actions row sets
+  `--input-button-text-white-space: normal`, so long `InputButton` labels wrap rather than being clipped.
 - The inner is a flex row (icon | main | dismiss), so a missing icon or dismiss button leaves no
   empty column or stray gap. Before 2026-09-27 it was a fixed three-column grid, and a
   non-dismissible alert carried an empty trailing column plus its gap.

package/.claude/skills/components/container-glow.md

@@ -17,7 +17,7 @@ It uses the named dynamic slots pattern (`v-for="(_, name) in $slots"`), so ther
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `tag` | `"div" \| "li" \| "article" \| "section"` | `"div"` | HTML tag rendered for each card. |
+| `tag` | `"div" \| "li" \| "article" \| "section"` | `"div"` | HTML tag rendered for each card. With `"li"` the wrapper renders as a `<ul>` (list styling reset); otherwise a `<div>`. |
 | `config` | `ContainerGlowConfig` | `{}` | Proximity/spread/blur/gap/direction/inactive-opacity — see below. All fields optional. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root wrapper element. |
 
@@ -25,12 +25,14 @@ It uses the named dynamic slots pattern (`v-for="(_, name) in $slots"`), so ther
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `proximity` | `number` | `40` | Pointer distance (px) at which a card starts glowing. |
-| `spread` | `number` | `80` | Angular spread of the glow (degrees). |
-| `blur` | `number` | `20` | Blur applied to the glow layer (px). |
-| `gap` | `number` | `32` | Gap between cards in the wrapper (px). |
+| `proximity` | `number` | `40` | Pointer distance (px) at which a card starts glowing. Minimum `0`. |
+| `spread` | `number` | `80` | Angular spread of the glow (degrees). Clamped to `0`–`360`. |
+| `blur` | `number` | `20` | Blur applied to the glow layer (px). Minimum `0`. |
+| `gap` | `number` | `32` | Gap between cards in the wrapper (px). Minimum `0`. |
 | `vertical` | `boolean` | `false` | Stack cards vertically instead of horizontally. |
-| `inactiveOpacity` | `number` | `0` | Glow opacity when the pointer isn't nearby. |
+| `inactiveOpacity` | `number` | `0` | Glow opacity when the pointer isn't nearby. Clamped to `0`–`1`. |
+
+Non-finite values (`NaN`, `Infinity`) fall back to the default.
 
 ## Slots
 
@@ -62,16 +64,19 @@ name list or count prop.
   that on a private `--_start` custom property (registered via `@property` so it participates in
   the conic-gradient mask math); the card's `--_opacity-active` is set to `1` (or
   `config.inactiveOpacity` otherwise).
-- Two pseudo-elements (`::before`/`::after`) and a `.glows` layer combine a thin proximity ring, a
+- Two pseudo-elements (`::before`/`::after`) and an `aria-hidden` `.container-glow-glows` layer combine a thin proximity ring, a
   coloured gradient glow, and a blurred backdrop glow, all masked by conic gradients driven from
   `--_start` and `--_spread`.
 - `config.gap`/`config.blur`/`config.spread`/`config.vertical` are applied once (and on every
   `config` change, via a deep `watch`) as private custom properties on the wrapper, which cards
   inherit.
+- The wrapper is a wrapping flex row (or column), so many cards flow onto new rows rather than
+  overflowing. Each card is `280px` wide by default, capped at the wrapper's width, and wraps long
+  unbroken text (`overflow-wrap: anywhere`).
 
 ## Styling
 
-Card background/padding/sizing/border-radius/highlight-colour/brightness/transition-duration and
+Card background (defaults to `--theme-surface-subtle`)/text colour (`--theme-text`)/padding/sizing/border-radius/highlight-colour/brightness/transition-duration and
 the glow gradient itself are public CSS custom properties — see `CONSUMER-STYLING.md` for the full
 token table. Layout and interaction behaviour (proximity, spread, blur, gap, direction, inactive
 opacity) go through the `config` prop instead, since they're computed in JavaScript per pointer
@@ -121,3 +126,11 @@ apply instantly instead of fading).
   `--_direction`/`--_gradient` to match the private-token convention (they're config-driven, not a
   direct CSS override surface).
 - Added a `prefers-reduced-motion: reduce` guard disabling the opacity transition.
+- 2026-10-08 stress-test pass (`StressTest` story): the glow layer class `.glows` was renamed to
+  `.container-glow-glows` (pitfall #16) and marked `aria-hidden`; `tag="li"` now renders the
+  wrapper as a `<ul>` instead of an invalid `<li>`-in-`<div>`; the wrapper wraps (`flex-wrap`)
+  instead of overflowing sideways with many cards; cards cap `min-width` at the wrapper's width and
+  use `overflow-wrap: anywhere`; `config` numbers are clamped (negative gap/blur/proximity, spread
+  outside 0–360, opacity outside 0–1, non-finite values) so a bad value can't produce an invalid
+  `calc()`. Card background default moved from `white` to `--theme-surface-subtle`, and a new
+  `--container-glow-text-colour` token defaults to `--theme-text`.

package/.claude/skills/components/display-avatar.md

@@ -1,5 +1,9 @@
 # DisplayAvatar Component
 
+> **Changed 2026-10-14:** size is a `data-size` attribute, not a bare class (`.display-avatar.lg` → `.display-avatar[data-size="lg"]`). New `image-size` prop (default `112`): `NuxtImg` used to get `width="100%"`, which @nuxt/image ignores, so the Vercel provider requested its largest screen width for every avatar. A broken image now falls back to the initials, initials are emoji-safe, and long fallback text is clipped inside the circle. With `chip`, the status dot was drawn at the avatar's diameter instead of its configured size: avatar and chip both declared a private `--_size` on the same root element and the avatar's size rules won. The avatar's private tokens are now `--_avatar-size`/`--_avatar-font-size`. Content (both slots too) now sits in a full-size `.display-avatar-surface` that carries the background, so the chip's cutout covers the whole avatar instead of landing on the initials span and cutting into the letters.
+
+> **Changed 2026-10-08:** new `status`/`status-label` props, forwarded to the chip. Chip status used to be an `online`/`idle`/`dnd` class through `style-class-passthrough`, which no longer colours the dot.
+
 ## Overview
 
 `DisplayAvatar` renders a circular avatar — either an image (via `NuxtImg`) or a text fallback showing initials derived from the `alt` prop. Optionally wraps in a `DisplayChip` to show a status indicator badge.
@@ -16,8 +20,11 @@
 | `src`                       | `string`                                  | —        | Image URL. Renders `NuxtImg` when set; fallback text otherwise.   |
 | `alt`                       | `string`                                  | —        | Alt text for the image; also used to derive initials.             |
 | `text`                      | `string`                                  | —        | Override the auto-derived initials with an explicit string.       |
-| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Controls width, height, and font-size.                            |
+| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Sets `data-size`, which picks width, height and font-size.        |
 | `chip`                      | `boolean \| DisplayChipConfig`           | —        | Add a status chip. `true` uses defaults; pass a config object to customise. |
+| `status`                    | `DisplayChipStatus`                       | —        | Chip status colour (`offline`/`online`/`idle`/`dnd`), forwarded to `DisplayChip`. Ignored without `chip`; the chip defaults to `offline`. |
+| `status-label`              | `string`                                  | —        | Screen-reader text for the chip status (e.g. "Online"), forwarded to `DisplayChip`. Ignored without `chip`. |
+| `:image-size`              | `number`                                  | `112`    | Pixel width and height requested from `@nuxt/image` (1x; 2x is double). Raise it if you resize the avatar past `xl` with `--display-avatar-size`. |
 | `:style-class-passthrough`  | `string \| string[]`                      | `[]`     | Extra CSS classes on the root element.                            |
 
 ### Size dimensions
@@ -41,24 +48,32 @@ Each step is a token (`--display-avatar-size-md`, `--display-avatar-font-size-md
 | `default` | Replaces the auto image/fallback content entirely.                  |
 | `icon`    | Appended inside the avatar (e.g. an icon overlay over the image). |
 
+Both slots render inside `.display-avatar-surface`, a full-size element that carries the background. With `chip`, that surface is what gets the cutout mask.
+
 ---
 
 ## Fallback text logic
 
 When `src` is not set, a `<span>` renders the fallback value:
 
-1. `text` prop — used as-is if provided.
-2. `alt` initials — first character of each word, capped at two characters.
+1. `text` prop — used as-is if it has any non-whitespace content.
+2. `alt` initials — the first character (a whole grapheme, so emoji and flags stay intact) of the first two words. Extra whitespace is ignored.
 3. Empty string — if neither is set.
 
 When `alt` is set, the initials are `aria-hidden` and the full `alt` is rendered as `sr-only` text, so a screen reader announces "Jane Smith" rather than "J S". With only `text`, the text is read as-is.
 
+If the image fails to load, the initials fallback shows instead (an empty circle when there is no `alt`). A new `src` tries the image again.
+
+The fallback is one line, clipped to the circle: keep `text` short (1–3 characters).
+
 With `src`, the image uses `alt`, or an empty (decorative) `alt` when none is given. Pass `alt` unless the name is already visible next to the avatar.
 
 ```
 alt="John Doe"     → "JD"
 alt="Alice"        → "A"
 alt="Alice Bob C"  → "AB"
+alt="🦄 Unicorn"    → "🦄U"
+alt="  Jane  Smith " → "JS"
 text="?"           → "?"
 ```
 
@@ -102,10 +117,12 @@ text="?"           → "?"
   src="/images/profile.jpg"
   alt="Jane Smith"
   :chip="true"
+  status="online"
+  status-label="Online"
 />
 ```
 
-Default chip config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg" }`.
+Default chip config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg" }`. Without `status` the dot is `offline`.
 
 ### With a custom chip
 
@@ -126,12 +143,12 @@ Full `DisplayChipConfig` shape (pass directly as the `chip` value):
 
 ```ts
 interface DisplayChipConfig {
-  size: string       // chip diameter, e.g. "12px"
-  maskWidth: string  // cutout ring width, e.g. "4px"
-  offset: string     // distance from avatar edge, e.g. "0px"
-  angle: string      // position around avatar (0–360deg), e.g. "45deg"
-  icon?: string      // Iconify icon name
-  label?: string     // short text (max 3 characters)
+  size?: string       // chip diameter, e.g. "12px"
+  maskWidth?: string  // cutout ring width, e.g. "4px"
+  offset?: string     // distance from avatar edge, e.g. "0px"
+  angle?: string      // position around avatar (0–360deg), e.g. "45deg"
+  icon?: string       // Iconify icon name
+  label?: string      // short text (max 3 characters)
 }
 ```
 

package/.claude/skills/components/display-chip.md

@@ -1,5 +1,7 @@
 # DisplayChip Component
 
+> **Changed 2026-10-08 (breaking):** status is the new `status` prop (`data-status`), not an `online`/`idle`/`dnd` class through `styleClassPassthrough`. Shape is `data-shape`, not a `.circle`/`.square` class. Inner classes are `.display-chip-icon`/`.display-chip-label` (were `.chip-icon`/`.chip-label`), with `data-length` instead of `.length-N`. Every `config` field is optional and falls back to a public `--display-chip-*` geometry token. Labels are counted and truncated by grapheme, so emoji are never split. New `statusLabel` prop for screen-reader text.
+
 > **Renamed 2026-09-27:** root class `.display-chip-core` → `.display-chip`. Status colours are now public tokens (`--display-chip-colour-*`, were unprefixed `--color-*`); the geometry vars fed from `config` are private (`--_chip-*`).
 
 ## Overview
@@ -18,23 +20,28 @@ Used directly for standalone chip overlays, and internally by `DisplayAvatar` wh
 | -------------------------- | -------------------------- | ---------- | -------------------------------------------------- |
 | `tag`                      | `"div" \| "span"`          | `"span"`   | Root element tag.                                  |
 | `shape`                    | `"circle" \| "square"`     | `"circle"` | Affects position maths — must match the parent shape. |
-| `:config`                  | `DisplayChipConfig`        | see below  | Controls chip geometry and optional content.       |
-| `:style-class-passthrough` | `string \| string[]`       | `[]`       | Extra CSS classes — use for status colour variants. |
+| `status`                   | `DisplayChipStatus`        | `"offline"` | `"offline" \| "online" \| "idle" \| "dnd"`. Sets the dot colour via `data-status`. |
+| `status-label`             | `string`                   | `""`       | Screen-reader text for the status (e.g. "Online"), so it isn't conveyed by colour alone. Pass translated copy. |
+| `:config`                  | `DisplayChipConfig`        | `{}`       | Geometry and optional content. Every field is optional. |
+| `:style-class-passthrough` | `string \| string[]`       | `[]`       | Extra CSS classes on the root.                     |
 
 ### DisplayChipConfig
 
 ```ts
 interface DisplayChipConfig {
-  size: string       // chip dot diameter, e.g. "12px"
-  maskWidth: string  // cutout ring width around the chip, e.g. "4px"
-  offset: string     // extra distance from the parent edge, e.g. "0px"
-  angle: string      // position around the parent (0–360deg), e.g. "45deg"
-  icon?: string      // Iconify icon name rendered inside the chip
-  label?: string     // short text rendered inside the chip (max 3 characters)
+  size?: string       // chip dot diameter, e.g. "12px"
+  maskWidth?: string  // cutout ring width around the chip, e.g. "4px"
+  offset?: string     // extra distance from the parent edge, e.g. "0px"
+  angle?: string      // position around the parent (0–360deg), e.g. "45deg"
+  icon?: string       // Iconify icon name rendered inside the chip (decorative, aria-hidden)
+  label?: string      // short text rendered inside the chip (max 3 characters)
 }
 ```
 
-Default config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg" }`.
+A missing geometry field falls back to its token: `--display-chip-size` (`1.2rem`),
+`--display-chip-mask-width` (`0.4rem`), `--display-chip-offset` (`0rem`), `--display-chip-angle`
+(`90deg`). A field set in `config` beats the token. Negative `size`/`maskWidth` clamp to `0`; values
+without units (`"45"`) are invalid CSS and hide the dot.
 
 ### Angle reference
 
@@ -53,27 +60,30 @@ Default config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg"
 
 ## Status colours
 
-Apply status via `styleClassPassthrough` — the component has built-in colour variants:
+Set with the `status` prop:
 
-| Class | Token | Default |
+| `status` | Token | Default |
 | --- | --- | --- |
-| (none) | `--display-chip-colour-offline` | `slategrey` |
-| `online` | `--display-chip-colour-online` | `rgb(0, 255, 135)` |
-| `idle` | `--display-chip-colour-idle` | `rgb(255, 185, 51)` |
-| `dnd` | `--display-chip-colour-dnd` | `rgb(255, 40, 80)` |
+| `offline` (default) | `--display-chip-colour-offline` | `var(--status-neutral)` |
+| `online` | `--display-chip-colour-online` | `var(--status-success)` |
+| `idle` | `--display-chip-colour-idle` | `var(--status-warning)` |
+| `dnd` | `--display-chip-colour-dnd` | `var(--status-danger)` |
+
+Defaults come from the global status tokens (changed 2026-10-07, were neon `rgb()` values); see
+`.claude/skills/theming-status-tokens.md`.
 
 Icon and label colour: `--display-chip-text-colour` (default `black`). Full reference:
 `app/components/02.molecules/display-chip/CONSUMER-STYLING.md`.
 
 ```vue
-<DisplayChip :style-class-passthrough="['online']">...</DisplayChip>
+<DisplayChip status="online" status-label="Online">...</DisplayChip>
 ```
 
 ---
 
 ## Label constraints
 
-- Max 3 characters. Longer values are silently truncated with a `console.warn`.
+- Max 3 characters, counted as graphemes: an emoji (including ZWJ sequences like 👨‍👩‍👧‍👦 and flags) counts as one and is never split. Longer values are truncated with a `console.warn`. Whitespace is trimmed; a whitespace-only label renders nothing.
 - Font-size scales automatically with chip size via `--_font-size-adjust`:
   - 1 char → `0.7 × size`
   - 2 chars → `0.6 × size`
@@ -97,7 +107,7 @@ Icon and label colour: `--display-chip-text-colour` (default `black`). Full refe
 <DisplayChip
   shape="circle"
   :config="{ size: '12px', maskWidth: '4px', offset: '0px', angle: '45deg' }"
-  :style-class-passthrough="['online']"
+  status="online"
 >
   <div class="avatar">SRC</div>
 </DisplayChip>
@@ -109,7 +119,7 @@ Icon and label colour: `--display-chip-text-colour` (default `black`). Full refe
 <DisplayChip
   shape="square"
   :config="{ size: '10px', maskWidth: '3px', offset: '2px', angle: '135deg' }"
-  :style-class-passthrough="['idle']"
+  status="idle"
 >
   <img src="/thumbnail.jpg" alt="Card thumbnail" />
 </DisplayChip>
@@ -120,7 +130,7 @@ Icon and label colour: `--display-chip-text-colour` (default `black`). Full refe
 ```vue
 <DisplayChip
   :config="{ size: '16px', maskWidth: '4px', offset: '0px', angle: '45deg', icon: 'bi:check-circle-fill' }"
-  :style-class-passthrough="['online']"
+  status="online"
 >
   <div class="avatar">SRC</div>
 </DisplayChip>
@@ -132,7 +142,7 @@ Icon and label colour: `--display-chip-text-colour` (default `black`). Full refe
 <!-- 1–3 characters only; longer values are truncated with a warning -->
 <DisplayChip
   :config="{ size: '16px', maskWidth: '4px', offset: '0px', angle: '45deg', label: '+2' }"
-  :style-class-passthrough="['dnd']"
+  status="dnd"
 >
   <div class="avatar">SRC</div>
 </DisplayChip>
@@ -156,7 +166,7 @@ const chipConfig = computed((): DisplayChipConfig => ({
 </script>
 
 <template>
-  <DisplayChip shape="circle" :config="chipConfig" :style-class-passthrough="['online']">
+  <DisplayChip shape="circle" :config="chipConfig" status="online">
     <div class="avatar">SRC</div>
   </DisplayChip>
 </template>
@@ -171,7 +181,8 @@ Prefer `DisplayAvatar` with its `chip` prop over wiring `DisplayChip` directly:
   src="/images/profile.jpg"
   alt="Jane Smith"
   :chip="{ size: '12px', maskWidth: '4px', offset: '0px', angle: '45deg' }"
-  :style-class-passthrough="['online']"
+  status="online"
+  status-label="Online"
 />
 ```
 
@@ -184,6 +195,7 @@ See [display-avatar.md](./display-avatar.md) for the full API.
 ```vue
 <DisplayChip
   :config="chipConfig"
+  status="online"
   :style-class-passthrough="['my-chip']"
 >
   <div class="avatar">SRC</div>
@@ -214,5 +226,7 @@ See [display-avatar.md](./display-avatar.md) for the full API.
 - `shape` must match the actual shape of the slot content — the position maths differs between `circle` (radius-based) and `square` (clamped corner-aware).
 - `config` values are geometric inputs to CSS `calc(cos())` / `calc(sin())` expressions. Pass them as strings with units (`"12px"`, `"45deg"`), not plain numbers.
 - The chip dot is rendered via `::after` pseudo-element; icon and label sit above it at `z-index: 2`.
-- The mask cutout is applied to all direct children of `.display-chip` except `.chip-icon` and `.chip-label` — ensure the host element is a direct child.
+- The mask cutout is applied to all direct children of `.display-chip` except `.display-chip-icon`, `.display-chip-label` and the `.sr-only` status text. The mask is positioned in percentages of each child's own box, so slot exactly one host element that fills the chip and carries its own background (an `<img>`, or a full-size wrapper around text). A small text span as a direct child gets the notch cut into its letters, and a background set on `.display-chip` itself is never cut. `DisplayAvatar` wraps its content in a full-size `.display-avatar-surface` for this reason.
+- A component that renders `DisplayChip` as its own root (as `DisplayAvatar` does) shares that element, so it must not declare the chip's private tokens (`--_size`, `--_offset`, ...) for its own values: they collide on the same element. `DisplayAvatar` uses `--_avatar-size`.
+- The `StressTest` story shows the worst-case labels and config values.
 - `DisplayChipConfig` and `DisplayChipProps` are both exported from the layer types. Use `DisplayChipConfig` when passing geometry values (the `config` prop). Use `DisplayChipProps` only if you need to pass the full component prop set (e.g. when building a wrapper component).

package/.claude/skills/components/display-pill.md

@@ -9,10 +9,10 @@ A classic pill/badge component for displaying status labels, tags, or metadata.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `tag` | `"span" \| "div" \| "button" \| "a"` | `"span"` | Root element. Use `"button"` or `"a"` for interactive pills: cursor switches to pointer and a `:focus-visible` outline is shown. A `button` gets `type="button"`; pass `href` (falls through) for an `a`. |
-| `label` | `string` | `undefined` | Pill text. When set, renders inside `.display-pill-label` and suppresses the default slot |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant |
-| `variant` | `"default" \| "primary" \| "success" \| "warning" \| "danger" \| "neutral"` | `"default"` | Colour variant |
-| `reversed` | `boolean` | `false` | Reverses icon/label order (`flex-direction: row-reverse`) |
+| `label` | `string` | `undefined` | Pill text. When set (and not just whitespace), renders inside `.display-pill-label` and suppresses the default slot |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size, rendered as `data-size` |
+| `variant` | `"default" \| "primary" \| "success" \| "warning" \| "danger" \| "neutral"` | `"default"` | Colour variant, rendered as `data-variant`; an unknown value gets the default colours |
+| `reversed` | `boolean` | `false` | Reverses icon/label order (`flex-direction: row-reverse`), rendered as `data-reversed` |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes merged onto the root element |
 
 ## Slots
@@ -20,7 +20,7 @@ A classic pill/badge component for displaying status labels, tags, or metadata.
 | Slot | Description |
 |------|-------------|
 | `icon` | Icon content, wrapped in `.display-pill-icon` (sized by `--display-pill-icon-size`) — rendered before the label by default, after when `reversed=true` |
-| `default` | Custom label content — only used when the `label` prop is not set |
+| `default` | Custom label content, wrapped in `.display-pill-label` (so it's line-clamped like `label`) — only used when the `label` prop is not set or is whitespace |
 
 ## Basic usage
 
@@ -69,7 +69,7 @@ When `label` is not set, the default slot is rendered instead:
 
 Full token list in `CONSUMER-STYLING.md` next to the component. All tokens are `--display-pill-*` (renamed from `--theme-pill-*` on 2026-09-27; `bg`/`color` became `background`/`text-colour`).
 
-Colour resolves as **variant token → base token → variant default**: `--display-pill-background`/`-text-colour` restyle every variant; `--display-pill-success-background` etc. win for that variant only. Sizes have `-sm`/`-lg` suffixed tokens for font size and icon size only; padding and gap are the icon size times a ratio (`--display-pill-padding-inline-ratio` 0.7, `-padding-inline-icon-ratio` 0.4, `-padding-block-ratio` 0.3, `-gap-ratio` 0.35), so spacing scales with the pill. Absolute `--display-pill-padding-inline`/`-padding-block`/`-gap` tokens still override. The icon side of a pill gets `--display-pill-padding-inline-icon` (tighter than `--display-pill-padding-inline`), placed by `data-icon-position` (`start`, `end` when `reversed`, `only` for icon-only, absent with no icon), so label-only pills stay evenly padded.
+Colour resolves as **variant token → base token → variant default**: `--display-pill-background`/`-text-colour` restyle every variant; `--display-pill-success-background` etc. win for that variant only. Borders follow the same chain: `--display-pill-<variant>-border-colour` → `--display-pill-border-colour` → `transparent`. So do rings (`--display-pill-ring-width`, a box-shadow): `--display-pill-<variant>-ring-colour` → `--display-pill-ring-colour` → the pill's background. Sizes have `-sm`/`-lg` suffixed tokens for font size and icon size only; padding and gap are the icon size times a ratio (`--display-pill-padding-inline-ratio` 0.7, `-padding-inline-icon-ratio` 0.4, `-padding-block-ratio` 0.3, `-gap-ratio` 0.35), so spacing scales with the pill. Absolute `--display-pill-padding-inline`/`-padding-block`/`-gap` tokens still override. The icon side of a pill gets `--display-pill-padding-inline-icon` (tighter than `--display-pill-padding-inline`), placed by `data-icon-position` (`start`, `end` when `reversed`, `only` for icon-only, absent with no icon), so label-only pills stay evenly padded.
 
 ```vue
 <DisplayPill label="New" variant="primary" style-class-passthrough="pill-new" />
@@ -89,17 +89,65 @@ Colour resolves as **variant token → base token → variant default**: `--disp
   --display-pill-border-style: dashed;
 }
 
-/* Decorative outline ring */
-.ringed.display-pill {
+/* Two-tone: dark border in the variant's text colour, light ring in its background colour */
+.two-tone.display-pill {
+  --display-pill-border-colour: currentColor;
+  --display-pill-ring-width: 0.2rem; /* --display-pill-ring-colour defaults to the variant background */
+}
+
+/* Offset outline (a gap between pill and line); unlike the ring, outline ignores border-radius before Safari 16.4 */
+.offset-outline.display-pill {
   --display-pill-outline: 0.2rem solid currentColor;
   --display-pill-outline-offset: 0.3rem;
 }
 ```
 
-## Notes
+## Outlined variants
+
+The default text steps (`-09`/`-10`) are near-black in every hue, so an outlined pill using
+`currentColor` for its border makes the variants look alike (`warning` and `danger` especially).
+Lift each variant's text to its `-07` step (all 48% lightness, so contrast stays even); the border
+follows. Neutral is normally the dark inverted pill, so give it a dark text step here.
+
+```css
+.tag-list {
+  --display-pill-background: transparent;
+  --display-pill-border-colour: currentColor;
+  --display-pill-text-colour: var(--slate-07);
+  --display-pill-primary-text-colour: var(--blue-07);
+  --display-pill-success-text-colour: var(--green-07);
+  --display-pill-warning-text-colour: var(--orange-07);
+  --display-pill-danger-text-colour: var(--red-07);
+  --display-pill-neutral-text-colour: var(--slate-10);
+
+  /* Optional 2px ring in each variant's -02 step */
+  --display-pill-ring-width: 0.2rem;
+  --display-pill-ring-colour: var(--slate-02);
+  --display-pill-primary-ring-colour: var(--blue-02);
+  --display-pill-success-ring-colour: var(--green-02);
+  --display-pill-warning-ring-colour: var(--orange-02);
+  --display-pill-danger-ring-colour: var(--red-02);
+}
+```
+
+To keep the dark text and colour only the border, set `--display-pill-<variant>-border-colour`
+instead (e.g. `var(--status-success)`). The ring is a box-shadow: it takes no layout space, so
+leave a gap between ringed pills.
 
-- Since 2026-10-06 a pill never grows past its container: a label too long for the space ends in an ellipsis (it still never wraps).
+## Stories
+
+`Default`, `AllVariants`, `OutlinedViaBaseTokens` (per-variant mid-step borders), `OutlinedMonochrome`
+(the recipe above, with a story-only `ring` control), `RingedTwoTone` (dark border inside a light ring;
+the `ring` control swaps the ring to `-02`), and `StressTest`. `labelLineClamp` and `ring` are
+story-only controls that set CSS tokens, not props. The stories link to `ServiceSummary` and
+`ServiceDetail`, which render neutral duration/price pills.
+
+## Notes
 
+- Since 2026-10-06 a pill never grows past its container: a label too long for the space ends in an ellipsis. Since 2026-10-08 that's a line clamp, `--display-pill-label-line-clamp` (default `1`); set `none` to let long labels wrap (worth it for text that must stay readable, like a price, in a narrow column).
+- Since 2026-10-08 a pill with no text and no icon (empty or whitespace-only `label`, no slots) renders nothing visible (`:empty { display: none }`), and a whitespace-only `label` with an icon gives an icon-only pill.
+- 2026-10-08 (breaking): size/variant/reversed moved from bare classes (`.sm`, `.primary`, `.is-reversed`) to `data-size`/`data-variant`/`data-reversed`, so a consumer's own `.primary`/`.success` utility classes can't hit the pill. Selectors like `.display-pill.primary` become `.display-pill[data-variant="primary"]`.
+- `StressTest` story covers long/unbroken/RTL/emoji/HTML-like labels, empty and whitespace labels, a broken icon and an unknown variant at three container widths.
 - `border-radius` defaults to `100vw` — this always collapses to the tightest possible radius on the shorter axis, making it geometry-independent (no magic number needed).
 - `cursor: default` and `user-select: none` are applied unconditionally. `cursor: pointer` is applied automatically via `:is(button, a)` when `tag` is interactive.
 - All variant colour pairs use a light-tint background (`--color-01`) with a dark text colour (`--color-09`/`--color-10`) to ensure WCAG AA contrast. The project colour scale runs `00` (lightest) → `10` (darkest) — the opposite of Tailwind.