@teamblind-chorus/ui 1.2.0 → 2.0.0

package/agents/components/carousel/profile.spec.json

@@ -26,7 +26,7 @@
     },
     "card": {
       "required": true,
-      "description": "One profile card per page. **Width is fixed at 176px** — every card paints the same footprint regardless of how many entries the rail carries. Vertical stack: cover band → avatar (overlapping) → name → followers → metrics row → follow toggle. `sys.color.surface` fill, `sys.radius.md` corner, `sys.borderWidth.hairline sys.color.outlineVariant` inset outline. `scroll-snap-align: start`.",
+      "description": "One profile card per page. **Width is fixed at 176px** — every card paints the same footprint regardless of how many entries the rail carries. Vertical stack: cover band → avatar (overlapping) → name → followers → metrics row → follow toggle. `sys.color.surface.default` fill, `sys.radius.md` corner, `sys.borderWidth.hairline sys.color.border.default` inset outline. `scroll-snap-align: start`.",
       "intrinsic": true
     },
     "cover": {
@@ -46,33 +46,33 @@
     },
     "name": {
       "required": true,
-      "description": "Entity name (channel / profile / company). `sys.typo.label.md` / Semibold / `sys.color.onSurface`. Centered; single line, truncates with ellipsis.",
+      "description": "Entity name (channel / profile / company). `sys.typo.label.md` / Semibold / `sys.color.text.default`. Centered; single line, truncates with ellipsis.",
       "accepts": [
         "text"
       ]
     },
     "followers": {
       "required": true,
-      "description": "Follower count line. `sys.typo.label.sm` / Semibold / `sys.color.onSurfaceVariant`. Centered; single line.",
+      "description": "Follower count line. `sys.typo.label.sm` / Semibold / `sys.color.text.subtle`. Centered; single line.",
       "accepts": [
         "text"
       ]
     },
     "metrics": {
       "required": false,
-      "description": "Row of metric chips below the name / followers stack. Each chip is `icon + value` painted in `sys.typo.label.sm` / `sys.color.onSurface`. Three default kinds: { icon: 'star', … } → `StarFillIcon` in `sys.color.icon.yellow`; { icon: 'pulse', … } → `PulseFillIcon` in `sys.color.success`; { icon: 'heart', … } → `HeartFillIcon` in `sys.color.icon.red`. Consumers may pass custom { icon: <ReactNode>, value, color? } entries for other shapes. Mutually exclusive with `description` — when both are present `description` wins.",
+      "description": "Row of metric chips below the name / followers stack. Each chip is `icon + value` painted in `sys.typo.label.sm` / `sys.color.text.default`. Three default kinds: { icon: 'star', … } → `StarFillIcon` in `sys.color.icon.accent.yellow.default`; { icon: 'pulse', … } → `PulseFillIcon` in `sys.color.text.success`; { icon: 'heart', … } → `HeartFillIcon` in `sys.color.icon.accent.red.default`. Consumers may pass custom { icon: <ReactNode>, value, color? } entries for other shapes. Mutually exclusive with `description` — when both are present `description` wins.",
       "intrinsic": true
     },
     "description": {
       "required": false,
-      "description": "Two-line clamped descriptive paragraph that replaces the metrics row when present. `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, centered. The slot reserves a fixed height of two `label.sm` lines so card height stays consistent across cards that carry metrics and cards that carry copy — extra content clamps with a trailing ellipsis.",
+      "description": "Two-line clamped descriptive paragraph that replaces the metrics row when present. `sys.typo.label.sm` / `sys.color.text.subtle`, centered. The slot reserves a fixed height of two `label.sm` lines so card height stays consistent across cards that carry metrics and cards that carry copy — extra content clamps with a trailing ellipsis.",
       "accepts": [
         "text"
       ]
     },
     "followAction": {
       "required": true,
-      "description": "Trailing full-width [Toggle Button](../button/text.md) at the foot of the card. `Follow` (inactive) → `Following` (active). The carousel does not paint its own follow chrome — every state binding lives on the Toggle Button (Chip-toggle) contract, which paints `sys.color.primary` while inactive and a `transparent` fill with a hairline outline while active so the followed state recedes against the card's own `surface` tier without re-painting a tone that would clash.",
+      "description": "Trailing full-width [Toggle Button](../button/text.md) at the foot of the card. `Follow` (inactive) → `Following` (active). The carousel does not paint its own follow chrome — every state binding lives on the Toggle Button (Chip-toggle) contract, which paints `sys.color.background.primary` while inactive and a `transparent` fill with a hairline outline while active so the followed state recedes against the card's own `surface` tier without re-painting a tone that would clash.",
       "accepts": [
         "button"
       ],
@@ -90,8 +90,8 @@
     "pagePeek": "ref.space.500",
     "pagePeekNote": "Guaranteed minimum visibility of the next card at the trailing edge — pinned to 40px (ref.space.500). Identical contract to PostCarousel.",
     "pageSnapAnchor": "Cards stick to the leading edge of the pager (the pager's own `padding-left`, the 16 rail). `scroll-snap-align: start` plus the pager's `scroll-padding-left: sys.layout.container.md` produce this anchor.",
-    "cardFill": "sys.color.surface",
-    "cardOutline": "sys.borderWidth.hairline sys.color.outlineVariant",
+    "cardFill": "sys.color.surface.default",
+    "cardOutline": "sys.borderWidth.hairline sys.color.border.default",
     "cardOutlineComposition": "overlay",
     "cardOutlineCompositionNote": "Painted on a dedicated `::after` overlay layer (`position: absolute; inset: 0; z-index: 2; pointer-events: none`), not as an inset `box-shadow` on the card box itself. The card hosts an opaque full-bleed cover band at the top; an inset shadow on the card would be masked by that fill at the top edge. Same overlay idiom DESIGN.md prescribes for the focus ring — so the stroke renders above every child regardless of edge-painting content.",
     "cardRadius": "sys.radius.md",
@@ -99,25 +99,25 @@
     "cardWidthNote": "Fixed pixel width — every profile card paints the same 176px footprint regardless of card count or screen width. The pager scrolls horizontally so the 176px footprint never reflows.",
     "cardStackGap": "sys.layout.stack.sm",
     "coverHeight": "88px",
-    "coverFill": "sys.color.surfaceContainerHigh (background underlay — the placeholder image paints on top via `object-fit: cover`)",
+    "coverFill": "sys.color.surface.default (background underlay — the placeholder image paints on top via `object-fit: cover`)",
     "coverImageSource": "Same `/placeholder.png` asset every Chorus image-area slot falls back to. Cropped to fill the 88px band via `object-fit: cover` — the placeholder's centered 'blind' wordmark stays visually centered. Decorative — `aria-hidden`. Consumers can override per-item via `items[i].cover.src` (any image URL preserving the same `object-fit: cover` crop).",
     "avatarSize": 64,
-    "avatarOverlap": "Avatar's vertical center sits on the cover band's bottom edge — the bottom half of the avatar bleeds onto the card surface. The 2-token (`sys.borderWidth.thin`) `sys.color.surface` halo separating the avatar from the cover band is owned by Thumbnail's `outlined={true}` case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)) — outset `box-shadow`, not a wrapper border. Same contract as ProfileHeader's avatar.",
+    "avatarOverlap": "Avatar's vertical center sits on the cover band's bottom edge — the bottom half of the avatar bleeds onto the card surface. The 2-token (`sys.borderWidth.thin`) `sys.color.surface.default` halo separating the avatar from the cover band is owned by Thumbnail's `outlined={true}` case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)) — outset `box-shadow`, not a wrapper border. Same contract as ProfileHeader's avatar.",
     "nameTypo": "sys.typo.label.md",
-    "nameColor": "sys.color.onSurface",
+    "nameColor": "sys.color.text.default",
     "followersTypo": "sys.typo.label.sm",
-    "followersColor": "sys.color.onSurfaceVariant",
+    "followersColor": "sys.color.text.subtle",
     "metricsRowGap": "sys.layout.inline.md",
     "metricChipTypo": "sys.typo.label.sm",
-    "metricChipColor": "sys.color.onSurface",
+    "metricChipColor": "sys.color.text.default",
     "metricIconSize": "sys.icon.md",
-    "metricIconStar": "StarFillIcon — sys.color.icon.yellow",
-    "metricIconPulse": "PulseFillIcon — sys.color.success",
-    "metricIconHeart": "HeartFillIcon — sys.color.icon.red",
+    "metricIconStar": "StarFillIcon — sys.color.icon.accent.yellow.default",
+    "metricIconPulse": "PulseFillIcon — sys.color.text.success",
+    "metricIconHeart": "HeartFillIcon — sys.color.icon.accent.red.default",
     "midSlotHeight": "calc(sys.typo.label.sm.size * sys.typo.label.sm.line * 2)",
     "midSlotHeightNote": "Shared fixed height for the metrics row and the description slot — exactly two `label.sm` lines (12 × 1.5 × 2 ≈ 36px). Cards that carry metrics and cards that carry a description paint the same outer height.",
     "descriptionTypo": "sys.typo.label.sm",
-    "descriptionColor": "sys.color.onSurfaceVariant",
+    "descriptionColor": "sys.color.text.subtle",
     "descriptionLineClamp": 2,
     "descriptionOverflow": "Two-line clamp with trailing ellipsis; copy exceeding two lines truncates so the slot height stays fixed.",
     "followActionRendersAs": "Button variant='toggle' — Chip-toggle anatomy. Stretched to full card width via a wrapper rule. All state tokens delegate to the Toggle Button (Chip) family.",

package/agents/components/chip/chip.md

@@ -8,5 +8,5 @@ A small, content-shaped control or label — chip-shaped affordance for two anch
 
 ## Sub-components
 
-- **[Filter](./filter.md)** — Selectable filter chip. Capsule (`radius.full`), `surfaceContainerHigh` raised tone with a hairline `outlineVariant` stroke at rest, swaps to an inverse fill when selected. Optional leading and trailing icons.
+- **[Filter](./filter.md)** — Selectable filter chip. Capsule (`radius.full`), `surfaceContainerHigh` raised tone with a hairline `border.default` stroke at rest, swaps to an inverse fill when selected. Optional leading and trailing icons.
 - **[Tag](./tag.md)** — Informational tag chip. Square-cornered (`radius.sm`), `secondaryContainer` fill that sits one tonal step *below* the lifted Filter so the label reads as attached metadata rather than a tappable choice. Optional trailing icon only — typically the dismiss "×" for opt-out flows.

package/agents/components/chip/filter.md

@@ -10,7 +10,7 @@ The selectable chip — a capsule-shaped toggle for refining a set. Unselected i
 
 ## Default
 
-At-rest — transparent fill with a hairline `outlineVariant` stroke so the chip sits on any surface without colliding with the surface ladder.
+At-rest — transparent fill with a hairline `border.default` stroke so the chip sits on any surface without colliding with the surface ladder.
 
 ```preview
 chip/filter/unselected
@@ -22,9 +22,7 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-## Use cases
-
-### Selected
+## Selected
 
 Active — inverse-toned fill. Toggle the `selected` flag on the same chip element.
 
@@ -41,7 +39,7 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-### With icon
+## Leading icon
 
 Facet glyph before the label — tag for category, magnifier for search, check on selection.
 
@@ -59,7 +57,7 @@ import { CheckedIcon } from '@teamblind-chorus/ui/icons';
 </Chip>
 ```
 
-### With trailing icon
+## Trailing icon
 
 Directional/dismiss glyph after the label — chevron-down to expand, *×* to clear.
 
@@ -77,7 +75,7 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 </Chip>
 ```
 
-### With trailing action
+## 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.
 
@@ -128,7 +126,21 @@ import { ArrowDownIcon } from '@teamblind-chorus/ui/icons';
 </div>
 ```
 
-### Group
+## Focused
+
+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>
+```
+
+## 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.
 
@@ -153,20 +165,6 @@ import { Chip } from '@teamblind-chorus/ui';
 </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.
@@ -197,8 +195,8 @@ Single visual variant; the selected/unselected toggle swaps the container/label
 
 | 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`      |
+| unselected   | `transparent`                       | `sys.color.border.default`                              | `sys.color.text.default`             |
+| selected     | `sys.color.background.inverse`          | `transparent`                                           | `sys.color.text.inverse`      |
 
 ## States
 

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

@@ -63,16 +63,16 @@
   "selectionStates": {
     "unselected": {
       "background": "transparent",
-      "label": "sys.color.onSurface",
+      "label": "sys.color.text.default",
       "border": {
         "width": "sys.borderWidth.hairline",
-        "color": "sys.color.outlineVariant"
+        "color": "sys.color.border.default"
       },
       "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",
+      "background": "sys.color.background.inverse",
+      "label": "sys.color.text.inverse",
       "border": null
     }
   },
@@ -102,35 +102,39 @@
         "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
         "innerCounterRing": {
           "width": "sys.borderWidth.hairline",
-          "color": "sys.color.focusInset"
+          "color": "sys.color.border.focused"
         },
         "outerRing": {
           "width": "sys.borderWidth.thin",
-          "color": "sys.color.focus"
+          "color": "sys.color.border.focused"
         }
       },
       "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the chip is in; never via plain mouse click."
     },
     "disabled": {
       "overlay": null,
-      "containerOpacity": "sys.state.disabled",
+      "background": "sys.color.background.disabled",
+      "label": "sys.color.text.disabled",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.border.bold"
+      },
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border so the shape reads on any surface, plus disabled label. Overrides the rest/selected appearance."
     }
   },
   "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.",
