@adia-ai/web-components 0.0.20 → 0.0.22

package/README.md

@@ -199,7 +199,7 @@ the `streams` registry export from `core/data-stream.js`.
 
 Implementation: `core/data-stream.js` (~360 lines). Full
 attribute table + live demos:
-[`/site/components/chart#data-stream`](./site/pages/components/chart/index.html).
+[`/site/components/chart#data-stream`](../../site/pages/components/chart/index.html).
 
 ## Build
 

package/components/agent-reasoning/agent-reasoning.js

@@ -371,9 +371,12 @@ class AdiaAgentReasoning extends AdiaElement {
   #makeStepItem(step) {
     const item = document.createElement('timeline-item-ui');
     item.setAttribute('text', step.label || '');
-    if (step.status === 'done')   item.setAttribute('completed', '');
-    if (step.status === 'error')  item.setAttribute('error', '');
-    if (step.status === 'active') { item.setAttribute('active', ''); item.setAttribute('spinner', ''); }
+    // Map step.status → canonical timeline-item-ui [status] enum.
+    // The legacy [completed]/[active]/[error] Booleans were removed
+    // in the Phase 6 cut (2026-04-27); only [status] is honoured.
+    if (step.status === 'done')   item.setAttribute('status', 'completed');
+    if (step.status === 'error')  item.setAttribute('status', 'error');
+    if (step.status === 'active') { item.setAttribute('status', 'active'); item.setAttribute('spinner', ''); }
 
     const duration = step.durationLabel
       || (step.duration != null ? formatDuration(step.duration) : '');

package/components/alert/alert.css

@@ -5,8 +5,6 @@
     --alert-fg:       var(--a-fg);
     --alert-border:   var(--a-border-subtle);
     --alert-icon-fg:  var(--a-fg-muted);
-    --alert-close-fg:       var(--a-fg-muted);
-    --alert-close-fg-hover: var(--a-fg);
 
     /* ── Layout ── */
     --alert-radius:   var(--a-radius-md);
@@ -15,19 +13,25 @@
     --alert-gap:      var(--a-space-2);
 
     /* ── Typography ── */
-    --alert-font:     var(--a-ui-size);
+    --alert-font:        var(--a-ui-size);
+    --alert-line-height: var(--a-ui-line-height, 1.5);
   }
 
   :scope {
     /* ── Base ── */
     box-sizing: border-box;
     display: flex;
-    align-items: center;
+    /* `align-items: start` so the leading icon and close button anchor
+       to the top — keeps the icon visually paired with the first line of
+       text on multi-line alerts. The leading slot's own height = body
+       line-height (below) means the icon optically centers on line 1. */
+    align-items: start;
     gap: var(--alert-gap);
     padding: var(--alert-py) var(--alert-px);
     border: 1px solid var(--alert-border);
     border-radius: var(--alert-radius);
     font-size: var(--alert-font);
+    line-height: var(--alert-line-height);
     color: var(--alert-fg);
     background: var(--alert-bg);
   }
@@ -65,6 +69,11 @@
   :scope [slot="leading"] {
     flex-shrink: 0;
     color: var(--alert-icon-fg);
+    /* Box height = one line of body so the icon optical-centers on the
+       first line under `align-items: start`. */
+    display: inline-flex;
+    align-items: center;
+    min-height: calc(var(--alert-font) * var(--alert-line-height));
     /* `ensure()` appends the leading-slot icon to the host, which
        puts it after any consumer-provided content in DOM order.
        Force it to the visual lead via flex `order` so the icon
@@ -77,17 +86,12 @@
     min-width: 0;
   }
 
+  /* Close button is a `<button-ui icon="x" variant="ghost" size="sm">`
+     stamped by alert.js — it brings its own focus ring, hover state,
+     and transitions. Box height matches the leading slot so X and icon
+     sit on the same first-line baseline. */
   :scope [slot="close"] {
-    background: none;
-    border: none;
-    cursor: pointer;
-    color: var(--alert-close-fg);
-    padding: 0;
-    line-height: 1;
-    font-size: 1rem;
-  }
-
-  :scope [slot="close"]:hover {
-    color: var(--alert-close-fg-hover);
+    flex-shrink: 0;
+    min-height: calc(var(--alert-font) * var(--alert-line-height));
   }
 }

package/components/alert/alert.js

@@ -24,22 +24,19 @@ class AdiaAlert extends AdiaElement {
   static parts = {
     leading: '<icon-ui slot="leading"></icon-ui>',
     content: '<span slot="content"></span>',
-    close:   '<button slot="close" type="button" aria-label="Close">\u00d7</button>',
+    /* Close affordance is a real button-ui \u2014 inherits the system focus
+       ring, hover transition, and icon sizing automatically. Listen for
+       the canonical `press` event (button-ui dispatches on click + Enter
+       + Space, no extra keydown wiring needed). */
+    close:   '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
   };
 
   static template = () => null;
 
-  #onClick = (e) => {
+  #onPress = (e) => {
     if (e.target.closest('[slot="close"]')) this.#close();
   };
 
