@agent-ui-kit/components 0.0.3

package/dist/controls/avatar/avatar.css

@@ -0,0 +1,87 @@
+/* avatar.css — ui-avatar, the Indicator-class compact identity mark (LLD-C3, feed-family.lld.md §3;
+ * SPEC-R4/R5/R6/R7/R19/R20; ADR-0112 cl.3, fork F3). Two sectioned blocks:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-avatar)` declares `--ui-avatar-*`: the widget box off the widget-box
+ *       ramp `--md-sys-compact-{sm,md,lg}` (ADR-0041 — fork F3, no new register minted; `[size]` repoints the
+ *       tier, `[scale]` on an ancestor re-tables the ramp for free, no avatar-local [scale] rule needed)
+ *       and ONE neutral plane + on-surface ink pair (SPEC-R7 — no per-identity hue).
+ *   [2] STYLES BLOCK — `@scope (ui-avatar)` consumes ONLY `--ui-avatar-*`. The host is a circle-masked
+ *       widget box (`inline-grid`, `place-items: center`, `border-radius: 50%`); exactly one child paints
+ *       at a time (avatar.ts) — an `<img>` (object-fit: cover), the `[data-part=initials]` text, or a
+ *       `<ui-icon>` glyph, each sized off the box.
+ *
+ * No hue anywhere (SPEC-R7 AC1): the fallback plane/ink pair is identical for every `name` — a
+ * computed-style equality probe, not a visual comparison. Identity is carried by the initials/name text,
+ * never by color (ADR-0057).
+ *
+ * Forced colors (SPEC-R19): a background-drawn circle plane can visually merge with the page under WHCM
+ * — an explicit `forced-colors` block adds a system-ink border so the circle boundary stays visible (the
+ * badge/checkbox box-boundary precedent); initials are real text and survive untouched.
+ *
+ * No interaction states (SPEC-R4 — non-interactive, no focus/hover/active, no post-connect motion gate:
+ * there is nothing to transition). Standalone stylesheet — linked via the host page / component-styles
+ * barrel; NEVER injected from avatar.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-avatar) declares --ui-avatar-* ════════════════ */
+
+:where(ui-avatar) {
+  /* Widget-box size (ADR-0041 fork F3) — defaults to the compact-realm `md` tier; a page override for
+     larger chrome (a profile header) is the token's job, not a new fleet register (F3's named trigger). */
+  --ui-avatar-size: var(--md-sys-compact-md);
+
+  /* ONE neutral pair (SPEC-R7) — AA-verifiable once; every `name` computes the identical plane/ink. */
+  --ui-avatar-plane: var(--md-sys-color-neutral-surface-high);
+  --ui-avatar-ink: var(--md-sys-color-neutral-on-surface);
+}
+
+/* [size] → widget-box tier (the checkbox/badge precedent: sm/lg repoint, md is the base default above). */
+:where(ui-avatar[size='sm']) {
+  --ui-avatar-size: var(--md-sys-compact-sm);
+}
+:where(ui-avatar[size='lg']) {
+  --ui-avatar-size: var(--md-sys-compact-lg);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-avatar) consumes ONLY --ui-avatar-* ════════════════ */
+
+@scope (ui-avatar) {
+  :scope {
+    display: inline-grid;
+    place-items: center;
+    overflow: hidden;
+    border-radius: 50%; /* the circle mask (SPEC-R7) */
+    inline-size: var(--ui-avatar-size);
+    block-size: var(--ui-avatar-size);
+    background: var(--ui-avatar-plane);
+    color: var(--ui-avatar-ink);
+    vertical-align: middle; /* an inline-grid box sitting beside text (SPEC-R6's "beside a name" case) */
+  }
+
+  :scope img {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+    display: block;
+  }
+
+  :scope [data-part='initials'] {
+    font-size: calc(var(--ui-avatar-size) * 0.42);
+    font-weight: var(--md-sys-typescale-label-medium-weight);
+    line-height: 1; /* single-line, centers like a glyph (geometry.md's control line-height law) */
+    user-select: none;
+    text-transform: uppercase;
+    letter-spacing: 0.02em;
+  }
+
+  :scope ui-icon {
+    /* the content-icon register (geometry.md taxonomy) — the glyph derives from the box, not the font */
+    font-size: calc(var(--ui-avatar-size) * 0.6);
+  }
+
+  @media (forced-colors: active) {
+    :scope {
+      border: 1px solid CanvasText; /* the circle boundary stays visible under WHCM (SPEC-R19) */
+    }
+  }
+}