+    "compositionReason": "Action affordance with breathing room around it; the 1px outward ring 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"
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused"
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },

package/agents/components/chip/tag.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/chip/tag.md`](../../../i18n/ko/schema/components/chip/tag.md)
 
-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.
+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.background.neutral` 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.
 
@@ -22,11 +22,9 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-## Use cases
+## Accent
 
-### 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.
+Tonal pale-primary fill — `sys.color.background.selected` background, `sys.color.background.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
@@ -38,7 +36,7 @@ import { Chip } from '@teamblind-chorus/ui';
 </Chip>
 ```
 
-### Dismissable
+## Dismissable
 
 Opt-out — same chip with a trailing *×* to remove the tag. Trailing icon inherits label color via `currentColor`.
 
@@ -56,7 +54,22 @@ import { XIcon } from '@teamblind-chorus/ui/icons';
 </Chip>
 ```
 
-### Group
+## Focused
+
+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>
+```
+
+## 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).
 
@@ -76,21 +89,6 @@ import { Chip } from '@teamblind-chorus/ui';
 </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.
@@ -120,8 +118,8 @@ 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`          |
+| `default`  | `sys.color.background.neutral` (translucent inverse-tone overlay — black 8% light / white 8% dark) | `sys.color.text.default`        |
+| `accent`   | `sys.color.background.selected` (theme-aware)                                                  | `sys.color.background.primary`          |
 
 ## States
 

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

@@ -3,7 +3,7 @@
   "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.",
+  "description": "Informational chip. Square-cornered metadata label. Passive (or dismissable via trailing ×). No leading icon. Two appearances: `default` paints the translucent `sys.color.background.neutral` 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.background.selected`) with primary label for tags that need to pop against the surface.",
   "element": "span",
   "props": {
     "variant": {
@@ -44,15 +44,15 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.scrimSubtle",
-      "label": "sys.color.onSurface",
+      "background": "sys.color.background.neutral",
+      "label": "sys.color.text.default",
       "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."
+      "note": "Background is the translucent inverse-tone scrim (`sys.color.background.neutral` — 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",
+      "background": "sys.color.background.selected",
+      "label": "sys.color.text.link",
       "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."
     }
@@ -83,35 +83,39 @@
         "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
         "innerCounterRing": {
           "width": "sys.borderWidth.hairline",
-          "color": "sys.color.focusInset"
+          "color": "sys.color.border.focused"
         },
         "outerRing": {
           "width": "sys.borderWidth.thin",
-          "color": "sys.color.focus"
+          "color": "sys.color.border.focused"
         }
       },
       "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the chip is in; never via plain mouse click."
     },
     "disabled": {
       "overlay": null,
-      "containerOpacity": "sys.state.disabled",
+      "background": "sys.color.background.disabled",
+      "label": "sys.color.text.disabled",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.border.bold"
+      },
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border so the shape reads on any surface, plus disabled label. Overrides the rest/selected appearance."
     }
   },
   "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.",
