@teamblind-chorus/ui 1.2.0 → 2.0.0

package/agents/components/feed/post.spec.json

@@ -84,7 +84,7 @@
     "offer": {
       "type": "object",
       "optional": true,
-      "description": "{ label, participants } — inline offer-evaluation banner. Same chrome as `poll` (surfaceVariant slab, leading glyph + label + divider + participant count), but the leading icon is `CompensationFillIcon` and the glyph + label paint in `sys.color.success` (resolves to `ref.palette.green.500`). Surfaces a 'compensation / offer evaluation' post — the author publishes their current salary or a competing offer and asks the community for better-option signals. `label` is constrained to the literal `\"Offer\"` (see `tagBanner.labelEnum`); `participants` is the participant count shown after the divider.",
+      "description": "{ label, participants } — inline offer-evaluation banner. Same chrome as `poll` (surfaceVariant slab, leading glyph + label + divider + participant count), but the leading icon is `CompensationFillIcon` and the glyph + label paint in `sys.color.text.success` (resolves to `ref.palette.green.500`). Surfaces a 'compensation / offer evaluation' post — the author publishes their current salary or a competing offer and asks the community for better-option signals. `label` is constrained to the literal `\"Offer\"` (see `tagBanner.labelEnum`); `participants` is the participant count shown after the divider.",
       "fields": {
         "label": {
           "type": "enum",
@@ -137,7 +137,7 @@
     },
     "channel": {
       "required": true,
-      "description": "Channel / author name, rendered by the [Metadata](../metadata/metadata.md) cluster as an `<a>` link to the channel page. 12px / Semibold / onSurface. No underline at rest; hover underlines the link alone; focus paints a hairline `sys.color.focus` outline at `sys.radius.xs`.",
+      "description": "Channel / author name, rendered by the [Metadata](../metadata/metadata.md) cluster as an `<a>` link to the channel page. 12px / Semibold / onSurface. No underline at rest; hover underlines the link alone; focus paints a hairline `sys.color.border.focused` outline at `sys.radius.xs`.",
       "accepts": [
         "text"
       ]
@@ -182,7 +182,7 @@
       "required": false,
       "agentRequired": true,
       "omittedBehavior": "collapse",
-      "fallbackOnMissingSrc": "sys.color.surfaceContainerHigh",
+      "fallbackOnMissingSrc": "sys.color.surface.sunken",
       "description": "80×80 square image at the trailing edge of the title/body block. radius.sm. `omittedBehavior: collapse` is a runtime safety net — when the prop is undefined the slot drops out of the layout (no reserved whitespace). `agentRequired: true` overrides this for scaffold/generation time: agents MUST always pass a `thumbnail` prop, falling back to `src: \"/placeholder.png\"` when no real subject is implied. `fallbackOnMissingSrc` is the dim-tone fill the component paints when `thumbnail` is present but `src` fails to load (network error or empty string). When the post carries 2+ images, overlays a `SquareStackIcon` badge at the top-right corner (16px / white / 4 inset on top + right).",
       "accepts": [
         "thumbnail"
@@ -190,11 +190,11 @@
     },
     "poll": {
       "required": false,
-      "description": "Inline banner naming an attached poll. surfaceVariant fill, 48px min-height. Leading glyph `PollFillIcon` + label, both painted in `sys.color.brand`; label is constrained to the literal `Poll`."
+      "description": "Inline banner naming an attached poll. surfaceVariant fill, 48px min-height. Leading glyph `PollFillIcon` + label, both painted in `sys.color.text.brand`; label is constrained to the literal `Poll`."
     },
     "offer": {
       "required": false,
-      "description": "Inline banner naming an attached offer-evaluation post. Identical chrome to `poll` — surfaceVariant fill, 48px min-height — with the leading glyph swapped to `CompensationFillIcon` and the glyph + label painted in `sys.color.success` (resolves to `ref.palette.green.500`). Label is constrained to the literal `Offer`."
+      "description": "Inline banner naming an attached offer-evaluation post. Identical chrome to `poll` — surfaceVariant fill, 48px min-height — with the leading glyph swapped to `CompensationFillIcon` and the glyph + label painted in `sys.color.text.success` (resolves to `ref.palette.green.500`). Label is constrained to the literal `Offer`."
     },
     "citation": {
       "required": false,
@@ -209,39 +209,39 @@
     },
     "engagement": {
       "required": false,
-      "description": "Footer row of three counters laid out as an `xsmall` Text Button group. Likes + Comments are real Text Buttons (`text` / `xsmall` / `secondary`); Views renders as a non-interactive `<span>` matching the same 16-glyph / 12-label rhythm. Row gap follows the xsmall-rung group rule (`sys.layout.inline.sm` = 4px). Like is a toggle: active state retones the label to `sys.color.brand` (via `--button-text-label` override) and swaps `HeartIcon` → `HeartFillIcon`, with the count incrementing in lockstep. Never wraps."
+      "description": "Footer row of three counters laid out as an `xsmall` Text Button group. Likes + Comments are real Text Buttons (`text` / `xsmall` / `secondary`); Views renders as a non-interactive `<span>` matching the same 16-glyph / 12-label rhythm. Row gap follows the xsmall-rung group rule (`sys.layout.inline.sm` = 4px). Like is a toggle: active state retones the label to `sys.color.text.brand` (via `--button-text-label` override) and swaps `HeartIcon` → `HeartFillIcon`, with the count incrementing in lockstep. Never wraps."
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerPaddingBlock": "sys.layout.container.lg",
     "containerPaddingInline": "sys.layout.container.md",
     "interBlockGap": "sys.layout.stack.md",
     "flagTypo": "sys.typo.label.sm",
-    "flagColor": "sys.color.brand",
+    "flagColor": "sys.color.text.brand",
     "avatarSize": 32,
     "channelTypo": "sys.typo.label.sm",
-    "channelColor": "sys.color.onSurface",
+    "channelColor": "sys.color.text.default",
     "timestampTypo": "sys.typo.label.sm",
-    "timestampColor": "sys.color.outline",
+    "timestampColor": "sys.color.border.boldest",
     "followActionTypo": "sys.typo.label.sm",
-    "followActionColorInactive": "sys.color.primary",
-    "followActionColorActive": "sys.color.onSurfaceVariant",
+    "followActionColorInactive": "sys.color.text.link",
+    "followActionColorActive": "sys.color.text.subtle",
     "channelRowGap": "sys.layout.inline.md",
     "metaTypo": "sys.typo.label.sm",
-    "metaColor": "sys.color.onSurfaceVariant",
+    "metaColor": "sys.color.text.subtle",
     "metaSeparatorGap": "sys.layout.inline.sm",
     "titleBodyGap": "ref.space.100",
     "titleTypo": "sys.typo.heading.sm",
-    "titleColor": "sys.color.onSurface",
+    "titleColor": "sys.color.text.default",
     "containerBottomDividerWidth": "sys.borderWidth.hairline",
-    "containerBottomDividerColor": "sys.color.outlineVariant",
+    "containerBottomDividerColor": "sys.color.border.default",
     "bodyTypo": "sys.typo.body.sm",
-    "bodyColor": "sys.color.onSurfaceVariant",
+    "bodyColor": "sys.color.text.subtle",
     "bodyLineClamp": 2,
     "thumbnailSize": "80 × 80",
     "thumbnailRadius": "sys.radius.sm",
-    "thumbnailFallbackFill": "sys.color.surfaceContainerHigh",
+    "thumbnailFallbackFill": "sys.color.surface.sunken",
     "thumbnailMultipleBadge": {
       "trigger": "thumbnail.stacked === true (2+ images attached to the post)",
       "icon": "SquareStackIcon",
@@ -254,49 +254,49 @@
     },
     "engagementCounterShape": "xsmall Text Button (Likes / Comments) or matching static span (Views)",
     "engagementLabelTypo": "sys.typo.label.sm",
-    "engagementLabelColor": "sys.color.onSurfaceVariant",
+    "engagementLabelColor": "sys.color.text.subtle",
     "engagementIconSize": "sys.icon.md",
     "engagementSlotGap": "sys.layout.inline.sm",
     "engagementRowGap": "sys.layout.inline.lg",
-    "likeActiveColor": "sys.color.brand",
+    "likeActiveColor": "sys.color.text.brand",
     "likeActiveIcon": "HeartFillIcon",
     "likeRestIcon": "HeartIcon",
     "likeLeadingOffset": "Inherited from Text Button's optical-alignment default — no per-call offset; the heart glyph sits at the card's content rail automatically."
   },
   "poll": {
-    "fill": "sys.color.surfaceVariant",
+    "fill": "sys.color.surface.sunken",
     "radius": "sys.radius.md",
     "paddingBlock": "ref.space.150",
     "paddingInline": "ref.space.200",
     "minHeight": "ref.space.600",
     "bodyTypo": "14",
     "glyph": "PollFillIcon",
-    "glyphColor": "sys.color.brand",
-    "labelColor": "sys.color.brand",
+    "glyphColor": "sys.color.text.brand",
+    "labelColor": "sys.color.text.brand",
     "labelLiteral": "Poll",
-    "anatomy": "Leading 'poll-title' sub-container groups glyph (brand tone) + label at 4px gap; 12px flex gap to vertical outlineVariant divider; 12px gap to participant count."
+    "anatomy": "Leading 'poll-title' sub-container groups glyph (brand tone) + label at 4px gap; 12px flex gap to vertical border.default divider; 12px gap to participant count."
   },
   "offer": {
-    "fill": "sys.color.surfaceVariant",
+    "fill": "sys.color.surface.sunken",
     "radius": "sys.radius.md",
     "paddingBlock": "ref.space.150",
     "paddingInline": "ref.space.200",
     "minHeight": "ref.space.600",
     "bodyTypo": "14",
     "glyph": "CompensationFillIcon",
-    "glyphColor": "sys.color.success",
+    "glyphColor": "sys.color.icon.success",
     "glyphColorResolved": "ref.palette.green.500",
-    "labelColor": "sys.color.success",
+    "labelColor": "sys.color.text.success",
     "labelLiteral": "Offer",
     "anatomy": "Identical to `poll` — same surfaceVariant slab, same 48 min-height, same leading sub-container + divider + participant count. Differs only in the glyph (CompensationFillIcon) and the editorial tone (success / green-500 instead of brand)."
   },
   "tagBanner": {
     "shared": "`poll` and `offer` are siblings of the same banner family — same chrome, same anatomy. They differ only on the glyph + editorial tone.",
-    "labelEnum": "The leading-icon label is constrained to exactly two literals across both modules combined: `\"Poll\"` (for the poll banner) and `\"Offer\"` (for the offer-evaluation banner). Consumers (including Lovable) MUST pass one of these two values, or omit `label` to use the default for the chosen banner kind. No other label string is valid.",
+    "labelEnum": "The leading-icon label is constrained to exactly two literals across both modules combined: `\"Poll\"` (for the poll banner) and `\"Offer\"` (for the offer-evaluation banner). Consumers MUST pass one of these two values, or omit `label` to use the default for the chosen banner kind. No other label string is valid.",
     "renderOrder": "When both modules are present on the same post, `poll` renders above `offer`. Either may stand alone."
   },
   "citation": {
-    "textColumnFill": "sys.color.surfaceVariant",
+    "textColumnFill": "sys.color.surface.sunken",
     "outerRadius": "sys.radius.md",
     "heroWidth": "120px",
     "heroBleed": "Flush against the card's leading edge — no container padding, no inter-column gap.",
@@ -311,7 +311,7 @@
   },
   "mention": {
     "typo": "sys.typo.body.sm",
-    "color": "sys.color.primary",
+    "color": "sys.color.text.link",
     "fontStyle": "italic"
   },
   "states": {
@@ -326,25 +326,21 @@
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "outerLayerPosition": "depth 0..2px from the card edge (the outer stroke)",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "insetLayerPosition": "depth 2..3px from the card edge (the counter-ring just inside the outer stroke)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "implementation": "inset box-shadow constrained strictly inside the card's footprint."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },
   "behavior": {
     "slotOmissionCollapses": "Runtime safety net — when these optional blocks (flag, followAction, thumbnail, poll, offer, citation, mention) are absent the layout reflows cleanly with no reserved whitespace. This is a graceful-degradation contract for downstream consumers, NOT a license for agents to omit slots at scaffold time. `thumbnail` in particular is `agentRequired` (see props.thumbnail) — agents must always pass it with `/placeholder.png` when no subject photo is implied.",
-    "containerBottomDivider": "Each Post card carries a hairline bottom divider (`sys.borderWidth.hairline` × `sys.color.outlineVariant`) so consecutive cards in a stream read with a deliberate inter-card seam. The divider is `border-bottom` on the card itself — layout-safe under `box-sizing: border-box`, no shadow tricks needed. Inside a `<FeedGroup>` (the 3-up bundle case), the inner posts keep their dividers and the group's last card carries the same outer-bottom divider as a standalone Post — the rhythm is identical, the wrapper is purely semantic.",
+    "containerBottomDivider": "Each Post card carries a hairline bottom divider (`sys.borderWidth.hairline` × `sys.color.border.default`) so consecutive cards in a stream read with a deliberate inter-card seam. The divider is `border-bottom` on the card itself — layout-safe under `box-sizing: border-box`, no shadow tricks needed. Inside a `<FeedGroup>` (the 3-up bundle case), the inner posts keep their dividers and the group's last card carries the same outer-bottom divider as a standalone Post — the rhythm is identical, the wrapper is purely semantic.",
     "groupCase": "Three (or more) Post cards bundled vertically inside a `<FeedGroup>` semantic wrapper. Used for thread-grouped or topic-bundled feeds where consecutive posts belong together. The group adds no extra surface chrome — each Post keeps its own `surface` fill, `container.lg/md` padding, and bottom divider; the wrapper only contributes a `role=\"region\"` + optional `aria-label` for the bundle's intent. There is no fixed item count contract; 3 is the canonical demo case.",
     "tagBannerLabelConstrained": "The poll and offer banners share one closed enum for their leading label: `\"Poll\"` or `\"Offer\"`. Each module defaults to its own literal when `label` is omitted; passing any other string is a contract violation.",
     "truncationNotWrap": "meta and title truncate; body clamps to two lines. The card never grows to fit a long title.",
     "thumbnailFlexSibling": "Title and body share their inline space with the thumbnail when both are present; thumbnail is a flex sibling, not floated, so the body's two-line clamp computes against the reduced inline width.",
     "engagementNoReflow": "Footer row stays single-line; tiny screens scroll the row rather than wrapping.",
-    "likeToggle": "Tapping Likes increments the count and swaps the rest-state HeartIcon / secondary appearance for the active-state HeartFillIcon with the label re-toned to `sys.color.brand` (via a `--button-text-label` override — not the Text Button `primary` appearance — because Feed's active-like colour is the editorial brand tone, not the interactive primary). Glyph re-colours via `currentColor`. Tapping again decrements and reverts. Controlled via `liked` + `onLikeChange`, or left uncontrolled for in-demo behaviour.",
+    "likeToggle": "Tapping Likes increments the count and swaps the rest-state HeartIcon / secondary appearance for the active-state HeartFillIcon with the label re-toned to `sys.color.text.brand` (via a `--button-text-label` override — not the Text Button `primary` appearance — because Feed's active-like colour is the editorial brand tone, not the interactive primary). Glyph re-colours via `currentColor`. Tapping again decrements and reverts. Controlled via `liked` + `onLikeChange`, or left uncontrolled for in-demo behaviour.",
     "likeLeadingNudge": "The Like glyph aligns flush with the card's content rail via Text Button's optical-alignment default — the chrome bleeds outward by its own padding on every side, so the visible heart sits at the rail without any per-call offset. The 4px row gap to Comments stays unaffected.",
     "viewsNonInteractive": "Views renders as a non-interactive `<span>` matching the xsmall Text Button visual rhythm — no hover / pressed / focus, no `cursor: pointer`. It is a metric display, not an action that has been turned off, so `aria-disabled` is the wrong shape.",
     "channelAndMetaAreLinks": "Channel name and every `meta` item are independent links. The middot separator between meta items is decorative (`aria-hidden`) and sits outside each link's hit area, so the hover underline never spans the separator."
@@ -353,8 +349,8 @@
     "thumbnail slot omitted at scaffold / agent time — every feed post MUST pass a `thumbnail` prop. Fill `src` with a real subject photo when implied, the bundled `/placeholder.png` otherwise. The runtime `slotOmissionCollapses` reflow is a safety net for downstream consumers, NOT permission for agents to skip the slot",
     "author meta collapsed into a single line — the two meta rows (channel · time / workplace · role · username) are anatomy invariants",
     "engagement footer rendered with raw <button> — like / comments / views are button/text + non-interactive span (views) per the spec",
-    "active-like color painted with sys.color.primary — active-like uses sys.color.brand via the --button-text-label plumbing var",
-    "raw <a> for hashtag / mention — inline link tone uses sys.color.primary via the body markup contract, not raw anchor styling",
+    "active-like color painted with sys.color.background.primary — active-like uses sys.color.text.brand via the --button-text-label plumbing var",
+    "raw <a> for hashtag / mention — inline link tone uses sys.color.background.primary via the body markup contract, not raw anchor styling",
     "Feed wrapped in a padding-inline div / className=\"px-*\" / style={{ padding }} — Feed is layoutInset=\"full-bleed\" and pays its own page rail once; an outer padding wrapper double-pays the gutter and misaligns the card with NavigationBar / TabBar (the runtime useFullBleedGuard warns on this)",
     "Feed wrapped in an external <Link>/<a> to make the card navigable — pass the `onClick` prop instead (the card surface becomes the target, interior affordances route independently). An outer anchor re-pays the page rail as a gutter AND nests the card's own anchors (channel link, citation, mention), which breaks DOM parsing"
   ]

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

@@ -8,6 +8,6 @@ The text-entry primitives — controls the user types into or picks a value from
 
 ## Sub-components
 
-- **[Input](./input.md)** — Single-line text input. Surface-toned box, hairline `outlineVariant` rest stroke, `onSurface` border while active, optional trailing clear ("×"). Corner radius `sys.radius.md`. `error` appearance re-tones to error family. Compose multiple via the **Group** use case.
+- **[Input](./input.md)** — Single-line text input. Surface-toned box, hairline `border.default` rest stroke, `onSurface` border while active, optional trailing clear ("×"). Corner radius `sys.radius.md`. `error` appearance re-tones to error family. Compose multiple via the **Group** use case.
 - **[Search bar](./search.md)** — Same anatomy and state model as Input with three deltas: leading `SearchIcon` glyph, corner radius stepped to `sys.radius.full` (pill), bare-box-only (no `label`, `helper`, or `maxLength`).
 - **[Select](./select.md)** — Input-shaped picker. Read-only field with a trailing `ArrowDownIcon` (16px) chevron; clicking opens a `BottomSheet` with the option list. Supports the same optional leading icon as Input, plus a horizontal **Group** use case (country code + number, currency + amount).

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

@@ -10,7 +10,7 @@ Single-line text field — a bordered, transparent-fill box for short values. Op
 
 ## Default
 
-Transparent fill, hairline `outlineVariant` stroke, placeholder in faint `outline`. Type to see the lifecycle: placeholder → value, stroke steps up, trailing clear (*×*) appears.
+Transparent fill, hairline `border.default` stroke, placeholder in faint `outline`. Type to see the lifecycle: placeholder → value, stroke steps up, trailing clear (*×*) appears.
 
 ```preview
 form-field/input/default
@@ -20,11 +20,9 @@ import { FormField } from '@teamblind-chorus/ui';
 <FormField variant="input" placeholder="Place holder" />
 ```
 
-## Use cases
+## Error
 
-### Error
-
-`errorContainer` wash, full-strength `error` stroke, `onErrorContainer` text. Optional helper rung re-tones to `sys.color.error`.
+`errorContainer` wash, full-strength `error` stroke, `onErrorContainer` text. Optional helper rung re-tones to `sys.color.text.danger`.
 
 ```preview
 form-field/input/error
@@ -55,7 +53,7 @@ import { FormField } from '@teamblind-chorus/ui';
 />
 ```
 
-### Label, assistive text & Count
+## Label, helper & count
 
 When any of `label` / `helper` / `maxLength` is set, the box wraps in a `.chorus-field-group` flex column at `sys.layout.stack.xs` between rungs — label above, helper left or count right below. Helper and count are mutually exclusive; pass both and count wins.
 
@@ -88,7 +86,7 @@ import { FormField } from '@teamblind-chorus/ui';
 />
 ```
 
-### Leading icon
+## Leading icon
 
 Optional `leadingIcon` (16px / `sys.icon.md`) pinned inner-left. Decorative (`aria-hidden`); tracks the field's active text colour. Also available on [`select`](./select.md).
 
@@ -107,23 +105,7 @@ import { LocationIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Group
-
-Compose multiple Inputs into a column via `<FormFieldGroup>`. Each rung keeps its own label / helper / count; group inserts `sys.layout.stack.md` (16px) between rungs — sign-up and profile forms.
-
-```preview
-form-field/input/group
----
-import { FormField, FormFieldGroup } from '@teamblind-chorus/ui';
-
-<FormFieldGroup direction="vertical">
-  <FormField variant="input" label="Name" placeholder="Your name" />
-  <FormField variant="input" label="Email" placeholder="you@example.com" helper="We'll send a confirmation" />
-  <FormField variant="input" label="Bio" placeholder="One sentence about you" />
-</FormFieldGroup>
-```
-
-### Focus indicator
+## Focused state
 
 Focus ring layered on top of the `active` border re-tone.
 
@@ -139,22 +121,38 @@ import { FormField } from '@teamblind-chorus/ui';
 />
 ```
 
+## Group
+
+Compose multiple Inputs into a column via `<FormFieldGroup>`. Each rung keeps its own label / helper / count; group inserts `sys.layout.stack.md` (16px) between rungs — sign-up and profile forms.
+
+```preview
+form-field/input/group
+---
+import { FormField, FormFieldGroup } from '@teamblind-chorus/ui';
+
+<FormFieldGroup direction="vertical">
+  <FormField variant="input" label="Name" placeholder="Your name" />
+  <FormField variant="input" label="Email" placeholder="you@example.com" helper="We'll send a confirmation" />
+  <FormField variant="input" label="Bio" placeholder="One sentence about you" />
+</FormFieldGroup>
+```
+
 ## Slots
 
 - **container** — the box. Owns transparent fill, the inset-`box-shadow` stroke, radius, padding, and focus ring.
 - **input** — editable text. Single line; value-driven placeholder swap.
 - **clear** — trailing *×* button (`XCircleFillIcon`). Shown only while the box is active and holds a non-empty value.
 - **group** *(optional)* — wrapper holding label / box / helper / count when any is supplied.
-- **label** *(optional)* — visible label above the box. `sys.typo.label.md` / `sys.color.onSurface`, bound via `htmlFor`.
-- **helper** *(optional)* — assistive text below the box, left-aligned. `sys.typo.body.sm` / `sys.color.onSurfaceVariant`, referenced by `aria-describedby`; re-tones to `error` on the error appearance. Mutually exclusive with `count`.
-- **count** *(optional)* — `current/max` count below the box, right-aligned. `sys.typo.body.sm` / `sys.color.onSurfaceVariant`; live digit steps to `label.md` weight. `aria-live="polite"`. Mutually exclusive with `helper`.
+- **label** *(optional)* — visible label above the box. `sys.typo.label.md` / `sys.color.text.default`, bound via `htmlFor`.
+- **helper** *(optional)* — assistive text below the box, left-aligned. `sys.typo.body.sm` / `sys.color.text.subtle`, referenced by `aria-describedby`; re-tones to `error` on the error appearance. Mutually exclusive with `count`.
+- **count** *(optional)* — `current/max` count below the box, right-aligned. `sys.typo.body.sm` / `sys.color.text.subtle`; live digit steps to `label.md` weight. `aria-live="polite"`. Mutually exclusive with `helper`.
 
 ## Appearance
 
 | Appearance | Background                    | Border (rest)                                       | Text                          | Placeholder                   |
 |------------|-------------------------------|-----------------------------------------------------|-------------------------------|-------------------------------|
-| `default`  | `transparent`                 | `sys.color.outlineVariant` (`borderWidth.hairline`) | `sys.color.onSurface`         | `sys.color.outline`           |
-| `error`    | `sys.color.errorContainer`    | `sys.color.error` (`borderWidth.hairline`)          | `sys.color.onErrorContainer`  | `sys.color.onErrorContainer`  |
+| `default`  | `transparent`                 | `sys.color.border.default` (`borderWidth.hairline`) | `sys.color.text.default`         | `sys.color.border.boldest`           |
+| `error`    | `sys.color.background.danger`    | `sys.color.text.danger` (`borderWidth.hairline`)          | `sys.color.text.danger`  | `sys.color.text.danger`  |
 
 Placeholder vs. value is value-driven, not focus-driven.
 
@@ -179,14 +177,14 @@ A single fixed footprint.
 
 ## States
 
-Four interactive states. Load-bearing: `active` — the field has the caret; stroke re-tones to `sys.color.onSurface` at 2px.
+Four interactive states. Load-bearing: `active` — the field has the caret; stroke re-tones to `sys.color.text.default` at 2px.
 
 | State      | Stroke (inset box-shadow)                                                 | Additional |
 |------------|---------------------------------------------------------------------------|------------|
-| `default`  | 1px, `borderRest` (`outlineVariant` / `error`)                            | Caret hidden. |
-| `hovered`  | 1px, `sys.color.outline` (error: stays `error`)                           | `:hover`. |
-| `pressed`  | 1px, `sys.color.outline` + `text` overlay at `sys.state.pressed`          | `:active`. |
-| `active`   | 2px, `sys.color.onSurface` (error: `error`)                               | Caret visible per the [system caret rule](../../DESIGN.md#caret). |
+| `default`  | 1px, `borderRest` (`border.default` / `error`)                            | Caret hidden. |
+| `hovered`  | 1px, `sys.color.border.boldest` (error: stays `error`)                           | `:hover`. |
+| `pressed`  | 1px, `sys.color.border.boldest` + `text` overlay at `sys.state.pressed`          | `:active`. |
+| `active`   | 2px, `sys.color.text.default` (error: `error`)                               | Caret visible per the [system caret rule](../../DESIGN.md#caret). |
 | `disabled` | 1px, `borderRest`; container at `sys.state.disabled` opacity              | Fill steps to `surfaceContainerLow`; overlays / clear suppressed; `cursor: not-allowed`. |
 
 ## Focus indicator

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": {
@@ -164,33 +164,34 @@
       "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. 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)."
+      "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)"
   },
@@ -203,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": {
@@ -105,33 +105,34 @@
       "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. 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)."
+      "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)"
   },