@agent-ui-kit/components 0.0.3

package/dist/controls/disclosure/disclosure.css

@@ -0,0 +1,162 @@
+/* disclosure.css — ui-disclosure, the single-file component stylesheet (ADR-0003; content-family.lld.md
+ * LLD-C9 · SPEC-R18). Two clearly-SECTIONED blocks, mirroring button.css / select.css / modal.css:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-disclosure)` (specificity 0,0,0) DECLARES the `--ui-disclosure-*` chain
+ *       from the colour roles (`--md-sys-color-neutral-*` — a disclosure carries no accent/family axis)
+ *       and the dimensional ramp. Pattern-class split (geometry.md "accordion" row): the summary row is
+ *       the interactive CONTROL-height row (`--md-sys-height-md`/`--md-sys-font-md`, density-INVARIANT frame); the
+ *       body rhythm rides the `--md-sys-space-*` layout ladder (density-RESPONSIVE). The chevron is an INLINE
+ *       AFFORDANCE (geometry.md §"Affordance vs content-icon") — sized `= font`, never the icon ramp.
+ *   [2] STYLES BLOCK — `@scope (ui-disclosure)` CONSUMES only `--ui-disclosure-*` (+ the two shared fleet
+ *       constants every control reads directly: the focus-ring pair, ADR-0009). The native `::marker`/
+ *       `::-webkit-details-marker` is replaced by the chevron; its ORIENTATION (not colour, not size)
+ *       carries the open/closed state — a non-color, non-motion signifier. NO fold animation and NO
+ *       transition on the chevron rotation (ADR-0113 cl.4 / SPEC-R18 — `::details-content` interpolation
+ *       is too cross-engine-fresh; a grep-able absence, pinned by disclosure-css.test.ts).
+ *
+ * Standalone stylesheet — NOT injected from disclosure.ts (behaviour-only `.ts`, no runtime injection per
+ * plan §2). Linked via the component-styles barrel at the integration wave (LLD-C11) — this folder ships
+ * standalone for the M1-a checkpoint (content-family.lld.md §9).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-disclosure) declares --ui-disclosure-* ════════════════ */
+
+:where(ui-disclosure) {
+  /* Summary row — Pattern-class interactive row (geometry.md: "interactive rows take the control
+     height"). Fixed at the md ramp step (ui-disclosure exposes no [size] axis — a fold header is not a
+     sized entry/action control). Density-INVARIANT (frame family, ∝ height). */
+  --ui-disclosure-height: var(--md-sys-height-md);
+  --ui-disclosure-font: var(--md-sys-font-md);
+  --ui-disclosure-ink: var(--md-sys-color-neutral-on-surface);
+  /* Hover (TKT-0047, revised twice): a background-PAINT wash, not an ink-step. The original ink-step
+     attempt (matching tabs.css) turned out visually inert — disclosure's idle ink already sits at the
+     ceiling of the neutral ramp (`-on-surface`, tokens.css:56), so no hover-ink value could ever show a
+     change. A first background-wash attempt reached for the tint ladder (`neutral-tint-dim`) — WRONG:
+     component-reviewer caught that the tint ladder was already EVICTED from row-hover fleet-wide (the
+     2026-07-07 menu.css consistency pass, menu.css:87-96 — a 10% tint wash was the ONLY row-hover using
+     it, read as visibly weaker/inconsistent, and was converged onto the solid, scheme-inverting
+     `--md-sys-color-neutral-surface-high` role every other interactive-row/control hover already uses:
+     select's option, button (even the ghost variant, the closest structural analogue to this summary
+     row), text-field, checkbox, switch, calendar's cell). `tint-dim` is also near-invisible in dark
+     scheme (a scheme-INVARIANT ~5% black wash, tokens.css:1060, vs. `surface-high`'s scheme-inverting
+     solid role, tokens.css:86) — it would have silently resurfaced this exact defect in dark mode.
+     Converged onto the fleet's actual hover answer instead. Forced-colors: no extra WHCM rule needed —
+     the UA forces any background to Canvas regardless of which role is named here (the tabs.css
+     precedent: only the SELECTED state gets an explicit forced-colors rule, not hover). */
+  --ui-disclosure-bg-hover: var(--md-sys-color-neutral-surface-high);
+
+  /* The chevron — an INLINE AFFORDANCE (geometry.md §"Affordance vs content-icon"): `= font`, never the
+     icon ramp (`--ui-ind`) — the named oversize-caret bug class this law fixes. */
+  --ui-disclosure-glyph: var(--ui-disclosure-font);
+
+  /* Summary row inline layout — the icon↔label gap (rhythm family, ∝ font × density; geometry.md). */
+  --ui-disclosure-gap: var(--md-sys-gap-md);
+
+  /* Body rhythm — the `--md-sys-space-*` LAYOUT ladder (density-RESPONSIVE; the Pattern-class split,
+     geometry.md: "the shell uses the space scale"), never the control-height frame. */
+  --ui-disclosure-body-pad-block: var(--md-sys-space-sm);
+  --ui-disclosure-body-pad-inline: var(--md-sys-space-md);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-disclosure) consumes ONLY --ui-disclosure-* ════════════════ */
+
+@scope (ui-disclosure) {
+  :scope {
+    display: block;
+    color: var(--ui-disclosure-ink); /* the ambient ink a bare instance paints (ADR-0102 Lane A) — body content may override */
+  }
+
+  /* The summary row — a Pattern-class interactive CONTROL-height row: [chevron | label], flex (not the
+     host-as-grid anatomy — ui-disclosure is a rendered content cell, ADR-0113 cl.4, not host-as-grid).
+     `padding-block: 0` — the geometry law: block-size, never block-padding, is the vertical lever. */
+  :scope [data-part='summary'] {
+    display: flex;
+    align-items: center;
+    gap: var(--ui-disclosure-gap);
+    box-sizing: border-box;
+    block-size: var(--ui-disclosure-height);
+    padding-block: 0;
+    padding-inline-start: calc(var(--ui-disclosure-height) / 2); /* slotless-edge law, h/2 (geometry.md) */
+    padding-inline-end: calc(var(--ui-disclosure-height) / 2);
+    font-size: var(--ui-disclosure-font);
+    line-height: var(--md-sys-control-line-height); /* single-line control standard (ADR-0036) */
+    color: var(--ui-disclosure-ink);
+    cursor: pointer;
+    list-style: none; /* hide the native ::marker (Chromium) */
+    -webkit-user-select: none;
+    user-select: none;
+  }
+
+  /* Firefox/older-WebKit render a `::-webkit-details-marker` / native triangle instead of `list-style` —
+     hide it explicitly (both engines, SPEC-R18 AC1). */
+  :scope [data-part='summary']::-webkit-details-marker {
+    display: none;
+  }
+  :scope [data-part='summary']::marker {
+    content: '';
+  }
+
+  /* The chevron — the inline affordance, sized = font (never the icon ramp). Orientation carries the
+     open/closed state (a shape/position signifier, not colour-only — ADR-0057); NO transition on the
+     rotation (SPEC-R18 — cross-engine + reduced-motion honesty; grep-able absence). */
+  :scope [data-part='chevron'] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    inline-size: var(--ui-disclosure-glyph);
+    block-size: var(--ui-disclosure-glyph);
+    color: currentColor;
+    rotate: 0deg;
+  }
+  :scope [data-part='chevron'] svg {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+  :scope > [data-part='details'][open] [data-part='chevron'] {
+    rotate: 90deg; /* caret-right → visually caret-down; orientation IS the state, no colour/size change */
+  }
+
+  /* The summary label — the fold's one-line text (the `summary` prop, textContent-only). */
+  :scope [data-part='summary-text'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+  }
+
+  /* Hover (TKT-0047, revised) — a background-tint wash (the combo-box.css active-descendant
+     precedent), not an ink-step: disclosure's idle ink has no headroom to step to (see the
+     TOKEN block comment above). */
+  :scope [data-part='summary']:hover {
+    background-color: var(--ui-disclosure-bg-hover);
+  }
+
+  /* The body — rides the `--md-sys-space` layout ladder (density-responsive; the Pattern-class split). No
+     control-height law applies here (it is a content shell, not an interactive row). */
+  :scope [data-part='body'] {
+    padding-block: var(--ui-disclosure-body-pad-block);
+    padding-inline: var(--ui-disclosure-body-pad-inline);
+  }
+
+  /* Keyboard focus — the ONE shared fleet ring (ADR-0009), read directly (the button.css/select.css
+     exception to "consume only --ui-disclosure-*"): identical across every control, keyboard-only,
+     layout-neutral. The summary is natively focusable — no tabbable trait needed. */
+  :scope [data-part='summary']:focus-visible {
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset);
+  }
+
+  /* forced-colors (WHCM) — summary/body text + the chevron all paint in system inks (SPEC-R18 AC3). Every
+     value here already resolves through a role that carries the WHCM mapping at the token layer
+     (tokens.md: neutral inks → CanvasText), so this block is belt-and-suspenders, explicit for the
+     computed-style probe — not load-bearing new colour. The chevron is `currentColor`, so it inherits the
+     summary's CanvasText for free; the focus ring survives via `--md-sys-color-focus-ring → Highlight`. */
+  @media (forced-colors: active) {
+    :scope {
+      color: CanvasText;
+    }
+    :scope [data-part='summary'] {
+      color: CanvasText;
+    }
+  }
+}

