@agent-ui-kit/components 0.0.3

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

@@ -0,0 +1,80 @@
+// bar-chart.ts — UIBarChartElement, the Display-class magnitude-comparison bar list (LLD-C5,
+// chart-family.lld.md §3; chart-family.spec.md SPEC-R5…R8; ADR-0107 cl.1-5, fork F2). BEHAVIOUR + props +
+// list-semantics ARIA + the component-built rows + self-define ONLY; the zero-baseline PROPORTION math
+// lives in bar-math.ts (DOM-free, unit-testable) and the CSS grid/token geometry lives in bar-chart.css.
+//
+// The name stays `ui-bar-chart`/`BarChart` even though v1 renders the horizontal bar-LIST model (ADR-0107
+// fork F2, SPEC-R5) — models know "BarChart"; the descriptor documents the deviation honestly.
+//
+// A chart is data, not decoration (ADR-0107 cl.4): the host carries `role=list` via `ElementInternals`
+// (the `ui-list` precedent, `list.ts:50`) — never a host attribute — named by `label` when non-empty
+// (SPEC-R8). Each rendered row is a real `role=listitem` element whose text content is `{label} {printed
+// value}`; the visual bar (track + fill) is `aria-hidden` — the printed value is the accessible datum, the
+// bar itself repeats it in the length channel only, never the sole carrier (ADR-0057).
+//
+// Content model — component-built rows, NOT host-as-grid: `data` is display-only, whole-array derived
+// state (no positional reconcile — LLD-C5's deliberate NOT-ADR-0024 call, LLD §7 row 7: these are inert
+// text rows with no focus/selection worth reconciling), so `render()` stays the inherited no-op and the
+// rows effect rebuilds the full light-DOM child list on every `data` change via `replaceChildren`. The
+// fill's geometry rides two row-scoped custom properties set imperatively (`--_bar-start`/`--_bar-length`,
+// a non-`--ui-*` namespace — the slider/slider-multi `--value-pct` precedent) so bar-chart.css owns every
+// paint decision and this file never writes a `width`.
+//
+// Imports inward only (controls → dom): UIElement + prop + the typed-schema helpers from the dom barrel;
+// the pure math from the co-located bar-math.ts (the ADR-0065 pure-core split, ADR-0107 cl.3/cl.7).
+import { UIElement, prop } from "../../dom/index.js";
+import { barDataProp, barRows, cleanData } from "./bar-math.js";
+const props = {
+    data: barDataProp, // { label: string; value: number }[] · safe JSON codec (bar-math.ts) · default []
+    label: { ...prop.string(''), reflect: true }, // the list's accessible name — SPEC-R8: unlabeled is legal, never a silent state
+};
+export class UIBarChartElement extends UIElement {
+    static props = props;
+    connected() {
+        // List semantics (SPEC-R8, the `ui-list` 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-R8 AC —
+        // the host stays `role=list` regardless, never aria-hidden, never a silent state).
+        this.effect(() => {
+            this.internals.ariaLabel = this.label || null;
+        });
+        // The rows effect (SPEC-R6/R7): whole-array derived state — every `data` change rebuilds the full
+        // light-DOM row list via one `replaceChildren` (display-only rows hold no focus/selection state worth
+        // a positional reconcile — LLD-C5's deliberate NOT-ADR-0024 call). `cleanData` runs again here (not
+        // just inside the codec), so a PROPERTY write of garbage never reaches the math either (the SPEC-R3
+        // AC2 sibling rule the codec alone cannot cover — the codec only guards the ATTRIBUTE path).
+        this.effect(() => {
+            const rows = barRows(cleanData(this.data));
+            this.replaceChildren(...rows.map((row) => this.#rowNode(row)));
+        });
+    }
+    /**
+     * Build one component-owned row: `label · track(aria-hidden) > fill · value` (LLD-C5's markup). The
+     * fill's geometry rides two row-scoped custom properties — bar-chart.css owns every paint decision, this
+     * method never writes a `width`. AT reading (SPEC-R8 AC1): the listitem's text content is
+     * `{label} {printed value}` (the two text spans); the track subtree is aria-hidden and text-free.
+     */
+    #rowNode(row) {
+        const item = document.createElement('div');
+        item.setAttribute('role', 'listitem');
+        const label = document.createElement('span');
+        label.setAttribute('data-part', 'label');
+        label.textContent = row.label;
+        const fill = document.createElement('span');
+        fill.setAttribute('data-part', 'fill');
+        fill.style.setProperty('--_bar-start', String(row.startPct));
+        fill.style.setProperty('--_bar-length', String(row.lengthPct));
+        const track = document.createElement('span');
+        track.setAttribute('data-part', 'track');
+        track.setAttribute('aria-hidden', 'true');
+        track.appendChild(fill);
+        const value = document.createElement('span');
+        value.setAttribute('data-part', 'value');
+        value.textContent = row.text;
+        item.append(label, track, value);
+        return item;
+    }
+}
+if (!customElements.get('ui-bar-chart'))
+    customElements.define('ui-bar-chart', UIBarChartElement); // idempotent self-define

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

@@ -0,0 +1,31 @@
+import type { PropConfig } from '../../dom/props.js';
+/** One bar-chart datum — the A2UI-emittable shape (SPEC-R5): `{ label: string; value: number }`. */
+export interface BarDatum {
+    label: string;
+    value: number;
+}
+/** A rendered row: the datum plus its printed text + zero-baseline geometry (each 0..100, a percentage). */
+export interface BarRow extends BarDatum {
+    /** The locale-formatted printed value (Intl.NumberFormat, default locale; sign preserved). */
+    text: string;
+    /** Fill inset from the track's inline-start, 0..100 (%). */
+    startPct: number;
+    /** Fill length, 0..100 (%). */
+    lengthPct: number;
+}
+/**
+ * Harden an arbitrary input into the rendered datum set (SPEC-R7): a non-array input yields `[]`; each
+ * entry survives only as a plain object with a `string` `label` and a finite `number` `value` — drop,
+ * never coerce (a stringly `"42"` value, a missing label, `NaN`/`Infinity` all drop the entry). Order is
+ * preserved — the rendered list is positional, not keyed (SPEC-R7's duplicate-label row: both rows render).
+ */
+export declare function cleanData(input: unknown): BarDatum[];
+/**
+ * The zero-baseline diverging bar math (SPEC-R6 + LLD-C4): `lo = min(0, …values)`, `hi = max(0, …values)`,
+ * `span = hi − lo`. Empty input is an early `[]` (the codec/hardening boundary handles absence — this
+ * function is never asked to normalize zero rows). `span === 0` (the all-zero case) ⇒ every row is
+ * `startPct = lengthPct = 0`. Else `zeroPct = (−lo / span) · 100` is the ONE shared origin every row
+ * measures from; `lengthPct = |v| / span · 100`; `startPct = v ≥ 0 ? zeroPct : zeroPct − lengthPct`.
+ */
+export declare function barRows(data: readonly BarDatum[]): BarRow[];
+export declare const barDataProp: PropConfig<BarDatum[]>;

package/dist/controls/bar-chart/bar-math.js

@@ -0,0 +1,106 @@
+// bar-math.ts — the pure, DOM-free bar-chart math (LLD-C4, chart-family.lld.md §3). No DOM, no host,
+// unit-testable in plain Node/Vitest. Owns three things:
+//
+//   1. Input hardening (`cleanData`, SPEC-R7): a non-array input is `[]`; an entry survives only as a
+//      plain object carrying a `string` `label` and a finite `number` `value` — dropped, never coerced.
+//      Order is preserved (positional semantics — SPEC-R7's duplicate-label row: the list is positional,
+//      not keyed).
+//   2. The zero-baseline diverging bar math (`barRows`, SPEC-R6): `lo = min(0, …values)`,
+//      `hi = max(0, …values)`, `span = hi − lo`. `span === 0` (the all-zero case; the empty case is an
+//      early return) ⇒ every row is zero-length — the printed `0`s carry the reading. Else
+//      `zeroPct = (−lo / span) · 100` (the ONE shared origin every row measures from — SPEC-R6 AC2);
+//      `lengthPct = |v| / span · 100`; `startPct = v ≥ 0 ? zeroPct : zeroPct − lengthPct`. All-positive ⇒
+//      `lo = 0`, bars measure from the inline-start edge (SPEC-R7 rows 3/4); all-negative ⇒ `hi = 0`, the
+//      zero point sits at the track's inline-end (SPEC-R7 row 7); mixed sign ⇒ every bar shares the one
+//      `zeroPct` (SPEC-R6 AC2). Every printed value rides a module-memoized default-locale
+//      `Intl.NumberFormat` — sign preserved for free (no special-casing negative text).
+//   3. `barDataProp`, the safe `data` codec (SPEC-R7 row 1/2): `from(null)` (attribute absent/removed) is
+//      `[]`, NEVER `null`; malformed attribute JSON is caught and also falls back to `[]` — no throw ever
+//      reaches `attributeChangedCallback`. `dom/props.ts`'s generic `jsonType<T>()` is deliberately NOT
+//      used here — its bare `JSON.parse` throws on malformed attributes and maps a removed attribute to
+//      `null` (props.ts:73-82), both of which SPEC-R7 forbids reaching the render path. This is the exact
+//      reasoning LLD-C1 (sparkline's `sparklineValuesProp`) states for its own codec — the two controls
+//      share the construction (chart-family.lld.md §3 LLD-C4: "same construction as LLD-C1's").
+/**
+ * Harden an arbitrary input into the rendered datum set (SPEC-R7): a non-array input yields `[]`; each
+ * entry survives only as a plain object with a `string` `label` and a finite `number` `value` — drop,
+ * never coerce (a stringly `"42"` value, a missing label, `NaN`/`Infinity` all drop the entry). Order is
+ * preserved — the rendered list is positional, not keyed (SPEC-R7's duplicate-label row: both rows render).
+ */
+export function cleanData(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const entry of input) {
+        if (entry !== null &&
+            typeof entry === 'object' &&
+            !Array.isArray(entry) &&
+            typeof entry.label === 'string' &&
+            typeof entry.value === 'number' &&
+            Number.isFinite(entry.value)) {
+            const e = entry;
+            out.push({ label: e.label, value: e.value });
+        }
+    }
+    return out;
+}
+/** Module-memoized default-locale formatter — the exact numbers `barRows` prints (SPEC-R6/R4's sibling rule). */
+const numberFormat = new Intl.NumberFormat();
+/**
+ * The zero-baseline diverging bar math (SPEC-R6 + LLD-C4): `lo = min(0, …values)`, `hi = max(0, …values)`,
+ * `span = hi − lo`. Empty input is an early `[]` (the codec/hardening boundary handles absence — this
+ * function is never asked to normalize zero rows). `span === 0` (the all-zero case) ⇒ every row is
+ * `startPct = lengthPct = 0`. Else `zeroPct = (−lo / span) · 100` is the ONE shared origin every row
+ * measures from; `lengthPct = |v| / span · 100`; `startPct = v ≥ 0 ? zeroPct : zeroPct − lengthPct`.
+ */
+export function barRows(data) {
+    if (data.length === 0)
+        return [];
+    let lo = 0;
+    let hi = 0;
+    for (const d of data) {
+        if (d.value < lo)
+            lo = d.value;
+        if (d.value > hi)
+            hi = d.value;
+    }
+    const span = hi - lo;
+    // `lo === 0` short-circuits to a literal `0` rather than `(-0 / span) * 100` — IEEE754 would otherwise
+    // hand back a NEGATIVE zero (`-0`) for the common all-positive case, which is numerically identical but
+    // needlessly surprising downstream (e.g. a strict `Object.is`-based equality check on the row's startPct).
+    const zeroPct = span === 0 || lo === 0 ? 0 : (-lo / span) * 100;
+    return data.map((d) => {
+        const text = numberFormat.format(d.value);
+        if (span === 0)
+            return { ...d, text, startPct: 0, lengthPct: 0 };
+        const lengthPct = (Math.abs(d.value) / span) * 100;
+        const startPct = d.value >= 0 ? zeroPct : zeroPct - lengthPct;
+        return { ...d, text, startPct, lengthPct };
+    });
+}
+/**
+ * The safe `data` codec (SPEC-R7 row 1/2): `from(null)` (the attribute absent/removed) → `[]`, never
+ * `null`; malformed attribute JSON is caught and also falls back to `[]` — no throw ever reaches
+ * `attributeChangedCallback`. Every parsed value (well-formed or not) is run through `cleanData`, so the
+ * property never carries a raw, un-hardened array — the codec and the SPEC-R7/case-3 property-write guard
+ * (bar-chart.ts's rows effect calls `cleanData(this.data)` again) share the one hardening function.
+ */
+const barDataType = {
+    from(attr) {
+        if (attr === null)
+            return [];
+        try {
+            return cleanData(JSON.parse(attr));
+        }
+        catch {
+            return [];
+        }
+    },
+    to(value) {
+        return JSON.stringify(value);
+    },
+};
+export const barDataProp = {
+    type: barDataType,
+    default: [],
+};

