@agent-ui-kit/components 0.0.3

package/dist/controls/radio/radio-group.js

@@ -0,0 +1,350 @@
+// radio-group.ts — UIRadioGroupElement, the radio-group container (Wave 1 Indicator, S3).
+//
+// The CONTAINER owns everything the radio itself cannot own: single-selection exclusivity, roving-focus
+// keyboard navigation (Arrow/Home/End), the group form value (the selected radio's `value`), and the
+// required → valueMissing validity verdict. Extends UIFormElement DIRECTLY — NOT UIIndicatorElement; the
+// group itself is not an indicator, it is a form-value-owning container whose children are the indicators.
+//
+// ADR-0051 growth: the group wires its own `trackUserInvalid` controller + `formUserInvalid()` override
+// (the text-field precedent) — the group, not any individual radio, is the constraint owner, so the
+// user-invalid TIMING and the :state(user-invalid)/aria-invalid reflection live here. The group has no
+// visual surface of its own (radio-group.css); the CSS danger leg reaches into each `ui-radio` child's
+// own `::before` border. `UISegmentedControlElement` inherits this unchanged — it never overrides
+// `connected()`/`formReset()`, so the wiring applies to its own internals directly.
+//
+// ARIA: `role='radiogroup'` via internals (FACE — never a host attribute). Each `ui-radio` child carries
+// `role='radio'` via its own internals. The group provides no `tabindex` of its own; the rovingFocus trait
+// manages tabindexes on the radio children (exactly one is tabindex=0; others are -1), matching the ARIA
+// APG radio-group keyboard pattern.
+//
+// Selection model:
+//   · Arrow keys (Up/Down) + Home/End: move focus AND selection simultaneously (selection-follows-focus,
+//     the ARIA APG radio-group contract; ADR-0022 roving tier).
+//   · Click / Space: check the targeted radio → base toggle fires `change` → group's delegated change
+//     listener calls #commit() for exclusivity + form-value update.
+//   · #commit(index): the ONE user-driven commit path — checks radios[index], clears all others, updates
+//     #selectedValue, emits `change` on the group when the selection is new. Built on #applySelection,
+//     the shared (silent, non-emitting) selection-transition primitive it shares with the public `value`
+//     accessor below (a programmatic value write selects/clears without emitting `change` — the
+//     `UICheckboxElement.checked` / `UISelectElement.value` fleet convention for programmatic sets).
+//
+// Form value: #selectedValue (a signal) drives the UIFormElement effects for setFormValue + setValidity.
+// The signal is updated inside #applySelection, which every path (Arrow key via onMove, click via change
+// delegation, AND the public `value` setter) converges on. Reading this.#selectedValue.value inside
+// formValue() + formValidity() keeps the effects reactive — they re-publish to internals automatically
+// when the signal changes. The public `value` GETTER is the same signal read, exposed for external
+// callers (e.g. the A2UI catalog's two-way `value:{prop:'value',event:'change'}` bind).
+//
+// ADR-0095 (supersedes ADR-0086's `variant="segmented"`): the segmented presentation is now the standalone
+// `UISegmentedControlElement` (controls/segmented-control/), NOT a variant of this class. `variant` does not
+// exist here — the group is back to its dot-only presentation surface. ADR-0103: the group OWNS its interior
+// layout (radio-group.css's `@scope` flex column/row + `--ui-radio-group-gap`) — direct-children discovery
+// (`#radios()` below) means the layout cannot be left to page-author composition, unlike a coordination
+// wrapper. Two PROTECTED seams exist purely so that subclass can reuse this class's exclusivity/roving/value/
+// validity machinery without forking it:
+//   · `defaultOrientation()` — the class-derived roving-axis default (this base returns 'vertical'; the
+//     resolve-once-and-reflect-at-connect mechanism below calls it only when no explicit `orientation`
+//     attribute is authored). ADR-0095 clause 1.
+//   · `selectionChanged(radios, index)` — a no-op hook fired on every selection-defining event (connect
+//     seed, every `#applySelection`, and `formReset()`) — the SAME three call sites ADR-0086 wired its
+//     (now-retired) `#writeIndexCount` state seam to. `UISegmentedControlElement` overrides it to write its
+//     own `--ui-segmented-control-index`/`-count` moving-indicator state. ADR-0095 clause 2.
+//
+// Layer: controls/ — imports reactive + dom + traits + controls/radio (inward-only ✓).
+import { signal } from "../../reactive/index.js";
+import { UIFormElement } from "../../dom/form.js";
+import { prop } from "../../dom/props.js";
+import { rovingFocus } from "../../traits/roving-focus.js";
+import { trackUserInvalid } from "../../traits/track-user-invalid.js";
+import { UIRadioElement } from "./radio.js";
+const groupProps = {
+    // Universal form attributes (name / disabled / required) — spread so the group participates
+    // in forms as the single form value owner for the radio family (ADR-0013 formProps spread pattern).
+    ...UIFormElement.formProps,
+    // ADR-0086 clause 1 (orientation SURVIVES the ADR-0095 supersession — clause 1 there: "orientation stays
+    // on the group"). The roving axis. Default 'vertical' (today's shipped roving). The EFFECTIVE orientation
+    // (author-set vs the class-derived default, `defaultOrientation()` below) is resolved once at connect —
+    // see `connected()` below — and reflected back here so CSS and the roving trait read ONE source.
+    orientation: { ...prop.enum(['horizontal', 'vertical'], 'vertical'), reflect: true },
+};
+export class UIRadioGroupElement extends UIFormElement {
+    static props = groupProps;
+    // The committed selection — the group's form value. A signal so the UIFormElement base's scope-owned
+    // `formValue()` + `formValidity()` effects re-run (and re-publish to internals) when it changes.
+    // null = no radio selected; a string = the selected radio's `value` prop.
+    #selectedValue = signal(null);
+    // The user-invalid TIMING controller (ADR-0051), created per connection (re-arms on reconnect;
+    // released on disconnect) — the text-field/select precedent.
+    #userInvalid = null;
+    connected() {
+        // ARIA: radiogroup role via internals, never a host role/aria-* attribute (FACE).
+        this.internals.role = 'radiogroup';
+        // ADR-0051 — the user-invalid TIMING controller. `blur` never bubbles, but the capture phase
+        // reaches this ancestor before whichever `ui-radio` child held focus (the track-user-invalid.ts
+        // precedent); `change` is the group's OWN re-emitted event (#commit(), below) — not the child
+        // radio's original (that one is stopImmediatePropagation'd) — so this listener always sees the
+        // group's real commits regardless of listener registration order. Reflects :state(user-invalid)
+        // + internals.ariaInvalid — the group carries no visual surface of its own (radio-group.css); the
+        // CSS leg reaches into each ui-radio child's own ::before border.
+        const invalidController = trackUserInvalid(this, { invalid: () => !this.formValidity().valid });
+        this.#userInvalid = invalidController;
+        this.effect(() => {
+            if (invalidController.userInvalid()) {
+                this.internals.states?.add('user-invalid');
+                this.internals.ariaInvalid = 'true';
+            }
+            else {
+                this.internals.states?.delete('user-invalid');
+                this.internals.ariaInvalid = null;
+            }
+        });
+        // Well-known data attribute marker: lets UIRadioElement.grouped() detect any UIRadioGroupElement
+        // subclass (e.g. probe subclasses in tests) via a CSS attribute selector without a circular import.
+        this.dataset['radioGroup'] = '';
+        // Seed from any initially-checked radio (HTML-parsed content: radios connect before the group's
+        // connected() runs, so they are already present and may carry a `checked` attribute from markup).
+        const radios = this.#radios();
+        const initial = radios.find((r) => r.checked);
+        if (initial)
+            this.#selectedValue.value = initial.value;
+        // ADR-0095 clause 1 (was ADR-0086 clause 1, variant-derived) — resolve the EFFECTIVE orientation
+        // ONCE, here, BEFORE the rovingFocus call below. `rovingFocus` captures `orientation` as a static
+        // value at call time (roving-focus.ts:148 reads the closed-over param directly, not a callback like
+        // `items`/`syncIndex`), so resolving this AFTER the call would silently keep the trait on the
+        // default. Precedence: an author-set `orientation` attribute wins; otherwise `defaultOrientation()`
+        // supplies the CLASS-derived default (this base: `'vertical'`, today's shipped roving, unchanged;
+        // `UISegmentedControlElement` overrides it to `'horizontal'`). Reflecting the resolved value back to
+        // the host attribute gives CSS (`[orientation]`) and the roving trait one single source of truth.
+        const resolvedOrientation = this.hasAttribute('orientation')
+            ? this.orientation
+            : this.defaultOrientation();
+        this.orientation = resolvedOrientation;
+        // ADR-0095 clause 2 (was ADR-0086 clauses 2/3, `#writeIndexCount`) — the protected post-selection
+        // hook, seeded here at connect. A no-op in this base; `UISegmentedControlElement` overrides it to
+        // write its own moving-indicator state.
+        this.selectionChanged(radios, this.#checkedIndex());
+        // ── roving-focus (Arrow/Home/End: selection-follows-focus) ──────────────────────────────────
+        // The ARIA APG radio-group keyboard contract: Arrow keys move focus AND selection simultaneously.
+        // `initialIndex` seeds the roving cursor at the currently-checked radio (or first if none), so
+        // reconnect restores the correct tabindex=0 position. `syncIndex` re-reads the checked position
+        // before each keydown so a preceding click (processed via the change-delegation path below) is
+        // visible to the next Arrow move.
+        rovingFocus(this, {
+            items: () => this.#radios(),
+            orientation: resolvedOrientation,
+            loop: true,
+            typeAhead: false,
+            initialIndex: () => {
+                const i = this.#checkedIndex();
+                return i >= 0 ? i : 0; // default to first when nothing is checked
+            },
+            syncIndex: () => this.#checkedIndex(),
+            onMove: (index) => { if (!this.effectiveDisabled())
+                this.#commit(index); },
+        });
+        // ── delegated change listener (click / Space commit path) ───────────────────────────────────
+        // The base indicator emits `change` (bubbling) when it toggles unchecked → checked via a click or
+        // Space keyup. The group's capture guard in UIRadioElement.grouped() prevents the already-checked →
+        // unchecked direction from firing (stopImmediatePropagation before the base toggle), so only the
+        // relevant direction (unchecked → checked) bubbles here. This handler:
+        //   · Identifies the originating UIRadioElement inside this group.
+        //   · Stops the radio's change event from propagating further (the group re-emits its own).
+        //   · Calls #commit to enforce exclusivity and update the group's form value.
+        this.listen(this, 'change', (event) => {
+            if (this.effectiveDisabled()) {
+                // A disabled group swallows child change events entirely: stopImmediatePropagation prevents
+                // any other listener on this element (or ancestors) from seeing the radio's change (C7).
+                event.stopImmediatePropagation();
+                return;
+            }
+            const target = event.target;
+            if (!(target instanceof UIRadioElement))
+                return;
+            if (!this.contains(target))
+                return;
+            // Stop immediate propagation: prevent the radio's internal change event from reaching
+            // other listeners registered on the group (e.g. external consumers). The group re-emits
+            // its own semantic change event below via #commit, so external code sees exactly one change.
+            event.stopImmediatePropagation();
+            const index = this.#radios().indexOf(target);
+            if (index !== -1)
+                this.#commit(index);
+        });
+    }
+    // ── public value accessor ───────────────────────────────────────────────────────────────────────
+    /**
+     * The group's selected value — the checked `ui-radio` child's `value`, or `null` when none is
+     * selected. A public getter/setter pair delegating to the private `#selectedValue` signal (the
+     * `UICheckboxElement.indeterminate` precedent, checkbox.ts:39 — a plain accessor over a private
+     * signal, not a `prop.*`-declared attribute: the value is DERIVED from child radio state, so it
+     * has nothing of its own to reflect).
+     *
+     * The getter reads the signal directly — a reactive caller (e.g. inside `this.effect`) tracks it
+     * exactly like any other signal read.
+     *
+     * The setter is the PROGRAMMATIC path (e.g. a two-way data-bind write): it selects the child
+     * `ui-radio` whose `value` matches (unchecking all others) via `#applySelection` — the SAME state
+     * transition `#commit` drives for a user click/keyboard commit — but it does NOT emit `change`.
+     * This matches the fleet convention for a programmatic prop write on a value-bearing control
+     * (`UICheckboxElement.checked` / `UISelectElement.value` are directly settable and never
+     * self-emit on assignment; only the interaction-driven commit path — `#commit` here — emits).
+     *
+     * `null` clears the selection (unchecks every radio). A value matching NO child radio also CLEARS
+     * the selection, rather than a silent no-op — the native `HTMLSelectElement.value` precedent:
+     * assigning a `<select>`'s `.value` to a string with no matching `<option>` resolves
+     * `selectedIndex` to `-1` (the value reads back as `''`) instead of leaving the prior selection
+     * in place.
+     */
+    get value() {
+        return this.#selectedValue.value;
+    }
+    set value(v) {
+        const radios = this.#radios();
+        const index = v === null ? -1 : radios.findIndex((r) => r.value === v);
+        this.#applySelection(radios, index);
+    }
+    // ── private helpers ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Live ordered set of `UIRadioElement` children (direct children only; re-read on each call).
+     * Uses `instanceof UIRadioElement` so subclasses (e.g. probe subclasses in tests) are also found,
+     * rather than relying on the `ui-radio` tag name which would miss subclasses.
+     */
+    #radios() {
+        return [...this.children].filter((el) => el instanceof UIRadioElement);
+    }
+    /** Index of the currently checked radio (first match), or -1 when nothing is checked. */
+    #checkedIndex() {
+        return this.#radios().findIndex((r) => r.checked);
+    }
+    /**
+     * ADR-0095 clause 1 — the CLASS-derived default roving-axis orientation, consulted by `connected()`'s
+     * resolve-once-and-reflect ONLY when no explicit `orientation` attribute is authored. This base returns
+     * `'vertical'` (today's shipped roving, unchanged). `UISegmentedControlElement` overrides this to
+     * `'horizontal'` — the ADR-0086 "variant=segmented ⇒ horizontal" default, now class-derived instead of
+     * variant-derived.
+     */
+    defaultOrientation() {
+        return 'vertical';
+    }
+    /**
+     * ADR-0095 clause 2 — a protected, no-op-in-the-base post-selection hook, fired from every
+     * selection-DEFINING event: the connect-time seed, every `#applySelection` (both `#commit`'s user-driven
+     * path AND the public `value` setter's programmatic path), and `formReset()`. This is the SAME seam
+     * ADR-0086's (now-retired) private `#writeIndexCount` fired from — moved here, as a protected hook,
+     * so `UISegmentedControlElement` can write its own `--ui-segmented-control-index`/`-count` moving-
+     * indicator state WITHOUT this base class knowing anything about segments or indicators. A no-op here
+     * costs nothing for the plain dot-group presentation.
+     */
+    selectionChanged(_radios, _index) { }
+    /**
+     * The shared selection-transition path: checks `radios[index]`, unchecks all others (direct prop
+     * writes — no click events, no change events on siblings, avoids re-entrancy into the group's own
+     * change listener via the UIRadioElement guard), updates `#selectedValue`, and fires the
+     * `selectionChanged` hook. `index === -1` clears the selection (no radio checked, `#selectedValue` →
+     * `null`) — the public `value` setter's "no match" path. Does NOT emit `change`; that is exclusively
+     * `#commit`'s concern (the user-driven path) — this is the silent primitive both `#commit` and the
+     * public `value` setter build on. Returns whether the selection actually changed.
+     */
+    #applySelection(radios, index) {
+        const radio = index >= 0 ? radios[index] : undefined;
+        const newValue = radio ? radio.value : null;
+        const changed = newValue !== this.#selectedValue.value;
+        // Exclusivity: check the target (if any), uncheck all others (direct writes — no click, no re-entrancy).
+        radios.forEach((r, i) => {
+            r.checked = i === index;
+        });
+        // ADR-0095 clause 2 — fire the post-selection hook on every transition (both the Arrow-key/click/Space
+        // commit paths AND the public value setter converge here); a no-op in this base.
+        this.selectionChanged(radios, index);
+        if (changed)
+            this.#selectedValue.value = newValue;
+        return changed;
+    }
+    /**
+     * The ONE user-driven commit path — invoked from both the rovingFocus `onMove` callback (Arrow keys)
+     * and the delegated change listener (click/Space). Applies the transition via `#applySelection` and
+     * emits `change` on the group when the selection is new. An out-of-range `index` (no radio at that
+     * position) is a no-op — unlike the public `value` setter's "no match" path, this never clears an
+     * existing selection (there is no user gesture that should silently blank the group).
+     */
+    #commit(index) {
+        const radios = this.#radios();
+        if (!radios[index])
+            return;
+        if (this.#applySelection(radios, index))
+            this.emit('change');
+    }
+    // ── form hooks ──────────────────────────────────────────────────────────────────────────────────
+    /**
+     * The group's form value: the selected radio's `value`, or `null` when nothing is checked.
+     * Reads `#selectedValue.value` (a signal) so the UIFormElement base's scope-owned setFormValue
+     * effect re-runs automatically when selection changes.
+     */
+    formValue() {
+        return this.#selectedValue.value;
+    }
+    /**
+     * Validity: `required` + no selection → `valueMissing`. Reads `#selectedValue.value` so the
+     * UIFormElement base's setValidity effect re-runs when selection changes. An empty, required group
+     * stays invalid until a radio is committed; a non-required empty group is always valid.
+     */
+    formValidity() {
+        if (this.required && this.#selectedValue.value === null) {
+            return {
+                valid: false,
+                flags: { valueMissing: true },
+                message: 'Please select one of these options.',
+            };
+        }
+        return { valid: true };
+    }
+    /**
+     * Form reset — group-level coordination (bug-A fix). Each child radio is its OWN `UIFormElement`
+     * participant with its OWN `formResetCallback` (now fixed, indicator-element.ts) that silently restores
+     * ITS `checked` to ITS `defaultChecked` — but the GROUP owns a SEPARATE `#selectedValue` signal
+     * (`formValue()`/`formValidity()` above), which no radio's own reset can reach. Recompute it here from
+     * every child's `defaultChecked` (a stable, native-parity PUBLIC getter — see UIIndicatorElement) rather
+     * than each child's live `checked`: the platform resets the group and its radios as INDEPENDENT
+     * `UIFormElement`s, in an order this class must not assume (tree order suggests ancestor-first, i.e.
+     * this runs BEFORE the radios' own resets — reading live `checked` here would see PRE-reset values).
+     * `defaultChecked` sidesteps the ordering question entirely: it is a fixed snapshot from each radio's
+     * first connect, unaffected by reset order on either side. Silent — no `change` emitted (a reset is not
+     * a user commit; matches `#commit`'s own emit-on-user-action-only discipline).
+     *
+     * Bug fix (component-reviewer B4, blocking; ADR-0086, preserved verbatim by ADR-0095 clause 2): a reset
+     * must ALSO fire the post-selection hook (`selectionChanged`). The hook was previously (ADR-0086) a
+     * private `#writeIndexCount` written only at connect and in `#commit` — but a radio's own reset
+     * (`indicator-element.ts`) restores its `checked` OUTSIDE `#commit`, so without this the seam desyncs
+     * in a subclass that consumes it (e.g. `UISegmentedControlElement`'s moving indicator): the CSS
+     * `:not(:has(ui-radio[checked]))`-style gate correctly re-shows the indicator (the DOM `[checked]` is
+     * genuinely restored), but a STALE index would still park the moving fill on the pre-reset selection —
+     * a visible indicator/ink mismatch. Recomputed from `defaultChecked` for the same reset-order-
+     * independence reason as `#selectedValue` above (not live `checked`, which may not have reset yet on
+     * this radio's siblings). `findIndex` returns `-1` when no radio was ever default-checked; a consuming
+     * subclass's hook is expected to clamp that to `0` the same way ADR-0086's seam did — harmless, since a
+     * segmented indicator hides itself whenever nothing is `[checked]`.
+     */
+    formReset() {
+        const radios = this.#radios();
+        const defaultIndex = radios.findIndex((r) => r.defaultChecked);
+        const defaultRadio = defaultIndex >= 0 ? radios[defaultIndex] : undefined;
+        this.#selectedValue.value = defaultRadio ? defaultRadio.value : null;
+        this.selectionChanged(radios, defaultIndex);
+        // ADR-0051 — a reset must not leave a required-empty group showing :state(user-invalid) until
+        // the user re-interacts (the text-field formReset() precedent).
+        this.#userInvalid?.reset();
+    }
+    disconnected() {
+        this.#userInvalid?.release(); // idempotent — the listeners already die with the connection scope
+        this.#userInvalid = null;
+    }
+    /** Feeds `FormConnectDetail.userInvalid` (ADR-0050) — the `trackUserInvalid` tracker IS the one
+     *  timing source; this override just exposes its gate. Inherited by `UISegmentedControlElement`
+     *  unchanged (it never overrides connected()/formReset(), so this base's wiring applies to its
+     *  own internals directly). */
+    formUserInvalid() {
+        return this.#userInvalid?.userInvalid() ?? false;
+    }
+}
+if (!customElements.get('ui-radio-group'))
+    customElements.define('ui-radio-group', UIRadioGroupElement);