package/dist/controls/disclosure/disclosure.d.ts

@@ -0,0 +1,37 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    open: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    summary: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+};
+export interface UIDisclosureElement extends ReactiveProps<typeof props> {
+}
+export declare class UIDisclosureElement extends UIElement {
+    #private;
+    static props: {
+        open: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        summary: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+    };
+    protected connected(): void;
+    protected disconnected(): void;
+}
+export {};

package/dist/controls/disclosure/disclosure.js

@@ -0,0 +1,207 @@
+// disclosure.ts — UIDisclosureElement, the content-family M1-a `ui-disclosure` (content-family.lld.md
+// LLD-C8 · SPEC-R14…R18 · ADR-0113 cl.4). BEHAVIOUR + props + the control-owned <details> part + self-
+// define ONLY. Anatomy/geometry per the LLD; styling lives in disclosure.css, the public contract in
+// disclosure.md.
+//
+// The no-native-form-elements law does not bind: a <details> participates in no form (the ADR-0017
+// <dialog> precedent, applied here per ADR-0113's Context). Native <details>/<summary> supplies the
+// toggle behaviour, the summary's button semantics + expanded/collapsed announcement, find-in-page
+// auto-expand of folded content, and the `name` exclusive-accordion substrate — all platform-free; a
+// bespoke button+region reimplements every one against internals-ARIA limits and loses the searchability
+// story (ADR-0113 fork F3). `ui-disclosure` extends UIElement (NOT form-associated).
+//
+// Anatomy (a component-owned part, created ONCE — idempotent across disconnect/reconnect, the
+// modal.ts/select.ts precedent):
+//   <ui-disclosure>
+//     <details data-part="details">
+//       <summary data-part="summary">
+//         <span data-part="chevron" aria-hidden="true"><svg>…caret-right (@agent-ui-kit/icons)…</svg></span>
+//         <span data-part="summary-text">…the `summary` prop…</span>
+//       </summary>
+//       <div data-part="body"><!-- the host's light-DOM children, adopted --></div>
+//     </details>
+//   </ui-disclosure>
+//
+// The anatomy invariant (SPEC-R16): the host's light-DOM children converge into the body part. Children
+// present at connect are adopted in #ensureParts(); parser-streamed children landing on the host AFTER
+// connect, and a destructive `host.textContent` write that detaches the details part, are healed by a
+// childList MutationObserver — the ADR-0078 cl.4 stamp/heal lineage (ui-select's options-move / ui-text's
+// stamp-heal precedent, `text.ts`).
+//
+// `open` is prop-as-source-of-truth under the ADR-0101 always-announce law (the ui-modal/ui-select `open`
+// precedent): a scope-owned effect drives model→platform (`details.open = this.open` — a same-value
+// assignment is a native no-op, no `toggle` event, the loop-breaker's first half); the platform's `toggle`
+// event (fired on a user click, a model-driven write reaching the platform, OR a find-in-page auto-
+// expand) is the SOLE announcer — it settles the prop (if the platform led) and always emits the host
+// `toggle`, with `this.open` already settled at listener time (ADR-0101 mechanic 3).
+//
+// The toggle LISTENER is wired explicitly wherever a `details` part becomes current — once in connected()
+// (covers the initial connect AND every reconnect, since parts persist across disconnect/reconnect but a
+// fresh AbortController is minted each connect — the modal.ts/select.ts discipline) and once more inside
+// the heal observer's rebuild branch (covers a MID-CONNECTION clobber-rebuild, which connected() never
+// reruns for). The OLD part's listener dies with it — abort-owned, freed at the next disconnect regardless
+// (a bounded, non-functional residual across a rare clobber, never a live double-fire).
+//
+// No internals role, no host ARIA (SPEC-R17): the details/summary part IS the semantic element (ADR-0017
+// cl.5 lineage). No focus machinery: the summary is natively focusable. `render()` stays the inherited
+// no-op (the part is imperative DOM, not a template commit). `controls → dom + @agent-ui-kit/icons` — the
+// allowed import direction (icons is a zero-dep sibling package, like select.ts's own caret glyph).
+import { UIElement, prop } from "../../dom/index.js";
+import { setIcon } from '@agent-ui-kit/icons';
+const props = {
+    // The fold's two-way state (ADR-0101 + ADR-0019) — prop-as-source-of-truth. Reflected so the [open]
+    // attribute mirrors the declared state (inspectable/serializable), the ui-modal/ui-select precedent.
+    open: { ...prop.boolean(false), reflect: true },
+    // The fold's one-line label — a bindable string prop (NOT a slot, SPEC-R14): keeps the heal invariant
+    // "children = body" simple (a rich `slot=summary` child is the named foreseen extension). Reflected so
+    // a JS-set value applies identically to an author-set attribute (the fleet reflect precedent).
+    summary: { ...prop.string(''), reflect: true },
+};
+export class UIDisclosureElement extends UIElement {
+    static props = props;
+    // The control-owned parts — created ONCE (idempotent guard in #ensureParts); persist through
+    // disconnect/reconnect. `#`-private: nothing outside the host can observe or hold them.
+    #details = null;
+    #summary = null;
+    #chevron = null;
+    #summaryText = null;
+    #body = null;
+    // The childList observer that heals the anatomy invariant (parser streaming / a host.textContent
+    // clobber). Disconnected in `disconnected()` — the ui-text `#observer` discipline (a raw platform
+    // observer isn't scope-owned, so teardown is by hand).
+    #observer = null;
+    connected() {
+        const { details } = this.#ensureParts();
+        // Summary effect — prop-driven, markup-free (SPEC-R16 AC2); never touches `open`. Reads the CURRENT
+        // `#summaryText` field (not a closed-over local) so it stays correct even after a heal rebuild
+        // replaces the part — though the rebuild itself re-syncs immediately (see #heal), without waiting for
+        // this effect to next fire.
+        this.effect(() => this.#syncSummary(this.summary));
+        // model→platform — `open` drives the platform. A same-value assignment is a native no-op (no `toggle`
+        // event fires) — the loop-breaker's first half (SPEC-R15 AC2). Reads `#details` fresh, same reason.
+        this.effect(() => this.#syncOpen(this.open));
+        // platform→prop→announce — wired for the CURRENT details part; re-wired on every connected() call
+        // (the reconnect case: parts persist but the AbortController is fresh) and again from the heal
+        // rebuild branch (the mid-connection clobber case, which connected() itself never reruns for).
+        this.#wireToggle(details);
+        // The heal observer — installed AFTER the initial part creation/effects above (the text.ts
+        // discipline: it never observes its own synchronous setup; it only fires for LATER host mutations).
+        this.#observer = new MutationObserver(() => this.#heal());
+        this.#observer.observe(this, { childList: true });
+    }
+    disconnected() {
+        this.#observer?.disconnect();
+        this.#observer = null;
+    }
+    /**
+     * Wire the platform `toggle` listener onto `details` (the SOLE announcer, SPEC-R15). Hears a user click
+     * on the summary, a find-in-page auto-expand, AND the open-effect's own platform write:
+     *   - user/platform-led: `details.open` has ALREADY flipped by the time `toggle` fires, so `now` differs
+     *     from the (still-stale) prop — sync `this.open = now` (which reflects the attribute synchronously,
+     *     ADR-0101 mechanic 3), then announce. The open effect's own later re-run assigns the SAME value —
+     *     a native no-op, no second event.
+     *   - model-led: the open effect already set `this.open` (and `details.open`) BEFORE the platform's
+     *     `toggle` fires, so `now === this.open` here — no re-write, no second wake — just the one announce.
+     *   - a re-assert (`open` written to its current value): the open effect's assignment is a same-value
+     *     platform no-op — no `toggle` ever fires, so this listener never runs and nothing announces
+     *     (the loop-breaker's other half).
+     */
+    #wireToggle(details) {
+        this.listen(details, 'toggle', () => {
+            const now = details.open;
+            if (now !== this.open)
+                this.open = now;
+            this.emit('toggle');
+        });
+    }
+    /** Apply `text` to the CURRENT summary-text part, if any (a no-op before the part exists). */
+    #syncSummary(text) {
+        const summaryText = this.#summaryText;
+        if (summaryText)
+            summaryText.textContent = text;
+    }
+    /** Apply `open` to the CURRENT details part, if any (a no-op before the part exists). */
+    #syncOpen(open) {
+        const details = this.#details;
+        if (details)
+            details.open = open;
+    }
+    /**
+     * Restore the anatomy invariant after a childList mutation lands directly on the host (SPEC-R16). A
+     * DETACHED details part (a `host.textContent` clobber — every child, details part included, replaced)
+     * is never reused (it holds stale content, the ADR-0106/text.ts lineage): null every part ref, rebuild
+     * fresh via #ensureParts, re-wire the toggle listener onto the NEW part, and re-run the summary/open
+     * sync immediately (not waiting for the reactive effects to next fire — they read the CURRENT field but
+     * only re-run on a future prop CHANGE). Otherwise every stray host child (parser-streamed content
+     * arriving after connect) is adopted into the body part, append order. Both branches mutate the host and
+     * so re-fire this very observer, but the next delivery finds the invariant satisfied — a no-op — so this
+     * self-converges within ≤2 passes; it can never loop forever (SPEC-R16 AC1/AC3).
+     */
+    #heal() {
+        const details = this.#details;
+        if (!details)
+            return;
+        if (details.parentNode !== this) {
+            this.#details = null;
+            this.#summary = null;
+            this.#chevron = null;
+            this.#summaryText = null;
+            this.#body = null;
+            const fresh = this.#ensureParts();
+            this.#wireToggle(fresh.details);
+            this.#syncSummary(this.summary);
+            this.#syncOpen(this.open);
+            return;
+        }
+        const body = this.#body;
+        if (!body)
+            return;
+        for (const node of Array.from(this.childNodes)) {
+            if (node !== details)
+                body.appendChild(node);
+        }
+    }
+    /**
+     * Create the control's FIVE light-DOM parts ONCE (idempotent across disconnect/reconnect — parts
+     * persist, the modal.ts/select.ts precedent): the `<details data-part="details">` wrapping a
+     * `<summary data-part="summary">` (a `[data-part="chevron"]` glyph + `[data-part="summary-text"]` label)
+     * and a `<div data-part="body">`. Pre-existing host children are adopted into the body — MOVED, never
+     * cloned (ADR-0022) — before the details part is appended as the host's only element child. Does NOT
+     * wire the toggle listener (that is connected()'s / #heal's job — see the class doc) so this helper
+     * stays a pure "ensure the DOM shape" primitive, callable from either site. `render()` stays the
+     * inherited no-op.
+     */
+    #ensureParts() {
+        if (this.#details && this.#summary && this.#chevron && this.#summaryText && this.#body) {
+            return { details: this.#details };
+        }
+        const details = document.createElement('details');
+        details.setAttribute('data-part', 'details');
+        const summary = document.createElement('summary');
+        summary.setAttribute('data-part', 'summary');
+        const chevron = document.createElement('span');
+        chevron.setAttribute('data-part', 'chevron');
+        chevron.setAttribute('aria-hidden', 'true'); // decorative — disclosure meaning rides the native summary/details, never the glyph (anatomy.md §5)
+        setIcon(chevron, 'caret-right'); // Phosphor, via @agent-ui-kit/icons; rotated 90deg under [open] in disclosure.css
+        const summaryText = document.createElement('span');
+        summaryText.setAttribute('data-part', 'summary-text');
+        summary.appendChild(chevron);
+        summary.appendChild(summaryText);
+        const body = document.createElement('div');
+        body.setAttribute('data-part', 'body');
+        // Adopt every pre-existing host child into the body — moved, never cloned (ADR-0022).
+        while (this.firstChild)
+            body.appendChild(this.firstChild);
+        details.appendChild(summary);
+        details.appendChild(body);
+        this.appendChild(details);
+        this.#details = details;
+        this.#summary = summary;
+        this.#chevron = chevron;
+        this.#summaryText = summaryText;
+        this.#body = body;
+        return { details };
+    }
+}
+if (!customElements.get('ui-disclosure'))
+    customElements.define('ui-disclosure', UIDisclosureElement);