package/dist/controls/button/button.css

@@ -0,0 +1,263 @@
+/* button.css — ui-button, the single-file component stylesheet (ADR-0003). Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-button)` (specificity 0,0,0) DECLARES the `--ui-button-*` chain from the
+ *       colour roles (`--md-sys-color-{family}-{role}`; default family = primary) and the dimensional ramp
+ *       (`--ui-{height,font,gap}-{size}` from `@agent-ui-kit/shared/dimensions.css`). `[variant]` repoints the
+ *       colour channels (solid=filled · soft=tonal · ghost=text), declaring per-state `-bg-hover`/`-bg-active`
+ *       from a ROLE-LADDER step (never a `color-mix` — colour opinions live in the token layer; ADR-0008);
+ *       `[size]` repoints the geometry.
+ *   [2] STYLES BLOCK — `@scope (ui-button)` CONSUMES only `--ui-button-*` for its OWN tokens. Geometry per
+ *       references/geometry.md (the law): `block-size` off the ramp, `padding-block: 0`. Anatomy per ADR-0006
+ *       (extended by ADR-0012): host-as-grid with OPTIONAL leading `[slot=leading]` AND trailing `[slot=trailing]`
+ *       adornment slots via presence-driven `:has()` — placement is POSITION-driven (the slot), glyph size is
+ *       ROLE-driven (`[data-role]`: icon = frame `--ui-button-icon`, caret = rhythm `--ui-button-glyph` = font).
+ *       Interaction states (ADR-0008): `:hover`/`:active` repoint `background` from the per-state tokens;
+ *       `:focus-visible` draws the SHARED focus ring (ADR-0009 — the fleet `--md-sys-color-focus-ring`/`--md-sys-state-focus-ring-*`,
+ *       keyboard-only, layout-neutral `outline`). Forced-colors keeps the ink/border (the ring survives via the
+ *       token layer's `--md-sys-color-focus-ring → Highlight` mapping). The reflected `disabled` attribute makes the host inert.
+ *
+ * Standalone stylesheet — linked via the host page / component-styles barrel (Phase 2); NEVER injected from
+ * button.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-button) declares --ui-button-* ════════════════ */
+
+:where(ui-button) {
+  /* Colour channel (default family = primary). solid = filled (accent bg, on-accent ink). Per-state bg from
+     the DEDICATED interaction roles (--md-sys-color-primary · -hover · -active) — distinct steps in BOTH schemes, a role
+     step NOT a color-mix (ADR-0008 + its tok-states amendment that split the LIGHT --md-sys-color-primary-650 collapse). */
+  --ui-button-bg: var(--md-sys-color-primary);
+  --ui-button-bg-hover: var(--md-sys-color-primary-hover);
+  --ui-button-bg-active: var(--md-sys-color-primary-active);
+  --ui-button-ink: var(--md-sys-color-primary-on-primary);
+  --ui-button-border: transparent;
+
+  /* Geometry — off the s6 dimensional ramp (default size = md). [size] repoints below. */
+  --ui-button-height: var(--md-sys-height-md);
+  --ui-button-font: var(--md-sys-font-md);
+  --ui-button-gap: var(--md-sys-gap-md);
+  --ui-button-icon: var(--md-sys-icon-md); /* content-icon = the shared §1-SET icon table (ADR-0035 4a hoist, dimensions.css), per-[scale]-tier; was pow(scale,0.58) */
+  --ui-button-glyph: var(--ui-button-font); /* inline-affordance (caret) ramp = font (--ui-glyph-ratio 1, §4.1) */
+}
+
+/* variant → colour roles (the channel pattern, tokens.md). Per-state bg steps the matching ladder:
+   soft = CONTAINER ladder (-container-low · -container · -container-high); ghost = TEXT (transparent idle,
+   a low container WASH on hover/active — ADR-0008's ghost wash). No color-mix; every value is a role. */
+:where(ui-button[variant='soft']) {
+  --ui-button-bg: var(--md-sys-color-primary-container-low);
+  --ui-button-bg-hover: var(--md-sys-color-primary-container);
+  --ui-button-bg-active: var(--md-sys-color-primary-container-high);
+  --ui-button-ink: var(--md-sys-color-primary-high); /* accent label ink — reads as a primary-family action, not neutral text */
+}
+:where(ui-button[variant='ghost']) {
+  --ui-button-bg: transparent;
+  --ui-button-bg-hover: var(--md-sys-color-primary-container-low);
+  --ui-button-bg-active: var(--md-sys-color-primary-container);
+  --ui-button-ink: var(--md-sys-color-primary-high); /* accent label ink (same as soft) — the transparent/wash variant still reads as primary */
+}
+
+/* size → dimensional ramp */
+:where(ui-button[size='sm']) {
+  --ui-button-height: var(--md-sys-height-sm);
+  --ui-button-font: var(--md-sys-font-sm);
+  --ui-button-gap: var(--md-sys-gap-sm);
+  --ui-button-icon: var(--md-sys-icon-sm); /* §1-SET icon table (ADR-0035) */
+}
+:where(ui-button[size='lg']) {
+  --ui-button-height: var(--md-sys-height-lg);
+  --ui-button-font: var(--md-sys-font-lg);
+  --ui-button-gap: var(--md-sys-gap-lg);
+  --ui-button-icon: var(--md-sys-icon-lg); /* §1-SET icon table (ADR-0035) */
+}
+
+/* disabled → muted neutral roles (overrides the family). HOLDS at idle: -bg-hover/-bg-active repoint to the
+   same muted neutral so no path lifts (and :hover/:active never match — the styles block makes the host
+   pointer-inert; ADR-0008). */
+:where(ui-button[disabled]) {
+  --ui-button-bg: var(--md-sys-color-neutral-surface-high);
+  --ui-button-bg-hover: var(--md-sys-color-neutral-surface-high);
+  --ui-button-bg-active: var(--md-sys-color-neutral-surface-high);
+  --ui-button-ink: var(--md-sys-color-neutral-on-surface-variant);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-button) consumes ONLY --ui-button-* ════════════════ */
+
+@scope (ui-button) {
+  :scope {
+    display: inline-grid;
+    grid-template-columns: 1fr; /* bare label — slotless */
+    align-items: center;
+    box-sizing: border-box;
+
+    block-size: var(--ui-button-height); /* the vertical lever — geometry.md */
+    padding-block: 0; /* NEVER block-padding */
+    padding-inline: calc(var(--ui-button-height) / 2); /* slotless edge = h/2 */
+    min-inline-size: var(--ui-button-height); /* frame: icon-only ≈ square */
+
+    font-size: var(--ui-button-font);
+    line-height: var(--md-sys-control-line-height); /* single-line control standard — ADR-0036; tight line box centered in the fixed frame */
+    white-space: nowrap; /* a control label NEVER wraps (Kim, 2026-07-08 — the gallery toolbar's two-line
+                            "More actions"); the ADR-0036 single-line frame assumes one line, so wrapping
+                            was always an overflow of the control's own contract. Inherits into the label
+                            wrapper below for free — ellipsis-on-constraint is completed there (ADR-0133). */
+    background: var(--ui-button-bg);
+    color: var(--ui-button-ink);
+    border: 1px solid var(--ui-button-border);
+    border-radius: calc(var(--ui-button-height) / 2); /* pill radius = h/2 */
+    cursor: pointer;
+    -webkit-user-select: none; /* WebKit/Safari still needs the prefix — the label is a control surface, not selectable text */
+    user-select: none;
+  }
+
+  /* The label wrapper (ADR-0133) — the real element button.ts adopts the label region into, so
+     `text-overflow` has a real box to attach to (anonymous grid text has none). `white-space: nowrap`
+     already lives on `:scope` above and inherits here for free — only the two CLIPPING properties are
+     needed. `min-inline-size: 0` overrides the grid item's default `min-width: auto` (its content's
+     intrinsic size), which would otherwise refuse to shrink below the label's full width and defeat the
+     clip — the one addition ADR-0106's block-level two-leg pattern never needed, host-as-grid's own. */
+  :scope > [data-part='label'] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    min-inline-size: 0;
+  }
+
+  /* Anatomy (ADR-0006, extended by ADR-0012): host-as-grid with three POSITION regions — an OPTIONAL leading
+     [slot=leading] adornment, the LABEL (the default/unnamed children — the accessible name), and an OPTIONAL
+     trailing [slot=trailing] adornment — each presence-driven via :has(). Five structures:
+     [label] · [leading | label] · [label | trailing] · [leading | label | trailing] · [icon-only, no label]
+     (the last is an explicit author opt-in, `[icon-only]` — CSS cannot detect an empty/text-node label on its
+     own; see the `:scope[icon-only]` rule below, geometry.md "icon-only (no label) → square"). Each adornment
+     gets a square, icon-sized CELL with edge-pad ½(h−icon); a bare (slotless) edge stays h/2; the column-gap is
+     the one density-bearing quantity (gap = font/2 × density).
+     POSITION (the slot) PLACES; ROLE (`data-role` on the node — icon · caret now, tag · badge later) SIZES the
+     glyph (ADR-0012 / geometry-sizing-spec §1.4, §4.6 — frame ∝ height vs rhythm ∝ font). Adornments are
+     decorative (aria-hidden); popup/disclosure meaning belongs on the host via ARIA (ElementInternals). */
+
+  /* The CELL — both adornment slots get the SAME square, icon-sized cell (border-box, so a role's inset stays
+     WITHIN the icon-sized cell). The cell stays icon-sized for BOTH roles → the grid column is icon-wide and
+     the centering law (slot edge-pad ½(h−icon)) holds whichever role sits in it. */
+  :scope > [slot='leading'],
+  :scope > [slot='trailing'] {
+    inline-size: var(--ui-button-icon);
+    block-size: var(--ui-button-icon); /* the square slot, icon-sized — the CELL */
+    box-sizing: border-box; /* padding insets the glyph WITHIN the icon-sized cell (the caret centering) */
+  }
+
+  /* ROLE = glyph size (the "position places, role sizes" split). The CELL above stays icon-sized for both
+     roles; only the GLYPH inside differs by role:
+       • icon  — a content icon (FRAME family) FILLS the icon-sized cell (= --ui-button-icon).
+       • caret — an inline affordance (RHYTHM family) is sized to the FONT (--ui-button-glyph = font) and
+         CENTERED in the icon-sized cell by a ½(icon−font) inset, so its glyph lands at the EMERGENT ½(h−font)
+         edge — never --ui-ind (an inline affordance at icon size is the named oversize "button caret" bug,
+         geometry.md §"Affordance vs content-icon"; locked by the BTN-CARET probe). */
+  :scope > [data-role='icon'] {
+    padding: 0; /* fills its icon-sized cell */
+  }
+  :scope > [data-role='caret'] {
+    padding: calc((var(--ui-button-icon) - var(--ui-button-glyph)) / 2); /* inset the font glyph, centered in the icon cell */
+  }
+
+  /* [leading | label] (no trailing): auto 1fr — leading slot edge ½(h−icon), trailing label edge h/2.
+     :not([icon-only]) — the icon-only structure below is the mutually-exclusive fifth anatomy. */
+  :scope:has(> [slot='leading']):not(:has(> [slot='trailing'])):not([icon-only]) {
+    grid-template-columns: auto 1fr;
+    column-gap: var(--ui-button-gap);
+    padding-inline-start: calc((var(--ui-button-height) - var(--ui-button-icon)) / 2);
+    padding-inline-end: calc(var(--ui-button-height) / 2);
+  }
+
+  /* [label | trailing] (no leading): 1fr auto — leading label edge h/2, trailing slot edge ½(h−icon).
+     :not([icon-only]) — same exclusion. */
+  :scope:has(> [slot='trailing']):not(:has(> [slot='leading'])):not([icon-only]) {
+    grid-template-columns: 1fr auto;
+    column-gap: var(--ui-button-gap);
+    padding-inline-start: calc(var(--ui-button-height) / 2);
+    padding-inline-end: calc((var(--ui-button-height) - var(--ui-button-icon)) / 2);
+  }
+
+  /* [leading | label | trailing]: auto 1fr auto — both adornment edges ½(h−icon), one gap rhythm on each
+     side. :not([icon-only]) — same exclusion. */
+  :scope:has(> [slot='leading']):has(> [slot='trailing']):not([icon-only]) {
+    grid-template-columns: auto 1fr auto;
+    column-gap: var(--ui-button-gap);
+    padding-inline-start: calc((var(--ui-button-height) - var(--ui-button-icon)) / 2);
+    padding-inline-end: calc((var(--ui-button-height) - var(--ui-button-icon)) / 2);
+  }
+
+  /* [icon-only] (no label): the geometry law's FIFTH structure (geometry.md "icon-only (no label) →
+     square") — a real slotted adornment with no label content at all. CSS cannot detect an empty/
+     text-node label on its own (`:has()` only matches elements, so a bare text-node label is invisible
+     to it), so this is an explicit author opt-in (the reflected `icon-only` attribute, button.ts).
+     `inline-size` is set EXPLICITLY (mirroring `block-size` exactly) rather than left intrinsic: under
+     `box-sizing: border-box` an EXPLICIT size makes border eat into the content box on BOTH axes
+     identically, giving a byte-exact square regardless of border width. A literal ½(h−icon) PADDING
+     would instead let intrinsic sizing add the border ON TOP of content+padding (no reinterpretation
+     without an explicit size to reinterpret), overshooting the square by the border width — the bug
+     this structure closes. `justify-content: center` centers the single icon-sized column the SAME way
+     the pre-existing `align-items: center` (base :scope rule) already centers it on the block axis — no
+     literal padding needed; the border cancels out of the maths, so the rendered inset still lands at
+     the law's ½(h−icon), measured from the outer edge. No column-gap (no label track to gap against).
+     Assumes a single adornment (leading OR trailing, not both) — the documented icon-only pattern. */
+  :scope[icon-only] {
+    grid-template-columns: auto;
+    inline-size: var(--ui-button-height);
+    padding-inline: 0;
+    justify-content: center;
+  }
+
+  /* Interaction states (ADR-0008) — repoint ONLY `background`, from the per-state ladder tokens (the geometry
+     law is untouched). Disabled holds at idle: the disabled host is pointer-inert (below), so :hover/:active
+     never match it. */
+  :scope:hover {
+    background: var(--ui-button-bg-hover);
+  }
+  :scope:active {
+    background: var(--ui-button-bg-active);
+  }
+
+  /* Focus ring (ADR-0009) — the SHARED fleet ring: `:focus-visible` (KEYBOARD-only, no ring on a mouse click)
+     draws a layout-neutral `outline` from the shared tokens. These are the ONE deliberate exception to the
+     "consume only --ui-button-*" rule: a focus ring is a fleet constant (read directly, NOT repointed through
+     the component chain) so every control draws the identical ring. `outline`/`outline-offset` do not
+     participate in box geometry — the geometry law stays intact. (Disabled is removed from the tab order by
+     the tabbable trait, so a disabled host never draws the ring.) */
+  :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 (ADR-0008 / interaction-states standard) — transition the state-PAINT properties ONLY
+     (background/colour/border colour), enumerated (never `transition: all`). Geometry is NEVER transitioned: a
+     [scale]/[size]/[density] change must SNAP — animating the --ui ramp fights the sizing law (geometry.md) and
+     reads as jank — and the keyboard focus ring stays instant (outline is omitted from the list). The rule is
+     gated behind the :state(ready) custom state, set in button.ts ONE FRAME PAST first paint, so the upgrade/
+     first-paint styling snaps in and only SUBSEQUENT hover/active/variant changes animate (no first-render flash). */
+  :scope:state(ready) {
+    transition:
+      background-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard),
+      color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard),
+      border-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :scope:state(ready) {
+      transition: none; /* accessibility (non-negotiable) — reduced motion zeroes the state transitions */
+    }
+  }
+
+  /* disabled host — pointer-inert (the reflected `disabled` attribute); makes :hover/:active inert so the
+     state overlay holds at idle */
+  :scope:is([disabled]) {
+    pointer-events: none;
+    cursor: default;
+  }
+
+  /* forced-colors — keep the ink + border visible (the label/outline must not vanish). The focus ring
+     survives for free: `--md-sys-color-focus-ring` carries the token layer's `→ Highlight` WHCM mapping, so the
+     `:focus-visible` outline above resolves to the system focus colour with no per-control rule. */
+  @media (forced-colors: active) {
+    :scope {
+      color: ButtonText;
+      border-color: ButtonText;
+    }
+  }
+}

package/dist/controls/button/button.d.ts

@@ -0,0 +1,61 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    variant: {
+        reflect: true;
+        type: import("../../index.js").PropType<"solid" | "soft" | "ghost">;
+        default: "solid" | "soft" | "ghost";
+        attribute?: string | false;
+    };
+    size: {
+        reflect: true;
+        type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+        default: "sm" | "md" | "lg";
+        attribute?: string | false;
+    };
+    disabled: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    iconOnly: {
+        reflect: true;
+        attribute: string;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+    };
+};
+export interface UIButtonElement extends ReactiveProps<typeof props> {
+}
+export declare class UIButtonElement extends UIElement {
+    #private;
+    static props: {
+        variant: {
+            reflect: true;
+            type: import("../../index.js").PropType<"solid" | "soft" | "ghost">;
+            default: "solid" | "soft" | "ghost";
+            attribute?: string | false;
+        };
+        size: {
+            reflect: true;
+            type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+            default: "sm" | "md" | "lg";
+            attribute?: string | false;
+        };
+        disabled: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        iconOnly: {
+            reflect: true;
+            attribute: string;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+        };
+    };
+    protected connected(): void;
+    protected disconnected(): void;
+}
+export {};