-  #onKeydown = (e) => {
-    if (e.target.closest('[slot="close"]') && (e.key === 'Enter' || e.key === ' ')) {
-      e.preventDefault();
-      this.#close();
-    }
-  };
-
   connected() {
     this.#updateRole();
 
@@ -48,13 +45,11 @@ class AdiaAlert extends AdiaElement {
     this.ensure('content');
     if (this.closable) this.ensure('close');
 
-    this.addEventListener('click', this.#onClick);
-    this.addEventListener('keydown', this.#onKeydown);
+    this.addEventListener('press', this.#onPress);
   }
 
   disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKeydown);
+    this.removeEventListener('press', this.#onPress);
   }
 
   render() {

package/components/avatar/avatar.js

@@ -1,12 +1,13 @@
 /**
- * <avatar-ui src="photo.jpg" name="Alice Smith" size="md" shape="circle"></avatar-ui>
+ * <avatar-ui src="photo.jpg" text="Alice Smith" size="md" shape="circle"></avatar-ui>
  *
  * Fallback chain: image → initials → empty.
- * If src fails to load, falls back to initials derived from name.
+ * If src fails to load, falls back to initials derived from text.
+ * `name` is a deprecated alias for `text` (warns on use).
  *
  * <avatar-group-ui max="4" size="md">
- *   <avatar-ui name="Alice"></avatar-ui>
- *   <avatar-ui name="Bob"></avatar-ui>
+ *   <avatar-ui text="Alice"></avatar-ui>
+ *   <avatar-ui text="Bob"></avatar-ui>
  *   ...
  * </avatar-group-ui>
  *

package/components/card/card.css

@@ -61,6 +61,7 @@
     box-shadow: var(--card-shadow);
     overflow: hidden;
     corner-shape: superellipse(1.1);
+    width: stretch;
   }
 
   /* ═══════ Variants — token-only overrides ═══════ */

package/components/chart-legend/chart-legend.js

@@ -3,8 +3,8 @@
  *
  * Standalone legend primitive for the AdiaUI chart family. Renders a row
  * of badge-ui chips (swatch + label) that are keyboard-focusable and
- * click-toggleable — clicking emits a `legend-toggle` event that consumers
- * (or chart-ui via [for]) wire to series visibility.
+ * click-toggleable — clicking emits a canonical `toggle` event that
+ * consumers (or chart-ui via [for]) wire to series visibility.
  *
  * Attributes:
  *   for        — id-ref of a chart-ui / heatmap-ui to mirror. When set, the
@@ -23,12 +23,12 @@
  *   static     — when set, rows render as non-interactive <span>s. Default
  *                is interactive <button>s that toggle.
  *   on-toggle  — hide | opacity. Default hide. Escape hatch per OD-CHART-09.
- *                Reported via legend-toggle event detail; chart-ui reads it
+ *                Reported via the `toggle` event detail; chart-ui reads it
  *                when wired via [for].
  *
  * Events:
- *   legend-toggle — detail: {key, active, mode}. Fires on row click when
- *                   not [static]. `active` is the new state (true=visible).
+ *   toggle — detail: {key, active, mode}. Fires on row click when
+ *            not [static]. `active` is the new state (true=visible).
  */
 
 import { AdiaElement } from '../../core/element.js';

package/components/col/col.css

@@ -12,6 +12,9 @@
     gap: var(--col-gap);
     justify-content: var(--col-justify);
     align-items: var(--col-align);
+    /* Universal [padding] / [margin] opt-in — see tokens.css for scale. */
+    padding: var(--a-padding, 0);
+    margin: var(--a-margin, 0);
     /* Neutralize legacy UA rule that maps HTML `align=` attr to `text-align`.
        Our [align="center"] sets flex cross-axis alignment, not text alignment. */
     text-align: inherit;

package/components/description-list/description-list.css

@@ -17,19 +17,15 @@
   }
 
   :scope {
-    /* ── Base ── */
+    /* ── Base ── stacked layout (term above desc, single column). */
     box-sizing: border-box;
     display: grid;
+    grid-template-columns: 1fr;
     gap: var(--description-list-gap-row) var(--description-list-gap-column);
     margin: 0;
     padding: 0;
   }
 
-  /* Default stacked: term above desc. Each pair in its own implicit row. */
-  :scope {
-    grid-template-columns: 1fr;
-  }
-
   [data-dl-term],
   dt {
     margin: 0;
@@ -48,9 +44,13 @@
     line-height: 1.4;
   }
 
-  /* Separate pairs with extra gap when stacked */
-  :scope[layout="stacked"] [data-dl-desc]:not(:last-child),
-  :scope[layout="stacked"] dd:not(:last-child) {
+  /* Pair separator: extra margin under each non-last dd so DD→DT (between
+     pairs) reads as a wider gap than DT→DD (within a pair). Match anything
+     that isn't `[layout="inline"]` so the default case (no attribute set —
+     `layout` defaults to "stacked" but only reflects when explicitly set)
+     and the explicit `[layout="stacked"]` both get the same rhythm. */
+  :scope:not([layout="inline"]) [data-dl-desc]:not(:last-child),
+  :scope:not([layout="inline"]) dd:not(:last-child) {
     margin-bottom: var(--description-list-gap-row);
   }
 

package/components/grid/grid.css

@@ -1,6 +1,8 @@
 @scope (grid-ui) {
   :where(:scope) {
-    --grid-gap:        var(--a-gap-md);
+    /* Read `--a-gap` so the universal `[gap="N"]` rules (tokens.css)
+       reach the grid; defaults to `--a-gap-md` at :root. */
+    --grid-gap:        var(--a-gap);
     --grid-column-gap: var(--grid-gap);
     --grid-row-gap:    var(--grid-gap);
   }
@@ -13,6 +15,9 @@
     grid-auto-columns: 1fr;
     column-gap: var(--grid-column-gap);
     row-gap: var(--grid-row-gap);
+    /* Universal [padding] / [margin] opt-in — see tokens.css for scale. */
+    padding: var(--a-padding, 0);
+    margin: var(--a-margin, 0);
   }
 
   /* Explicit column count — switches to template mode */

package/components/input/input.css

@@ -69,7 +69,13 @@
        baseline centered regardless of line-height. */
     line-height: 1.4;
     cursor: text;
-    transition: border-color var(--input-duration) var(--input-easing);
+    /* Cover every property the hover / focus / invalid states change so
+       the field doesn't half-snap (border slides, but bg/colour/ring snap). */
+    transition:
+      background  var(--input-duration) var(--input-easing),
+      border-color var(--input-duration) var(--input-easing),
+      color       var(--input-duration) var(--input-easing),
+      box-shadow  var(--input-duration) var(--input-easing);
   }
   :scope:not([disabled]) [slot="field"]:hover {
     background: var(--input-bg-hover);

package/components/list/list.css

@@ -57,6 +57,14 @@
     border-inline-start: 2px solid transparent;
     padding-inline-start: var(--a-space-2);
     outline: none;
+    transition:
+      background   var(--a-duration-fast) var(--a-easing),
+      color        var(--a-duration-fast) var(--a-easing),
+      border-color var(--a-duration-fast) var(--a-easing);
+  }
+
+  :scope[selectable] > [role="listitem"]:hover {
+    background: var(--a-bg-hover);
   }
 
   :scope[selectable] > [role="listitem"][aria-selected="true"] {

package/components/modal/modal.js

@@ -143,11 +143,47 @@ class AdiaModal extends AdiaElement {
       this.drop('close');
     }
 
-    const body = this.ensure('body');
-    if (body.parentElement !== panel) panel.appendChild(body);
+    // Body — accept bare `<section>` tags, explicit `[slot="body"]`, OR
+    // unslotted light-DOM children (so `<modal-ui><p>…</p></modal-ui>` works
+    // with no markup ceremony). Mirrors drawer-ui's authoring contract.
+    const authorBody = [...this.children].find(c =>
+      c.getAttribute('slot') === 'body' || (!c.getAttribute('slot') && c.localName === 'section')
+    );
+    const looseChildren = [...this.children].filter(c =>
+      !c.getAttribute('slot') && c.localName !== 'section' && c.localName !== 'dialog' && c.localName !== 'footer'
+    );
+
+    let body;
+    if (authorBody) {
+      if (authorBody.getAttribute('slot') !== 'body') authorBody.setAttribute('slot', 'body');
+      if (authorBody.parentElement !== panel) panel.appendChild(authorBody);
+      panel.querySelector(':scope > [slot="body"][data-stamped]')?.remove();
+      body = authorBody;
+    } else {
+      body = this.ensure('body');
+      body.setAttribute('data-stamped', '');
+      if (body.parentElement !== panel) panel.appendChild(body);
+    }
+
+    // Migrate any remaining unslotted light-DOM children into the body so
+    // `<modal-ui><p>…</p></modal-ui>` lands in the visible region.
+    for (const child of looseChildren) {
+      if (child !== body) body.appendChild(child);
+    }
 
-    const footer = this.ensure('footer');
-    if (footer.parentElement !== panel) panel.appendChild(footer);
+    // Footer — opt-in via [slot="footer"] or bare <footer> tag (card-ui style).
+    const userFooter = [...this.children].find(c =>
+      c.getAttribute('slot') === 'footer' || (!c.getAttribute('slot') && c.localName === 'footer')
+    );
+    if (userFooter) {
+      if (userFooter.getAttribute('slot') !== 'footer') userFooter.setAttribute('slot', 'footer');
+      if (userFooter.parentElement !== panel) panel.appendChild(userFooter);
+      panel.querySelector(':scope > [slot="footer"][data-stamped]')?.remove();
+    } else {
+      const footer = this.ensure('footer');
+      footer.setAttribute('data-stamped', '');
+      if (footer.parentElement !== panel) panel.appendChild(footer);
+    }
 
     // Sync open state
     if (this.open && !dialog.open) {

package/components/pipeline-status/pipeline-status.js

@@ -7,9 +7,11 @@ import { AdiaElement } from '../../core/element.js';
  * an expandable history log. Auto-collapses when the pipeline finishes.
  *
  * Properties:
- *   stage    : String  — current stage name (interpret, analyze, plan, generate, validate, render)
- *   message  : String  — current stage description
- *   complete : Boolean — when true, shows final state and collapses history
+ *   stage   : String — current stage name (interpret, analyze, plan, generate, validate, render)
+ *   message : String — current stage description
+ *   status  : String — 'idle' | 'active' | 'completed' | 'error'. Set to
+ *                       'completed' to render the final state and collapse
+ *                       the history log.
  */
 
 const STAGE_LABELS = {

package/components/progress/progress.css

@@ -37,6 +37,14 @@
     border-radius: var(--progress-radius);
     background: var(--progress-fill);
     transition: width var(--progress-duration) var(--progress-easing);
+
+    /* Enter animation: paint the fill at 0 on first frame, then transition
+       to the inline width set by JS — so a freshly-mounted determinate bar
+       animates 0 → value rather than snapping in (or, in some cascades,
+       briefly painting at the indeterminate width:100% before settling). */
+    @starting-style {
+      width: 0;
+    }
   }
 
   /* Indeterminate bar shimmer */

package/components/progress-row/progress-row.js

@@ -53,6 +53,15 @@ class AdiaProgressRow extends AdiaElement {
     this.#progressEl = this.querySelector(':scope > progress-ui');
     if (!this.#progressEl) {
       this.#progressEl = document.createElement('progress-ui');
+      // Pre-set value BEFORE append so progress-ui's first paint is
+      // determinate at the target value — `@starting-style { width: 0 }`
+      // in progress.css then transitions 0 → value on mount. Without this,
+      // the bar mounts indeterminate (width: 100% from the shimmer rule),
+      // and `render()` setting value: N triggers a backwards 100% → N
+      // animation, which reads as the bar shrinking right-to-left.
+      if (this.value != null && this.value >= 0) {
+        this.#progressEl.setAttribute('value', String(this.value));
+      }
       this.appendChild(this.#progressEl);
     }
   }

package/components/richtext/richtext.css

@@ -128,6 +128,29 @@
     margin: var(--richtext-h4-margin-top) 0 var(--richtext-h4-margin-bottom);
   }
 
+  [data-richtext-body] h5 {
+    font-size: var(--richtext-body-size);
+    font-weight: var(--richtext-h4-weight);
+    color: var(--richtext-fg-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    margin: var(--richtext-h4-margin-top) 0 var(--richtext-h4-margin-bottom);
+  }
+
+  [data-richtext-body] h6 {
+    font-size: var(--richtext-code-size);
+    font-weight: var(--richtext-h4-weight);
+    color: var(--richtext-fg-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    margin: var(--richtext-h4-margin-top) 0 var(--richtext-h4-margin-bottom);
+  }
+
+  /* First-element rhythm reset — first heading shouldn't push content
+     down with its top margin (already controlled at the body inset). */
+  [data-richtext-body] > :first-child { margin-top: 0; }
+  [data-richtext-body] > :last-child { margin-bottom: 0; }
+
   /* ── Body text ── */
 
   [data-richtext-body] p {
@@ -180,6 +203,112 @@
     margin-bottom: var(--richtext-li-margin-bottom);
   }
 
+  /* Nested lists — collapse the vertical block margin so children
+     don't add a full paragraph gap before/after the parent <li>. */
+  [data-richtext-body] li > ul,
+  [data-richtext-body] li > ol {
+    margin-block: var(--a-space-1);
+  }
+
+  /* ── Definition lists ── */
+  [data-richtext-body] dl {
+    margin: var(--richtext-list-my) 0;
+  }
+  [data-richtext-body] dt {
+    font-weight: var(--richtext-strong-weight);
+    color: var(--richtext-fg);
+    margin-top: var(--a-space-2);
+  }
+  [data-richtext-body] dd {
+    margin: 0 0 var(--richtext-li-margin-bottom) var(--richtext-list-indent);
+    color: var(--richtext-fg-muted);
+  }
+
+  /* ── Blockquote ── */
+  [data-richtext-body] blockquote {
+    margin: var(--richtext-block-my) 0;
+    padding: var(--a-space-1) var(--a-space-4);
+    border-inline-start: 3px solid var(--richtext-border);
+    color: var(--richtext-fg-muted);
+    font-style: italic;
+  }
+  [data-richtext-body] blockquote > :last-child { margin-bottom: 0; }
+
+  /* ── Inline emphasis & semantic glyphs ── */
+  [data-richtext-body] mark {
+    background: var(--a-warning-muted, var(--richtext-code-bg));
+    color: inherit;
+    padding: 0 0.2em;
+    border-radius: var(--richtext-code-radius);
+  }
+  [data-richtext-body] del,
+  [data-richtext-body] s {
+    color: var(--richtext-fg-muted);
+    text-decoration: line-through;
+  }
+  [data-richtext-body] kbd {
+    font-family: var(--richtext-font-code);
+    font-size: 0.85em;
+    background: var(--richtext-code-bg);
+    border: 1px solid var(--richtext-border);
+    border-bottom-width: 2px;
+    border-radius: var(--richtext-code-radius);
+    padding: 0.05em 0.4em;
+    box-shadow: inset 0 -1px 0 var(--richtext-border);
+    white-space: nowrap;
+  }
+  [data-richtext-body] sup,
+  [data-richtext-body] sub {
+    font-size: 0.75em;
+    line-height: 0;
+  }
+  [data-richtext-body] abbr[title] {
+    text-decoration: underline dotted;
+    text-underline-offset: 2px;
+    cursor: help;
+  }
+
+  /* ── Media ── */
+  [data-richtext-body] img,
+  [data-richtext-body] video {
+    max-width: 100%;
+    height: auto;
+    display: block;
+    margin: var(--richtext-block-my) auto;
+    border-radius: var(--richtext-pre-radius);
+  }
+  [data-richtext-body] figure {
+    margin: var(--richtext-block-my) 0;
+  }
+  [data-richtext-body] figcaption {
+    font-size: var(--richtext-code-size);
+    color: var(--richtext-fg-muted);
+    text-align: center;
+    margin-top: var(--a-space-1);
+  }
+
+  /* ── Disclosure ── */
+  [data-richtext-body] details {
+    margin: var(--richtext-block-my) 0;
+    border: 1px solid var(--richtext-border);
+    border-radius: var(--richtext-pre-radius);
+    padding: var(--a-space-3) var(--a-space-4);
+  }
+  [data-richtext-body] details[open] {
+    background: var(--richtext-code-bg);
+  }
+  [data-richtext-body] summary {
+    cursor: pointer;
+    font-weight: var(--richtext-strong-weight);
+    margin: calc(-1 * var(--a-space-3)) calc(-1 * var(--a-space-4));
+    padding: var(--a-space-3) var(--a-space-4);
+    list-style-position: inside;
+  }
+  [data-richtext-body] details[open] summary {
+    margin-bottom: var(--a-space-2);
+    border-bottom: 1px solid var(--richtext-border);
+  }
+
   /* ── Tables ── */
 
   [data-richtext-body] table {
@@ -217,9 +346,18 @@
     color: var(--richtext-link);
     text-decoration: underline;
     text-underline-offset: 2px;
+    transition: color var(--a-duration-fast) var(--a-easing);
   }
 
   [data-richtext-body] a:hover {
     color: var(--richtext-link-hover);
   }
+
+  [data-richtext-body] a:focus-visible {
+    outline: var(--a-focus-ring);
+    outline-offset: 2px;
+    border-radius: var(--a-radius-sm);
+  }
+
+  [data-richtext-body] small { font-size: var(--richtext-code-size); color: var(--richtext-fg-muted); }
 }

package/components/row/row.css

@@ -1,6 +1,9 @@
 @scope (row-ui) {
   :where(:scope) {
-    --row-gap:     var(--a-gap-md);
+    /* `--a-gap` defaults to `--a-gap-md` at :root in tokens.css; the
+       universal `[gap="N"]` rules override it on the element, so reading
+       `--a-gap` here picks up `<row-ui gap="…">` automatically. */
+    --row-gap:     var(--a-gap);
     --row-justify: flex-start;
     --row-align:   center;
     --row-drag-bg-active: var(--a-accent-muted);
@@ -13,6 +16,9 @@
     gap: var(--row-gap);
     justify-content: var(--row-justify);
     align-items: var(--row-align);
+    /* Universal [padding] / [margin] opt-in — see tokens.css for scale. */
+    padding: var(--a-padding, 0);
+    margin: var(--a-margin, 0);
     text-align: inherit;
   }
 

package/components/select/select.css

@@ -84,9 +84,12 @@
     background: var(--select-bg);
     line-height: 1;
     cursor: pointer;
+    /* Match every property the hover / focus / invalid states change. */
     transition:
+      background   var(--select-duration) var(--select-easing),
       border-color var(--select-duration) var(--select-easing),
-      background   var(--select-duration) var(--select-easing);
+      color        var(--select-duration) var(--select-easing),
+      box-shadow   var(--select-duration) var(--select-easing);
   }
   [slot="trigger"]:hover {
     border-color: var(--select-border-hover);

package/components/stack/stack.css

@@ -7,6 +7,9 @@
     box-sizing: border-box;
     display: grid;
     place-items: var(--stack-align);
+    /* Universal [padding] / [margin] opt-in — see tokens.css for scale. */
+    padding: var(--a-padding, 0);
+    margin: var(--a-margin, 0);
     /* Same UA override as row-ui/col-ui: [align=...] is for flex/grid, not text. */
     text-align: inherit;
   }

package/components/stepper/stepper.css

@@ -32,10 +32,17 @@
     --stepper-line-done:       var(--a-accent);
     --stepper-line-size:       2px;
 
-    /* ── Layout ── */
+    /* ── Layout ──
+       Parent tokens use the bare `--stepper-*` name (no `-item-` infix)
+       so the child's `:where(stepper-item-ui)` block can pull from
+       parent → child via `var(--stepper-X, …)` without name collisions.
+       A self-named child declaration like
+       `--stepper-item-gap-sm: var(--stepper-item-gap-sm, …)` resolves
+       to invalid (cycle), which silently breaks any calc() that
+       consumes it. */
     --stepper-radius-full:     var(--a-radius-full);
-    --stepper-item-gap:        var(--a-space-3);
-    --stepper-item-gap-sm:     var(--a-space-2);
+    --stepper-gap:             var(--a-space-3);
+    --stepper-gap-sm:          var(--a-space-2);
     --stepper-pad-x:           var(--a-space-4);
     --stepper-pad-y:           var(--a-space-6);
     --stepper-offset-xs:       var(--a-space-1);
@@ -82,7 +89,8 @@
     --stepper-item-line-size:      var(--stepper-line-size, 2px);
 
     --stepper-item-radius-full:    var(--a-radius-full);
-    --stepper-item-gap-sm:         var(--stepper-item-gap-sm, var(--a-space-2));
+    --stepper-item-gap:            var(--stepper-gap, var(--a-space-3));
+    --stepper-item-gap-sm:         var(--stepper-gap-sm, var(--a-space-2));
     --stepper-item-pad-x:          var(--stepper-pad-x, var(--a-space-4));
     --stepper-item-pad-y:          var(--stepper-pad-y, var(--a-space-6));
     --stepper-item-offset-xs:      var(--stepper-offset-xs, var(--a-space-1));

package/components/stepper/stepper.js

@@ -38,18 +38,18 @@ class AdiaStepper extends AdiaElement {
     const last = items[items.length - 1];
     if (last) last.setAttribute('data-last', '');
 
-    // Parent drives child state via step index
+    // Parent drives child state via step index. Canonical Phase 6
+    // contract: `status` enum (`completed` / `active` / `idle`).
+    // CSS only matches `[status="…"]`; the legacy `[completed]` /
+    // `[active]` Booleans were removed in 0.0.20.
     items.forEach((item, i) => {
       item.setAttribute('data-index', i);
       if (i < this.step) {
-        item.setAttribute('completed', '');
-        item.removeAttribute('active');
+        item.setAttribute('status', 'completed');
       } else if (i === this.step) {
-        item.removeAttribute('completed');
-        item.setAttribute('active', '');
+        item.setAttribute('status', 'active');
       } else {
-        item.removeAttribute('completed');
-        item.removeAttribute('active');
+        item.setAttribute('status', 'idle');
       }
     });
   }

package/components/swiper/swiper.css

@@ -89,6 +89,16 @@
 
   :scope > [data-swiper-track]::-webkit-scrollbar { display: none; }
 
+  /* Click-and-drag affordance for cursor users — touch keeps native pan. */
+  @media (hover: hover) {
+    :scope > [data-swiper-track] { cursor: grab; }
+    :scope > [data-swiper-track][data-dragging] {
+      cursor: grabbing;
+      scroll-snap-type: none;       /* let the pointer track 1:1 during drag */
+      user-select: none;
+    }
+  }
+
   /* ── Slides ── */
 
   :scope > [data-swiper-track] > * {

package/components/swiper/swiper.js

@@ -43,6 +43,7 @@ class AdiaSwiper extends AdiaElement {
   #activeIndex = 0;
   #bound = false;
   #fallbackNav = false;
+  #drag = null; /* { pointerId, startX, startScrollLeft, hasMoved } */
 
   get slides() {
     if (!this.#track) return [];
@@ -88,6 +89,14 @@ class AdiaSwiper extends AdiaElement {
 
       // Keyboard navigation
       this.addEventListener('keydown', this.#onKeydown);
+
+      // Click + drag (mouse / pen). Touch keeps native pan via scroll-snap.
+      this.#track.addEventListener('pointerdown', this.#onPointerDown);
+      this.#track.addEventListener('pointermove', this.#onPointerMove);
+      this.#track.addEventListener('pointerup',     this.#onPointerUp);
+      this.#track.addEventListener('pointercancel', this.#onPointerUp);
+      // Capture-phase click suppression so a drag-on-button doesn't activate it.
+      this.#track.addEventListener('click', this.#onClickCapture, true);
     }
 
     if (this.autoplay) this.play();
@@ -109,6 +118,14 @@ class AdiaSwiper extends AdiaElement {
     this.removeEventListener('focusin', this.#onPauseFocus);
     this.removeEventListener('focusout', this.#onResumeFocus);
     this.removeEventListener('keydown', this.#onKeydown);
+    if (this.#track) {
+      this.#track.removeEventListener('pointerdown',   this.#onPointerDown);
+      this.#track.removeEventListener('pointermove',   this.#onPointerMove);
+      this.#track.removeEventListener('pointerup',     this.#onPointerUp);
+      this.#track.removeEventListener('pointercancel', this.#onPointerUp);
+      this.#track.removeEventListener('click',         this.#onClickCapture, true);
+    }
+    this.#drag = null;
     this.#track = null;
     this.#bound = false;
   }
@@ -280,6 +297,66 @@ class AdiaSwiper extends AdiaElement {
     if (e.key === 'ArrowRight') { e.preventDefault(); this.next(); }
     if (e.key === 'ArrowLeft') { e.preventDefault(); this.prev(); }
   };
+
+  // ── Click + drag (mouse / pen) ──
+  // Native touch already scroll-pans the track; we only intercept mouse and
+  // pen so cursor users get the same swipe affordance as touch users.
+
+  #DRAG_THRESHOLD_PX = 5;
+
+  #onPointerDown = (e) => {
+    if (e.pointerType === 'touch') return;        /* native pan handles touch */
+    if (e.button !== 0) return;                   /* primary button only */
+    if (e.target.closest('button, button-ui, a, input, select, textarea')) return;
+    this.#drag = {
+      pointerId: e.pointerId,
+      startX: e.clientX,
+      startScrollLeft: this.#track.scrollLeft,
+      hasMoved: false,
+    };
+    /* Disable smooth scroll during drag so the bar tracks the pointer 1:1. */
+    this.#track.style.scrollBehavior = 'auto';
+    this.#track.setAttribute('data-dragging', '');
+  };
+
+  #onPointerMove = (e) => {
+    if (!this.#drag || e.pointerId !== this.#drag.pointerId) return;
+    const dx = e.clientX - this.#drag.startX;
+    if (Math.abs(dx) >= this.#DRAG_THRESHOLD_PX) {
+      if (!this.#drag.hasMoved) {
+        this.#drag.hasMoved = true;
+        /* Capture pointer so we keep tracking even if it leaves the track. */
+        try { this.#track.setPointerCapture(e.pointerId); } catch { /* noop */ }
+      }
+      this.#track.scrollLeft = this.#drag.startScrollLeft - dx;
+      e.preventDefault(); /* suppress text selection while dragging */
+    }
+  };
+
+  #onPointerUp = (e) => {
+    if (!this.#drag || e.pointerId !== this.#drag.pointerId) return;
+    const wasMoved = this.#drag.hasMoved;
+    if (wasMoved) {
+      try { this.#track.releasePointerCapture(e.pointerId); } catch { /* noop */ }
+    }
+    this.#drag = null;
+    /* Re-enable smooth scrolling; scroll-snap will glide to the nearest slide. */
+    this.#track.style.scrollBehavior = '';
+    this.#track.removeAttribute('data-dragging');
+    /* Ensure dragging stays "active" through the click event that follows
+       on the same gesture so #onClickCapture can suppress it. */
+    if (wasMoved) {
+      this.#track.setAttribute('data-just-dragged', '');
+      requestAnimationFrame(() => this.#track?.removeAttribute('data-just-dragged'));
+    }
+  };
+
+  #onClickCapture = (e) => {
+    if (this.#track?.hasAttribute('data-just-dragged')) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
 }
 
 customElements.define('swiper-ui', AdiaSwiper);

package/components/switch/switch.css

@@ -89,7 +89,9 @@
     border-radius: var(--switch-radius);
     background: var(--switch-thumb-bg);
     box-shadow: var(--switch-thumb-shadow);
-    transition: transform var(--switch-duration) var(--switch-easing);
+    transition:
+      transform  var(--switch-duration) var(--switch-easing),
+      background var(--switch-duration) var(--switch-easing);
   }
   :scope[checked] [slot="thumb"] {
     transform: translateX(var(--switch-thumb-travel));

package/components/timeline/timeline.js

@@ -1,21 +1,23 @@
 /**
  * <timeline-ui> — Vertical (or horizontal) event / progress log.
  *
- * Each <timeline-item-ui> is one entry, with its own state (completed / active
- * / error), optional icon, duration, and an expandable outcomes list.
+ * Each <timeline-item-ui> is one entry, with its own state via the `status`
+ * enum (idle | active | completed | error), optional icon, duration, and an
+ * expandable outcomes list. `[spinner]` is an orthogonal presentation hint
+ * that animates the dot as a ring when combined with `status="active"`.
  *
  *   <timeline-ui>
- *     <timeline-item-ui text="Shipped"   time="2h ago" completed></timeline-item-ui>
- *     <timeline-item-ui text="Delivery"  time="now"    active spinner></timeline-item-ui>
- *     <timeline-item-ui text="Received"                         ></timeline-item-ui>
+ *     <timeline-item-ui text="Shipped"   time="2h ago" status="completed"></timeline-item-ui>
+ *     <timeline-item-ui text="Delivery"  time="now"    status="active" spinner></timeline-item-ui>
+ *     <timeline-item-ui text="Received"></timeline-item-ui>
  *   </timeline-ui>
  *
  * For agent reasoning / pipeline views, set size="sm" and use
- *   duration, outcomes, spinner, error
+ *   duration, outcomes, spinner, status="error"
  *
  *   <timeline-ui size="sm">
- *     <timeline-item-ui text="search" duration="850ms" completed></timeline-item-ui>
- *     <timeline-item-ui text="generate" active spinner></timeline-item-ui>
+ *     <timeline-item-ui text="search" duration="850ms" status="completed"></timeline-item-ui>
+ *     <timeline-item-ui text="generate" status="active" spinner></timeline-item-ui>
  *   </timeline-ui>
  *
  * For wizard / numbered-circle patterns, use the dedicated <stepper-ui>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-utils.",
   "type": "module",
   "exports": {

package/styles/colors/semantics.css

@@ -83,10 +83,10 @@
      compresses from 10 to 5 step-fractions — visual hierarchy
      leans more on font-weight + size and less on shade contrast. */
   --a-canvas-text-strong:   light-dark(var(--a-neutral-05-shade), var(--a-neutral-05-tint));
-  --a-canvas-text:          light-dark(var(--a-neutral-30-shade), var(--a-neutral-30-tint));
+  --a-canvas-text:          light-dark(var(--a-neutral-20-shade), var(--a-neutral-20-tint));
   --a-canvas-text-subtle:   light-dark(var(--a-neutral-35-shade), var(--a-neutral-35-tint));
-  --a-canvas-text-muted:    light-dark(var(--a-neutral-40-shade), var(--a-neutral-40-tint));
-  --a-canvas-text-disabled: light-dark(var(--a-neutral-60-shade), var(--a-neutral-60-tint));
+  --a-canvas-text-muted:    light-dark(var(--a-neutral-50-shade), var(--a-neutral-50-tint));
+  --a-canvas-text-disabled: light-dark(var(--a-neutral-65-shade), var(--a-neutral-65-tint));
   --a-canvas-text-inverse:  var(--a-neutral-10);
 
   /* Luminance-direction surfaces (always darken relative to canvas-0) */
@@ -154,9 +154,9 @@
      primitive — the naming inverts past the convergence point. Light
      mode wants dark-on-light, so we pick `tint` (deep accent); dark
      mode wants light-on-dark, so we pick `shade` (lifted accent). */
-  --a-link:         light-dark(var(--a-accent-65-tint), var(--a-accent-65-shade));
+  --a-link:         light-dark(var(--a-accent-55-tint), var(--a-accent-55-shade));
   --a-link-hover:   light-dark(var(--a-accent-70-tint), var(--a-accent-70-shade));
-  --a-link-visited: light-dark(var(--a-accent-75-tint), var(--a-accent-75-shade));
+  --a-link-visited: light-dark(var(--a-accent-65-tint), var(--a-accent-65-shade));
 
   /* Accent text on accent solid bg — needs light text on dark-ish accent */
   --a-accent-text-strong:   light-dark(var(--a-accent-05-shade), var(--a-accent-05-tint));

package/styles/prose.css

@@ -24,9 +24,9 @@
   --a-inset:       var(--a-inset-md);
 
   /* ── Gaps — shifted up the space scale ── */
-  --a-gap-sm:      var(--a-space-4);
-  --a-gap-md:      var(--a-space-5);
-  --a-gap-lg:      var(--a-space-6);
+  --a-gap-sm:      var(--a-space-3);
+  --a-gap-md:      var(--a-space-4);
+  --a-gap-lg:      var(--a-space-5);
   --a-gap:         var(--a-gap-md);
 
   /* ── Sizing — larger controls ── */
@@ -70,8 +70,8 @@
 
   /* body */
   --a-body-sm:         14px;
-  --a-body-md:         15px;
-  --a-body-lg:         16px;
+  --a-body-md:         16px;
+  --a-body-lg:         18px;
   --a-body-size:       var(--a-body-md);
 
   /* deck */

package/styles/tokens.css

@@ -327,3 +327,60 @@
 [gap="lg"] {
   --a-gap: var(--a-space-8);
 }
+
+/* ── Universal [padding] / [margin] — same scale as [gap]. Layout
+   primitives (row-ui, col-ui, grid-ui, stack-ui) opt in by reading
+   var(--a-padding, 0) and var(--a-margin, 0). Components with their
+   own padding/margin contracts (block-ui, card-ui, drawer-ui) keep
+   their scoped declarations and aren't affected.
+
+   Registered as non-inheriting via @property so a parent's
+   [padding="6"] doesn't bleed into nested layout primitives —
+   children see the initial-value (0) unless they declare their own
+   [padding] / [margin]. */
+@property --a-padding {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0;
+}
+@property --a-margin {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0;
+}
+
+[padding="0"]  { --a-padding: 0; }
+[padding="1"]  { --a-padding: var(--a-space-1); }
+[padding="2"]  { --a-padding: var(--a-space-2); }
+[padding="3"]  { --a-padding: var(--a-space-3); }
+[padding="4"]  { --a-padding: var(--a-space-4); }
+[padding="5"]  { --a-padding: var(--a-space-5); }
+[padding="6"]  { --a-padding: var(--a-space-6); }
+[padding="7"]  { --a-padding: var(--a-space-7); }
+[padding="8"]  { --a-padding: var(--a-space-8); }
+[padding="9"]  { --a-padding: var(--a-space-9); }
+[padding="10"] { --a-padding: var(--a-space-10); }
+[padding="12"] { --a-padding: var(--a-space-12); }
+[padding="16"] { --a-padding: var(--a-space-16); }
+
+[padding="sm"] { --a-padding: var(--a-space-4); }
+[padding="md"] { --a-padding: var(--a-space-6); }
+[padding="lg"] { --a-padding: var(--a-space-8); }
+
+[margin="0"]  { --a-margin: 0; }
+[margin="1"]  { --a-margin: var(--a-space-1); }
+[margin="2"]  { --a-margin: var(--a-space-2); }
+[margin="3"]  { --a-margin: var(--a-space-3); }
+[margin="4"]  { --a-margin: var(--a-space-4); }
+[margin="5"]  { --a-margin: var(--a-space-5); }
+[margin="6"]  { --a-margin: var(--a-space-6); }
+[margin="7"]  { --a-margin: var(--a-space-7); }
+[margin="8"]  { --a-margin: var(--a-space-8); }
+[margin="9"]  { --a-margin: var(--a-space-9); }
+[margin="10"] { --a-margin: var(--a-space-10); }
+[margin="12"] { --a-margin: var(--a-space-12); }
+[margin="16"] { --a-margin: var(--a-space-16); }
+
+[margin="sm"] { --a-margin: var(--a-space-4); }
+[margin="md"] { --a-margin: var(--a-space-6); }
+[margin="lg"] { --a-margin: var(--a-space-8); }