+    "compositionReason": "Action affordance with breathing room around it; the 1px outward ring 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"
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused"
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },

package/agents/components/dialog/dialog.md

@@ -33,9 +33,7 @@ const [open, setOpen] = useState(false);
 </>
 ```
 
-## Use cases
-
-### With image
+## Image
 
 Pass an `image` to add a centred illustration between title and actions. With the image present, the whole stack centre-aligns. `imageFirst` (default `true`) controls whether the image sits under the title or the body.
 

package/agents/components/dialog/dialog.spec.json

@@ -90,18 +90,18 @@
   "sizing": {
     "scrimTint": "ref.palette.black.600",
     "scrimPaddingInline": "ref.space.500",
-    "containerFill": "sys.color.surfaceContainerHigh",
+    "containerFill": "sys.color.surface.default",
     "containerRadius": "sys.radius.xl",
     "elevation": "sys.elevation.overlay",
     "containerPadding": "sys.layout.container.lg",
     "maxWidth": "480px",
     "titleTypo": "sys.typo.heading.sm",
-    "titleColor": "sys.color.onSurface",
+    "titleColor": "sys.color.text.default",
     "imageWidth": "100%",
     "imageHeight": "auto",
     "imageRadius": "sys.radius.lg",
     "bodyTypo": "sys.typo.body.sm",
-    "bodyColor": "sys.color.onSurfaceVariant",
+    "bodyColor": "sys.color.text.subtle",
     "interSlotGap": "sys.layout.stack.md",
     "actionsStackGap": "sys.layout.stack.xs"
   },

package/agents/components/directory-list/directory-list.md

@@ -31,9 +31,7 @@ import { DirectoryList } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With header action
+## Header action
 
 Extends the header with a trailing `accent` Text Button when the screen has a broader index page to route to.
 

package/agents/components/directory-list/directory-list.spec.json

@@ -55,12 +55,12 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerPaddingBlock": "sys.layout.container.lg",
     "containerPaddingInline": "sys.layout.container.md",
     "headerToListGap": "sys.layout.stack.md",
     "labelTypo": "sys.typo.heading.md",
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — link-affordance accent rule.",
     "rowRung": "list/entry size=\"large\" — 48 avatar, inline.lg gap, label.md primary, label.sm secondary + description.",
     "rowInlinePaddingNote": "Each row keeps the list/entry native sys.layout.container.md inline padding (the tap target reaches the surface edge) and adds margin-inline: calc(-1 * sys.layout.container.md) so the visible avatar sits flush at the section's content rail — aligned with the header label at 16 from the surface.",

package/agents/components/divider/divider.family.json

@@ -2,7 +2,7 @@
   "$schema": "../../family.schema.json",
   "family": "divider",
   "name": "Divider",
-  "description": "Region separator — a heavy tonal band that splits adjacent regions whose vertical rhythm alone doesn't read as a boundary. Painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) so the band stays visible on every host surface tier (`surface`, `surfaceContainer`, `surfaceContainerHigh`, hero, …) without colliding with a fixed neutral step. Same scrim used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton — Divider is the section-level member of that family. Reserved for *region*-level separation between groups that don't share an enclosing container (a feed segment ending and a followed-channels list beginning, a recents block ending above a single anchored CTA). Not for row-level separators inside a List (the list's own `divider={true}` paints those as a hairline `outlineVariant` rule). Single-spec family.",
+  "description": "Region separator — a heavy tonal band that splits adjacent regions whose vertical rhythm alone doesn't read as a boundary. Painted with `sys.color.border.default` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) so the band stays visible on every host surface tier (`surface`, `surfaceContainer`, `surfaceContainerHigh`, hero, …) without colliding with a fixed neutral step. Same scrim used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton — Divider is the section-level member of that family. Reserved for *region*-level separation between groups that don't share an enclosing container (a feed segment ending and a followed-channels list beginning, a recents block ending above a single anchored CTA). Not for row-level separators inside a List (the list's own `divider={true}` paints those as a hairline `border.default` rule). Single-spec family.",
   "useCases": [
     "between page-level content groups",
     "between a feed segment and the section below",

package/agents/components/divider/divider.md

@@ -2,19 +2,19 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/divider/divider.md`](../../../i18n/ko/schema/components/divider/divider.md)
 
