@teamblind-chorus/ui 1.1.0 → 2.0.0

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

@@ -39,7 +39,7 @@
     "helper": {
       "type": "node",
       "optional": true,
-      "description": "Assistive text rendered below the field box, left-aligned. **Optional on every appearance** — omit the prop to render the field without an assistive rung; the box and label keep their footprint. On the `error` appearance the helper re-tones to `sys.color.error` so the message reads as the error caption; an error field may still be shown without a helper, in which case only the field box re-tones. Mutually exclusive with `maxLength` — if both are given, the character count is shown and `helper` is ignored."
+      "description": "Assistive text rendered below the field box, left-aligned. **Optional on every appearance** — omit the prop to render the field without an assistive rung; the box and label keep their footprint. On the `error` appearance the helper re-tones to `sys.color.text.danger` so the message reads as the error caption; an error field may still be shown without a helper, in which case only the field box re-tones. Mutually exclusive with `maxLength` — if both are given, the character count is shown and `helper` is ignored."
     },
     "maxLength": {
       "type": "number",
@@ -59,7 +59,7 @@
     },
     "label": {
       "required": false,
-      "description": "Visible label above the box. `sys.typo.label.md`, `sys.color.onSurface`. Associated with the input via `htmlFor`.",
+      "description": "Visible label above the box. `sys.typo.label.md`, `sys.color.text.default`. Associated with the input via `htmlFor`.",
       "accepts": [
         "text"
       ]
@@ -83,14 +83,14 @@
     },
     "helper": {
       "required": false,
-      "description": "Assistive text below the box, left-aligned. `sys.typo.body.sm`, `sys.color.onSurfaceVariant`; on the `error` appearance the colour re-tones to `sys.color.error` so the message reads as the error caption. Referenced by the input's `aria-describedby`. Not rendered when a `maxLength` count is present, and intentionally omittable on every appearance (including `error`) — pass nothing and the field renders without an assistive rung.",
+      "description": "Assistive text below the box, left-aligned. `sys.typo.body.sm`, `sys.color.text.subtle`; on the `error` appearance the colour re-tones to `sys.color.text.danger` so the message reads as the error caption. Referenced by the input's `aria-describedby`. Not rendered when a `maxLength` count is present, and intentionally omittable on every appearance (including `error`) — pass nothing and the field renders without an assistive rung.",
       "accepts": [
         "text"
       ]
     },
     "count": {
       "required": false,
-      "description": "`current/max` character count below the box, right-aligned, present when `maxLength` is set. `sys.typo.body.sm`, `sys.color.onSurfaceVariant`; the current-count number is `sys.typo.label.md` weight in `sys.color.onSurface`. Referenced by the input's `aria-describedby`; updates `aria-live=\"polite\"`.",
+      "description": "`current/max` character count below the box, right-aligned, present when `maxLength` is set. `sys.typo.body.sm`, `sys.color.text.subtle`; the current-count number is `sys.typo.label.md` weight in `sys.color.text.default`. Referenced by the input's `aria-describedby`; updates `aria-live=\"polite\"`.",
       "accepts": [
         "text"
       ]
@@ -103,7 +103,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",
@@ -113,28 +113,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": {
@@ -155,35 +155,43 @@
       "nestedActionScope": "The pressed overlay (and hover stroke) is suppressed while the pointer presses / hovers the trailing clear button — that '×' is an independent nested action, so the small control owns the state and the large field does not also read as pressed. The visual-state boundary matches the action boundary."
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
       "strokeWeight": "activeStrokeWeight",
       "caret": "visible",
       "showsClearWhenValue": true,
-      "note": "The stroke steps from its rest `hairline` (1px) to `activeStrokeWeight` (2px) and re-tones to `borderActive` — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
+      "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.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. The stroke stays at `hairline` (1px) and re-tones to `borderActive` on active (no thickening) — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
     },
     "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",
       "suppressClear": true,
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border + disabled text/placeholder."
     }
   },
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the field is in (most commonly `active` since focus implies the caret is in the box). 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)"
   },
