@teamblind-chorus/ui 1.0.0

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

@@ -0,0 +1,11 @@
+# Form field
+
+The text-entry primitives — controls the user types into or picks a value from. **Input** is single-line text; **Search Bar** is its search-shaped sibling; **Select** is the Input-shaped picker that opens a sheet. Cross-family contract: bordered surface-toned container, hairline rest stroke that thickens while active, `error` appearance re-tones the whole field.
+
+**Layout inset.** `inline` — slot atom. No page-rail responsibility; the surrounding container places it. Sits inside a labelled form layout (vertical FormField stack) or another component's slot (NavigationBar centre for Search, BottomSheet body for quick-entry) — never a sibling of `full-bleed` page rows. The form column pays the page gutter, not the field.
+
+## 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.
+- **[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

@@ -0,0 +1,198 @@
+# Input
+
+Single-line text field — a bordered, transparent-fill box for short values. Optional `label`, `helper`, or `maxLength` compose it into a labeled group; `appearance="error"` re-tones fill, text, and stroke.
+
+**Reach for this when** capturing a short single-line value — name, email, search query, comment subject. **Skip when** the value is multi-line (use a textarea), a one-of-many selection (use a select), or a free-form search with built-in results (use the [search](./search.md) sub).
+
+**Layout inset.** inline — content-sized inside its surface's padding. With `label` / `helper` / `maxLength` it wraps in a `.chorus-field-group` flex column.
+
+## Default
+
+Transparent fill, hairline `outlineVariant` stroke, placeholder in faint `outline`. Type to see the lifecycle: placeholder → value, stroke steps up, trailing clear (*×*) appears.
+
+```preview
+form-field/input/default
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField variant="input" placeholder="Place holder" />
+```
+
+## Use cases
+
+### Error
+
+`errorContainer` wash, full-strength `error` stroke, `onErrorContainer` text. Optional helper rung re-tones to `sys.color.error`.
+
+```preview
+form-field/input/error
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="input"
+  appearance="error"
+  label="Label text"
+  placeholder="Place holder"
+  helper="Assistive text"
+/>
+```
+
+Omit `helper` when the surrounding row already carries the failure message — the box still re-tones.
+
+```preview
+form-field/input/error-no-helper
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="input"
+  appearance="error"
+  label="Label text"
+  placeholder="Place holder"
+/>
+```
+
+### Label, assistive text & 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.
+
+```preview
+form-field/input/with-label
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="input"
+  label="Label text"
+  placeholder="Place holder"
+  helper="Assistive text"
+/>
+```
+
+Same shape with a character count:
+
+```preview
+form-field/input/with-count
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="input"
+  label="Label text"
+  placeholder="Place holder"
+  defaultValue="Text"
+  maxLength={30}
+/>
+```
+
+### 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).
+
+```preview
+form-field/input/with-leading-icon
+---
+import { FormField } from '@teamblind-chorus/ui';
+import { LocationIcon } from '@teamblind-chorus/ui/icons';
+
+<FormField
+  variant="input"
+  label="Location"
+  leadingIcon={<LocationIcon />}
+  placeholder="City, region"
+  helper="Used to suggest local channels"
+/>
+```
+
+### 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
+
+Focus ring layered on top of the `active` border re-tone.
+
+```preview
+form-field/input/focused
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="input"
+  placeholder="Place holder"
+  state="focused"
+/>
+```
+
+## 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`.
+
+## 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`  |
+
+Placeholder vs. value is value-driven, not focus-driven.
+
+## Sizes
+
+A single fixed footprint.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Height                            | 40px ‡               | `ref.space.500` |
+| Padding (block × inline)          | 8 × 12               | `sys.layout.container.xs` × `sys.layout.container.sm` |
+| Slot gap (input ↔ clear)          | 8px                  | `sys.layout.inline.md`             |
+| Radius                            | 8px                  | `sys.radius.md`                    |
+| Stroke (rest / hover)             | 1px ⁋                | `sys.borderWidth.hairline`         |
+| Stroke (active)                   | 2px ⁋                | `sys.borderWidth.thin`             |
+| Text / placeholder                | 16 / Regular         | `sys.typo.body.md`                 |
+| Clear icon                        | 16px                 | `sys.icon.md`                      |
+
+‡ Height is exactly `content + padding` (24px line-box + 2 × 8px). `min-height` binds raw `ref.space.500`.
+
+⁋ Stroke is an inset `box-shadow`, never a `border` — zero layout cost; footprint pixel-stable in every state. See [DESIGN.md → Border & Stroke](../../DESIGN.md#border-scale).
+
+## States
+
+Four interactive states. Load-bearing: `active` — the field has the caret; stroke re-tones to `sys.color.onSurface` 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). |
+| `disabled` | 1px, `borderRest`; container at `sys.state.disabled` opacity              | Fill steps to `surfaceContainerLow`; overlays / clear suppressed; `cursor: not-allowed`. |
+
+## Focus indicator
+
+Standard outward ring on a `position: absolute` pseudo-element — never affects layout. Suppressed while `disabled`. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Behavior
+
+- **Clear button** shown only while active and holding a non-empty value. Click empties, fires `onClear`, returns focus. Real `<button>`, keyboard-reachable, `aria-label="Clear"`.
+- **Placeholder vs. value** value-driven. Placeholder shows only while empty; never the field's only accessible name — pair with a visible label or `aria-label`.
+- **Single line.** Long values scroll horizontally.

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

@@ -0,0 +1,202 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "FormField",
+  "family": "form-field",
+  "subcomponent": "input",
+  "exportAlias": "Input",
+  "description": "Single-line text field. Transparent-fill box (so it adopts whatever surface it sits on — a bottom sheet, a card, the page) whose visible stroke is an inset box-shadow, never a `border`, so it costs zero layout in every state — the field's height is exactly content + padding (a 24px line-box + 2 × 8px = 40px). Rest/hover stroke is 1px `hairline`, the active stroke steps to 2px `thin`; going active never moves the field's footprint or caret. The placeholder shows in a faint `placeholder` colour while the field is empty and the value in `text` colour once it isn't (value-driven). A trailing clear button appears only while the field is active and holds text. An optional `label` above and `helper` text or `maxLength` character count below (the two are mutually exclusive) wrap the box in a field group. The Chorus focus ring is a position:absolute overlay layer; an error appearance re-tones the whole container.",
+  "element": "input",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "input"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "error"
+      ],
+      "default": "default"
+    },
+    "value": {
+      "type": "string",
+      "optional": true
+    },
+    "defaultValue": {
+      "type": "string",
+      "optional": true
+    },
+    "placeholder": {
+      "type": "string",
+      "optional": true
+    },
+    "label": {
+      "type": "node",
+      "optional": true,
+      "description": "Visible label rendered above the field box and associated with it (`<label htmlFor>`)."
+    },
+    "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."
+    },
+    "maxLength": {
+      "type": "number",
+      "optional": true,
+      "description": "Caps the input length and renders a `current/max` character count below the field box, right-aligned. Mutually exclusive with `helper`."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "group": {
+      "required": false,
+      "description": "Wrapper around the label + box + helper/count, present only when at least one of `label` / `helper` / `maxLength` is supplied. A `display: flex` column at `groupGap` between rungs.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": false,
+      "description": "Visible label above the box. `sys.typo.label.md`, `sys.color.onSurface`. Associated with the input via `htmlFor`.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "container": {
+      "required": true,
+      "description": "The box — owns the transparent fill, the stroke (an inset box-shadow, not a `border`, so it never affects layout), radius, padding, focus ring.",
+      "intrinsic": true
+    },
+    "input": {
+      "required": true,
+      "description": "The editable single-line text. Renders the value in the appearance's `text` colour when present, or the appearance's faint `placeholder` colour when empty — value-driven, not focus-driven. Carries `aria-describedby` pointing at the helper / count when present.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "clear": {
+      "required": false,
+      "description": "Trailing '×' button (XCircleFillIcon) that wipes the value and returns focus to the input. Rendered into the DOM whenever the value is non-empty and the field isn't disabled, but **shown only while the box is focused** — so it appears only in the active state with text to clear; hidden on an empty / blurred / disabled field.",
+      "intrinsic": true
+    },
+    "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.",
+      "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\"`.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.500",
+    "paddingBlock": "sys.layout.container.xs",
+    "paddingInline": "sys.layout.container.sm",
+    "slotGap": "sys.layout.inline.md",
+    "radius": "sys.radius.md",
+    "borderWidth": "sys.borderWidth.hairline",
+    "activeStrokeWeight": "sys.borderWidth.thin",
+    "groupGap": "sys.layout.stack.xs",
+    "labelTypo": "sys.typo.label.md",
+    "helperTypo": "sys.typo.body.sm",
+    "countTypo": "sys.typo.body.sm",
+    "countCurrentTypo": "sys.typo.label.md",
+    "textTypo": "sys.typo.body.md",
+    "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"
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "text": "sys.color.onSurface",
+      "placeholder": "sys.color.outline",
+      "borderRest": "sys.color.outlineVariant",
+      "borderHover": "sys.color.outline",
+      "borderActive": "sys.color.onSurface"
+    },
+    "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"
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null,
+      "border": "borderRest"
+    },
+    "hovered": {
+      "overlay": null,
+      "border": "borderHover"
+    },
+    "pressed": {
+      "border": "borderHover",
+      "overlay": {
+        "color": "text",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "active": {
+      "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)."
+    },
+    "disabled": {
+      "overlay": null,
+      "background": "sys.color.surfaceContainerLow",
+      "containerOpacity": "sys.state.disabled",
+      "suppressClear": true,
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "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.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "accessibility": {
+    "labelling": "The visible label associates with the input via `<label htmlFor>`. When no visible label is composed, the consumer supplies an aria-label.",
+    "describedby": "The input's aria-describedby points at the helper id (when a helper is rendered) or the count id (when a maxLength count is rendered) — the two are mutually exclusive.",
+    "invalid": "On the `error` appearance the input carries aria-invalid='true' — color alone does not expose invalidity to assistive tech. aria-invalid clears when the appearance returns to default.",
+    "errorAnnouncement": "When the helper is carrying an error message (error appearance), its container is a polite live region (role='alert' / aria-live='polite') so the message is announced when it appears without yanking focus. The neutral (non-error) helper is not a live region.",
+    "count": "The character count updates aria-live='polite' (see the count slot)."
+  },
+  "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",
+    "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

@@ -0,0 +1,81 @@
+# Search bar
+
+Search-shaped single-line field — sibling of [Input](./input.md) with a leading `SearchIcon` and `sys.radius.full` pill corner. Box, stroke, placeholder rule, clear button, and focus ring inherited from Input unchanged. **Bare box only — no `label`, `helper`, `maxLength`, or `error` appearance.** Error reporting belongs to a labelled Input.
+
+**Reach for this when** the rung is a query against an open set — directory search, post filter, command palette entry. **Skip when** the value is a labelled form field ([Input](./input.md)), the user picks from a known closed set ([Select](./select.md)), or the surface needs error reporting (a bare search rung has nowhere to host it — use a labelled [Input](./input.md)).
+
+**Layout inset.** `inline` — ships no padding outside its own pill chrome. Sits inside a host slot (NavigationBar search row, filter sheet header, page-body search row) with the host paying surrounding inline padding. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), the host already owns the inset — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## 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.
+
+```preview
+form-field/search/default
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField variant="search" placeholder="Search" />
+```
+
+## Use cases
+
+### Focus indicator
+
+Focus ring layered on top of the `active` pill border. Same composition as [Input → Focus indicator](./input.md#focus-indicator).
+
+```preview
+form-field/search/focused
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="search"
+  placeholder="Search"
+  state="focused"
+/>
+```
+
+## Appearance
+
+Single `default` appearance — Search Bar does **not** carry an `error` form. Error reporting belongs to a labelled [Input](./input.md#appearance), which can pair the re-tone with assistive text; a bare search rung has nowhere to host that message.
+
+## Slots
+
+- **container** — pill box. Same as Input's, radius stepped to `sys.radius.full`.
+- **leading** — `SearchIcon` at `sys.icon.md` (16px), pinned inner-left with an 8px gap. Inherits field text colour; decorative (`aria-hidden`).
+- **input** — same as Input. Pair with `aria-label` at the call site.
+- **clear** — same as Input. Trailing "×" shown only while active and holding a value.
+
+## Sizes
+
+Same fixed footprint as Input — 40px tall — radius stepped to full. Inline column reads `[icon 16] [text] [clear 16]`.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Height                            | 40px                 | `ref.space.500`                     |
+| Padding (block × inline)          | 8 × 12               | `sys.layout.container.xs` × `sys.layout.container.sm` |
+| Slot gap (leading ↔ input ↔ clear)| 8px                  | `sys.layout.inline.md`              |
+| Radius                            | full (pill)          | `sys.radius.full`                   |
+| Leading icon                      | 16px                 | `sys.icon.md`                       |
+| Clear icon                        | 16px                 | `sys.icon.md`                       |
+| Stroke (rest / hover)             | 1px                  | `sys.borderWidth.hairline`          |
+| Stroke (active)                   | 2px                  | `sys.borderWidth.thin`              |
+| Text / placeholder                | 16 / Regular         | `sys.typo.body.md`                  |
+
+Stroke is an inset `box-shadow`, focus ring is a `position: absolute` overlay — footprint pixel-stable in every state. See [Input → Sizes](./input.md#sizes).
+
+## States
+
+Identical to Input — see [Input → States](./input.md#states). The leading glyph follows the field's text colour.
+
+## Focus indicator
+
+Composition: Outward (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)). On a `position: absolute` `::after` overlay, sits above the `active` border. Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Search action.** Glyph is decorative; search fires from the input via `onChange` or `Enter`.
+- **Clear button.** Same as Input — see [Input → Behavior](./input.md#behavior).
+- **Placeholder vs. value.** Same value-driven swap; pair with `aria-label`.
+- **Single line.** Long values scroll horizontally.

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

@@ -0,0 +1,135 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "FormField",
+  "family": "form-field",
+  "subcomponent": "search",
+  "exportAlias": "SearchBar",
+  "description": "Single-line search field — a search-shaped sibling of Input. Same transparent-fill box, same hairline-at-rest / thin-at-active inset box-shadow stroke (so the box model is untouched in every state), same placeholder-vs-value colour rules, same focus ring, same trailing clear button. Two anatomy differences from Input — a leading `SearchIcon` glyph pinned at the box's inner-left edge so the field reads as a search affordance before the user types, and the corner radius steps from `sys.radius.md` to `sys.radius.full` (pill). **Search Bar is a bare box only — it does not accept a `label`, `helper`, or `maxLength`**, and so never renders the field-group wrapper; it also carries no `error` appearance — error reporting belongs to a labelled field. A search rung sits in chrome (a header bar, a list filter, a sheet's top) where the affordance is carried by the leading glyph and the placeholder; stacking a visible label or a `current/max` count on top of that competes with the search affordance instead of reinforcing it. Reach for [Input](./input.md) when the rung needs a labelled / counted form field or an error treatment.",
+  "element": "input",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "search"
+    },
+    "appearance": {
+      "type": "literal",
+      "value": "default",
+      "description": "Search Bar carries only the `default` appearance — there is no `error` form (error reporting belongs to a labelled Input)."
+    },
+    "value": {
+      "type": "string",
+      "optional": true
+    },
+    "defaultValue": {
+      "type": "string",
+      "optional": true
+    },
+    "placeholder": {
+      "type": "string",
+      "optional": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "The pill box — owns the transparent fill, the stroke (an inset box-shadow, not a `border`, so it never affects layout), full radius, padding, focus ring.",
+      "intrinsic": true
+    },
+    "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.",
+      "intrinsic": true
+    },
+    "input": {
+      "required": true,
+      "description": "The editable single-line text. Renders the value in the appearance's `text` colour when present, or the appearance's faint `placeholder` colour when empty — value-driven, not focus-driven.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "clear": {
+      "required": false,
+      "description": "Trailing '×' button (XCircleFillIcon) that wipes the value and returns focus to the input. Rendered into the DOM whenever the value is non-empty and the field isn't disabled, but **shown only while the box is focused** — so it appears only in the active state with text to clear; hidden on an empty / blurred / disabled field.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.500",
+    "paddingBlock": "sys.layout.container.xs",
+    "paddingInline": "sys.layout.container.sm",
+    "slotGap": "sys.layout.inline.md",
+    "radius": "sys.radius.full",
+    "borderWidth": "sys.borderWidth.hairline",
+    "activeStrokeWeight": "sys.borderWidth.thin",
+    "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"
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null,
+      "border": "borderRest"
+    },
+    "hovered": {
+      "overlay": null,
+      "border": "borderHover"
+    },
+    "pressed": {
+      "border": "borderHover",
+      "overlay": {
+        "color": "text",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "active": {
+      "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)."
+    },
+    "disabled": {
+      "overlay": null,
+      "background": "sys.color.surfaceContainerLow",
+      "containerOpacity": "sys.state.disabled",
+      "suppressClear": true,
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "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.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "leading search glyph as a separate hit area — the entire field is the click / focus target",
+    "clear glyph rendered when value is empty — the clear affordance only appears with content",
+    "search field stacked under a navigation-bar/search — the bar variant already embeds the search input"
+  ]
+}