-A section-break band — a single full-bleed block painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black in light mode, white in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). Reach for it when two adjacent regions don't share an enclosing container and vertical rhythm alone doesn't read as a boundary — a directory of suggested channels ending and a fresh recommendation list beginning, a feed segment ending and a followed-channels list resuming, a promo strip ending and content picking up below.
+A section-break band — a single full-bleed block painted with `sys.color.border.default` (~8% inverse-tone overlay — black in light mode, white in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). Reach for it when two adjacent regions don't share an enclosing container and vertical rhythm alone doesn't read as a boundary — a directory of suggested channels ending and a fresh recommendation list beginning, a feed segment ending and a followed-channels list resuming, a promo strip ending and content picking up below.
 
-**Reach for this when** the boundary between two regions is ambiguous because they share the same surface and vertical rhythm — the visitor's eye should *land* on the break, not infer it. **Skip when** the regions already sit on different surfaces (one card, one canvas — the surface change is the break), when one region carries a heading that itself reads as the start of a new block, or when the separation is between *rows of the same list* (List's own `divider={true}` paints those as a hairline `outlineVariant` rule).
+**Reach for this when** the boundary between two regions is ambiguous because they share the same surface and vertical rhythm — the visitor's eye should *land* on the break, not infer it. **Skip when** the regions already sit on different surfaces (one card, one canvas — the surface change is the break), when one region carries a heading that itself reads as the start of a new block, or when the separation is between *rows of the same list* (List's own `divider={true}` paints those as a hairline `border.default` rule).
 