@@ -196,7 +204,7 @@
   },
   "forbidden": [
     "raw <input> styled with Tailwind / inline color — the input is wrapped in the chorus-field chrome that owns the stroke",
-    "active-state stroke painted with sys.color.primary / a container tier — the active stroke is sys.color.onSurface (default appearance) or sys.color.error (error appearance), never primary or a container tier",
+    "active-state stroke painted with sys.color.background.primary / a container tier — the active stroke is sys.color.text.default (default appearance) or sys.color.text.danger (error appearance), never primary or a container tier",
     "stroke painted via `border:` — stroke is an inset box-shadow on the field",
     "helper text rendered outside the helperText slot"
   ]

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

@@ -10,7 +10,7 @@ Search-shaped single-line field — sibling of [Input](./input.md) with a leadin
 
 ## Default
 
-Neutral at-rest search bar — transparent fill, hairline `outlineVariant` stroke, `SearchIcon` left, placeholder in faint `outline` colour. Type into the specimen: placeholder → full-strength `onSurface` text, stroke steps to `active`, trailing clear ("×") appears at the right edge.
+Neutral at-rest search bar — transparent fill, hairline `border.default` stroke, `SearchIcon` left, placeholder in faint `outline` colour. Type into the specimen: placeholder → full-strength `onSurface` text, stroke steps to `active`, trailing clear ("×") appears at the right edge.
 
 ```preview
 form-field/search/default
@@ -20,9 +20,7 @@ import { FormField } from '@teamblind-chorus/ui';
 <FormField variant="search" placeholder="Search" />
 ```
 
-## Use cases
-
-### Focus indicator
+## Focused state
 
 Focus ring layered on top of the `active` pill border. Same composition as [Input → Focus indicator](./input.md#focus-indicator).
 

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

@@ -41,7 +41,7 @@
     },
     "leading": {
       "required": true,
-      "description": "The leading `SearchIcon` glyph pinned at the box's inner-left edge. Inherits the field's text colour (`sys.color.onSurface`); decorative — not a real button, has `aria-hidden`. 16px (`sys.icon.md`), matching the clear button's footprint so the two affixes balance.",
+      "description": "The leading `SearchIcon` glyph pinned at the box's inner-left edge. Inherits the field's text colour (`sys.color.text.default`); decorative — not a real button, has `aria-hidden`. 16px (`sys.icon.md`), matching the clear button's footprint so the two affixes balance.",
       "intrinsic": true
     },
     "input": {
@@ -64,18 +64,18 @@
     "slotGap": "sys.layout.inline.md",
     "radius": "sys.radius.full",
     "borderWidth": "sys.borderWidth.hairline",
-    "activeStrokeWeight": "sys.borderWidth.thin",
+    "activeStrokeWeight": "sys.borderWidth.hairline",
     "textTypo": "sys.typo.body.md",
     "iconSize": "sys.icon.md"
   },
   "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"
     }
   },
   "states": {
@@ -96,35 +96,43 @@
       "nestedActionScope": "The pressed overlay (and hover stroke) is suppressed while the pointer presses / hovers the trailing clear button — that '×' is an independent nested action, so the small control owns the state and the large field does not also read as pressed. The visual-state boundary matches the action boundary."
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
       "strokeWeight": "activeStrokeWeight",
       "caret": "visible",
       "showsClearWhenValue": true,
-      "note": "The stroke steps from its rest `hairline` (1px) to `activeStrokeWeight` (2px) and re-tones to `borderActive` — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
+      "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.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. The stroke stays at `hairline` (1px) and re-tones to `borderActive` on active (no thickening) — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
     },
     "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",
       "suppressClear": true,
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border + disabled text/placeholder."
     }
   },
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the field 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/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": {
@@ -150,20 +150,31 @@
       }
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
-      "strokeWeight": "activeStrokeWeight"
+      "strokeWeight": "activeStrokeWeight",
+      "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.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` (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": {
@@ -171,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": {
@@ -137,33 +137,41 @@
       "nestedActionScope": "The pressed overlay (and hover stroke) is suppressed while the pointer presses / hovers the trailing clear button — that '×' is an independent nested action, so the small control owns the state and the large field does not also read as pressed. The visual-state boundary matches the action boundary."
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
       "strokeWeight": "activeStrokeWeight",
       "caret": "visible",
-      "note": "Stroke steps from `hairline` (1px) to `activeStrokeWeight` (2px) as an inset box-shadow — same pixel-stable contract as input."
+      "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.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 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.