@agent-ui-kit/components 0.0.3

package/dist/controls/icon/icon.d.ts

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

package/dist/controls/icon/icon.js

@@ -0,0 +1,55 @@
+// icon.ts — UIIconElement, the Display-class icon-adapter consumer (LLD-C5, ADR-0065/0066). The
+// declarative surface over `@agent-ui-kit/icons`: <ui-icon glyph="caret-down"> resolves the active pack's
+// SVG body and injects it via `setIcon` (the cross-package edge the layering trip-wire admits — icons
+// as a second lower-tier sibling, mirroring components → shared). Light-DOM, self-defining, no traits.
+//
+// Two props, two connected() effects — nothing else:
+//   • `glyph` — reacts ONLY to glyph (and re-runs setIcon on every change); empty clears the host. Live
+//     pack-swap reactivity is DEFERRED (ADR-0065 clause 4) — the registry exposes no subscribable
+//     signal, so an already-rendered <ui-icon> does not auto-update when a pack is swapped AFTER first
+//     render; re-setting `glyph` reflects a swap.
+//   • `label` — decorative by default (aria-hidden, no role); non-empty makes the icon MEANINGFUL
+//     (role=img + aria-label). ARIA via ElementInternals only — never a host attribute (the FACE rule),
+//     so aria-hidden is toggled through `internals.ariaHidden`, not `setAttribute`, and is explicitly
+//     CLEARED when a label is supplied (so a labelled icon is never simultaneously aria-hidden).
+//
+// `glyph` is typed `prop.string('')`, not `prop.enum(ICON_NAMES, ...)`, deliberately: the swappable-pack
+// architecture means a consumer's own pack can register names beyond the shipped nine, so the prop stays
+// an open string; the IconName cast happens only at the internal setIcon call (an unregistered name is a
+// non-throwing `data-icon-missing` render, per resolve.ts).
+//
+// render() stays the inherited no-op — there is no template; `setIcon`/`replaceChildren` manage the host's
+// only child imperatively (the fleet's existing imperative-injection idiom, ADR-0065 context).
+import { UIElement, prop } from "../../dom/index.js";
+import { setIcon } from '@agent-ui-kit/icons';
+const props = {
+    glyph: prop.string(''), // an IconName; empty → renders nothing (clears the host). Renamed from `name` (TKT-0069 item 1 ruling: `name` is reserved fleet-wide for the FORM name; the A2UI catalog keeps the wire field `name`, mapped in its bespoke factory)
+    label: { ...prop.string(''), reflect: true }, // non-empty → meaningful: role=img + aria-label; empty → decorative (aria-hidden)
+};
+export class UIIconElement extends UIElement {
+    static props = props;
+    connected() {
+        // glyph effect: (re)inject the active pack's svg on glyph change; an empty glyph clears the host.
+        this.effect(() => {
+            if (this.glyph)
+                setIcon(this, this.glyph);
+            else
+                this.replaceChildren();
+        });
+        // label effect: decorative (aria-hidden) vs meaningful (role=img + aria-label). ElementInternals only.
+        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-icon'))
+    customElements.define('ui-icon', UIIconElement); // idempotent self-define

package/dist/controls/index.d.ts

@@ -0,0 +1,57 @@
+export * from './button/button.js';
+export * from './text-field/text-field.js';
+export * from './textarea/textarea.js';
+export * from './text/text.js';
+export * from './icon/icon.js';
+export * from './checkbox/checkbox.js';
+export * from './switch/switch.js';
+export * from './radio/radio.js';
+export * from './radio/radio-group.js';
+export * from './slider/slider.js';
+export * from './slider-multi/slider-multi.js';
+export * from './segment/segment.js';
+export * from './segmented-control/segmented-control.js';
+export * from './row/row.js';
+export * from './column/column.js';
+export * from './list/list.js';
+export * from './grid/grid.js';
+export * from './card/card.js';
+export * from './tabs/tabs.js';
+export * from './modal/modal.js';
+export * from './toolbar/toolbar.js';
+export * from './popover/popover.js';
+export * from './tooltip/tooltip.js';
+export * from './menu/menu.js';
+export * from './select/select.js';
+export * from './combo-box/combo-box.js';
+export * from './calendar/calendar.js';
+export * from './color-picker/color-picker.js';
+export * from './field/field.js';
+export * from './form-provider/form-provider.js';
+export * from './theme-provider/theme-provider.js';
+export * from './sparkline/sparkline.js';
+export * from './bar-chart/bar-chart.js';
+export * from './table/table.js';
+export * from './stat/stat.js';
+export * from './badge/badge.js';
+export * from './code/code.js';
+export * from './disclosure/disclosure.js';
+export * from './swatch/swatch.js';
+export * from './ramp/ramp.js';
+export * from './ladder/ladder.js';
+export * from './progress/progress.js';
+export * from './avatar/avatar.js';
+export * from './attachment/attachment.js';
+export * from './toast/toast.js';
+export * from './toast/toast-region.js';
+export * from './split/split.js';
+export * from './split/split-pane.js';
+export * from './timeline-item/timeline-item.js';
+export * from './timeline/timeline.js';
+export * from './status-stream/status-stream.js';
+export * from './swiper/swiper.js';
+export * from './swiper/swiper-item.js';
+export * from './swiper/swiper-pagination.js';
+export * from './swiper/swiper-paddles.js';
+export * from './swiper/swiper-label.js';
+export * from './command-modal/command-modal.js';

package/dist/controls/index.js

@@ -0,0 +1,136 @@
+// components — the self-defining ui-* FACE-control family barrel (ADR-0003). Importing this module pulls in
+// every control, each of which `customElements.define`s its tag as a top-level side effect, so importing the
+// package `./components` entry registers the whole family in one line. Re-exporting each control's module ALSO
+// surfaces its element class (e.g. UIButtonElement, UITextFieldElement, UIRowElement, UICardElement) for typed
+// references. Layer-4 barrel: composes the controls layer only; never reaches into kernel internals.
+//
+// Today's family:
+//   • form controls — ui-button (G5), ui-text-field (G6).
+//   • display controls — ui-text (ADR-0025), the Display-class text primitive (typographic scale leaf);
+//     ui-icon (ADR-0065/0066), the icon-adapter's declarative consumer (imports @agent-ui-kit/icons).
+//   • Indicator controls — Wave 1 (ADR-0041/0042): ui-checkbox · ui-switch · ui-radio · ui-radio-group.
+//     All four extend UIIndicatorElement (boolean form value + checked-state machine + pressActivation
+//     toggle); ui-radio-group extends UIFormElement directly and owns the group value + rovingFocus.
+//   • the G9 container/layout family (extends the dom UIContainerElement surface base, NOT form-associated):
+//     the flex/grid layout primitives ui-row · ui-column · ui-list · ui-grid; the compound ui-card (whose
+//     family entry transitively self-defines its region sub-elements ui-card-header/-content/-footer); the
+//     compound ui-tabs (transitively self-defines ui-tab/-tab-panel); and ui-modal (native <dialog>).
+//   • Coordination controls — G7 (ADR-0050/ADR-0051): ui-field (the label/description/error wrapper around
+//     ONE slotted form control) and ui-form-provider (the discovery/aggregation layer over UIFormElement
+//     descendants). Neither carries a form value of its own — both extend UIElement directly.
+//   • Chart family — Wave M1 (ADR-0107, chart-family.lld.md): ui-sparkline (series-shape mark) and
+//     ui-bar-chart (magnitude-comparison bar list). Both Display-class, axis-free, non-interactive,
+//     non-form-associated leaves — extend UIElement directly, tier=display, no [size]/[scale] geometry row.
+//   • Report family — Wave M1 (ADR-0111, report-family.lld.md): ui-table (native <table>, scroll-preserving
+//     re-render), ui-stat (metric tile, direction-as-text delta), ui-badge (compact-realm intent badge). All
+//     Display-class, non-interactive, non-form-associated leaves — extend UIElement directly.
+//   • Content family — Wave M1 (ADR-0113, content-family.lld.md): ui-code (zero-machinery verbatim code
+//     leaf, host-as-content) and ui-disclosure (native <details>/<summary> fold, Pattern-class). The
+//     hyperlink capability (`as='a'`/`href`) is an in-place extension of ui-text (exported above).
+// A compound's main `.ts` imports its sub-element modules so `export * from './{family}/{family}.ts'` here
+// registers the WHOLE family — importing the barrel self-defines all ~20+ tags.
+export * from "./button/button.js";
+export * from "./text-field/text-field.js";
+export * from "./textarea/textarea.js"; // ui-textarea (ADR-0134) — the multi-line FACE sibling of ui-text-field
+export * from "./text/text.js";
+export * from "./icon/icon.js"; // ui-icon (ADR-0065/0066) — the icon-adapter's declarative consumer surface
+// Indicator controls — Wave 1 (ADR-0041/0042).
+export * from "./checkbox/checkbox.js";
+export * from "./switch/switch.js";
+export * from "./radio/radio.js"; // self-defines ui-radio
+export * from "./radio/radio-group.js"; // self-defines ui-radio-group
+// Range controls — Wave 2 (ADR-0042 Range half): single + dual-thumb slider.
+export * from "./slider/slider.js";
+export * from "./slider-multi/slider-multi.js";
+// Pattern controls — ADR-0095 (supersedes ADR-0086's ui-radio-group[variant='segmented'], hard cutover):
+// the standalone segmented control. segmented-control.ts imports segment.ts as a side effect (both tags
+// self-define together), but each still gets its own `export *` line here — the barrel↔exports-map
+// three-way bijection (barrels.test.ts T4) requires one per public `./controls/{name}` entry, and
+// `segment`/`segmented-control` live in SEPARATE folders (the family-coherence naming trip-wire's
+// `name === folder || name.startsWith(folder + '-')` rule has no prefix relationship between them, unlike
+// the radio/radio-group one-folder precedent — see segmented-control.ts's own note).
+export * from "./segment/segment.js";
+export * from "./segmented-control/segmented-control.js";
+// G9 container / layout family — surface axes + the shared flex grammar (ADR-0015/0016).
+export * from "./row/row.js";
+export * from "./column/column.js";
+export * from "./list/list.js";
+export * from "./grid/grid.js";
+export * from "./card/card.js"; // transitively self-defines ui-card-header / -content / -footer
+export * from "./tabs/tabs.js"; // transitively self-defines ui-tab / -tab-panel
+export * from "./modal/modal.js";
+export * from "./toolbar/toolbar.js"; // Pattern-class action bar (ADR-0121) — role=toolbar + roving focus, posture via elevation/brightness
+// Overlay controls — Wave 4 (ADR-0043 / overlay-controller.lld): the `overlay` controller composed into five
+// controls. Non-form disclosure/hover/action overlays (UIElement hosts) + the two form-associated pickers
+// (UIFormElement + a role=listbox popup). All emit the family two-way-`open` contract (toggle/close, ADR-0019).
+export * from "./popover/popover.js"; // disclosure overlay — proves the overlay controller
+export * from "./tooltip/tooltip.js"; // hover/focus overlay (popover=manual, never steals focus)
+export * from "./menu/menu.js"; // action overlay — rovingFocus over [role=menuitem], commit→select
+export * from "./select/select.js"; // form-associated single-select (overlay + roving + selectionCommit)
+export * from "./combo-box/combo-box.js"; // form-associated filter combobox (overlay + active-descendant)
+// Picker controls — Wave 5B (ADR-0048): standalone month-grid date picker; also the popup body
+// for ui-text-field type=date (lazily imported there in slice 5B-3).
+export * from "./calendar/calendar.js"; // form-associated date picker (bespoke 2D grid, UIFormElement base)
+// ADR-0123 — ui-color-picker, the OKLCH-internal 2-axis color-input control (color-picker.lld.md): a
+// Pattern-class UIFormElement composite (pad + composed ui-slider channels + ui-text-field readout +
+// ui-swatch preview). Also the popup body for ui-text-field type=color (lazily imported there, LLD-C9),
+// the ADR-0048 type=date→ui-calendar seam verbatim.
+export * from "./color-picker/color-picker.js";
+// Coordination controls — G7 (ADR-0050/ADR-0051): the labelling wrapper + the aggregation/discovery provider.
+export * from "./field/field.js"; // the label/description/error wrapper (LLD-C4)
+export * from "./form-provider/form-provider.js"; // also surfaces FormSubmitDetail (LLD-C7)
+// Coordination/carrier controls — ADR-0117: the fleet's SECOND pure UIElement coordination primitive (after
+// ui-form-provider). Establishes a color-scheme subtree + reflects scale/density/theme as pure carriers.
+export * from "./theme-provider/theme-provider.js";
+// Chart family — Wave M1 (ADR-0107, chart-family.lld.md): Display-class, axis-free chart marks. Neither is
+// form-associated or interactive (extends UIElement directly, tier=display, no [size]/[scale] geometry row).
+export * from "./sparkline/sparkline.js"; // series-shape mark (LLD-C1/C2/C3)
+export * from "./bar-chart/bar-chart.js"; // magnitude-comparison bar list (LLD-C4/C5/C6)
+// Report family — Wave M1 (ADR-0111, report-family.lld.md): the real native <table>, the metric tile, and
+// the compact-realm intent badge. All Display-class, non-interactive, non-form-associated leaves.
+export * from "./table/table.js"; // scroll-preserving static data table (LLD-C1/C2/C3)
+export * from "./stat/stat.js"; // metric tile, direction-as-text delta (LLD-C4/C5/C6)
+export * from "./badge/badge.js"; // compact-realm intent badge (LLD-C7/C8)
+// Content family — Wave M1 (ADR-0113, content-family.lld.md): the zero-machinery code leaf and the native
+// <details>/<summary> disclosure. (The ui-text hyperlink extension lives in ./text/text.ts, exported above.)
+export * from "./code/code.js"; // verbatim code leaf, host-as-content (LLD-C5/C6/C7)
+export * from "./disclosure/disclosure.js"; // native details/summary fold (LLD-C8/C9/C10)
+// Token-surface family — M1 (ADR-0118, token-surfaces.lld.md): show-never-edit color/dimension primitives.
+// All three Display-class, non-interactive, non-form-associated leaves — extend UIElement directly, tier=
+// display, no [size]/[scale] geometry row. Share the DOM-free value-lane helper `_token-surface/token-surface.ts`.
+export * from "./swatch/swatch.js"; // color-identity leaf, role=img + composed name (LLD-C2/C3)
+export * from "./ramp/ramp.js"; // ordered color series, role=list (LLD-C4/C5)
+export * from "./ladder/ladder.js"; // labeled dimensional tiers, literal-length bars, role=list (LLD-C6/C7)
+// Feed family — Wave M1 (ADR-0112, feed-family.lld.md): agent-activity primitives. All Display/Indicator-
+// class, non-form-associated leaves except the toast pair (pattern/layout, no catalog row — ADR-0112 cl.6).
+export * from "./progress/progress.js"; // thin-rail progress bar (LLD-C1)
+export * from "./avatar/avatar.js"; // compact identity mark (LLD-C2/C3)
+export * from "./attachment/attachment.js"; // FilePart-aligned file card, metadata surface only (LLD-C4/C5)
+export * from "./toast/toast.js"; // transient notification card (LLD-C7)
+export * from "./toast/toast-region.js"; // toast's top-layer host, same-folder sibling (LLD-C8)
+// M4 Phase 1 — the split primitive (ADR-0120 cl.2, app-surfaces-m4.lld.md LLD-C1): a Container/layout
+// control (tier: layout, sibling to ui-row/-column/-grid) — one folder, TWO real components (the
+// radio/radio-group precedent): ui-split (the N-pane resizable container) + ui-split-pane (the generic
+// pane child, own descriptor/contract per ADR-0080's radio-group special case).
+export * from "./split/split.js";
+export * from "./split/split-pane.js";
+// Timeline family — ADR-0122 (timeline-family.lld.md): a three-tag event-rail family — the shared inert
+// visual atom (ui-timeline-item), its durable authored-children host (ui-timeline, role=list), and its
+// live imperatively-fed sibling (ui-status-stream, role=log). The item lands first — both hosts depend on it.
+export * from "./timeline-item/timeline-item.js"; // the shared marker+content+detail rail row (F1/F2/F3/F6)
+export * from "./timeline/timeline.js"; // the durable host — authored children, static (F1/F6)
+export * from "./status-stream/status-stream.js"; // the live host — append/update/finalize, tail-follow (F4)
+// ADR-0124 — the ui-swiper family: a CSS-native scroll-snap carousel (swiper-family.lld.md). swiper.ts
+// imports the four leaf modules (registering all five family tags on its own import), but each of the
+// five carries its own `{name}.md` descriptor (LLD §10 — unlike ui-tab/ui-tab-panel, which have none), so
+// every one gets its own barrel export line too (the C1 lifecycle bijection, family-coherence.test.ts) —
+// a harmless re-export of an already-registered module, and it surfaces each leaf's class at the barrel.
+export * from "./swiper/swiper.js";
+export * from "./swiper/swiper-item.js";
+export * from "./swiper/swiper-pagination.js";
+export * from "./swiper/swiper-paddles.js";
+export * from "./swiper/swiper-label.js";
+// ADR-0125 — ui-command-modal, the CMD-K command palette (command-modal.lld.md): a Pattern-class coordinator
+// that nests a ui-modal for the surface and re-derives ui-combo-box's active-descendant filter. Permanently
+// catalog-excluded (app-owner launcher chrome, F8) — still a fleet member, exported like any other control.
+export * from "./command-modal/command-modal.js";

package/dist/controls/ladder/ladder.css

@@ -0,0 +1,89 @@
+/* ladder.css — ui-ladder, the Display-class labeled-dimensional-tiers leaf (LLD-C7, token-surfaces.lld.md
+ * §3.3; SPEC-R10/R13/R14/R15/R16). Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-ladder)` (specificity 0,0,0) declares the `--ui-ladder-*` chain: the
+ *       whole-shape floor (SPEC-R13 AC1), bar THICKNESS (density-invariant mark geometry), the fill ink
+ *       (>=3:1 vs surface — WCAG 1.4.11), and the density-RESPONSIVE row/column rhythm (rides `--md-sys-space`
+ *       × `[density]` for free, the `ui-bar-chart` precedent).
+ *   [2] STYLES BLOCK — `@scope (ui-ladder)` consumes ONLY `--ui-ladder-*` (∪ the shared `--md-sys-color-*`/
+ *       `--md-sys-typescale-*` namespaces). Display-class (SPEC-R16): no `[size]`/`[scale]` row.
+ *
+ * The literal-length ruling (SPEC-R10): `inline-size: min(100%, var(--_mag, 0px))` renders each tier at its
+ * REAL length, capped to the track — a deliberate departure from `ui-bar-chart`'s normalized proportion math
+ * (ADR-0118 cl.2/3: a ladder has no math module, a dimensional value already IS a renderable length). The
+ * `var(--_mag, 0px)` fallback is the zero-bar floor for BOTH the LLD-C6 non-length route (`--_mag` set to
+ * `0px` directly) AND an undefined `--var` (whose `var(--…)` substitution is guaranteed-invalid, so
+ * `var(--_mag, 0px)` genuinely falls to `0px`) — SPEC-R11's unified no-silent-state rule.
+ *
+ * Rows are real `role="listitem"` SUBGRID children (NOT `display: contents`, whose role-semantics engine-bug
+ * history the fleet avoids — the `ui-bar-chart` precedent).
+ *
+ * RTL is free (SPEC-R15): logical grid + `inline-size` mirror under `dir="rtl"` — no physical property
+ * anywhere in this file. WHCM (SPEC-R14): the bar paints `CanvasText` (a system ink is never forced away) —
+ * magnitude still travels by length + the printed value.
+ *
+ * Standalone stylesheet — linked via the component-styles barrel; NEVER injected from ladder.ts
+ * (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-ladder) declares --ui-ladder-* ════════════════ */
+
+:where(ui-ladder) {
+  --ui-ladder-min-inline-size: 16em; /* the whole-shape floor */
+  --ui-ladder-bar-size: 0.75rem; /* bar THICKNESS — density-invariant */
+  --ui-ladder-bar-radius: 2px;
+  --ui-ladder-bar-ink: var(--md-sys-color-primary); /* the magnitude fill — >=3:1 vs surface (WCAG 1.4.11) */
+  --ui-ladder-row-gap: var(--md-sys-space-sm); /* rides [density] for free (ADR-0103) */
+  --ui-ladder-col-gap: var(--md-sys-space-sm);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-ladder) consumes ONLY --ui-ladder-* ════════════════ */
+
+@scope (ui-ladder) {
+  :scope {
+    display: grid;
+    grid-template-columns: fit-content(30%) 1fr auto;
+    column-gap: var(--ui-ladder-col-gap);
+    row-gap: var(--ui-ladder-row-gap);
+    align-items: center;
+    min-inline-size: var(--ui-ladder-min-inline-size);
+    box-sizing: border-box;
+    font-size: var(--md-sys-typescale-body-medium-size);
+    line-height: var(--md-sys-typescale-body-medium-line-height);
+  }
+
+  :scope [role='listitem'] {
+    display: grid;
+    grid-template-columns: subgrid;
+    grid-column: 1 / -1;
+    align-items: center;
+  }
+
+  :scope [data-part='label'] {
+    overflow-wrap: anywhere;
+  }
+
+  :scope [data-part='track'] {
+    display: block;
+    block-size: var(--ui-ladder-bar-size);
+  }
+
+  :scope [data-part='bar'] {
+    display: block;
+    block-size: 100%;
+    inline-size: min(100%, var(--_mag, 0px)); /* LITERAL length, track-capped — NO normalization (SPEC-R10) */
+    background: var(--ui-ladder-bar-ink);
+    border-radius: var(--ui-ladder-bar-radius);
+  }
+
+  :scope [data-part='value'] {
+    text-align: end;
+    font-variant-numeric: tabular-nums;
+  }
+
+  @media (forced-colors: active) {
+    :scope [data-part='bar'] {
+      background: CanvasText; /* a system ink is never forced away — magnitude still carries by length */
+    }
+  }
+}

package/dist/controls/ladder/ladder.d.ts

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

package/dist/controls/ladder/ladder.js

@@ -0,0 +1,78 @@
+// ladder.ts — UILadderElement, the Display-class labeled-dimensional-tiers leaf (LLD-C6, token-surfaces.lld.md
+// §3.3; SPEC-R9…R12; ADR-0118 cl.1/2/4). BEHAVIOUR + props + list-semantics ARIA + the component-built rows +
+// self-define ONLY — the value-lane/hardening/length-routing logic lives in the shared
+// `_token-surface/token-surface.ts` (LLD-C1), the row/bar geometry in ladder.css.
+//
+// A ladder is data, not decoration (ADR-0118 cl.4): the host carries `role=list` via `ElementInternals` (the
+// `ui-bar-chart`/`ui-ramp` precedent) — never a host attribute — named by `label` when non-empty (SPEC-R12).
+// Each rendered row is a real `role=listitem` element whose text content is its label plus the printed value;
+// the magnitude bar (`[data-part='track']`) is `aria-hidden` — the printed value is the accessible datum either
+// way, whether the bar rendered a real length or degraded to zero (the unified no-silent-state rule, SPEC-R11).
+//
+// The literal-length ruling (SPEC-R10, the deliberate ui-bar-chart departure): NO cross-tier normalization math
+// — a tier's magnitude bar is its LITERAL length, capped to the track (`min(100%, …)`, ladder.css). Length
+// VALIDITY is a rendering ROUTER, not a drop gate (SPEC-R11): `isRenderableLength` decides whether a tier's
+// value drives a real bar or a `0px` zero-bar — the row + its printed value survive either way, so `cleanEntries`
+// runs with NO further length-based filtering (only a genuinely malformed {label,value} shape drops an entry).
+//
+// Imports inward only (controls → dom + the sibling shared helper).
+import { UIElement, prop } from "../../dom/index.js";
+import { cleanEntries, cssValue, isRenderableLength, tokenEntriesProp } from "../_token-surface/token-surface.js";
+const props = {
+    tiers: tokenEntriesProp(), // { label: string; value: string }[] · safe JSON codec (LLD-C1) · default []
+    label: { ...prop.string(''), reflect: true }, // the list's accessible name — SPEC-R12: unlabeled is legal, never a silent state
+    // NO `scheme` — dimensions are scheme-invariant (SPEC-R9).
+};
+export class UILadderElement extends UIElement {
+    static props = props;
+    connected() {
+        // List semantics (SPEC-R12, the `ui-bar-chart`/`ui-ramp` precedent) — a constant semantic role, set
+        // directly (not inside an effect); re-set on each connect (idempotent).
+        this.internals.role = 'list';
+        // The label effect — `label` names the list when non-empty; an unlabeled list is legal (SPEC-R12 AC2).
+        this.effect(() => {
+            this.internals.ariaLabel = this.label || null;
+        });
+        // The tiers effect (SPEC-R10/R11): whole-array derived state — every `tiers` change rebuilds the full
+        // light-DOM row list via one `replaceChildren`. `cleanEntries` runs again here (not just inside the
+        // codec) — the SPEC-R7-sibling property-write guard the codec alone cannot cover. NO length-based drop:
+        // a non-length tier value KEEPS its row (routed to a zero-length bar by `#rowNode`, SPEC-R11).
+        this.effect(() => {
+            const rendered = cleanEntries(this.tiers);
+            this.replaceChildren(...rendered.map((tier) => this.#rowNode(tier)));
+        });
+    }
+    /**
+     * Build one component-owned row: `label · track(aria-hidden) > bar · value` (LLD-C6's markup). The bar's
+     * magnitude rides the row-scoped custom property `--_mag`, set imperatively — ladder.css owns every paint
+     * decision, this method never writes a `width`. A resolvable length (SPEC-R11: `isRenderableLength` — a
+     * `--var` counts, its own resolution is the browser's job) passes through `cssValue` (the LOAD-BEARING
+     * transform, LLD-C6: a `--`-prefixed value becomes `var(--…)`, never a bare dashed-ident, which is invalid at
+     * computed-value time inside `min(100%, …)`); a non-length value (`"red"`) routes to a literal `'0px'` — the
+     * row + printed value survive either way (SPEC-R11 the unified no-silent-state rule). AT reading (SPEC-R12):
+     * the listitem's text content is `{label}{value}` (the two real text spans, the `ui-bar-chart`/`ui-ramp`
+     * listitem-text precedent); the track subtree is `aria-hidden` and text-free.
+     */
+    #rowNode(tier) {
+        const item = document.createElement('div');
+        item.setAttribute('role', 'listitem');
+        const label = document.createElement('span');
+        label.setAttribute('data-part', 'label');
+        label.textContent = tier.label;
+        const bar = document.createElement('span');
+        bar.setAttribute('data-part', 'bar');
+        const mag = isRenderableLength(tier.value) ? cssValue(tier.value) : '0px';
+        bar.style.setProperty('--_mag', mag);
+        const track = document.createElement('span');
+        track.setAttribute('data-part', 'track');
+        track.setAttribute('aria-hidden', 'true');
+        track.appendChild(bar);
+        const value = document.createElement('span');
+        value.setAttribute('data-part', 'value');
+        value.textContent = tier.value;
+        item.append(label, track, value);
+        return item;
+    }
+}
+if (!customElements.get('ui-ladder'))
+    customElements.define('ui-ladder', UILadderElement); // idempotent self-define

package/dist/controls/list/list.css

@@ -0,0 +1,118 @@
+/* list.css — ui-list, the single-file component stylesheet (ADR-0003). Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-list)` (specificity 0,0,0) DECLARES the `--ui-list-*` flex chain. Each
+ *       `flexProps` literal-union (align/justify/gap/wrap — ADR-0016 cl.1) is mapped here to its CSS keyword
+ *       (start→start, end→end, between→space-between, … — box-alignment dialect, ADR-0039) or to a `--md-sys-space` ladder step, via `[attr=value]`
+ *       attribute selectors. The `--md-sys-space-*` layout-spacing ladder (the SHARED, density-responsive gap
+ *       vocabulary — dimensions.css / ADR-0015 cl.4) is read ONLY here, on the declaration side — exactly as
+ *       button.css reads the `--md-sys-color-*` colour roles only in its `:where()` token block.
+ *   [2] STYLES BLOCK — `@scope (ui-list)` CONSUMES only `--ui-list-*` for its layout. `ui-list` is a
+ *       `ui-column` SPECIALIZATION: `display:flex; flex-direction:column` (the vertical stack — the tag's
+ *       identity, A2UI-faithful, ADR-0016 cl.2/3). No control height (geometry.md "Container/layout" class —
+ *       spacing rides `--md-sys-space` × `[density]`, never `--md-sys-height-*`).
+ *
+ * Surface — NOT here. The role-pure surface seam (`--ui-container-bg`/`-tint` consumption, the
+ * `[elevation]`/`[brightness]` mapping) + the forced-colors surface survival are owned by the SHARED
+ * `controls/_surface/container.css` (ADR-0015), which lists `ui-list` among the surface-bearing tags.
+ * list.css therefore carries NO colour opinion and needs no forced-colors block — there is nothing of its own
+ * to protect (it owns layout only). `ui-list` establishes NO query container of its own (ADR-0100 — it is
+ * intrinsically sized, like every layout primitive, so it can never safely be one); a `ui-list` has no
+ * `@container` rule of its own anyway (its direction is fixed — always a column), so this only matters for
+ * children that might want to query — an externally-sized ancestor boundary provides that context, not the
+ * list.
+ *
+ * Standalone stylesheet — linked via the component-styles barrel (wired in s12, AFTER container.css); NEVER
+ * injected from list.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-list) declares --ui-list-* ════════════════ */
+
+:where(ui-list) {
+  /* The flex chain — defaults are each `flexProps` prop's value, with the ADR-0030 column-parity override:
+     `align` defaults to `stretch` (the cross-axis inline default for a vertical stack — a list IS a column;
+     flexProps.align default stays `start` for row). A custom property holds the resolved CSS keyword;
+     `[attr=value]` repoints the NON-DEFAULT keywords below. A default is NOT reflected as an attribute
+     (ADR-0005), so the base token must carry the new default. */
+  --ui-list-align: stretch; /* align (cross-axis) → align-items: stretch (ADR-0030 flip start→stretch) */
+  --ui-list-justify: start; /* justify (main-axis distribution) → justify-content; box-alignment start (ADR-0039) */
+  --ui-list-gap: var(--md-sys-space-none); /* gap → a --md-sys-space ladder step (0 = no gap) */
+  --ui-list-wrap: nowrap; /* wrap → flex-wrap (boolean presence) */
+}
+
+/* align → align-items (stretch = the new default above; start is now a non-default needing its own repoint).
+   ADR-0030: `start` gains a repoint rule; the now-redundant `stretch` rule is removed (stretch = the base). */
+:where(ui-list[align='start']) {
+  --ui-list-align: start; /* start is a non-default: the [align='start'] repoint (box-alignment start — ADR-0039) */
+}
+:where(ui-list[align='center']) {
+  --ui-list-align: center;
+}
+:where(ui-list[align='end']) {
+  --ui-list-align: end; /* box-alignment end (ADR-0039) */
+}
+:where(ui-list[align='baseline']) {
+  --ui-list-align: baseline;
+}
+
+/* justify → justify-content (start is the default; between/around/evenly map to the space-* keywords) */
+:where(ui-list[justify='center']) {
+  --ui-list-justify: center;
+}
+:where(ui-list[justify='end']) {
+  --ui-list-justify: end; /* box-alignment end (ADR-0039) */
+}
+:where(ui-list[justify='between']) {
+  --ui-list-justify: space-between;
+}
+:where(ui-list[justify='around']) {
+  --ui-list-justify: space-around;
+}
+:where(ui-list[justify='evenly']) {
+  --ui-list-justify: space-evenly;
+}
+
+/* gap → the SHARED density-responsive --md-sys-space ladder (read only here, the declaration side). `none` is the
+   default above; each step is `calc(<base px> * var(--md-sys-density))`, so a subtree [density] re-multiplies the
+   list's row-gap (the one density-bearing quantity — the geometry smoke proves it CHANGES with [density]). */
+:where(ui-list[gap='xs']) {
+  --ui-list-gap: var(--md-sys-space-xs);
+}
+:where(ui-list[gap='sm']) {
+  --ui-list-gap: var(--md-sys-space-sm);
+}
+:where(ui-list[gap='md']) {
+  --ui-list-gap: var(--md-sys-space-md);
+}
+:where(ui-list[gap='lg']) {
+  --ui-list-gap: var(--md-sys-space-lg);
+}
+:where(ui-list[gap='xl']) {
+  --ui-list-gap: var(--md-sys-space-xl);
+}
+:where(ui-list[gap='2xl']) {
+  --ui-list-gap: var(--md-sys-space-2xl);
+}
+
+/* wrap → flex-wrap (boolean presence: present ⇒ wrap) */
+:where(ui-list[wrap]) {
+  --ui-list-wrap: wrap;
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-list) consumes ONLY --ui-list-* ════════════════ */
+
+@scope (ui-list) {
+  :scope {
+    display: flex;
+    flex-direction: column; /* the vertical stack — the list's identity (ADR-0016 cl.2/3) */
+    box-sizing: border-box;
+
+    /* The flex mapping — every value reads the own `--ui-list-*` chain (role-pure; no raw --md-sys-space/--md-sys-color-*
+       leaks into the consumption, mirroring button.css's @scope hygiene). The surface background rides the
+       shared controls/_surface/container.css; NO `container-type` (ADR-0100 — ui-list is never a query
+       container). NO control height. */
+    align-items: var(--ui-list-align);
+    justify-content: var(--ui-list-justify);
+    gap: var(--ui-list-gap); /* the density-bearing quantity — rides --md-sys-space × [density] */
+    flex-wrap: var(--ui-list-wrap);
+  }
+}