-**Surface-agnostic by design.** The fill is `sys.color.scrimSubtle` — a ~8% inverse-tone overlay (black in light mode, white in dark) — so the band reads as a tint *darker than the host surface* without pinning to a fixed neutral step. The same band visibly separates regions on `surface`, `surfaceContainerHigh`, a hero panel, or a coloured card without retoning per-host. Same scrim tier as Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton.
+**Surface-agnostic by design.** The fill is `sys.color.border.default` — a ~8% inverse-tone overlay (black in light mode, white in dark) — so the band reads as a tint *darker than the host surface* without pinning to a fixed neutral step. The same band visibly separates regions on `surface`, `surfaceContainerHigh`, a hero panel, or a coloured card without retoning per-host. Same scrim tier as Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton.
 
-**Layout inset.** `full-bleed` — Divider stretches edge-to-edge inside the page-shell content box. It ships **no** inline padding, **no** outer margin, **no** corner radius, **no** stroke; it just paints `scrimSubtle` across a `sys.layout.stack.xs` (8) block. Drop it as a direct child of the page-shell `<main>` (or any full-width host column) between two regions — do not wrap in a `padding-inline` div, `className="px-*"`, or `style={{ padding }}`; the band reading edge-to-edge IS what makes it a region boundary.
+**Layout inset.** `full-bleed` — Divider stretches edge-to-edge inside the page-shell content box. It ships **no** inline padding, **no** outer margin, **no** corner radius, **no** stroke; it just paints `border.default` across a `sys.layout.stack.xs` (8) block. Drop it as a direct child of the page-shell `<main>` (or any full-width host column) between two regions — do not wrap in a `padding-inline` div, `className="px-*"`, or `style={{ padding }}`; the band reading edge-to-edge IS what makes it a region boundary.
 