package/dist/controls/field/field.css

@@ -0,0 +1,140 @@
+/* field.css — ui-field, the label/description/error wrapper stylesheet (ADR-0051 · LLD-C5).
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-field)` (specificity 0,0,0) declares the `--ui-field-*` chain: a single
+ *       density-bearing spacing token (`--ui-field-gap`, off `--md-sys-space-xs` — the label↔control↔description
+ *       rhythm) plus the three part inks/fonts (label / description / error), each a ROLE (`--md-sys-color-{family}-{role}`)
+ *       or a font-ramp read (`--md-sys-font-*`) — never a `color-mix` (colour opinions live in the token layer). The
+ *       error ink/font MATCH text-field's own message tokens (`--ui-text-field-message-*`) — one visual voice for
+ *       the ONE error, whichever control renders it. `:has([disabled])` on the slotted control REPOINTS the
+ *       label/description ink to the muted on-surface-variant role (role REPOINT, NOT opacity — tokens.md); kept
+ *       in this `:where()` block (specificity 0, declared after the base) so the @scope block below still reads
+ *       only `--ui-field-*`, same pattern as text-field's/checkbox's own `[disabled]` repoint.
+ *   [2] STYLES BLOCK — `@scope (ui-field)` consumes ONLY `--ui-field-*`. Geometry class: Container/layout (the
+ *       decomp's "STRUCTURE" intent) — NO control height anywhere, NO `[size]` prop/ramp; the host is a column
+ *       flex stack (`row-gap: --ui-field-gap`) and the slotted control brings its own ADR-0021 width floor (the
+ *       field adds none). Parts styled by `[data-part=label|description|error]`; DOM placement (label prepended,
+ *       description/error appended — field.ts) already IS the reading order, so no CSS `order` is needed. The
+ *       error part defaults to `display: none`, shown by `:scope:state(user-invalid) [data-part=error]` PLUS an
+ *       explicit `[hidden]` guard written AFTER it (both (0,3,0) — source order breaks the tie; the guard must
+ *       win so a state flip can't out-race the control's own hide — a frozen m4 repair, do not reorder). Motion:
+ *       an UNCONDITIONAL small transition on the error part (the INDICATOR family pattern — no `:state(ready)`
+ *       gate, because user-invalid is interaction-gated and the error literally cannot show at first paint, so
+ *       the first-paint-flash concern :state(ready) exists for elsewhere never applies here), reduced-motion
+ *       zeroes it. Forced-colors: the inks stay CanvasText (real text, not decorative glyphs — no
+ *       `forced-color-adjust: none`); the error stays distinguishable by presence, not colour alone (WCAG 1.4.1).
+ *
+ * Standalone stylesheet — linked via the host page / component-styles barrel (s12); NEVER injected from
+ * field.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-field) declares --ui-field-* ════════════════ */
+
+:where(ui-field) {
+  /* Layout rhythm — the ONE density-bearing quantity (label↔control↔description column gap). */
+  --ui-field-gap: var(--md-sys-space-xs);
+
+  /* Label — the field's own name text, above/beside the slotted control. */
+  --ui-field-label-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-field-label-font: var(--md-sys-font-md);
+  --ui-field-label-weight: 500;
+
+  /* Required marker — the STATIC requiredness affordance appended to the label. Reads the LABEL ink, NOT
+     the error ink: requiredness is INVARIANT (it persists through a valid value), so the marker must read
+     as part of the label — never as the DYNAMIC validity/error signifier (which owns --ui-field-error-ink
+     and its own [data-part=error] text). Painting a required marker in the danger colour made a satisfied
+     field still read as "erroring" (the mark stays after a valid pick); that is exactly the intent-by-colour-
+     alone conflation ADR-0057 forbids. Following --ui-field-label-ink also mutes the marker with its label
+     under [disabled] (the repoint below flows through, var() being lazily substituted). */
+  --ui-field-required-ink: var(--ui-field-label-ink);
+
+  /* Description — the muted helper text under the control. */
+  --ui-field-description-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-field-description-font: var(--md-sys-font-sm);
+
+  /* Error — matches text-field's own message voice (--ui-text-field-message-*): one visual voice for
+     the ONE error, whichever control renders it. */
+  --ui-field-error-ink: var(--md-sys-color-danger-on-surface-variant); /* danger TEXT ink — AA-gated on-surface (8.48:1 light / 8.91:1 dark). Bare --md-sys-color-danger is 4.05:1 light = an AA text FAIL; only the TEXT ink moves (any danger BORDER channel stays --md-sys-color-danger, the 3:1 UI bar). 2026-07-02 color audit item 1. */
+  --ui-field-error-font: var(--md-sys-font-sm);
+}
+
+/* disabled → a role-REPOINT of the label/description ink (NOT opacity, tokens.md canon), keyed off the
+   SLOTTED control's reflected [disabled] attr (the field carries no disabled prop of its own — LLD-C4).
+   :where() holds this at specificity 0 so it wins the cascade by declaration order alone, the same pattern
+   as text-field's/checkbox's own [disabled] repoint block. */
+:where(ui-field:has([disabled])) {
+  --ui-field-label-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-field-description-ink: var(--md-sys-color-neutral-on-surface-variant);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-field) consumes ONLY --ui-field-* ════════════════ */
+
+@scope (ui-field) {
+  /* Container/layout geometry class (no control height, no [size] ramp — the radio-group precedent):
+     a column stack, spacing off --md-sys-space-* × density. The parts' DOM order (label prepended,
+     description/error appended around the slotted control — field.ts) already IS the reading order. */
+  :scope {
+    display: flex;
+    flex-direction: column;
+    row-gap: var(--ui-field-gap);
+    min-inline-size: 0; /* the slotted control brings its own ADR-0021 width floor; the field adds none */
+  }
+
+  :scope [data-part='label'] {
+    color: var(--ui-field-label-ink);
+    font-size: var(--ui-field-label-font);
+    font-weight: var(--ui-field-label-weight);
+  }
+
+  :scope [data-part='description'] {
+    color: var(--ui-field-description-ink);
+    font-size: var(--ui-field-description-font);
+  }
+
+  /* required affordance — pure CSS off the slotted control's reflected [required] attr (LLD-C4/C5); no
+     field-side state duplication. */
+  :scope:has([required]) [data-part='label']::after {
+    content: ' *';
+    color: var(--ui-field-required-ink); /* label-matched, NOT error ink — a static requiredness mark is not the dynamic error signifier (ADR-0057) */
+  }
+
+  /* Error visibility — default hidden; field.ts toggles the host's :state(user-invalid) custom state and
+     the part's [hidden] attribute together (#renderValidity), but the CSS gate is the custom state (the
+     part's own text emptiness is the content guard). Base rule at (0,2,0) carries the ink/font always. */
+  :scope [data-part='error'] {
+    display: none;
+    color: var(--ui-field-error-ink);
+    font-size: var(--ui-field-error-font);
+    transition: color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard); /* unconditional — the INDICATOR pattern: no :state(ready) gate, the error cannot show at first paint (user-invalid is interaction-gated) */
+  }
+
+  /* Shown when the associated control's user-invalid gate is live (LLD-C1's userInvalid() read, mirrored
+     onto this host's own :state(user-invalid) by field.ts's #renderValidity). */
+  :scope:state(user-invalid) [data-part='error'] {
+    display: block;
+  }
+
+  /* The explicit [hidden] guard — written AFTER the state rule above. Both compute specificity (0,3,0),
+     so source order decides; this guard MUST win so field.ts's own hidden toggle (e.g. an empty
+     validationMessage while user-invalid) can always suppress the box. Frozen m4 repair — do not reorder. */
+  :scope [data-part='error'][hidden] {
+    display: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :scope [data-part='error'] {
+      transition: none; /* accessibility (non-negotiable) — reduced motion zeroes the error transition */
+    }
+  }
+
+  /* Forced colors (WHCM) — label/description/error stay CanvasText (real text content, not decorative
+     glyphs — no forced-color-adjust:none). The error remains distinguishable by PRESENCE, not colour
+     alone (WCAG 1.4.1 — the text IS the cue; --md-sys-color-danger already degrades to CanvasText's fleet mapping
+     via the token layer, this rule documents the intent rather than overriding a colour that survives). */
+  @media (forced-colors: active) {
+    :scope [data-part='label'],
+    :scope [data-part='description'],
+    :scope [data-part='error'] {
+      color: CanvasText;
+    }
+  }
+}

package/dist/controls/field/field.d.ts

@@ -0,0 +1,27 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    label: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    description: import("../../index.js").PropConfig<string>;
+};
+export interface UIFieldElement extends ReactiveProps<typeof props> {
+}
+export declare class UIFieldElement extends UIElement {
+    #private;
+    static props: {
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        description: import("../../index.js").PropConfig<string>;
+    };
+    protected connected(): void;
+    protected disconnected(): void;
+}
+export {};