@teamblind-chorus/ui 1.2.0 → 2.0.0

package/agents/components/form-field/select.md

@@ -10,7 +10,7 @@ Input-shaped picker — same box, label, helper, and error re-tone as [Input](./
 
 ## Default
 
-Neutral at-rest field — transparent fill, hairline `outlineVariant` stroke, placeholder in faint `outline` colour. The trailing 16px chevron signals that the field opens a sheet rather than a caret.
+Neutral at-rest field — transparent fill, hairline `border.default` stroke, placeholder in faint `outline` colour. The trailing 16px chevron signals that the field opens a sheet rather than a caret.
 
 ```preview
 form-field/select/default
@@ -20,9 +20,7 @@ import { FormField } from '@teamblind-chorus/ui';
 <FormField variant="select" placeholder="Select an option" onOpen={() => {}} />
 ```
 
-## Use cases
-
-### With leading icon
+## Leading icon
 
 Optional `leadingIcon` (16px / `sys.icon.md`) pins inner-left — same affordance as Search bar's glyph. Available on `input` and `select`.
 
@@ -40,22 +38,7 @@ import { GlobeIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Group
-
-Pair a Select with an Input on one row via `<FormFieldGroup direction="horizontal">`. The group owns one shared label above and helper below; children render as bare boxes joined at `sys.layout.inline.md` gap. Typical pattern: leading Select (country dial code, currency, unit) + trailing real Input.
-
-```preview
-form-field/select/group
----
-import { FormField, FormFieldGroup } from '@teamblind-chorus/ui';
-
-<FormFieldGroup direction="horizontal" label="Phone number" helper="We'll text a one-time code">
-  <FormField variant="select" value="+82" onOpen={() => {}} style={{ flex: '0 0 96px' }} />
-  <FormField variant="input" placeholder="010-0000-0000" />
-</FormFieldGroup>
-```
-
-### Focus indicator
+## Focused state
 
 Same as [Input → Focus indicator](./input.md#focus-indicator) — layered on top of the `active` border re-tone.
 
@@ -72,6 +55,21 @@ import { FormField } from '@teamblind-chorus/ui';
 />
 ```
 
+## Group
+
+Pair a Select with an Input on one row via `<FormFieldGroup direction="horizontal">`. The group owns one shared label above and helper below; children render as bare boxes joined at `sys.layout.inline.md` gap. Typical pattern: leading Select (country dial code, currency, unit) + trailing real Input.
+
+```preview
+form-field/select/group
+---
+import { FormField, FormFieldGroup } from '@teamblind-chorus/ui';
+
+<FormFieldGroup direction="horizontal" label="Phone number" helper="We'll text a one-time code">
+  <FormField variant="select" value="+82" onOpen={() => {}} style={{ flex: '0 0 96px' }} />
+  <FormField variant="input" placeholder="010-0000-0000" />
+</FormFieldGroup>
+```
+
 ## Appearance
 
 Same two-appearance axis as [Input → Appearance](./input.md#appearance) — `default` and `error`. The error re-tone covers box, chevron, label and helper rung; placeholder text steps to `onErrorContainer`.

package/agents/components/form-field/select.spec.json

@@ -42,7 +42,7 @@
     "leadingIcon": {
       "type": "node",
       "optional": true,
-      "description": "Optional 16px (`sys.icon.md`) decorative glyph pinned at the inner-left edge of the field. Tracks the field's active text colour (`sys.color.onSurface` on the default appearance, `sys.color.onErrorContainer` on `error`) so the glyph reads as part of the typed content."
+      "description": "Optional 16px (`sys.icon.md`) decorative glyph pinned at the inner-left edge of the field. Tracks the field's active text colour (`sys.color.text.default` on the default appearance, `sys.color.text.danger` on `error`) so the glyph reads as part of the typed content."
     },
     "onOpen": {
       "type": "function",
@@ -99,7 +99,7 @@
     "slotGap": "sys.layout.inline.md",
     "radius": "sys.radius.md",
     "borderWidth": "sys.borderWidth.hairline",
-    "activeStrokeWeight": "sys.borderWidth.thin",
+    "activeStrokeWeight": "sys.borderWidth.hairline",
     "groupGap": "sys.layout.stack.xs",
     "labelTypo": "sys.typo.label.md",
     "helperTypo": "sys.typo.body.sm",
@@ -109,28 +109,28 @@
     "iconSize": "sys.icon.md"
   },
   "groupColors": {
-    "label": "sys.color.onSurface",
-    "helper": "sys.color.onSurfaceVariant",
-    "helperError": "sys.color.error",
-    "count": "sys.color.onSurfaceVariant",
-    "countCurrent": "sys.color.onSurface"
+    "label": "sys.color.text.default",
+    "helper": "sys.color.text.subtle",
+    "helperError": "sys.color.text.danger",
+    "count": "sys.color.text.subtle",
+    "countCurrent": "sys.color.text.default"
   },
   "appearances": {
     "default": {
       "background": "transparent",
-      "text": "sys.color.onSurface",
-      "placeholder": "sys.color.outline",
-      "borderRest": "sys.color.outlineVariant",
-      "borderHover": "sys.color.outline",
-      "borderActive": "sys.color.onSurface"
+      "text": "sys.color.text.default",
+      "placeholder": "sys.color.border.boldest",
+      "borderRest": "sys.color.border.default",
+      "borderHover": "sys.color.border.boldest",
+      "borderActive": "sys.color.border.focused"
     },
     "error": {
-      "background": "sys.color.errorContainer",
-      "text": "sys.color.onErrorContainer",
-      "placeholder": "sys.color.onErrorContainer",
-      "borderRest": "sys.color.error",
-      "borderHover": "sys.color.error",
-      "borderActive": "sys.color.error"
+      "background": "sys.color.background.danger",
+      "text": "sys.color.text.danger",
+      "placeholder": "sys.color.text.danger",
+      "borderRest": "sys.color.border.danger",
+      "borderHover": "sys.color.border.danger",
+      "borderActive": "sys.color.border.danger"
     }
   },
   "states": {
@@ -157,21 +157,24 @@
       "focusRing": {
         "composition": "outward",
         "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
-        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.focusInset" },
-        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.focus" }
+        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.border.focused" },
+        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.border.focused" }
       },
-      "note": "This IS the trigger's keyboard-focus / open state — `:focus-visible` and the engaged (open) state coincide for the select trigger, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. The stroke re-tones to `borderActive` at `activeStrokeWeight` (2px) as an inset box-shadow, pixel-stable (no reflow)."
+      "note": "This IS the trigger's keyboard-focus / open state — `:focus-visible` and the engaged (open) state coincide for the select trigger, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. The stroke re-tones to `borderActive` at `activeStrokeWeight` (1px, = rest) as an inset box-shadow, pixel-stable (no reflow)."
     },
     "disabled": {
       "overlay": null,
-      "background": "sys.color.surfaceContainerLow",
-      "containerOpacity": "sys.state.disabled",
+      "background": "sys.color.background.disabled",
+      "text": "sys.color.text.disabled",
+      "placeholder": "sys.color.text.disabled",
+      "border": "sys.color.border.bold",
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border + disabled text/placeholder."
     }
   },
   "focusIndicator": {
-    "description": "Same keyboard-focus indicator as Input — outward two-layer ring composed over the active stroke.",
+    "description": "Same keyboard-focus indicator as Input — outward single ring composed over the active stroke.",
     "composition": "outward",
     "compositionReason": "Action affordance with breathing room around it.",
     "overlay": {
@@ -179,10 +182,8 @@
       "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"
   },

package/agents/components/form-field/textarea.md

@@ -25,11 +25,9 @@ import { FormField } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
+## Error
 
-### Error appearance
-
-`appearance="error"` re-tones container to `errorContainer` and stroke to `error`. The optional `helper` paints in `sys.color.error` as the error caption.
+`appearance="error"` re-tones container to `errorContainer` and stroke to `error`. The optional `helper` paints in `sys.color.text.danger` as the error caption.
 
 ```preview
 form-field/textarea-error
@@ -45,7 +43,7 @@ import { FormField } from '@teamblind-chorus/ui';
 />
 ```
 
-### With character count
+## Character count
 
 `maxLength` caps value length and renders a `current/max` count below the box (right-aligned). Mutually exclusive with `helper` — count wins.
 

package/agents/components/form-field/textarea.spec.json

@@ -36,7 +36,7 @@
     "helper": {
       "type": "node",
       "optional": true,
-      "description": "Assistive text rendered below the field box, left-aligned. Same rules as [input.helper](./input.md): mutually exclusive with `maxLength`, optional on every appearance, re-tones to `sys.color.error` on the error appearance."
+      "description": "Assistive text rendered below the field box, left-aligned. Same rules as [input.helper](./input.md): mutually exclusive with `maxLength`, optional on every appearance, re-tones to `sys.color.text.danger` on the error appearance."
     },
     "maxLength": {
       "type": "number",
@@ -61,7 +61,7 @@
     },
     "label": {
       "required": false,
-      "description": "Visible label above the box. `sys.typo.label.md`, `sys.color.onSurface`. Associated with the textarea via `htmlFor`.",
+      "description": "Visible label above the box. `sys.typo.label.md`, `sys.color.text.default`. Associated with the textarea via `htmlFor`.",
       "accepts": ["text"]
     },
     "container": {
@@ -92,7 +92,7 @@
     "slotGap": "sys.layout.inline.md",
     "radius": "sys.radius.md",
     "borderWidth": "sys.borderWidth.hairline",
-    "activeStrokeWeight": "sys.borderWidth.thin",
+    "activeStrokeWeight": "sys.borderWidth.hairline",
     "groupGap": "sys.layout.stack.xs",
     "labelTypo": "sys.typo.label.md",
     "helperTypo": "sys.typo.body.sm",
@@ -104,28 +104,28 @@
     "resize": "vertical"
   },
   "groupColors": {
-    "label": "sys.color.onSurface",
-    "helper": "sys.color.onSurfaceVariant",
-    "helperError": "sys.color.error",
-    "count": "sys.color.onSurfaceVariant",
-    "countCurrent": "sys.color.onSurface"
+    "label": "sys.color.text.default",
+    "helper": "sys.color.text.subtle",
+    "helperError": "sys.color.text.danger",
+    "count": "sys.color.text.subtle",
+    "countCurrent": "sys.color.text.default"
   },
   "appearances": {
     "default": {
       "background": "transparent",
-      "text": "sys.color.onSurface",
-      "placeholder": "sys.color.outline",
-      "borderRest": "sys.color.outlineVariant",
-      "borderHover": "sys.color.outline",
-      "borderActive": "sys.color.onSurface"
+      "text": "sys.color.text.default",
+      "placeholder": "sys.color.border.boldest",
+      "borderRest": "sys.color.border.default",
+      "borderHover": "sys.color.border.boldest",
+      "borderActive": "sys.color.border.focused"
     },
     "error": {
-      "background": "sys.color.errorContainer",
-      "text": "sys.color.onErrorContainer",
-      "placeholder": "sys.color.onErrorContainer",
-      "borderRest": "sys.color.error",
-      "borderHover": "sys.color.error",
-      "borderActive": "sys.color.error"
+      "background": "sys.color.background.danger",
+      "text": "sys.color.text.danger",
+      "placeholder": "sys.color.text.danger",
+      "borderRest": "sys.color.border.danger",
+      "borderHover": "sys.color.border.danger",
+      "borderActive": "sys.color.border.danger"
     }
   },
   "states": {
@@ -145,32 +145,33 @@
       "focusRing": {
         "composition": "outward",
         "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
-        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.focusInset" },
-        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.focus" }
+        "innerCounterRing": { "width": "sys.borderWidth.hairline", "color": "sys.color.border.focused" },
+        "outerRing": { "width": "sys.borderWidth.thin", "color": "sys.color.border.focused" }
       },
-      "note": "This IS the field's keyboard/input-focus state — `active` (caret visible, input engaged) and `:focus-visible` coincide for a text field, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. Stroke steps from `hairline` (1px) to `activeStrokeWeight` (2px) as an inset box-shadow — same pixel-stable contract as input."
+      "note": "This IS the field's keyboard/input-focus state — `active` (caret visible, input engaged) and `:focus-visible` coincide for a text field, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. Stroke stays at `hairline` (1px), re-toning to `borderActive` as an inset box-shadow (no thickening) — same pixel-stable contract as input."
     },
     "disabled": {
       "overlay": null,
-      "background": "sys.color.surfaceContainerLow",
-      "containerOpacity": "sys.state.disabled",
+      "background": "sys.color.background.disabled",
+      "text": "sys.color.text.disabled",
+      "placeholder": "sys.color.text.disabled",
+      "border": "sys.color.border.bold",
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border + disabled text/placeholder."
     }
   },
   "focusIndicator": {
-    "description": "Same outward 3-layer ring as input.focusIndicator.",
+    "description": "Same outward single ring as input.focusIndicator.",
     "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/header/main.md

@@ -23,9 +23,7 @@ import { Header } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With drill-in chevron
+## Drill-in chevron
 
 `trailingIcon` mode — the chevron is a [Button `variant="icon"`](../button/icon.md) at `size="medium"` (32 × 32 capsule, 16-glyph) that owns its own tap target. The chevron paints in `onSurfaceVariant` and rotates -90° to read as chevron-right. The surrounding `<header>` element stays non-interactive — clicks land on the Icon Button, not on the row chrome. Use when the trailing affordance is "open this surface", not "commit a labelled action". `headerAction` and `trailingIcon` are mutually exclusive.
 
@@ -42,7 +40,7 @@ import { Header } from '@teamblind-chorus/ui';
 />
 ```
 
-### With dropdown
+## Dropdown
 
 `headerDropdown` mode — the trailing affordance is a [Text Button dropdown](../button/text.md#dropdown) (`size="xsmall"`, default appearance) whose **label is the current value** ("Top", "Newest", "All time") and whose trailing chevron flips with `open` as a state signal. Use when the heading row needs an inline sort / filter / range disclosure — "Recommended channels [Top ▾]", "Posts [Last 7 days ▾]". Consumer owns the menu surface (Menu, popover, ListBox) and the `open` state; Header only renders the trigger.
 
@@ -69,7 +67,7 @@ function Example() {
 }
 ```
 
-### Label only
+## Label only
 
 Set only `label` (omit `headerAction`, `trailingIcon`, and `headerDropdown`) for a labelled region that needs a heading without a trailing affordance. The row collapses to a single heading at the requested size — no spacer, no empty container.
 
@@ -84,7 +82,7 @@ import { Header } from '@teamblind-chorus/ui';
 ## Slots
 
 - **container** — outer row. Flex with `space-between`; label leads, action / icon / dropdown trails, 8px (`layout.inline.md`) gap. Full-bleed — transparent background and its own padding: `container.md` (16) inline (the shared content rail), `stack.lg` (24) block-start, `stack.md` (16) block-end — so the label lands on the same rail as the rows beneath it; bundling hosts add no inline padding of their own and absorb only the block padding. Stays a non-interactive `<header>` / `<div>` — the trailing affordance owns its own hit target.
-- **label** *(optional)* — heading text. `<h3>` by default; override the wrapper with `as="div"` when the surrounding host already owns the heading semantics. Color `sys.color.onSurface`. Typo per size.
+- **label** *(optional)* — heading text. `<h3>` by default; override the wrapper with `as="div"` when the surrounding host already owns the heading semantics. Color `sys.color.text.default`. Typo per size.
 - **action** *(optional, headerAction mode)* — trailing Text Button. Fixed at `size="xsmall"`, `appearance="accent"`.
 - **icon** *(optional, trailingIcon mode)* — trailing [Icon Button](../button/icon.md) (`variant="icon"` `size="medium"`) hosting a 16px glyph (canonical: chevron-right). Its own tap target — clicks land on the Icon Button, not the surrounding header. Supply `aria-label` for the icon-only button (defaults to `"Open <label>"` when `label` is a string).
 - **dropdown** *(optional, headerDropdown mode)* — trailing [Text Button dropdown](../button/text.md#dropdown) (`size="xsmall"`, default appearance). Label is the current value; trailing chevron flips between `ChevronDownIcon` (closed) and `ChevronUpIcon` (open) tied to `headerDropdown.open`. Owns its own tap target — clicks land on the dropdown trigger, not the surrounding header.

package/agents/components/header/main.spec.json

@@ -56,7 +56,7 @@
     },
     "label": {
       "required": false,
-      "description": "Heading text. `<h3>` by default. Size `large` → `sys.typo.heading.md`; size `medium` → `sys.typo.heading.sm`. Color `sys.color.onSurface`."
+      "description": "Heading text. `<h3>` by default. Size `large` → `sys.typo.heading.md`; size `medium` → `sys.typo.heading.sm`. Color `sys.color.text.default`."
     },
     "action": {
       "required": false,
@@ -85,10 +85,10 @@
     "medium": {
       "labelTypo": "sys.typo.heading.sm (16 / Semibold)"
     },
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "actionSize": "Text Button xsmall, appearance accent",
     "iconButtonSize": "Button variant=\"icon\" size=\"medium\" (32 × 32 capsule, 16-glyph)",
-    "iconColor": "sys.color.onSurfaceVariant (glyph inherits via `currentColor` from the Icon Button)"
+    "iconColor": "sys.color.text.subtle (glyph inherits via `currentColor` from the Icon Button)"
   },
   "appearance": {
     "background": "transparent",

package/agents/components/header/sub.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/header/sub.md`](../../../i18n/ko/schema/components/header/sub.md)
 
-Quiet section-dividing label — a 14px (`sys.typo.label.md`, 14 / Semibold) line in the muted `sys.color.onSurfaceVariant` tone that names the group of rows beneath it ("Following", "More Topics to follow"). The muted tone is the dividing device: it reads as a region label rather than a heading that competes with the page title, while the label-weight typo keeps it from dissolving into body copy. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label.
+Quiet section-dividing label — a 14px (`sys.typo.label.md`, 14 / Semibold) line in the muted `sys.color.text.subtle` tone that names the group of rows beneath it ("Following", "More Topics to follow"). The muted tone is the dividing device: it reads as a region label rather than a heading that competes with the page title, while the label-weight typo keeps it from dissolving into body copy. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label.
 
 It may carry one quiet trailing affordance — a single [Text Button](../button/text.md) `action` ("See all", "Edit", "Manage") — for a region-level commit that stays subordinate to the muted label. Icon drill-in and dropdown disclosure are *not* SubHeader's: those belong on [Main](./main.md), whose louder `onSurface` heading earns the heavier affordance set.
 
@@ -22,9 +22,7 @@ import { SubHeader } from '@teamblind-chorus/ui';
 <SubHeader label="Following" />
 ```
 
-## Use cases
-
-### Grouping a list
+## Grouping a list
 
 The canonical placement — a SubHeader labels each group of rows, splitting one stacked list into named sections. The muted label sits at the same `16px` inset as the rows; the block rhythm (more above, less below) reads as "new group starts here".
 
@@ -69,7 +67,7 @@ function Example() {
 }
 ```
 
-### With a trailing action
+## Trailing action
 
 Pass `action={{ label, href, onClick }}` for a single quiet commit on the trailing edge — "See all" above a previewed group, "Edit" above an editable cluster. The wrapper becomes a full-bleed flex row: the muted label holds the leading edge, the [Text Button](../button/text.md) (`size="xsmall"`, `appearance="accent"`) hugs the trailing edge at the same 16 inset. The action stays subordinate to the label — this is still a quiet region marker, not a [Main](./main.md) heading row. Use Main instead when the region needs the louder `onSurface` heading, an icon drill-in, or a sort dropdown.
 
@@ -91,7 +89,7 @@ import { SubHeader, List } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### Host owns the heading
+## Host owns the heading
 
 When the surrounding host already carries the section semantics, override the wrapping element with `as="div"` so the document outline doesn't gain a stray heading — the label keeps its muted tone and inset.
 
@@ -106,7 +104,7 @@ import { SubHeader } from '@teamblind-chorus/ui';
 ## Slots
 
 - **container** — the full-bleed label line. `16px` (`layout.container.md`) inline inset to align with the rows beneath, `24px` (`layout.stack.lg`) block padding above and `8px` (`layout.stack.xs`) below. Non-interactive. Without `action` the container *is* the heading element (`as`); with `action` it is a non-semantic flex `<div>` (`space-between`, `8px` `layout.inline.md` gap) holding the nested label and the trailing action on opposite edges.
-- **label** — required. Section label text. `<h3>` by default (override via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.onSurfaceVariant`. Single line.
+- **label** — required. Section label text. `<h3>` by default (override via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.text.subtle`. Single line.
 - **action** — optional. Trailing [Text Button](../button/text.md) (`size="xsmall"`, `appearance="accent"`) from `action={{ label, href, onClick }}`. The one trailing affordance SubHeader carries; owns its own tap target. Present only when `action` is set.
 
 ## Anatomy
@@ -114,7 +112,7 @@ import { SubHeader } from '@teamblind-chorus/ui';
 | Slot      | Token bindings |
 |-----------|----------------|
 | container | `sys.layout.container.md` (16) inline padding, `sys.layout.stack.lg` (24) block-start, `sys.layout.stack.xs` (8) block-end, full inline width, no border, no radius; in `action` mode flex `space-between` with `sys.layout.inline.md` (8) gap |
-| label     | `sys.typo.label.md` (14 / Semibold) typo, `sys.color.onSurfaceVariant` color |
+| label     | `sys.typo.label.md` (14 / Semibold) typo, `sys.color.text.subtle` color |
 | action    | [Text Button](../button/text.md) `size="xsmall"`, `appearance="accent"`; intrinsic width, never grows |
 
 ## Appearance

package/agents/components/header/sub.spec.json

@@ -3,7 +3,7 @@
   "name": "SubHeader",
   "family": "header",
   "subcomponent": "sub",
-  "description": "The quiet member of the Header family — a section-dividing label. A single line of 14px (`sys.typo.label.md`, 14 / Semibold) text in the muted `sys.color.onSurfaceVariant` tone that names the group of rows beneath it (\"Following\", \"More Topics to follow\"). No size axis — the muted tone is the dividing device, and the label-weight typo keeps it reading as a section label rather than body copy. Reached as `<SubHeader>`; its louder sibling is [Main](./main.md) (`<Header>`), an `onSurface` heading at 16 / 20. Optionally carries a single trailing `action` Text Button (`size=\"xsmall\"`, `appearance=\"accent\"`) for a quiet region-level commit (\"See all\", \"Edit\", \"Manage\"); icon drill-in and dropdown disclosure stay Main's territory, where the louder `onSurface` heading tone belongs. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label; consumers may override the wrapping element via the `as` prop (e.g. `as=\"div\"` when the host already owns the heading semantics). Full-bleed: pays the same 16 (`sys.layout.container.md`) inline inset as the List rows it labels, with asymmetric block padding (24 above to break from the previous region, 8 below to bind the label to its group).",
+  "description": "The quiet member of the Header family — a section-dividing label. A single line of 14px (`sys.typo.label.md`, 14 / Semibold) text in the muted `sys.color.text.subtle` tone that names the group of rows beneath it (\"Following\", \"More Topics to follow\"). No size axis — the muted tone is the dividing device, and the label-weight typo keeps it reading as a section label rather than body copy. Reached as `<SubHeader>`; its louder sibling is [Main](./main.md) (`<Header>`), an `onSurface` heading at 16 / 20. Optionally carries a single trailing `action` Text Button (`size=\"xsmall\"`, `appearance=\"accent\"`) for a quiet region-level commit (\"See all\", \"Edit\", \"Manage\"); icon drill-in and dropdown disclosure stay Main's territory, where the louder `onSurface` heading tone belongs. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label; consumers may override the wrapping element via the `as` prop (e.g. `as=\"div\"` when the host already owns the heading semantics). Full-bleed: pays the same 16 (`sys.layout.container.md`) inline inset as the List rows it labels, with asymmetric block padding (24 above to break from the previous region, 8 below to bind the label to its group).",
   "element": "h3",
   "props": {
     "label": {
@@ -40,7 +40,7 @@
     },
     "label": {
       "required": false,
-      "description": "Section label text. `<h3>` by default (overridable via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.onSurfaceVariant`. Single line.",
+      "description": "Section label text. `<h3>` by default (overridable via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.text.subtle`. Single line.",
       "accepts": ["text"]
     },
     "action": {
@@ -53,7 +53,7 @@
   "appearance": {
     "containerFill": "transparent",
     "labelTypo": "sys.typo.label.md",
-    "labelColor": "sys.color.onSurfaceVariant",
+    "labelColor": "sys.color.text.subtle",
     "paddingInline": "sys.layout.container.md",
     "paddingBlockStart": "sys.layout.stack.lg",
     "paddingBlockEnd": "sys.layout.stack.xs",

package/agents/components/list/accordion.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/list/accordion.md`](../../../i18n/ko/schema/components/list/accordion.md)
 
-Expandable-row List sub. Each item exposes a List-row trigger (label + auto-rendered trailing chevron that rotates `180°` on expand) and a body that paints below it when open. Rows tile flush with the family hairline `outlineVariant` divider between them; an extra rule paints between the open trigger and its child row group.
+Expandable-row List sub. Each item exposes a List-row trigger (label + auto-rendered trailing chevron that rotates `180°` on expand) and a body that paints below it when open. Rows tile flush with the family hairline `border.default` divider between them; an extra rule paints between the open trigger and its child row group.
 
 **Reach for this when** a list of titled sections is too long to keep open at once — FAQs, T&C sections, expandable filter groups, settings groups with infrequent edits, hierarchical menus (companies → channels, regions → cities). **Skip when** bodies are short enough to read inline (use [Carousel](../carousel/carousel.md) per group), the user needs to act on labels (use a [List/standard](./standard.md) drill-in row or [List/radio](./radio.md)), or every item should be visible at once (stack [Carousel](../carousel/carousel.md)s).
 
@@ -12,7 +12,7 @@ Row geometry, label typography, divider, state overlays, and inward focus ring a
 
 ## Default
 
-Single-mode form. One item open at a time; clicking an open item collapses it (`collapsible={true}` by default).
+A single expandable row — the atomic Accordion item. Click the trigger to expand its body; click again to collapse (`collapsible` by default). The Group / Multiple sections below stack several. `type="single"` keeps one item open at a time.
 
 ```preview
 accordion/default
@@ -23,42 +23,12 @@ import { Accordion } from '@teamblind-chorus/ui';
   <Accordion.Item value="why" label="Why does Blind anonymise posts?">
     Anonymity is the only way employees can compare salaries, escalate misconduct, or ask candid culture questions without retaliation. Verified company badges keep the channel trustworthy without unmasking the author.
   </Accordion.Item>
-  <Accordion.Item value="verify" label="How is my company verified?">
-    Sign up with your corporate email — the verification code lands in your inbox, never on a public profile. Once verified, the badge persists across job changes (we re-verify when you update your employer).
-  </Accordion.Item>
-  <Accordion.Item value="data" label="What can other users see?">
-    Other users see your company badge, your career stage, and the content you post. Your email, name, and exact title are never exposed.
-  </Accordion.Item>
-</Accordion>
-```
-
-## Use cases
-
-### Multiple
-
-`type="multiple"` lets the user open any number of items at once. Use when rows are independent and the user reads across several — comparing T&C clauses, expanding filter groups, reviewing policy sections.
-
-```preview
-accordion/multiple
----
-import { Accordion } from '@teamblind-chorus/ui';
-
-<Accordion type="multiple" defaultValue={['salary', 'tenure']} aria-label="Active filters">
-  <Accordion.Item value="salary" label="Compensation">
-    Filter posts by salary range, equity, sign-on bonus.
-  </Accordion.Item>
-  <Accordion.Item value="tenure" label="Tenure">
-    Filter authors by years at current company.
-  </Accordion.Item>
-  <Accordion.Item value="role" label="Role">
-    Filter by IC level, manager track, or specialty.
-  </Accordion.Item>
 </Accordion>
 ```
 
-### Nested list
+## Nested list
 
-When the body holds a same-kind row group rather than prose — directory sub-entries, settings sub-options, filter children, menu sub-items — drop a `<List>` into the content slot with `embedded={true}` so the list defers its own chrome to the host. The body recognises the embedded child via `:has([data-embedded='true'])` and switches to compact-host geometry: body inline padding flips from prose's `32 leading / 16 trailing` to `16 / 0` (sub-list stretches flush right), a hairline `outlineVariant` top group-divider paints via the body's `::before`, and sub-list rows compress to `body.sm` at `40px` min-height with inter-row dividers suppressed. Call sites pass no extra mode prop — dropping `<List embedded>` (or a nested `<Accordion embedded>`) activates it automatically.
+When the body holds a same-kind row group rather than prose — directory sub-entries, settings sub-options, filter children, menu sub-items — drop a `<List>` into the content slot with `embedded={true}` so the list defers its own chrome to the host. The body recognises the embedded child via `:has([data-embedded='true'])` and switches to compact-host geometry: body inline padding flips from prose's `32 leading / 16 trailing` to `16 / 0` (sub-list stretches flush right), a hairline `border.default` top group-divider paints via the body's `::before`, and sub-list rows compress to `body.sm` at `40px` min-height with inter-row dividers suppressed. Call sites pass no extra mode prop — dropping `<List embedded>` (or a nested `<Accordion embedded>`) activates it automatically.
 
 ```preview
 accordion/nested-list
@@ -107,7 +77,7 @@ import { Accordion, List } from '@teamblind-chorus/ui';
 </Accordion>
 ```
 
-### Disabled item
+## Disabled item
 
 A `disabled` row fades to `sys.state.disabled` opacity and ignores click / keyboard activation. Stays in the DOM so surrounding items keep their stable index.
 
@@ -123,8 +93,27 @@ import { Accordion } from '@teamblind-chorus/ui';
   <Accordion.Item value="billing" label="Billing" disabled>
     Available for verified enterprise accounts only.
   </Accordion.Item>
-  <Accordion.Item value="notifications" label="Notifications">
-    Email, push, and in-app notification preferences.
+</Accordion>
+```
+
+## Group
+
+`type="multiple"` lets the user open any number of items at once. Use when rows are independent and the user reads across several — comparing T&C clauses, expanding filter groups, reviewing policy sections.
+
+```preview
+accordion/multiple
+---
+import { Accordion } from '@teamblind-chorus/ui';
+
+<Accordion type="multiple" defaultValue={['salary', 'tenure']} aria-label="Active filters">
+  <Accordion.Item value="salary" label="Compensation">
+    Filter posts by salary range, equity, sign-on bonus.
+  </Accordion.Item>
+  <Accordion.Item value="tenure" label="Tenure">
+    Filter authors by years at current company.
+  </Accordion.Item>
+  <Accordion.Item value="role" label="Role">
+    Filter by IC level, manager track, or specialty.
   </Accordion.Item>
 </Accordion>
 ```
@@ -132,25 +121,25 @@ import { Accordion } from '@teamblind-chorus/ui';
 ## Slots
 
 - **container** — outer stack. Transparent fill so the host surface tone reads through. `role="region"` carries the accordion's accessible name (`aria-label`).
-- **item** — single expandable row. Hairline `outlineVariant` divider inset 16px on both inline edges, painted as an `::after` overlay on every row except the last.
+- **item** — single expandable row. Hairline `border.default` divider inset 16px on both inline edges, painted as an `::after` overlay on every row except the last.
 - **trigger** — header button. Holds the label and the auto-rendered trailing chevron. Same geometry as a List row (48px min-height, 8 × 16 padding). `aria-expanded` reflects open-state, `aria-controls` references the content region.
 - **label** — trigger label. `16 / Regular / onSurface` — matches the List family `label` spec so the trigger reads as a List row that happens to expand. Wraps to a second line; no truncation.
 - **chevron** — auto-rendered 16px `ChevronDownIcon`. Rotates `0°` → `180°` over 120ms `ease-out` on expand. Decorative.
-- **content** — body region. Paints below the trigger when open; toggled via the `hidden` attribute when closed. `min-height: 40px` keeps short single-line bodies on a touch-target rhythm. Two padding modes by content kind: *prose body* (text, icon, button, form-field) uses `32 leading / 16 trailing` inline padding so prose reads as nested inside the trigger's label column, body text at `body.sm` (one rung below the trigger label), no top group-divider. *Embedded row group* (`<List embedded>` or nested `<Accordion embedded>`, detected via `:has([data-embedded='true'])`) uses `16 / 0` inline padding with a hairline `outlineVariant` top divider via `::before`; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
+- **content** — body region. Paints below the trigger when open; toggled via the `hidden` attribute when closed. `min-height: 40px` keeps short single-line bodies on a touch-target rhythm. Two padding modes by content kind: *prose body* (text, icon, button, form-field) uses `32 leading / 16 trailing` inline padding so prose reads as nested inside the trigger's label column, body text at `body.sm` (one rung below the trigger label), no top group-divider. *Embedded row group* (`<List embedded>` or nested `<Accordion embedded>`, detected via `:has([data-embedded='true'])`) uses `16 / 0` inline padding with a hairline `border.default` top divider via `::before`; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
 
 ## Anatomy
 
 | Slot          | Token bindings |
 |---------------|----------------|
 | container     | Transparent fill, no padding (full-bleed, edge-to-edge) |
-| item          | Hairline `outlineVariant` divider inset 16px on both inline edges, omitted on the last row — family-wide List divider |
+| item          | Hairline `border.default` divider inset 16px on both inline edges, omitted on the last row — family-wide List divider |
 | trigger       | 48px min-height, 8px block / 16px inline padding, full-row click target |
 | label         | `16 / Regular`, `onSurface` — matches the List `label` spec |
 | chevron       | 16 × 16, `onSurfaceVariant`, rotates 0° → 180° over 120ms `ease-out` |
 | content (prose)          | 8px block padding, `32 leading / 16 trailing` inline padding, `min-height: 40px`, `sys.typo.body.sm` (14 / Regular) at `onSurfaceVariant` |
 | content (embedded group) | 8px block padding, `16 leading / 0 trailing` inline padding; sub-list rows render at `body.sm` (14 / Regular), `min-height: 40px`, with `::after` row dividers suppressed |
-| divider       | `sys.borderWidth.hairline` × `sys.color.outlineVariant`, inset 16px on both inline edges via `::after` overlay |
-| groupDivider  | `sys.borderWidth.hairline` × `sys.color.outlineVariant`, inset 16px on both inline edges via `::before` overlay on the content body, painted ONLY when the body hosts a `<List embedded>` child group |
+| divider       | `sys.borderWidth.hairline` × `sys.color.border.default`, inset 16px on both inline edges via `::after` overlay |
+| groupDivider  | `sys.borderWidth.hairline` × `sys.color.border.default`, inset 16px on both inline edges via `::before` overlay on the content body, painted ONLY when the body hosts a `<List embedded>` child group |
 
 ## Appearance
 
@@ -167,14 +156,14 @@ A single appearance — Accordion paints no fill of its own and offers no emphas
 
 ## Focus indicator
 
-Inward 3-layer ring painted inside the trigger's footprint via a `::before` overlay. Trigger: `:focus-visible`. Items tile flush with only a hairline divider between them, so an outward ring would overlap the divider and the neighbouring row — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+Inward single ring painted inside the trigger's footprint via a `::before` overlay. Trigger: `:focus-visible`. Items tile flush with only a hairline divider between them, so an outward ring would overlap the divider and the neighbouring row — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
 ## Behavior
 
 - **Edge-to-edge composition.** `layoutInset: full-bleed` — direct child of the page shell. Wrapping in another `padding-inline` / `px-*` div double-pays the rail. Use the negative-margin opt-out inside a bounded surface.
-- **Inset divider.** 1px `outlineVariant` rule inset 16px on both inline edges — same as every other List sub.
+- **Inset divider.** 1px `border.default` rule inset 16px on both inline edges — same as every other List sub.
 - **Indented prose.** Expanded body sits one extra 16px in from the trigger's label edge for parent ↔ child hierarchy.
-- **Embedded groups switch the body to compact-host geometry.** When the body hosts a `<List embedded>`, three things change at once: body inline padding flips from `32 / 16` to `16 / 0` (sub-list flush right); a hairline `outlineVariant` rule paints at the body's top edge so parent and child read as a hierarchy; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
+- **Embedded groups switch the body to compact-host geometry.** When the body hosts a `<List embedded>`, three things change at once: body inline padding flips from `32 / 16` to `16 / 0` (sub-list flush right); a hairline `border.default` rule paints at the body's top edge so parent and child read as a hierarchy; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
 - **Whole trigger is the click target.** Chevron is decorative.
 - **Element swap.** Trigger is `<button>`; content region is `<div role="region">` with `hidden` toggled.
 - **Keyboard.** Space / Enter toggle. Arrow up/down moves focus between triggers.