package/dist/controls/radio/radio.css

@@ -0,0 +1,219 @@
+/* radio.css — ui-radio, the radio-button indicator (Wave 1 S3, ADR-0042 / ADR-0041).
+ *
+ * Two SECTIONED blocks:
+ *   [1] TOKEN BLOCK  — `:where(ui-radio)` declares `--ui-radio-*` from the compact ramp + colour roles.
+ *       [size] repoints the box from the --md-sys-compact-{sm/md/lg} widget ramp (ADR-0041). No --md-sys-scale
+ *       multiplier: the compact ramp is an EXPLICIT per-[scale] lookup re-tabled in dimensions.css, so the
+ *       radio box tracks scale automatically (ADR-0038 pattern). [checked] reflects so the dot selector
+ *       works as a CSS attribute hook (the custom state :state(checked) is the browser-only alternative;
+ *       both selectors appear for coverage).
+ *   [2] STYLES BLOCK — `@scope (ui-radio)` consumes only `--ui-radio-*`.
+ *       Anatomy: the host is an inline-flex row; `::before` is the circular indicator box (border-radius
+ *       50%); `::after` is the checked DOT, a separate absolutely-positioned circle centred on `::before`
+ *       (switch/slider precedent: ring/track = `::before`, glyph/thumb = `::after`); the default slot
+ *       content flows after both as the optional label. Focus ring: `:focus-visible` on `:scope` (the
+ *       whole host), not only on the circle — standard fleet focus treatment (ADR-0009).
+ *       Forced-colors: the ring + dot survive via `ButtonText`/`Highlight`; the focus ring via
+ *       `--md-sys-color-focus-ring`.
+ *
+ * 2026-07-07 fix (Kim-filed visual bug): the checked ring AND dot both read `--ui-radio-ink` (the SAME
+ * primary blue) — the box-shadow-inset dot rendered as a solid blue disc indistinguishable from its own
+ * ring, unlike ui-switch's checked thumb (`--md-sys-color-primary-on-primary`, bright on a primary track).
+ * Fix: the checked ring FILLS solid primary (`background: var(--ui-radio-ink)`, matching the switch's
+ * filled-track pattern) and the NEW `::after` dot reads the bright `--md-sys-color-primary-on-primary` role —
+ * the switch's own high-contrast pair, verified 4.79:1 light / 3.32:1 dark against the primary fill
+ * (`tokens.test.ts`'s AA-selected block independently reproduces the light leg; both clear the SC 1.4.11
+ * 3:1 non-text bar). Radio's geometry (a single filled disc, no rail/page-surface straddle) has none of
+ * ui-slider's competing-backdrop constraint, so the switch's flat on-primary pair ports directly.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-radio) declares --ui-radio-* ════════════════ */
+
+:where(ui-radio) {
+  /* Box size from the widget ramp (ADR-0041). Default = md. */
+  --ui-radio-box: var(--md-sys-compact-md);
+
+  /* Dot geometry: the SAME 22%-inset law as before (unchanged diameter maths), now sizing a real
+     `::after` circle instead of an inset box-shadow annulus — the fix touches COLOUR, not proportion. */
+  --ui-radio-dot-inset: calc(var(--ui-radio-box) * 0.22);
+  --ui-radio-dot-size: calc(var(--ui-radio-box) - 2 * var(--ui-radio-dot-inset));
+
+  /* Border: idle ring colour. */
+  --ui-radio-border: var(--md-sys-color-neutral-on-surface-variant);
+
+  /* Ink: the checked ring + FILL repoint (matches ui-switch's filled-track pattern). */
+  --ui-radio-ink: var(--md-sys-color-primary);
+
+  /* Dot: the checked glyph — BRIGHT on-primary, the ui-switch checked-thumb role (2026-07-07 fix). Was
+     `--ui-radio-ink` reused (same blue as the ring/fill it sits on) — a same-hue dot never reads as a
+     distinct indicator. Clears SC 1.4.11 (3:1) against the primary fill: 4.79:1 light / 3.32:1 dark. */
+  --ui-radio-dot: var(--md-sys-color-primary-on-primary);
+
+  /* Gap: between the circle and the label slot (font/2, the anatomy gap law — density-bearing). */
+  --ui-radio-gap: var(--md-sys-gap-md);
+}
+
+/* [size] → compact ramp repoint (ADR-0041). Gap follows the font-size tier (density gap = font/2). */
+:where(ui-radio[size='sm']) {
+  --ui-radio-box: var(--md-sys-compact-sm);
+  --ui-radio-gap: var(--md-sys-gap-sm);
+}
+:where(ui-radio[size='lg']) {
+  --ui-radio-box: var(--md-sys-compact-lg);
+  --ui-radio-gap: var(--md-sys-gap-lg);
+}
+
+/* disabled → muted neutral roles. Holds at idle (pointer-inert below). Disabled is SC 1.4.11-EXEMPT
+   (ADR-0059 precedent: an inactive component doesn't need the checked ring/dot to stay distinguishable),
+   so ring, fill, AND dot collapse onto the SAME muted neutral — a flat disabled disc. */
+:where(ui-radio[disabled]) {
+  --ui-radio-border: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-radio-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-radio-dot: var(--md-sys-color-neutral-on-surface-variant);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-radio) consumes ONLY --ui-radio-* ════════════════ */
+
+@scope (ui-radio) {
+  /* Host: inline-flex row — circle (::before) + optional label slot side by side.
+     position: relative is the containing block for the absolutely-positioned ::after dot (switch/slider
+     precedent — the thumb/dot is centred on the ring via calc + translate, not flow layout). */
+  :scope {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ui-radio-gap);
+    position: relative;
+
+    /* Control-standard single-line line-height (ADR-0036): 1 keeps the text box = the font box. */
+    line-height: var(--md-sys-control-line-height);
+
+    cursor: pointer;
+    -webkit-user-select: none; /* WebKit/Safari: prefix needed */
+    user-select: none;
+  }
+
+  /* ── Circular indicator box ──────────────────────────────────────────────────────────────────── */
+
+  /* ::before = the circle. Sized to --ui-radio-box; circular via border-radius 50%; ring via border.
+     background: transparent at idle (the interior stays empty — just the 2px ring). */
+  :scope::before {
+    content: '';
+    display: block;
+    flex-shrink: 0; /* never crushed by label text */
+
+    inline-size: var(--ui-radio-box);
+    block-size: var(--ui-radio-box);
+    border-radius: 50%;
+
+    /* 2px border (same weight as the focus ring and --md-sys-widget-inset's 2px law; ADR-0041). */
+    border: 2px solid var(--ui-radio-border);
+    box-sizing: border-box;
+    background: transparent;
+  }
+
+  /* ── Checked: ring FILLS solid primary; the dot (::after) carries the bright glyph ─────────────── */
+
+  /* [checked] is the reflected attribute (boolean prop, reflect=true). :state(checked) is the
+     custom-state equivalent (absent in jsdom; browser-only). Both selectors ensure coverage.
+     The circle fills solid primary (ring border + interior both --ui-radio-ink) — the same "filled
+     track" treatment ui-switch gives its checked track; the ::after dot below is what reads as the
+     distinct indicator, not a same-hue box-shadow annulus (the 2026-07-07 fix). */
+  :scope:is([checked])::before,
+  :scope:state(checked)::before {
+    border-color: var(--ui-radio-ink);
+    background: var(--ui-radio-ink);
+  }
+
+  /* ── Dot (::after) — the bright checked glyph, centred on the ::before circle ────────────────────
+   * ::before is the FIRST flex item at the host's inline-start (align-items: center vertically centres
+   * it); its horizontal centre is therefore `--ui-radio-box / 2` from the host's inline-start. The dot
+   * is absolutely positioned at that point (inset-inline-start + inset-block-start: 50%) and pulled back
+   * by half its own size (translate(-50%, -50%)) so its CENTRE — not its corner — lands there. Sized to
+   * --ui-radio-dot-size (the same 22%-inset diameter maths the old box-shadow used). Transparent at idle
+   * (no dot); the bright --ui-radio-dot fill is repointed in on checked. */
+  :scope::after {
+    content: '';
+    position: absolute;
+    box-sizing: border-box;
+
+    inline-size: var(--ui-radio-dot-size);
+    block-size: var(--ui-radio-dot-size);
+    border-radius: 50%;
+
+    inset-block-start: 50%;
+    inset-inline-start: calc(var(--ui-radio-box) / 2);
+    transform: translate(-50%, -50%);
+
+    background: transparent;
+    transition: background-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+
+  :scope:is([checked])::after,
+  :scope:state(checked)::after {
+    background: var(--ui-radio-dot);
+  }
+
+  /* ── Interaction states ──────────────────────────────────────────────────────────────────────── */
+
+  /* hover: subtle border lift — repoint border to the ink colour (matches native <input type=radio>
+     hover treatment: the ring reinforces intent before click). No background change (no filled bg). */
+  :scope:hover::before {
+    border-color: var(--ui-radio-ink);
+  }
+
+  /* Focus ring (ADR-0009): fleet-wide shared `:focus-visible` outline on the HOST (covers the circle
+     AND the label text — standard for labelled controls). Not on ::before alone, so screen-reader
+     users see a full enclosing ring. layout-neutral (outline outside the box model). */
+  :scope: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);
+  }
+
+  /* Motion (interaction-states standard) — transition state-PAINT properties on ::before (the ring/fill)
+     and ::after (the dot, transition declared alongside its rule above). Geometry (box size) is never
+     transitioned. Unconditional — no :state(ready) gate (the base sets no such state). */
+  :scope::before {
+    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);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :scope::before,
+    :scope::after {
+      transition: none;
+    }
+  }
+
+  /* Disabled: pointer-inert + cursor reset (the reflected [disabled] attribute makes the host inert).
+     TKT-0047 — the redundant `opacity: 0.5` this rule carried is removed: the TOKEN block's own
+     `:where(ui-radio[disabled])` already repoints border/ink/dot to the muted neutral role, converging
+     on the fleet's dominant disabled mechanism (token-repoint, not opacity) — the doubled dimming was
+     never load-bearing, just an acknowledged v1 leftover. */
+  :scope:is([disabled]) {
+    pointer-events: none;
+    cursor: default;
+  }
+
+  /* ── Forced colors (WHCM) ────────────────────────────────────────────────────────────────────── */
+
+  @media (forced-colors: active) {
+    /* Ensure the idle ring is visible. */
+    :scope::before {
+      border-color: ButtonText;
+    }
+    /* Checked: ring + fill map to Highlight (matches the switch/slider checked-fill forced-colors
+       pattern); the dot (::after) maps to HighlightText — the system's own paired "on-fill" colour,
+       guaranteed distinct from Highlight by the platform (same pairing as the switch's checked thumb). */
+    :scope:is([checked])::before,
+    :scope:state(checked)::before {
+      forced-color-adjust: none;
+      border-color: Highlight;
+      background: Highlight;
+    }
+    :scope:is([checked])::after,
+    :scope:state(checked)::after {
+      forced-color-adjust: none;
+      background: HighlightText;
+    }
+  }
+}

package/dist/controls/radio/radio.d.ts

@@ -0,0 +1,19 @@
+import { UIIndicatorElement } from '../_base/indicator-element.js';
+export declare class UIRadioElement extends UIIndicatorElement {
+    /**
+     * LLD-C2: ARIA role for this leaf — `internals.role` is set by the UIIndicatorElement base
+     * from this declaration in `connected()`.
+     */
+    static role: string;
+    /**
+     * LLD-C5: group wiring hook — called from `connected()` after all base wiring is in place.
+     * When this radio is nested inside a `ui-radio-group`, registers a capture-phase click guard:
+     * if the radio is already checked, the click is stopped (via stopImmediatePropagation) before it
+     * reaches the base's bubble-phase toggle handler. This enforces the radio-button invariant that a
+     * selected radio cannot be deselected by clicking — only by selecting another radio in the group.
+     *
+     * Without a group parent, this is a no-op and the base toggle runs normally (full checkbox semantics:
+     * click toggles unchecked ↔ checked).
+     */
+    protected grouped(): void;
+}