package/dist/controls/avatar/avatar.d.ts

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

package/dist/controls/avatar/avatar.js

@@ -0,0 +1,77 @@
+// avatar.ts — UIAvatarElement, the Indicator-class compact identity mark (LLD-C3, feed-family.lld.md §3;
+// SPEC-R4…R7; ADR-0112 cl.3). Non-interactive, non-form-associated leaf: no events, no keyboard contract,
+// no focus. The fallback chain (SPEC-R5) never renders a broken-image box and never renders empty —
+// exactly one of `src` image / initials / person glyph paints at a time.
+//
+// ONE render effect (reads src/identity/#failedSrc) walks the chain in order:
+//   1. `src` non-empty AND not the failed src ⇒ an <img alt=""> (empty-alt — the Option/MenuItem sanction;
+//      host ARIA stays on internals) with an `error` listener that records the src into `#failedSrc`. The
+//      effect re-runs on that write and falls through to initials/glyph — no broken-image final state. A
+//      NEW `src` no longer equals `#failedSrc`, so it re-attempts (SPEC-R5's re-attempt transition falls
+//      out of the equality check, no extra state machine); clearing `src` falls back immediately.
+//   2. else `initialsFrom(identity)` non-empty ⇒ a `<span data-part="initials">`.
+//   3. else ⇒ `<ui-icon glyph="user">` — decorative by its own default; the icon control module is
+//      statically imported so the tag is defined before use (the sanctioned sibling-control import).
+//
+// A second effect owns ARIA (SPEC-R6) — the `ui-icon` contract shape verbatim: decorative by default
+// (`internals.ariaHidden = 'true'`, no role — a feed avatar beside a visible name would otherwise
+// duplicate it); non-empty `label` opts into `role=img` + `ariaLabel` + clears `ariaHidden`. A label-less
+// avatar beside no name announces nothing — that is a contract-level author error, not a defect here
+// (the descriptor states it explicitly).
+import { signal } from "../../reactive/index.js";
+import { UIElement, prop } from "../../dom/index.js";
+import { initialsFrom } from "./avatar-initials.js";
+import { UIIconElement } from "../icon/icon.js"; // sanctioned sibling-control import — self-defines ui-icon
+const props = {
+    src: prop.string(''), // image URL; a load error falls back without ever painting a broken-image box
+    identity: prop.string(''), // the identity the initials derive from; NOT announced by default (SPEC-R6). Renamed from `name` (TKT-0069 item 1 ruling: `name` = the FORM name, reserved; the A2UI catalog keeps wire `name`, mapped in its bespoke factory)
+    label: { ...prop.string(''), reflect: true }, // the a11y escape hatch — non-empty makes the avatar itself the accessible name
+    size: { ...prop.enum(['sm', 'md', 'lg'], 'md'), reflect: true }, // reflected — the CSS [size] hook
+};
+export class UIAvatarElement extends UIElement {
+    static props = props;
+    // The most recent `src` that failed to load — an equality check, not a boolean flag, so a NEW src
+    // (which no longer equals this value) re-attempts for free (SPEC-R5's re-attempt transition).
+    #failedSrc = signal('');
+    connected() {
+        this.effect(() => {
+            const src = this.src;
+            const name = this.identity;
+            const failedSrc = this.#failedSrc.value;
+            if (src !== '' && src !== failedSrc) {
+                const img = document.createElement('img');
+                img.alt = ''; // empty-alt semantics on an interior node — host ARIA stays on internals
+                img.addEventListener('error', () => { this.#failedSrc.value = src; }, { once: true });
+                img.src = src;
+                this.replaceChildren(img);
+                return;
+            }
+            const initials = initialsFrom(name);
+            if (initials !== '') {
+                const span = document.createElement('span');
+                span.dataset.part = 'initials';
+                span.textContent = initials;
+                this.replaceChildren(span);
+                return;
+            }
+            const icon = document.createElement('ui-icon');
+            icon.glyph = 'user';
+            this.replaceChildren(icon);
+        });
+        // ARIA effect (SPEC-R6): decorative by default; `label` opts into role=img + accessible name.
+        this.effect(() => {
+            if (this.label) {
+                this.internals.role = 'img';
+                this.internals.ariaLabel = this.label;
+                this.internals.ariaHidden = null;
+            }
+            else {
+                this.internals.role = null;
+                this.internals.ariaLabel = null;
+                this.internals.ariaHidden = 'true';
+            }
+        });
+    }
+}
+if (!customElements.get('ui-avatar'))
+    customElements.define('ui-avatar', UIAvatarElement); // idempotent self-define

package/dist/controls/badge/badge.css

@@ -0,0 +1,175 @@
+/* badge.css — ui-badge, the compact realm's first shipped non-interactive widget (report-family.lld.md
+ * LLD-C8 · SPEC-R12/R13/R14/R15/R16/R17 · ADR-0041 · ADR-0057 · ADR-0111 cl.5).
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-badge)` (specificity 0,0,0) declares the --ui-badge-* chain from the
+ *       colour roles (--md-sys-color-{family}-{role}) and the compact-realm widget-box ramp
+ *       (--md-sys-compact-lg, ADR-0041 — box = compact-realm law, NOT h/2; SPEC-R13). `[intent]` repoints the
+ *       colour channel (fill/ink/outline) here — the SAME technique checkbox.css uses for `[size]`/
+ *       `[disabled]`: every attribute-conditional token repoint stays inside `:where()`, never inside
+ *       `@scope` (component-packaging.md/tokens.md — "@scope consumes ONLY --ui-{name}-*"). No `[size]`
+ *       attribute in v1 (SPEC-R13 AC3) — the box is fixed to `--md-sys-compact-lg` regardless of content.
+ *   [2] STYLES BLOCK — `@scope (ui-badge)` consumes ONLY --ui-badge-*. The host is an inline-flex pill:
+ *       fixed square block-size (the compact-realm box), the compact pad law `2px + box·ratio·density`
+ *       (never `h/2` — geometry.md's compact-realm exception), radius = box/2 (the realm's "count pill"
+ *       case). The glyph is a real, constant `[data-part=glyph]` node; its SHAPE differs per `[intent]`
+ *       via `clip-path` (the checkbox tick precedent, ADR-0057's non-color signifier — shape is the
+ *       meaning channel, colour is the redundant one) — `neutral` shows no glyph at all (absence IS its
+ *       signifier). Forced-colors maps the host to Canvas/CanvasText and the glyph to CanvasText so both
+ *       survive WHCM (the bar-chart fill lesson: a background-drawn clip-path glyph is otherwise flattened
+ *       to `Canvas` and vanishes).
+ *
+ * No interaction states at all (SPEC-R11 — non-interactive, no focus/hover/active, no post-connect motion
+ * gate: there is nothing to transition). Standalone stylesheet — linked via the host page / component-
+ * styles barrel; NEVER injected from badge.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-badge) declares --ui-badge-* ════════════════ */
+
+:where(ui-badge) {
+  /* Compact-realm widget-box (ADR-0041; SPEC-R13) — fixed regardless of content/label length; [scale] on
+     an ancestor re-tables --md-sys-compact-lg for its subtree for free (no badge-local [scale] rule needed). */
+  --ui-badge-box: var(--md-sys-compact-lg); /* 18px @ default ui-md scale */
+
+  /* The compact pad law (dimensional-standard.md §2.4; geometry.md "the compact realm") — 2px + box ×
+     0.375 × density. Density rides the PAD only; the box above stays density-invariant (geometry.md). */
+  --ui-badge-pad: calc(2px + var(--ui-badge-box) * 0.375 * var(--md-sys-density, 1));
+
+  /* Text rides the fleet font ramp (NOT the compact box) — ADR-0111 cl.5's dual-listing resolution: box =
+     compact-realm law, text = --md-sys-font-*. line-height:1 in the styles block centers it like a glyph. */
+  --ui-badge-font: var(--md-sys-font-sm);
+
+  /* Rhythm — the glyph↔label gap (density-responsive for free, geometry.md "rhythm ∝ font"). */
+  --ui-badge-gap: var(--md-sys-gap-sm);
+
+  /* The glyph fills half the box — a content-mark, not an inline affordance (anatomy.md's frame family). */
+  --ui-badge-glyph: calc(var(--ui-badge-box) * 0.5);
+
+  /* Colour channel — neutral default (the "tag" reading of the one component, ADR-0111 fork F3). */
+  --ui-badge-fill: var(--md-sys-color-neutral-container);
+  --ui-badge-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-badge-outline: var(--md-sys-color-neutral-outline-variant);
+}
+
+/* [intent] → the colour channel repoint (SPEC-R14 AC3 defaults, build-time AA-probe-gated per intent ×
+   light/dark — the -on-surface-variant / -container pairing was flagged as a likely AA casualty at design
+   time). MEASURED (badge.browser.test.ts, both engines): 7.10–7.62:1 across all four intents × both
+   colour schemes — clears 4.5:1 comfortably; the predicted casualty did not materialize, no repoint owed.
+   A failing pairing would be a token-default repoint here, never a mechanism change (SPEC-R14/LLD-C8
+   failure-mode #13). */
+:where(ui-badge[intent='info']) {
+  --ui-badge-fill: var(--md-sys-color-info-container);
+  --ui-badge-ink: var(--md-sys-color-info-on-surface-variant);
+  --ui-badge-outline: var(--md-sys-color-info-outline-variant);
+}
+:where(ui-badge[intent='success']) {
+  --ui-badge-fill: var(--md-sys-color-success-container);
+  --ui-badge-ink: var(--md-sys-color-success-on-surface-variant);
+  --ui-badge-outline: var(--md-sys-color-success-outline-variant);
+}
+:where(ui-badge[intent='warning']) {
+  --ui-badge-fill: var(--md-sys-color-warning-container);
+  --ui-badge-ink: var(--md-sys-color-warning-on-surface-variant);
+  --ui-badge-outline: var(--md-sys-color-warning-outline-variant);
+}
+:where(ui-badge[intent='danger']) {
+  --ui-badge-fill: var(--md-sys-color-danger-container);
+  --ui-badge-ink: var(--md-sys-color-danger-on-surface-variant);
+  --ui-badge-outline: var(--md-sys-color-danger-outline-variant);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-badge) consumes ONLY --ui-badge-* ════════════════ */
+
+@scope (ui-badge) {
+  :scope {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ui-badge-gap);
+    box-sizing: border-box;
+    block-size: var(--ui-badge-box);
+    min-inline-size: var(--ui-badge-box); /* empty-label floor → a filled pill/dot (SPEC-R13 AC2) */
+    padding-inline: var(--ui-badge-pad);
+    padding-block: 0; /* the frame law — block-size is the vertical lever, never block-padding */
+    border-radius: calc(var(--ui-badge-box) / 2); /* the pill = box/2, the realm's "count pill" case */
+    border: 1px solid var(--ui-badge-outline);
+    background: var(--ui-badge-fill);
+    color: var(--ui-badge-ink);
+    font-size: var(--ui-badge-font);
+    line-height: 1; /* single-line token centers like a glyph (geometry.md's control line-height law) */
+    white-space: nowrap; /* anonymous host-as-content label text — the SAME no-wrapper gap ui-button had
+                            (button.css, fixed by ADR-0133) also exists here: no overflow/text-overflow, so
+                            a label an ancestor constrains would clip/overlap with no ellipsis affordance.
+                            NAMED DEFERRAL, not fixed here (ADR-0133 §Decision cl.3, TKT-0042): no evidence
+                            has been submitted that a badge label actually overflows in practice (the
+                            compact-realm box is meant for short tags/counts), and ADR-0106's Alternatives
+                            already rejected a generic fleet-wide truncate fix — per-control adoption stays
+                            per-control evidence. A future report against this control reopens ADR-0133's
+                            Alternatives with its own evidence, rather than starting cold. */
+  }
+
+  /* Glyph visibility is DEFAULT-OFF, opted in per the four known intents below — never default-on with a
+     neutral/unknown opt-out. This is deliberately robust to an out-of-enum [intent] attribute value that
+     the property-level hardening effect (badge.ts) cannot reach: the effect snaps the PROPERTY back to
+     'neutral', but a raw/reflected attribute mismatch (e.g. a plain-author typo, or a window where the
+     attribute briefly differs from the hardened property) must still degrade to "no glyph," never a
+     shapeless solid square (component-review finding — verified reachable on a literal out-of-enum
+     attribute in both engines before this fix). */
+  :scope [data-part='glyph'] {
+    display: none;
+    flex: none;
+    background-color: currentColor;
+    inline-size: var(--ui-badge-glyph);
+    block-size: var(--ui-badge-glyph);
+  }
+
+  /* Per-intent glyph SHAPES — pairwise-distinct clip-paths (SPEC-R12 AC1/AC2; the checkbox tick
+     precedent). Shape is the meaning channel; the [intent] colour repoints above are the REDUNDANT hue
+     channel (ADR-0057) — removing colour (e.g. grayscale) must never collapse two intents together.
+     `neutral` (and any unrecognized [intent]) inherits the base rule's `display: none` — absence IS
+     neutral's signifier, and it is also the safe fallback for anything not in this closed set. */
+  :scope[intent='success'] [data-part='glyph'] {
+    /* tick — the checkbox ✓ clip-path polygon, reused verbatim as the shared fleet "affirmative" mark */
+    display: inline-block;
+    clip-path: polygon(14% 44%, 0% 65%, 50% 100%, 100% 16%, 80% 0%, 43% 62%);
+  }
+  :scope[intent='danger'] [data-part='glyph'] {
+    /* cross — an X polygon, distinct from the tick and the triangle at every corner */
+    display: inline-block;
+    clip-path: polygon(
+      20% 8%,
+      8% 20%,
+      38% 50%,
+      8% 80%,
+      20% 92%,
+      50% 62%,
+      80% 92%,
+      92% 80%,
+      62% 50%,
+      92% 20%,
+      80% 8%,
+      50% 38%
+    );
+  }
+  :scope[intent='warning'] [data-part='glyph'] {
+    display: inline-block;
+    clip-path: polygon(50% 0, 100% 100%, 0 100%); /* triangle */
+  }
+  :scope[intent='info'] [data-part='glyph'] {
+    display: inline-block;
+    clip-path: circle(50%); /* disc */
+  }
+
+  /* Forced-colors (SPEC-R15) — the badge keeps its boxed identity via a system-ink border, and the glyph
+     paints in CanvasText: a background-drawn clip-path glyph is otherwise forced to `Canvas` and vanishes
+     (the bar-chart fill lesson). forced-color-adjust:none preserves these explicit system-colour mappings. */
+  @media (forced-colors: active) {
+    :scope {
+      background-color: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+      forced-color-adjust: none;
+    }
+    :scope [data-part='glyph'] {
+      background-color: CanvasText;
+    }
+  }
+}

package/dist/controls/badge/badge.d.ts

@@ -0,0 +1,36 @@
+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;
+    };
+    intent: {
+        reflect: true;
+        type: import("../../index.js").PropType<"neutral" | "info" | "success" | "warning" | "danger">;
+        default: "neutral" | "info" | "success" | "warning" | "danger";
+        attribute?: string | false;
+    };
+};
+export interface UIBadgeElement extends ReactiveProps<typeof props> {
+}
+export declare class UIBadgeElement extends UIElement {
+    #private;
+    static props: {
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        intent: {
+            reflect: true;
+            type: import("../../index.js").PropType<"neutral" | "info" | "success" | "warning" | "danger">;
+            default: "neutral" | "info" | "success" | "warning" | "danger";
+            attribute?: string | false;
+        };
+    };
+    protected connected(): void;
+}
+export {};