-**Safe zone — none.** The parent column pays no `gap`, `padding-block`, or `margin-block` around Divider. The 8 of `scrimSubtle` is the breathing. If two regions feel cramped after dropping Divider between them, the fix is to add internal padding to the regions themselves (`layout.container.*`), never to wrap Divider in a spacer or paint outer margin on it.
+**Safe zone — none.** The parent column pays no `gap`, `padding-block`, or `margin-block` around Divider. The 8 of `border.default` is the breathing. If two regions feel cramped after dropping Divider between them, the fix is to add internal padding to the regions themselves (`layout.container.*`), never to wrap Divider in a spacer or paint outer margin on it.
 
 ## Default
 
-The single canonical band. 8 high, full inline width, `scrimSubtle` fill.
+The single canonical band. 8 high, full inline width, `border.default` fill.
 
 ```preview
 divider/default
@@ -24,9 +24,7 @@ import { Divider } from '@teamblind-chorus/ui';
 <Divider />
 ```
 
-## Use cases
-
-### Between adjacent lists
+## Between adjacent lists
 
 The canonical placement — a region break between two full-bleed lists stacked on the same page. Above: a directory of new channels (DirectoryList, an inert directory). Below: a recommendation set keyed to the visitor (SuggestionList, the pager-flavoured sibling). Both lists own their internal divider hairlines for rows, but the *boundary between the two lists* is a region break — that is the role Divider plays.
 
