@agent-ui-kit/components 0.0.3

package/dist/controls/text-field/text-field.css

@@ -0,0 +1,498 @@
+/* text-field.css — ui-text-field, the single-file component stylesheet (ADR-0003). Two clearly-SECTIONED
+ * blocks, mirroring button.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-text-field)` (specificity 0,0,0) DECLARES the `--ui-text-field-*` chain from
+ *       the colour roles (`--md-sys-color-{family}-{role}`; family = neutral) and the dimensional ramp
+ *       (`--ui-{height,font,gap}-{size}` from `@agent-ui-kit/shared/dimensions.css`). The state is Kim's
+ *       filled/container law (TKT-0062, superseding ADR-0014 cl.2c's border-only channel) — background,
+ *       border, AND text-ink all repoint together across five states (default/filled/hover/focus/disabled;
+ *       see the TOKEN block's own table comment for the exact role per state). The SOLID role ladder (NOT
+ *       soft-alpha — alpha outlines resolve sub-3:1 against the field surface, failing WCAG 1.4.11) is
+ *       declared as per-state `--ui-text-field-{bg,border,ink}[-filled|-hover|-focus]` tokens, each from a
+ *       ROLE (never a `color-mix`) — border is `transparent` in every state except `:hover` (the shared
+ *       `outline` ring is the sole focus indicator; a focus border-color step would double with the ring;
+ *       ADR-0014 dev#1). `user-invalid`'s danger border channel is UNCHANGED/orthogonal, layered on top.
+ *       `[size]` repoints the geometry ramp + INLINES `--ui-text-field-icon` the way button.css does (no
+ *       shared `--ui-ind` edit).
+ *   [2] STYLES BLOCK — `@scope (ui-text-field)` CONSUMES only `--ui-text-field-*` for its OWN tokens (the one
+ *       fleet exception: the shared focus-ring + motion constants, read DIRECTLY so every control draws the
+ *       identical ring / uses the identical timing). Geometry per references/geometry.md (the law — Control
+ *       class): `block-size` off the ramp, `padding-block: 0`, value edge `h/2`, slot edge `½(h − icon)`.
+ *       Anatomy per references/anatomy.md (ADR-0006/0012, host-as-grid): a presence-driven `:has()` grid with
+ *       OPTIONAL `[slot=leading]` / `[slot=trailing]` adornments — `order` places `[leading? | editor | trailing?]`
+ *       because the editor is a CONTROL-INJECTED part (`[data-part=editor]`, the centre value cell), not DOM-ordered.
+ *       The BORDER-ON-HOST field frame (border + radius on the host) so a slotted adornment sits INSIDE the box.
+ *       The filled/hover/focus state rules repoint the underlying `--ui-text-field-ink` TOKEN (not a
+ *       standalone `color:` on `:scope`) so the editor part's own `color: var(--ui-text-field-ink)` and the
+ *       placeholder's alias both re-resolve for free (a host-only `color:` override never reaches a child
+ *       with its own explicit declaration — a real bug this exact file hit and fixed). Focus (ADR-0014
+ *       dev#1) = the shared `outline` ring as the SOLE indicator, with the field border stepped to
+ *       `transparent` (NOT a `--md-sys-color-focus-ring` border-color step — that doubled with the ring into a visible
+ *       double border), BOTH on `:focus-within` (ALL focus — native text-input parity), NOT `:focus-visible`
+ *       (the focusable element is the editor child). The transparent border holds the box geometry (no layout
+ *       shift); the outline is also the FORCED-COLORS indicator (`border-color` is dropped by `forced-colors`;
+ *       the outline survives via `--md-sys-color-focus-ring → Highlight`). State PAINT motion gated behind `:state(ready)`, reduced-motion
+ *       zeroed. A forced-colors block keeps the border + ink + placeholder visible (CanvasText).
+ *
+ * Standalone stylesheet — linked via the host page / component-styles barrel (s12); NEVER injected from
+ * text-field.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-text-field) declares --ui-text-field-* ════════════════ */
+/* Wave 3 (ADR-0044): type-specific styles are in [2] @scope — password masking via -webkit-text-security
+   (a de-facto-standard property, universally supported despite the -webkit- prefix), search clear-button
+   visibility via :has([data-empty]), and forced-color-adjust:none on decorative adornment glyphs so the
+   magnifier/symbol/reveal survive forced-colors (they are aria-hidden decoration, not the text content). */
+
+:where(ui-text-field) {
+  /* Field-frame colour channel (family = neutral) — Kim's filled/container state law (TKT-0062),
+     SUPERSEDING the ADR-0014 cl.2c border-only channel: THREE channels now repoint per state
+     (background, border, text-ink), keyed off five states — default (empty, idle) / filled (has a
+     value, idle) / hover / focus / disabled. user-invalid is UNCHANGED — its own border-only danger
+     channel (below) layers on top of whichever bg/ink this table already picked; it never touches bg.
+       state    | bg              | border           | ink
+       default  | container-low   | transparent       | neutral
+       filled   | container       | transparent       | on-surface-variant
+       hover    | container       | outline-variant   | on-surface-variant
+       focus    | container-low   | transparent (ring)| on-surface
+       disabled | container-low   | transparent       | neutral-low
+     "filled" reads `[data-part='editor']:not([data-empty])` (the SAME emptiness signal the placeholder
+     ::before already keys off) — see @scope's `:has()` selector below. Declared here, consumed at the
+     matching pseudo-/state selector in @scope (so @scope reads only --ui-text-field-*, never a role). */
+  --ui-text-field-bg: var(--md-sys-color-neutral-container-low); /* default */
+  --ui-text-field-bg-filled: var(--md-sys-color-neutral-container);
+  --ui-text-field-bg-hover: var(--md-sys-color-neutral-container);
+  --ui-text-field-bg-focus: var(--md-sys-color-neutral-container-low);
+  --ui-text-field-border: transparent; /* default — the ring is the interactive indicator, not the border */
+  --ui-text-field-border-hover: var(--md-sys-color-neutral-outline-variant); /* :hover — the ONE visible-border state */
+  --ui-text-field-border-focus: transparent; /* :focus-within — TRANSPARENT: the shared outline ring is the SOLE focus indicator (a --md-sys-color-focus-ring border-color step doubled with the ring into a visible double border — a defect found on the live site; ADR-0014 dev#1). Transparent holds the box geometry (the 1px frame still occupies its track — no layout shift). */
+  --ui-text-field-border-invalid: var(--md-sys-color-danger); /* :state(user-invalid) — UNCHANGED, orthogonal to the table above */
+  --ui-text-field-border-invalid-hover: var(--md-sys-color-danger-high); /* user-invalid + :hover — UNCHANGED */
+  --ui-text-field-ink: var(--md-sys-color-neutral); /* default — empty, idle (== the placeholder ink, below) */
+  --ui-text-field-ink-filled: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-text-field-ink-hover: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-text-field-ink-focus: var(--md-sys-color-neutral-on-surface);
+  --ui-text-field-placeholder: var(--ui-text-field-ink); /* tracks the SAME default-state ink role (Kim's table has no separate placeholder row) — re-resolves live off whatever --ui-text-field-ink cascades to for this element, so the disabled repoint below reaches it for free */
+
+  /* Geometry — off the s6 dimensional ramp (default size = md). [size] repoints below. */
+  --ui-text-field-height: var(--md-sys-height-md);
+  --ui-text-field-font: var(--md-sys-font-md);
+  --ui-text-field-gap: var(--md-sys-gap-md); /* the one density-bearing quantity (slot↔editor column-gap) */
+  --ui-text-field-icon: var(--md-sys-icon-md); /* §1-SET icon per [scale]-tier (ADR-0038 / ADR-0035 conformance gap); repoints with [scale] from dimensions.css — was calc(18px * var(--md-sys-scale)) */
+
+  /* Size-INVARIANT frame quantities — declared ONCE in the base block (NOT in the per-[size] blocks below): */
+  --ui-text-field-radius: var(--md-sys-shape-corner-base); /* fixed --md-sys-shape-corner-base rounded-rect — the container-fleet referent an ENTRY control takes (NOT the action family's h/2 pill); overridable per-field; ADR-0015 cl.5 / #71 amendment. */
+  --ui-text-field-min-inline-size: 20ch; /* the host typing-width floor (entry-control frame-law leg, ADR-0021) — ch is font-relative so one ~20ch already scales with --ui-text-field-font across [size]; native <input size> parity so a bare field is hittable (width above the floor is the layout's job). */
+
+  /* Visible inline-validation message tokens (ADR-0029 A1 — extends ADR-0014): the .ui-text-field-message
+     node (control-managed, aria-describedby target) becomes VISIBLE when non-empty under :state(user-invalid).
+     Declared here (specificity 0, overridable), consumed in the @scope block. */
+  --ui-text-field-message-font: var(--md-sys-font-sm); /* small type — subordinate to the field's own label/value */
+  --ui-text-field-message-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, so the TEXT ink moves; the danger BORDER channel above (--ui-text-field-border-invalid) stays --md-sys-color-danger (border = 3:1 UI bar). ADR-0014 cl.2c · 2026-07-02 color audit item 1. */
+}
+
+/* size → dimensional ramp (size is reflected, so the attribute is present) */
+:where(ui-text-field[size='sm']) {
+  --ui-text-field-height: var(--md-sys-height-sm);
+  --ui-text-field-font: var(--md-sys-font-sm);
+  --ui-text-field-gap: var(--md-sys-gap-sm);
+  --ui-text-field-icon: var(--md-sys-icon-sm); /* §1-SET icon per [scale]-tier (ADR-0038) */
+}
+:where(ui-text-field[size='lg']) {
+  --ui-text-field-height: var(--md-sys-height-lg);
+  --ui-text-field-font: var(--md-sys-font-lg);
+  --ui-text-field-gap: var(--md-sys-gap-lg);
+  --ui-text-field-icon: var(--md-sys-icon-lg); /* §1-SET icon per [scale]-tier (ADR-0038) */
+}
+
+/* disabled → a role-REPOINT (NOT opacity, tokens.md canon; TKT-0062's disabled row). Matches BOTH the
+   own/reflected [disabled] AND the effective :state(disabled) (own || form-disabled — ADR-0013/0014
+   cl.2b). Declared LAST so it wins the specificity-0 cascade for the BASE `--ui-text-field-{bg,border,
+   ink}` tokens the unconditional `:scope` rule reads. Only the base trio needs repointing — @scope's
+   `filled`/`hover` selectors are explicitly guarded with `:not(:is([disabled], :state(disabled)))` (a
+   genuinely new hazard the old border-only law never had: "filled" is a content-based `:has()` selector,
+   not an interaction pseudo-class, so it WOULD still match a disabled-but-non-empty field without that
+   guard — unlike `:hover`/`:focus-within`, which a pointer-inert, non-focusable disabled host can never
+   really trigger). user-invalid cannot co-occur (a disabled field does not willValidate — text-field.ts
+   gates it), so the danger border is left untouched. */
+:where(ui-text-field:is([disabled], :state(disabled))) {
+  --ui-text-field-bg: var(--md-sys-color-neutral-container-low);
+  --ui-text-field-border: transparent;
+  --ui-text-field-ink: var(--md-sys-color-neutral-low);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-text-field) consumes ONLY --ui-text-field-* ════════════════ */
+
+@scope (ui-text-field) {
+  :scope {
+    display: inline-grid;
+    grid-template-columns: 1fr; /* bare editor — slotless */
+    align-items: center;
+    box-sizing: border-box;
+
+    block-size: var(--ui-text-field-height); /* the vertical lever — geometry.md (Control class) */
+    /* the host typing-width floor (the entry-control leg of the frame-law min-inline-size, ADR-0021 — the sibling
+       of button's action-control square floor) so a BARE, unsized field is hittable instead of collapsing its 1fr
+       editor cell to a ~0-width typing target (the box keeps only its ~30px padding+border chrome). Width ABOVE the floor stays the layout's / author's job (a flex/grid
+       track or an explicit inline-size grows it; --ui-text-field-min-inline-size is the per-field / theme override).
+       COMPLEMENTARY to the editor cell's `min-inline-size: 0` below: that lets long text scroll WITHIN the field,
+       this holds the box open. */
+    min-inline-size: var(--ui-text-field-min-inline-size);
+    padding-block: 0; /* NEVER block-padding */
+    padding-inline: calc(var(--ui-text-field-height) / 2); /* slotless value edge = h/2 */
+
+    font-size: var(--ui-text-field-font);
+    background: var(--ui-text-field-bg);
+    color: var(--ui-text-field-ink);
+
+    /* the BORDER-ON-HOST field frame (§5): border + radius on the host, so a slotted adornment sits INSIDE the
+       box. The radius is the fixed --md-sys-shape-corner-base rounded-rect — the SAME referent the container fleet (card /
+       modal) uses, because a field is an entry SURFACE kin to a container, NOT the action/keyboard family's
+       press-affordance h/2 pill (ADR-0015 cl.5 / the #71 amendment; geometry.md "Corner radius"). It reads the
+       component --ui-text-field-radius token (role-purity + per-field override). The browser clamps border-radius
+       to ≤ h/2, so a very dense/short field degrades gracefully to the pill — never overflows. */
+    border: 1px solid var(--ui-text-field-border);
+    border-radius: var(--ui-text-field-radius);
+    cursor: text;
+  }
+
+  /* Anatomy (references/anatomy.md — ADR-0006 extended by ADR-0012): host-as-grid with three POSITION regions —
+     an OPTIONAL leading [slot=leading] adornment, the EDITOR (the control-injected centre value cell, the
+     accessible textbox), and an OPTIONAL trailing [slot=trailing] adornment — each presence-driven via :has().
+     Because the editor is control-INJECTED (appended in connected(), so NOT reliably between the user-slotted
+     adornments in DOM order), placement is by `order`, not source order:
+       [leading?] order 0 · [editor] order 1 · [trailing?] order 2. */
+  :scope > [slot='leading'] {
+    order: 0;
+  }
+  :scope > [data-part='editor'] {
+    order: 1;
+    font-size: var(--ui-text-field-font);
+    line-height: var(--md-sys-control-line-height); /* single-line control standard — ADR-0036; explicit here because the editor re-declares font-size (the host `:scope` inherits, but the explict editor decl makes the contract visible at both sites) */
+    color: var(--ui-text-field-ink);
+    min-inline-size: 0; /* let the 1fr cell shrink so the editor scrolls (overflow) instead of widening the grid */
+    white-space: nowrap; /* single-line */
+    overflow: hidden; /* clip the overflow; the editor self-scrolls to keep the caret in view */
+    outline: none; /* the focus ring is on the HOST frame, never the editor child */
+  }
+  :scope > [slot='trailing'] {
+    order: 2;
+  }
+
+  /* the placeholder — a control-toggled `data-empty` attr keys generated content carrying the `data-placeholder`
+     prop (NOT `:empty` — a cleared contenteditable can carry a bogus trailing <br>; ADR-0014 consequences).
+     `pointer-events: none` + generated content ⇒ it never participates in the editable text or the caret. */
+  :scope > [data-part='editor'][data-empty]::before {
+    content: attr(data-placeholder);
+    color: var(--ui-text-field-placeholder);
+    pointer-events: none;
+  }
+
+  /* The adornment CELL — both slots get the SAME square, icon-sized cell (border-box), so the grid column is
+     icon-wide and the per-edge centering pad (½(h − icon)) holds whichever adornment sits in it. Glyph SIZING
+     (icon fills / caret = font) is the role axis — out of G6 scope here (the minimal field is editor + value +
+     validity); a leading content-icon (the active role) fills its icon-sized cell. */
+  :scope > [slot='leading'],
+  :scope > [slot='trailing'] {
+    inline-size: var(--ui-text-field-icon);
+    block-size: var(--ui-text-field-icon); /* the square slot, icon-sized — the CELL */
+    box-sizing: border-box;
+  }
+
+  /* [leading | editor] (no trailing): auto 1fr — leading slot edge ½(h−icon), trailing value edge h/2 */
+  :scope:has(> [slot='leading']):not(:has(> [slot='trailing'])) {
+    grid-template-columns: auto 1fr;
+    column-gap: var(--ui-text-field-gap);
+    padding-inline-start: calc((var(--ui-text-field-height) - var(--ui-text-field-icon)) / 2);
+    padding-inline-end: calc(var(--ui-text-field-height) / 2);
+  }
+
+  /* [editor | trailing] (no leading): 1fr auto — leading value edge h/2, trailing slot edge ½(h−icon) */
+  :scope:has(> [slot='trailing']):not(:has(> [slot='leading'])) {
+    grid-template-columns: 1fr auto;
+    column-gap: var(--ui-text-field-gap);
+    padding-inline-start: calc(var(--ui-text-field-height) / 2);
+    padding-inline-end: calc((var(--ui-text-field-height) - var(--ui-text-field-icon)) / 2);
+  }
+
+  /* [leading | editor | trailing]: auto 1fr auto — both adornment edges ½(h−icon), one gap rhythm on each side */
+  :scope:has(> [slot='leading']):has(> [slot='trailing']) {
+    grid-template-columns: auto 1fr auto;
+    column-gap: var(--ui-text-field-gap);
+    padding-inline-start: calc((var(--ui-text-field-height) - var(--ui-text-field-icon)) / 2);
+    padding-inline-end: calc((var(--ui-text-field-height) - var(--ui-text-field-icon)) / 2);
+  }
+
+  /* The filled/container state ladder (TKT-0062, Kim's ruling — supersedes the ADR-0014 cl.2c
+     border-only channel) — repoints `background`/`border-color`/`color` together from the per-state
+     tokens declared in the :where() block (the geometry law is untouched). "filled" = the editor
+     carries a value (`:not([data-empty])`, the SAME emptiness signal the placeholder ::before already
+     keys off) — a CONTENT-based selector, not an interaction pseudo-class, so unlike :hover/
+     :focus-within it WOULD still match a disabled-but-non-empty field.
+
+     Precedence is enforced by MUTUAL EXCLUSION (`:not()`), not source-order/specificity: `:has()`/
+     `:not()` combinators contribute REAL specificity in a plain (non-:where()) selector — unlike the
+     old border-only law's bare single-pseudo-class rules, source order alone can no longer be trusted
+     to pick a winner (a `:not(:is(disabled))`-guarded `:hover` was measured to OUTRANK an unguarded
+     `:focus-within` by specificity, so clicking to focus — which also leaves the pointer hovering —
+     kept the hover border instead of stepping transparent; a live regression this exact history was
+     caught fixing). Making each rule EXPLICITLY exclude every state that should outrank it removes the
+     ambiguity regardless of computed specificity: filled excludes hover/focus/disabled; hover excludes
+     focus/disabled; focus is checked last and excludes nothing (a disabled field is never focusable, so
+     no guard is needed there, matching the old law). user-invalid's border-only override still layers
+     on top of whichever bg/ink row above resolved, untouched. */
+  /* NOTE (code-reviewer HIGH finding, fixed): repointing the --ui-text-field-ink TOKEN itself here,
+     NOT a direct `color:` declaration on `:scope` — the editor part carries its OWN color declaration
+     reading that same token (text-field.css's anatomy block), which reads the token directly, not the
+     host's computed `color` (an element's own declared `color` always wins over inherited value, so a
+     host-only `color:` override never reached the visible typed text or the placeholder — proven red
+     in a real browser gate, both engines, before this fix). Repointing the TOKEN cascades to every
+     consumer (the base :scope rule's own color read, the editor's own, AND the placeholder token's
+     alias onto it) for free — the same mechanism the disabled `:where()` block below already used
+     correctly. */
+  :scope:not(:hover):not(:focus-within):not(:is([disabled], :state(disabled))):has(> [data-part='editor']:not([data-empty])) {
+    background: var(--ui-text-field-bg-filled);
+    --ui-text-field-ink: var(--ui-text-field-ink-filled);
+  }
+  :scope:not(:focus-within):not(:is([disabled], :state(disabled))):hover {
+    background: var(--ui-text-field-bg-hover);
+    border-color: var(--ui-text-field-border-hover);
+    --ui-text-field-ink: var(--ui-text-field-ink-hover);
+  }
+
+  /* Focus (ADR-0014 dev#1) = the shared `outline` ring as the SOLE interactive-frame indicator, with the
+     field border stepped to TRANSPARENT (the --ui-text-field-border-focus token), BOTH on :focus-within
+     (ALL focus — a text field must visibly signal where typing lands, including on a mouse click), NOT
+     :focus-visible. A `--md-sys-color-focus-ring` border-color step here doubled with the ring into a
+     visible DOUBLE border (a defect found on the live site); transparent makes the ring the lone focus
+     indicator AND preserves the box geometry (no layout shift — the 1px border still occupies its
+     track). :focus-within (not :focus-visible on the editor) is used because the focusable element is
+     the editor child; the ring is drawn on the host frame off the focused editor. The OUTLINE is the
+     load-bearing FORCED-COLORS indicator — `border-color` does NOT survive `forced-colors: active`, the
+     `outline` does (via --md-sys-color-focus-ring → Highlight) — so the ring is the focus indicator
+     there too. The outline reads the SHARED fleet tokens DIRECTLY (the one --ui-text-field-* exception,
+     same as button) so every control draws the identical ring; outline/outline-offset do not
+     participate in box geometry. Focus's bg/ink (TKT-0062) override filled/hover unconditionally — a
+     focused-and-filled field still shows the FOCUS row (container-low bg, on-surface ink), not filled's. */
+  :scope:focus-within {
+    background: var(--ui-text-field-bg-focus);
+    border-color: var(--ui-text-field-border-focus);
+    --ui-text-field-ink: var(--ui-text-field-ink-focus);
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset);
+  }
+
+  /* user-invalid (the danger border) — appears only AFTER the first interaction; the trackUserInvalid
+     controller (G4) owns that timing and text-field.ts toggles the :state(user-invalid) custom state. */
+  :scope:state(user-invalid) {
+    border-color: var(--ui-text-field-border-invalid);
+  }
+  :scope:state(user-invalid):hover {
+    border-color: var(--ui-text-field-border-invalid-hover);
+  }
+
+  /* Visible inline-validation message (ADR-0029 A1 — extends ADR-0014). The control-managed
+     `.ui-text-field-message` node (the aria-describedby target, ADR-0014 cl.4) is `hidden` by default
+     (out of flow) and has no base display rule. When :state(user-invalid) is active AND the node carries
+     a message text (text-field.ts toggles `hidden` false only when non-empty), it becomes visible:
+     danger ink, small type — subordinate to the field, consistent with the danger border. Gated by
+     :state(user-invalid) to keep the ADR-0014 interaction-state timing (only after first blur/change).
+     `ui-field` (G7), when it lands, will relayout/host this node rather than re-introduce it. */
+  :scope:state(user-invalid) > .ui-text-field-message {
+    display: block;
+    font-size: var(--ui-text-field-message-font);
+    color: var(--ui-text-field-message-ink);
+  }
+
+  /* disabled host — pointer-inert (matches BOTH own [disabled] and the effective :state(disabled), so a
+     fieldset-disabled field is inert too); makes :hover / :focus-within never match, holding the muted frame
+     repointed in the :where() block. The editor's non-focusability + the role repoint do the rest (text-field.ts). */
+  :scope:is([disabled], :state(disabled)) {
+    pointer-events: none;
+    cursor: default;
+  }
+
+  /* Motion (ADR-0008 / interaction-states standard) — transition the state-PAINT properties ONLY
+     (border/background/colour), enumerated (never `transition: all`). Geometry is NEVER transitioned (a
+     [scale]/[size]/[density] change must SNAP — animating the ramp fights the sizing law), and the focus ring
+     stays instant (outline omitted). Gated behind the :state(ready) custom state, set in text-field.ts one frame
+     past first paint, so the upgrade/first paint snaps and only SUBSEQUENT state changes animate. */
+  :scope:state(ready) {
+    transition:
+      border-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard),
+      background-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard),
+      color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :scope:state(ready) {
+      transition: none; /* accessibility (non-negotiable) — reduced motion zeroes the state transitions */
+    }
+  }
+
+  /* ── Wave 3 type-specific styles (ADR-0044) ─────────────────────────────────────────────────────── */
+
+  /* password masking (ADR-0044): -webkit-text-security is a de-facto-standard property (Chrome/Safari/Firefox)
+     that renders the editable text as bullet discs while the real value stays in textContent. The :state(revealed)
+     custom state (toggled by the reveal button in text-field.ts) flips it to none so the user can see their
+     password. The contenteditable editor carries the masking — the host NEVER carries a type attribute (it is the
+     class host, not a native input), so we scope on :scope[type='password'] (the reflected type prop attribute). */
+  :scope[type='password'] > [data-part='editor'] {
+    -webkit-text-security: disc; /* the password mask — discs hide the typed characters visually */
+  }
+  :scope[type='password']:state(revealed) > [data-part='editor'] {
+    -webkit-text-security: none; /* reveal toggle: show raw text */
+  }
+
+  /* search: the clear button (data-role='clear') is hidden when the field is empty — keyed off the
+     [data-empty] attribute on the editor PART (toggled by the model→surface effect in text-field.ts).
+     :has() reaches the editor sibling to check emptiness. When non-empty, the button is visible so the
+     user can clear the search field with one click. */
+  :scope:has(> [data-part='editor'][data-empty]) [data-role='clear'] {
+    display: none; /* empty field: hide the clear affordance */
+  }
+
+  /* adornment button baseline: no default browser button chrome, inherit the field's font/color, sized to
+     the slot cell (the [slot='leading']/[slot='trailing'] CSS above sizes the cell to --ui-text-field-icon;
+     the button fills it). Interactive affordances (clear / reveal / steppers / calendar) use data-part names;
+     they share the same reset so they render chrome-free and glyph-sized out of the box. */
+  :scope [data-part='clear-button'],
+  :scope [data-part='reveal-button'],
+  :scope [data-part='step-up'],
+  :scope [data-part='step-down'],
+  :scope [data-part='calendar-button'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border: none;
+    background: none;
+    padding: 0;
+    cursor: pointer;
+    font: inherit; /* inherit the field font — the glyph is font-sized */
+    color: inherit;
+    line-height: 1;
+  }
+
+  /* stepper container: stacks the two step buttons vertically in the trailing icon-sized cell.
+     Used for type=number and type=currency (no suffix — just the caret-up/caret-down steppers
+     stacked in the icon square). */
+  :scope [data-role='stepper'] {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--ui-text-field-icon);
+    block-size: var(--ui-text-field-icon);
+  }
+  :scope [data-part='step-up'],
+  :scope [data-part='step-down'] {
+    block-size: 50%; /* each stepper takes half the icon cell height */
+    inline-size: 100%;
+  }
+
+  /* Wave 5A (ADR-0047): numeric trailing cell — suffix span + steppers in a flex ROW.
+     Used for type=unit (localized label) and type=percent (%).
+     inline-size is auto (wider than the icon square); block-size stays icon-sized for vertical centering. */
+  :scope [data-role='numeric'] {
+    display: inline-flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: flex-end;
+    inline-size: auto;
+    block-size: var(--ui-text-field-icon);
+    gap: 0;
+  }
+  /* Override the slot's fixed icon inline-size for numeric cells (they carry suffix + steppers). */
+  :scope > [slot='trailing'][data-role='numeric'] {
+    inline-size: auto;
+  }
+  /* Numeric steppers inside a numeric cell: each is font-sized and shares the row (no 50%-block override). */
+  :scope [data-role='numeric'] [data-part='step-up'],
+  :scope [data-role='numeric'] [data-part='step-down'] {
+    block-size: auto;
+    inline-size: auto;
+    line-height: 1;
+  }
+
+  /* Wave 5B (ADR-0048): calendar popup wrapper (type=date). The `[data-part='calendar-popup']` div is
+     the `[popover]` element that hosts the `<ui-calendar>`. Strip UA popover defaults (padding / border /
+     background) so the calendar's own `[data-box]` panel owns all spacing and appearance — the wrapper
+     is a transparent host for the top-layer popup; it contributes no visual chrome of its own. */
+  :scope > [popover][data-part='calendar-popup'] {
+    padding: 0;
+    border: 0;
+    background: transparent;
+    margin: 0;
+  }
+
+  /* suffix span: the trailing unit label ('kg') or percent sign ('%) — sized = font (§4.6 inline
+     affordance law), decorative (aria-hidden). Subdued ink (the placeholder role) so it reads as
+     a unit annotation, not competing with the editor value. */
+  :scope [data-part='suffix'] {
+    font-size: var(--ui-text-field-font);
+    line-height: 1;
+    user-select: none;
+    color: var(--ui-text-field-placeholder);
+  }
+
+  /* leading/trailing adornment content (magnifier icon, currency symbol text): font-sized, centered.
+     The cell is icon-sized (--ui-text-field-icon from the slot rule above); the glyph fits within it. */
+  :scope [data-part='leading-adornment'],
+  :scope [data-part='trailing-adornment'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-size: var(--ui-text-field-font); /* the glyph is sized = font (§4.6 law) */
+    line-height: 1;
+    user-select: none;
+  }
+
+  /* Injected Phosphor glyphs (setIcon, @agent-ui-kit/icons): magnifier · x (clear) · eye/eye-slash (reveal) ·
+     calendar-blank · caret-up/caret-down (steppers). 1em tracks each part's own font-size — inherited
+     (--ui-text-field-font) on the buttons, explicit on [data-part='leading-adornment'] above — at every
+     [size] tier, matching the previous inline-text glyphs' rendered size exactly. Overrides the svg's own
+     width/height="100%" presentational attributes (resolve.ts); [data-part='suffix'] carries NO icon (a
+     text label — kg / %), so it is deliberately absent from this selector list. */
+  :scope [data-part='clear-button'] svg,
+  :scope [data-part='reveal-button'] svg,
+  :scope [data-part='step-up'] svg,
+  :scope [data-part='step-down'] svg,
+  :scope [data-part='calendar-button'] svg,
+  :scope [data-part='leading-adornment'] svg {
+    display: block;
+    inline-size: 1em;
+    block-size: 1em;
+  }
+
+  /* forced-colors — keep the field border + ink + placeholder VISIBLE (they must not vanish). The focus ring
+     survives for free: `--md-sys-color-focus-ring` carries the token layer's `→ Highlight` WHCM mapping, so the
+     :focus-within outline above resolves to the system focus colour with no per-control rule (border-color is
+     dropped by forced-colors — which is WHY deviation #1 makes the OUTLINE the sole focus indicator: the
+     transparent focus border carries nothing, the ring carries it). A disabled field reads GrayText (the system
+     disabled colour). The decorative adornment glyphs (magnifier / currency symbol / reveal eye / steppers) are
+     aria-hidden and use forced-color-adjust:none so they keep their inherited ink in forced-colors mode — they
+     are VISUAL cues, not the accessible text content (which lives in the editor). */
+  @media (forced-colors: active) {
+    :scope {
+      border-color: CanvasText;
+      color: CanvasText;
+    }
+    :scope > [data-part='editor'][data-empty]::before {
+      color: CanvasText; /* the placeholder stays visible */
+    }
+    :scope:is([disabled], :state(disabled)) {
+      border-color: GrayText;
+      color: GrayText;
+    }
+    /* adornment glyphs: keep their ink (they are decorative, aria-hidden — not a text content channel) */
+    :scope [data-part='leading-adornment'],
+    :scope [data-part='trailing-adornment'],
+    :scope [data-part='suffix'],
+    :scope [data-part='clear-button'],
+    :scope [data-part='reveal-button'],
+    :scope [data-part='step-up'],
+    :scope [data-part='step-down'],
+    :scope [data-part='calendar-button'] {
+      forced-color-adjust: none; /* the magnifier / symbol / reveal / suffix / steppers / calendar glyph survive */
+    }
+  }
+}