package/dist/controls/badge/badge.js

@@ -0,0 +1,71 @@
+// badge.ts — UIBadgeElement, the compact-realm's first shipped non-interactive status/label token
+// (report-family.lld.md LLD-C7; SPEC-R11…R13; ADR-0111 cl.1/2/3/4/5, fork F3; ADR-0057). Light-DOM
+// display leaf — extends UIElement directly (no form participation, no focus, no keyboard contract, no
+// events; SPEC-R11): a badge announces via its own real text, nothing else.
+//
+// Two props: `label` (plain string text) and `intent` (bindable STATUS DATA, unlike Sparkline's
+// structural `variant` — ADR-0111 cl.2) — the enum snaps an unknown ATTRIBUTE string back to 'neutral'
+// for free (`prop.enum`'s codec, the attribute↔value crossing in dom/props.ts). That codec guard fires
+// only on the attribute-string path, though: a raw PROPERTY write (`el.intent = 'bogus'`, the shape a
+// `{path}` DATA-MODEL bind actually takes at runtime — ADR-0098's validator sees literals at parse time,
+// never a bound value) goes straight through `finalize()`'s generic accessor with no codec involved at
+// all. SPEC-R11 AC2 requires the STORED value itself to read back 'neutral' after such a write (not just
+// what a render effect happens to clean on the way out) — so the render-boundary hardening idiom
+// (sparkline's `cleanSeries`, table's `cleanColumns`/`cleanRows`) is not enough on its own here; this file
+// adds one self-correcting `effect` (below) that re-validates `intent` on every change and writes the
+// snapped value BACK through the normal reactive setter (which also re-reflects the `[intent]` attribute
+// — AC2's second half). It converges in at most one extra microtask (bad → 'neutral' → no further write)
+// and uses only the public `this.effect`/`this.intent` surface — no reach into the props.ts internals.
+//
+// The glyph node is CONSTANT DOM — built once in connected(), never replaced. Every per-intent visual
+// difference (shape, color, visibility) is CSS keyed off the reflected `[intent]` host attribute, so an
+// intent change (a bound update) is a zero-DOM-churn attribute flip, never a re-render.
+import { UIElement, prop } from "../../dom/index.js";
+/** The closed intent set (SPEC-R11) — shared between the enum prop and the runtime hardening guard below. */
+const INTENTS = ['neutral', 'info', 'success', 'warning', 'danger'];
+const props = {
+    label: { ...prop.string(''), reflect: true },
+    // Bindable status data (fork F3): `prop.enum`'s codec snaps an unknown ATTRIBUTE string to 'neutral'
+    // for free; the property-write path is hardened separately (see the connected() effect). REFLECTS so
+    // `[intent]` CSS keys on JS-set/bound values (the ui-text `variant`/`size` precedent).
+    intent: { ...prop.enum(INTENTS, 'neutral'), reflect: true },
+};
+export class UIBadgeElement extends UIElement {
+    static props = props;
+    // The label part — held so the build below is genuinely once-EVER (TKT-0067): light-DOM children
+    // persist across a disconnect, so a reconnect reuses the SAME nodes instead of re-minting them.
+    #label;
+    connected() {
+        // Component-side hardening (SPEC-R11 AC2, ADR-0111 cl.2): a bound-garbage `intent` value snaps back
+        // to 'neutral' — re-checked on every change, written back through the normal reactive setter so BOTH
+        // `el.intent` and the reflected `[intent]` attribute read the sanitized value. Self-converging: the
+        // corrective write changes the signal from the bad value to 'neutral', which re-runs this same effect
+        // once more, finds 'neutral' valid, and stops (never a tight loop — `intent`'s own change is what
+        // re-triggers it, and the second pass is a no-op).
+        this.effect(() => {
+            if (!INTENTS.includes(this.intent))
+                this.intent = 'neutral';
+        });
+        // One-time DOM build (LLD-C7), now genuinely once-EVER behind an idempotent guard (TKT-0067: the
+        // prior code re-minted both nodes on every connect despite this comment's own "neither node is ever
+        // replaced" claim — true within a connection, false across reconnect; the parts-once canon): the
+        // glyph is decorative-only (aria-hidden; shape/visibility ride CSS off `[intent]`), the label
+        // carries the announced text. Only the label's textContent updates; only the host's `[intent]` flips.
+        if (this.#label === undefined) {
+            const glyph = document.createElement('span');
+            glyph.dataset.part = 'glyph';
+            glyph.setAttribute('aria-hidden', 'true');
+            this.#label = document.createElement('span');
+            this.#label.dataset.part = 'label';
+            this.replaceChildren(glyph, this.#label);
+        }
+        const label = this.#label;
+        // The one render effect: real text is the whole announcement (SPEC-R12 AC3) — no internals ARIA is
+        // minted at all (no role, no aria-label); the host's accessible name is its own text content.
+        this.effect(() => {
+            label.textContent = this.label;
+        });
+    }
+}
+if (!customElements.get('ui-badge'))
+    customElements.define('ui-badge', UIBadgeElement);

package/dist/controls/bar-chart/bar-chart.css

@@ -0,0 +1,110 @@
+/* bar-chart.css — ui-bar-chart, the Display-class magnitude-comparison bar list (LLD-C6,
+ * chart-family.lld.md §3; SPEC-R6/R9/R10/R11/R12). Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-bar-chart)` (specificity 0,0,0) declares the `--ui-bar-chart-*` chain:
+ *       the whole-shape floor (SPEC-R9 AC1 — a bare, unstyled chart in a flex row must still paint a
+ *       visible, non-collapsed, proportionally-correct box), density-INVARIANT mark geometry (bar
+ *       thickness/radius — SPEC-R12: mark geometry never rides `[scale]`), the data-bearing fill ink (a
+ *       ≥3:1-vs-surface fleet colour role, WCAG 1.4.11 — the fill is the graphic, the track is
+ *       decorative) and the density-RESPONSIVE row/column rhythm (rides `--md-sys-space` × `[density]` for
+ *       free — the ADR-0103 radio-group precedent, mirroring `ui-list`'s gap).
+ *   [2] STYLES BLOCK — `@scope (ui-bar-chart)` consumes ONLY `--ui-bar-chart-*` (∪ the shared
+ *       `--md-sys-color-*`/`--md-sys-typescale-*` namespaces the token block itself reads to build that
+ *       chain). `ui-bar-chart` is Display-class, TEXT-BEARING (SPEC-R12): labels/values read the
+ *       `--md-sys-typescale-body-medium-*` row directly (no `[size]`/`[scale]` lever — a chart takes
+ *       neither, SPEC-R12 AC2); no control height, no `padding-block` law.
+ *
+ * Row model: `fit-content(40%) 1fr auto` — labels cap at 40% and WRAP (`overflow-wrap: anywhere`, SPEC-R6
+ * AC3 — never starve the track); the track takes the remainder; values right-align with tabular numerals
+ * so magnitudes scan vertically. Each `[role='listitem']` row is a REAL `subgrid` child sharing the three
+ * columns (not `display: contents`, whose role-semantics engine-bug history the fleet doesn't need — LLD
+ * §3 note). The fill's inset/length ride two row-scoped custom properties SET IMPERATIVELY by bar-chart.ts
+ * (`--_bar-start`/`--_bar-length` — a non-`--ui-*` namespace, the slider/slider-multi `--value-pct`
+ * precedent the family-coherence token gate already exempts) — this sheet owns every paint decision, the
+ * behaviour file never writes a `width`.
+ *
+ * RTL is free (SPEC-R11 AC1): `inset-inline-start` + logical grid flow mirror under `dir="rtl"` — no
+ * physical property anywhere in this file. WHCM (SPEC-R10 AC1): the fill MUST render in a system ink (a
+ * background-drawn fill is otherwise forced to `Canvas` and vanishes) — an explicit `forced-colors` block
+ * paints it `CanvasText`, with the track kept visible + distinguishable via a `Canvas` fill + `CanvasText`
+ * border. Non-color signifier (SPEC-R8, ADR-0057): magnitude travels by length + the printed number; no
+ * intent-role is consumed anywhere in this sheet — nothing to co-carry.
+ *
+ * Standalone stylesheet — linked via the component-styles barrel (wave M1-b); NEVER injected from
+ * bar-chart.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-bar-chart) declares --ui-bar-chart-* ════════════════ */
+
+:where(ui-bar-chart) {
+  --ui-bar-chart-min-inline-size: 16em; /* the whole-shape floor (SPEC-R9 AC1) — never a collapsed sliver */
+  --ui-bar-chart-bar-size: 0.5rem; /* bar/track thickness — density-invariant (SPEC-R12) */
+  --ui-bar-chart-bar-radius: 2px;
+  --ui-bar-chart-bar-ink: var(--md-sys-color-primary); /* the data-bearing fill — >=3:1 vs surface (WCAG 1.4.11) */
+  --ui-bar-chart-track-ink: var(--md-sys-color-neutral-container); /* the decorative rail */
+  --ui-bar-chart-text-ink: var(--md-sys-color-neutral-on-surface); /* label/value ink — the ONE role reference (role-pure) */
+  --ui-bar-chart-row-gap: var(--md-sys-space-sm); /* row rhythm — rides [density] for free (ADR-0103) */
+  --ui-bar-chart-col-gap: var(--md-sys-space-sm);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-bar-chart) consumes ONLY --ui-bar-chart-* ════════════════ */
+
+@scope (ui-bar-chart) {
+  :scope {
+    display: grid;
+    grid-template-columns: fit-content(40%) 1fr auto;
+    column-gap: var(--ui-bar-chart-col-gap);
+    row-gap: var(--ui-bar-chart-row-gap);
+    align-items: center;
+    min-inline-size: var(--ui-bar-chart-min-inline-size);
+    box-sizing: border-box;
+    /* text-bearing Display (SPEC-R12) — the type matrix is the lever, not [size]/[scale]/--md-sys-height-* */
+    font-size: var(--md-sys-typescale-body-medium-size);
+    line-height: var(--md-sys-typescale-body-medium-line-height);
+    color: var(--ui-bar-chart-text-ink);
+  }
+
+  :scope [role='listitem'] {
+    display: grid;
+    grid-template-columns: subgrid;
+    grid-column: 1 / -1;
+    align-items: center;
+  }
+
+  :scope [data-part='label'] {
+    overflow-wrap: anywhere; /* long labels wrap at the 40% cap (SPEC-R6 AC3) instead of starving the track */
+  }
+
+  :scope [data-part='track'] {
+    position: relative;
+    display: block;
+    block-size: var(--ui-bar-chart-bar-size);
+    border-radius: var(--ui-bar-chart-bar-radius);
+    background: var(--ui-bar-chart-track-ink);
+  }
+
+  :scope [data-part='fill'] {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: calc(var(--_bar-start) * 1%); /* row-scoped, imperatively set (bar-chart.ts) */
+    inline-size: calc(var(--_bar-length) * 1%);
+    display: block;
+    background: var(--ui-bar-chart-bar-ink);
+    border-radius: inherit;
+  }
+
+  :scope [data-part='value'] {
+    text-align: end;
+    font-variant-numeric: tabular-nums;
+  }
+
+  @media (forced-colors: active) {
+    :scope [data-part='fill'] {
+      background: CanvasText; /* a background-drawn fill is otherwise forced to Canvas and vanishes */
+    }
+    :scope [data-part='track'] {
+      background: Canvas;
+      border: 1px solid CanvasText; /* keeps the track distinguishable from the fill under WHCM */
+    }
+  }
+}

package/dist/controls/bar-chart/bar-chart.d.ts

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