@@ -56,13 +54,13 @@ import { Divider, DirectoryList, SuggestionList } from '@teamblind-chorus/ui';
 
 ## Slots
 
-- **container** — the tonal band. `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no padding, no border, no corner radius. The native `<hr>` element with all browser defaults reset. `aria-hidden="true"` by default — the band is decorative.
+- **container** — the tonal band. `sys.color.border.default` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no padding, no border, no corner radius. The native `<hr>` element with all browser defaults reset. `aria-hidden="true"` by default — the band is decorative.
 
 ## Anatomy
 
 | Slot       | Token bindings |
 |------------|----------------|
-| container  | `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block height, 100% inline width, `border: none`, `margin: 0`, `border-radius: 0` |
+| container  | `sys.color.border.default` fill, `sys.layout.stack.xs` (8) block height, 100% inline width, `border: none`, `margin: 0`, `border-radius: 0` |
 
 ## Appearance
 
@@ -70,11 +68,11 @@ Single appearance — Divider has no emphasis axis, no orientation axis, and no
 
 | Appearance | Fill                       | When to use                                                                 |
 |------------|----------------------------|-----------------------------------------------------------------------------|
-| `default`  | `sys.color.scrimSubtle`    | The only mode. Same scrim used by Banner default / Chip-Tag default / Progress track / StatusTag neutral / Skeleton — Divider is the section-level member of that family. |
+| `default`  | `sys.color.border.default`    | The only mode. Same scrim used by Banner default / Chip-Tag default / Progress track / StatusTag neutral / Skeleton — Divider is the section-level member of that family. |
 
 ## Behavior
 
 - **aria-hidden by default.** The band is decorative chrome; screen-reader users navigate by headings and landmarks, not visual breaks. Override `aria-hidden={false}` only when the divider genuinely marks a semantic section change (rare — prefer a heading).
-- **Fixed thickness.** Block thickness is `sys.layout.stack.xs` (8) and is not a prop. Heavier bands compete with content; thinner bands collapse to a hairline (use the host's own `outlineVariant` border for row-level breaks, not Divider).
+- **Fixed thickness.** Block thickness is `sys.layout.stack.xs` (8) and is not a prop. Heavier bands compete with content; thinner bands collapse to a hairline (use the host's own `border.default` border for row-level breaks, not Divider).
 - **Full-bleed by contract.** The band must touch the page edge to read as a region boundary. Wrapping Divider in a padding-inline container breaks the affordance — see the AGENTS.md "one gutter, paid once" rule.
-- **Not a row separator.** Inside a List, rows already separate via the list's own `divider={true}` hairline `outlineVariant` rule. Reach for Divider only at the *region* level, between groups that don't share an enclosing container.
+- **Not a row separator.** Inside a List, rows already separate via the list's own `divider={true}` hairline `border.default` rule. Reach for Divider only at the *region* level, between groups that don't share an enclosing container.