@adia-ai/web-components 0.8.38 → 0.8.40

package/components/modal/modal.class.js

@@ -43,6 +43,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 export class UIModal extends UIElement {
   #bound = false;
@@ -51,6 +52,14 @@ export class UIModal extends UIElement {
   #closeTimer = null;
   #dialogRef = null;
 
+  // Guards `close` against firing twice for one dismissal — #animateClose's
+  // timer dispatches it directly (the authoritative path, gh#1295) and the
+  // native <dialog> 'close' listener also calls in as a redundant safety
+  // net for a consumer that closes the raw <dialog> element itself, and
+  // disconnected()'s teardown fallback (below) is a third path into the
+  // same guard. Reset whenever the dialog (re)opens.
+  #closeDispatched = false;
+
   // Monotonic, instance-agnostic counter for the fallback aria-labelledby
   // id stamped onto an author's [slot="heading"] (see render()) — multiple
   // <modal-ui> instances on one page must not collide on the same id.
@@ -93,6 +102,19 @@ export class UIModal extends UIElement {
   };
 
   #onDialogClose = () => {
+    // Native <dialog> 'close' — fires as a browser-QUEUED task (per the
+    // HTML spec, dialog.close() queues a task; it is not synchronous), so
+    // it can be lost if a consumer tears the listener down (removes this
+    // element) before that task runs. #animateClose's own timer is the
+    // authoritative dispatch path (gh#1295); this stays wired as a
+    // redundant net for a consumer calling the raw <dialog> element's
+    // own `.close()` directly.
+    this.#emitCloseOnce();
+  };
+
+  #emitCloseOnce = () => {
+    if (this.#closeDispatched) return;
+    this.#closeDispatched = true;
     this.open = false;
     this.#previousFocus?.focus();
     this.#previousFocus = null;
@@ -128,6 +150,32 @@ export class UIModal extends UIElement {
       clearTimeout(this.#closeTimer);
       this.#closeTimer = null;
     }
+    // Teardown fallback — the ROOT CAUSE of gh#1295 (adiav2 ADIA2-8581).
+    // Every internal close path (the native <dialog> 'close' listener,
+    // #animateClose's own timer) only ever runs from THIS element's own
+    // render effect (element.js's connectedCallback), which is set up as
+    // a signals.js effect that reacts to the `open` property write via a
+    // MICROTASK — the property setter itself only marks the signal dirty;
+    // it doesn't render synchronously. `disconnectedCallback()` disposes
+    // every effect (including that one) BEFORE disconnected() runs. A
+    // consumer whose own re-render removes <modal-ui> from the DOM in the
+    // SAME tick as setting `open = false` — an extremely common framework
+    // shape: a Confirm/Cancel handler flips reactive state that ALSO
+    // unmounts the modal on that same pass — tears down the render effect
+    // before it ever gets a chance to run, so #animateClose's timer is
+    // never even CREATED, let alone fired. No error, no warning: the
+    // ENTIRE close pipeline silently never starts, and any caller awaiting
+    // `close` (showConfirmDialog-style APIs) hangs forever. Confirmed via
+    // browser reproduction — vitest/happy-dom's synchronous effect
+    // scheduling masked this (see modal.test.js "parent-driven teardown").
+    // Disconnection always resolves an open-or-mid-close modal's `close`
+    // obligation as a last resort, regardless of which (if any) internal
+    // path got a chance to run first — #emitCloseOnce's guard makes this
+    // safe to call unconditionally alongside those other paths.
+    if (this.open || this.#closing || this.#dialogRef?.open) {
+      this.#emitCloseOnce();
+    }
+    this.#closing = false;
     this.#bound = false;
     this.#dialogRef = null;
   }
@@ -136,10 +184,15 @@ export class UIModal extends UIElement {
     // Read the computed `--modal-duration` (= --a-duration = 250ms unless a
     // consumer overrides) so the JS close timer matches the CSS exit animation
     // exactly — a stale/unset value clipped the animation ~50ms early
-    // (bug class shared with swiper bug-29).
+    // (bug class shared with swiper bug-29). `parseFloat` alone silently
+    // drops a `s` vs `ms` unit (gh#1295 — a consumer-computed value observed
+    // as `.25s` parsed to 0.25, a 0.25ms timer instead of 250ms), so a
+    // trailing `s` (and not `ms`) is converted explicitly rather than
+    // trusted to already be milliseconds.
     const cs = getComputedStyle(this);
     const raw = cs.getPropertyValue('--modal-duration').trim();
-    return parseFloat(raw) || 200;
+    const ms = /ms\s*$/.test(raw) ? parseFloat(raw) : /s\s*$/.test(raw) ? parseFloat(raw) * 1000 : parseFloat(raw);
+    return ms > 0 ? ms : 200;
   }
 
   render() {
@@ -195,8 +248,12 @@ export class UIModal extends UIElement {
     // dialog-modal pattern's accessible-name requirement. Re-evaluated
     // every render so a later `text=` set, or the heading being removed,
     // clears the reference instead of leaving it stale. (gh#947, from
-    // PR #944.)
-    const authoredHeading = header.querySelector(':scope > [slot="heading"]');
+    // PR #944.) `logicalSlotted` (not a `:scope >` direct-child query)
+    // pierces the template engine's display:contents/role=presentation
+    // wrapper spans, so a consumer that renders the heading conditionally
+    // (`${title ? html\`<span slot="heading">…\` : null}`) still gets an
+    // aria-labelledby — the wrapper-trap class, gh#1301.
+    const authoredHeading = logicalSlotted(header, 'heading')[0];
     if (!this.text && authoredHeading) {
       if (!authoredHeading.id) authoredHeading.id = `modal-heading-${++UIModal.#headingIdSeq}`;
       if (dialog.getAttribute('aria-labelledby') !== authoredHeading.id) {
@@ -261,6 +318,7 @@ export class UIModal extends UIElement {
     // See .claude/docs/BROWSER-COMPAT.md §3a (Flavor C).
     if (this.open && !dialog.open) {
       this.#closing = false;
+      this.#closeDispatched = false;
       this.#previousFocus = document.activeElement;
       dialog.showModal();
       void dialog.offsetHeight;
@@ -285,6 +343,12 @@ export class UIModal extends UIElement {
       this.#closing = false;
       dialog.removeAttribute('data-closing');
       if (dialog.open) dialog.close();
+      // Authoritative dispatch (gh#1295) — don't rely solely on the native
+      // <dialog> 'close' listener above, whose task can be lost if this
+      // element (or an ancestor) is torn down before it runs.
+      // #emitCloseOnce guards so a close event ALSO reaching
+      // #onDialogClose is a no-op.
+      this.#emitCloseOnce();
     }, this.#getDuration());
   }
 

package/components/nav/nav.a2ui.json

@@ -31,6 +31,11 @@
       "type": "string",
       "default": ""
     },
+    "multiExpand": {
+      "description": "Opt out of the default single-expanded-group behavior. When unset, selecting a nav-item-ui collapses every nav-group-ui except the one containing the newly selected item (all, when the selection is ungrouped); manual multi-expansion still works up until the next selection.",
+      "type": "boolean",
+      "default": false
+    },
     "variant": {
       "description": "Visual treatment. primary = app sidebar; section = subnav rail.",
       "type": "string",

package/components/nav/nav.class.js

@@ -45,10 +45,14 @@ import { UIElement } from '../../core/element.js';
 
 export class UINav extends UIElement {
   static properties = {
-    variant:   { type: String,  default: 'primary', reflect: true },
-    collapsed: { type: Boolean, default: false,     reflect: true },
-    divider:   { type: Boolean, default: false,     reflect: true },
-    heading:   { type: String,  default: '',        reflect: true },
+    variant:     { type: String,  default: 'primary', reflect: true },
+    collapsed:   { type: Boolean, default: false,     reflect: true },
+    divider:     { type: Boolean, default: false,     reflect: true },
+    heading:     { type: String,  default: '',        reflect: true },
+    // gh#1306: selection is the cleanup event for manually multi-expanded
+    // groups — default-on; opt out to let multiple groups stay open across
+    // selections (the operator's ruling, 2026-08-14).
+    multiExpand: { type: Boolean, default: false, reflect: true, attribute: 'multi-expand' },
   };
 
   static template = () => null;
@@ -99,6 +103,7 @@ export class UINav extends UIElement {
     if (item) {
       item.setAttribute('selected', '');
       this.#flushHoverState();
+      this.#collapseSiblingGroups(item);
       this.dispatchEvent(new CustomEvent('nav-select', {
         bubbles: true,
         detail: { item, text: item.text, value: item.value },
@@ -106,6 +111,21 @@ export class UINav extends UIElement {
     }
   }
 
+  // gh#1306: on selection, collapse every top-level group except the one
+  // containing the newly selected item (none, when the selection is
+  // ungrouped — every group collapses). Manual multi-expansion stays
+  // allowed right up until the next selection; [multi-expand] opts out
+  // entirely. Runs for every select() caller — click, keyboard, and the
+  // collapsed-rail popover path (nav-group.class.js's showPopover(),
+  // which also calls nav.select()).
+  #collapseSiblingGroups(item) {
+    if (this.multiExpand) return;
+    const activeGroup = item.closest('nav-group-ui');
+    for (const group of this.querySelectorAll(':scope > nav-group-ui')) {
+      if (group !== activeGroup) group.open = false;
+    }
+  }
+
   toggle() {
     if (this.variant === 'section') return; // no-op for section variant
     this.collapsed = !this.collapsed;

package/components/nav/nav.css

@@ -80,7 +80,7 @@
     font-weight: var(--nav-label-weight);
     color: var(--nav-label-fg);
     text-transform: uppercase;
-    letter-spacing: 0.06em;
+    letter-spacing: var(--a-font-tracking-wider);
     white-space: nowrap;
     overflow: hidden;
   }
@@ -134,7 +134,7 @@
     font-weight: var(--nav-label-weight);
     color: var(--nav-label-fg);
     text-transform: uppercase;
-    letter-spacing: 0.06em;
+    letter-spacing: var(--a-font-tracking-wider);
     white-space: nowrap;
     overflow: hidden;
   }

package/components/nav/nav.d.ts

@@ -38,6 +38,8 @@ export class UINav extends UIElement {
   divider: boolean;
   /** Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. */
   heading: string;
+  /** Opt out of the default single-expanded-group behavior. When unset, selecting a nav-item-ui collapses every nav-group-ui except the one containing the newly selected item (all, when the selection is ungrouped); manual multi-expansion still works up until the next selection. */
+  multiExpand: boolean;
   /** Visual treatment. primary = app sidebar; section = subnav rail. */
   variant: 'primary' | 'section';
 

package/components/nav/nav.yaml

@@ -39,6 +39,12 @@ props:
     type: string
     default: ''
     description: "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only."
+  multiExpand:
+    type: boolean
+    default: false
+    reflect: true
+    attribute: multi-expand
+    description: "Opt out of the default single-expanded-group behavior. When unset, selecting a nav-item-ui collapses every nav-group-ui except the one containing the newly selected item (all, when the selection is ungrouped); manual multi-expansion still works up until the next selection."
 
 events:
   nav-select:
@@ -91,6 +97,18 @@ a2ui:
       or anchor) → <nav-ui>. If the user switches VIEWS within the same
       logical page → <tabs-ui>. Never use <nav-ui> as an in-page section
       switcher.
+    - >-
+      Group expansion on selection: selecting a <nav-item-ui> collapses
+      every <nav-group-ui> except the one containing the newly selected
+      item (all groups, when the selection is ungrouped). Manual
+      multi-expansion is allowed right up until the next selection. Set
+      [multi-expand] on <nav-ui> to opt out and keep multiple groups open
+      across selections. This clears the JS [open] state (and
+      aria-expanded) on every collapsed group in BOTH variants — primary
+      visually hides that group's children as a result; section variant's
+      CSS keeps children visible regardless of [open] (per the
+      section-variant cascade rule above), so only the accessibility
+      state resets there, with no visible change.
     - >-
       Anti-patterns: do NOT wrap <nav-ui> children in <col-ui> /
       <row-ui> — wrapping breaks selection bubbling + the variant

package/components/nav-group/nav-group.css

@@ -169,7 +169,7 @@
     background: var(--nav-group-badge-bg);
     padding: 1px var(--nav-group-badge-px);
     border-radius: var(--nav-group-badge-radius);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
   }
 
   [slot="header"] [slot="caret"] {
@@ -313,7 +313,7 @@ nav-group-ui [slot="popover-label"] {
   color: var(--nav-group-fg-muted);
   font-size: var(--a-ui-tiny);
   text-transform: uppercase;
-  letter-spacing: 0.06em;
+  letter-spacing: var(--a-font-tracking-wider);
 }
 
 nav-group-ui [slot="popover"] [role="option"] {
@@ -364,7 +364,7 @@ nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"] {
   font-weight: var(--a-weight-medium);
   color: var(--nav-group-fg-muted);
   text-transform: uppercase;
-  letter-spacing: 0.06em;
+  letter-spacing: var(--a-font-tracking-wider);
   cursor: default;
   border-radius: 0;
 }

package/components/nav-item/nav-item.css

@@ -136,7 +136,7 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
     background: var(--nav-item-badge-bg);
     padding: 1px var(--nav-item-badge-px);
     border-radius: var(--nav-item-badge-radius);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     margin-inline-start: auto;
   }
 
@@ -147,7 +147,7 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
     border: 1px solid var(--nav-item-trailing-border);
     border-radius: var(--nav-item-trailing-radius);
     padding: 0 var(--nav-item-trailing-px);
-    line-height: 1.6;
+    line-height: var(--a-font-leading-loose);
     flex-shrink: 0;
   }
 

package/components/option-card/option-card.css

@@ -77,7 +77,7 @@ option-card-ui[checked] [slot="icon"] {
     --option-card-heading-size:           var(--a-ui-size);
     --option-card-desc-color:             var(--a-fg-muted);
     --option-card-desc-size:              var(--a-ui-sm);
-    --option-card-desc-line-height:       1.4;
+    --option-card-desc-line-height:       var(--a-font-leading-relaxed);
     --option-card-icon-color:             var(--md-sys-color-neutral-on-surface-variant);
     --option-card-icon-color-checked:     var(--a-fg-strong);
     --option-card-icon-size:              1.5rem;

package/components/otp-input/otp-input.css

@@ -56,7 +56,7 @@
     color: var(--otp-input-fg);
     font-family: var(--otp-input-font);
     font-size: var(--otp-input-font-size);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     outline: none;
     transition: border-color var(--otp-input-duration) var(--otp-input-easing);
     /* Hide number spinner */

package/components/page/page.css

@@ -183,7 +183,7 @@
   :scope > :where(header, header-ui) > :is(text-ui[variant="display"], text-ui[variant="title"], text-ui[variant="heading"], text-ui[variant="subsection"]):not([slot]),
   :scope > :where(header, header-ui) > [slot="heading"] :is(h1, h2, h3, h4, h5, h6) {
     grid-row: 1;
-    line-height: 1.3;
+    line-height: var(--a-font-leading-normal);
     margin: 0;
   }
 
@@ -210,7 +210,7 @@
   :scope > :where(header, header-ui) > :is(text-ui[variant="body"], text-ui[variant="caption"]):not([slot]) {
     grid-row: 2;
     grid-column: 1 / -1;
-    line-height: 1.4;
+    line-height: var(--a-font-leading-relaxed);
     margin: 0;
   }
   :scope > :where(header, header-ui):has(> [slot="icon"]) > :is([slot="description"], p:not([slot]), small:not([slot])) { grid-column: 2 / -1; }

package/components/pagination/pagination.css

@@ -58,7 +58,7 @@
     font-size: var(--pagination-ellipsis-font);
     pointer-events: none;
     user-select: none;
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
   }
 
   /* ── variant="button" — square 1:1 cells via outline button-ui ──

package/components/pane/pane.css

@@ -141,7 +141,7 @@
     color: var(--pane-section-header-fg);
     padding-bottom: var(--pane-col-gap);
     text-transform: uppercase;
-    letter-spacing: 0.06em;
+    letter-spacing: var(--a-font-tracking-wider);
     font-weight: var(--pane-section-header-weight);
   }
 

package/components/progress-row/progress-row.css

@@ -31,7 +31,7 @@
     grid-area: label;
     font-size: var(--progress-row-label-size);
     color: var(--progress-row-label-fg);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
@@ -44,7 +44,7 @@
     color: var(--progress-row-meta-fg);
     font-variant-numeric: tabular-nums;
     justify-self: end;
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
   }
 
   progress-ui {

package/components/qr-code/qr-code.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/QRCode.json",
   "title": "QRCode",
-  "description": "Inline QR code generator — renders a scannable code as inline SVG.\nTwo modes:\n\n**A. Auto-encode (default).** Set `[value]` to a string (URL, plain\ntext, share link, 2FA secret). The component encodes the data with\nthe built-in zero-deps QR encoder (byte mode, ECC level configurable,\nversions 1–10 up to ~150 byte chars) and renders an SVG.\n\n**B. Bring-your-own matrix.** Set `[matrix]` to a JSON string of a\n2-D 0/1 array (`[[1,0,1,...],[...],...]`). The component renders the\nsupplied matrix directly without invoking its own encoder. Use this\nwhen you need versions 11–40, kanji/alphanumeric mode, or any\nencoder feature beyond the built-in. When both `[value]` and\n`[matrix]` are set, the matrix wins (BYO override).\n\nOutput is a single `<svg>` with `viewBox=\"0 0 N N\"`. Crisp-edges\nrendering preserves the scannable cell boundaries at any size.\nSizing is controlled by the `[size]` prop (host CSS-pixel dimension);\ninternal cell size is computed from `size / (matrix-size + 2 ·\nmargin)`. ARIA: `role=\"img\"` with `aria-label` (default \"QR code\"\nor the `[label]` prop).\n",
+  "description": "Inline QR code generator — renders a scannable code as inline SVG.\nTwo modes:\n\n**A. Auto-encode (default).** Set `[value]` to a string (URL, plain\ntext, share link, 2FA secret). The component encodes the data with\nthe built-in zero-deps QR encoder (byte mode, ECC level configurable,\nversions 1–10 up to ~150 byte chars) and renders an SVG.\n\n**B. Bring-your-own matrix.** Set `[matrix]` to a JSON string of a\n2-D 0/1 array (`[[1,0,1,...],[...],...]`). The component renders the\nsupplied matrix directly without invoking its own encoder. Use this\nwhen you need versions 11–40, kanji/alphanumeric mode, or any\nencoder feature beyond the built-in. When both `[value]` and\n`[matrix]` are set, the matrix wins (BYO override).\n\nOutput is a single `<svg>` with `viewBox=\"0 0 N N\"`. Crisp-edges\nrendering preserves the scannable cell boundaries at any size.\nSizing is controlled by the `[size]` prop (host CSS-pixel dimension);\ninternal cell size is computed from `size / (matrix-size + 2 ·\nquiet-zone)`. ARIA: `role=\"img\"` with `aria-label` (default \"QR code\"\nor the `[label]` prop).\n",
   "type": "object",
   "allOf": [
     {
@@ -42,18 +42,18 @@
       "type": "string",
       "default": "QR code"
     },
-    "margin": {
-      "description": "Quiet zone in cells around the QR pattern. QR spec requires a\nminimum 4-cell margin for reliable scanning; smaller values may\nnot scan on some devices. Default `4`.\n",
-      "type": "number",
-      "default": 4
-    },
     "matrix": {
       "description": "BYO precomputed bit matrix as JSON — a 2-D array of 0/1\n(`[[1,0,...],[0,1,...],...]`). When set, the built-in encoder is\nbypassed and this matrix renders directly. Useful for QR variants\nthe built-in doesn't support (versions 11–40, alphanumeric mode,\nkanji, etc.) — bring your own encoder, pass the matrix here.\n",
       "type": "string",
       "default": ""
     },
+    "quietZone": {
+      "description": "Quiet zone in cells around the QR pattern. QR spec requires a\nminimum 4-cell quiet zone for reliable scanning; smaller values\nmay not scan on some devices. Default `4`. (Renamed from\n`[margin]` — that name collided with the framework's global\n`[margin]` Scale attribute; `margin` on `qr-code-ui` now means\nthe global spacing attribute, per ADR-0053.)\n",
+      "type": "number",
+      "default": 4
+    },
     "size": {
-      "description": "Host display size in CSS pixels (width and height; the SVG is\nalways square). Default 200. Internal cell size is computed from\nthis divided by `matrix-size + 2·margin`.\n",
+      "description": "Host display size in CSS pixels (width and height; the SVG is\nalways square). Default 200. Internal cell size is computed from\nthis divided by `matrix-size + 2·quiet-zone`.\n",
       "type": "number",
       "default": 200
     },
@@ -75,9 +75,9 @@
         "wrong": "<qr-code-ui value=\"https://very.long.url.that.exceeds.150.bytes.of.utf8.encoded.length...\"></qr-code-ui>\n"
       },
       {
-        "fix": "<qr-code-ui value=\"...\" margin=\"4\"></qr-code-ui>\n",
-        "why": "Zero margin breaks scanning. QR spec requires a 4-cell quiet\nzone for reliable detection.\n",
-        "wrong": "<qr-code-ui value=\"...\" margin=\"0\"></qr-code-ui>\n"
+        "fix": "<qr-code-ui value=\"...\" quiet-zone=\"4\"></qr-code-ui>\n",
+        "why": "Zero quiet zone breaks scanning. QR spec requires a 4-cell quiet\nzone for reliable detection.\n",
+        "wrong": "<qr-code-ui value=\"...\" quiet-zone=\"0\"></qr-code-ui>\n"
       }
     ],
     "category": "display",

package/components/qr-code/qr-code.class.js

@@ -33,7 +33,7 @@ export class UIQRCode extends UIElement {
     matrix:          { type: String, default: '',       reflect: true },
     size:            { type: Number, default: 200,      reflect: true },
     errorCorrection: { type: String, default: 'M',      reflect: true, attribute: 'error-correction' },
-    margin:          { type: Number, default: 4,        reflect: true },
+    quietZone:       { type: Number, default: 4,        reflect: true, attribute: 'quiet-zone' },
     color:           { type: String, default: '',       reflect: true },
     background:      { type: String, default: '',       reflect: true },
     label:           { type: String, default: 'QR code', reflect: true },
@@ -91,7 +91,7 @@ export class UIQRCode extends UIElement {
     // Cheap idempotence: compute a signature of inputs, skip re-render
     // if nothing changed (encoding is non-trivial — version selection +
     // RS ECC + 8 mask evaluations).
-    const sig = `${this.value}|${this.matrix}|${this.size}|${this.errorCorrection}|${this.margin}|${this.color}|${this.background}`;
+    const sig = `${this.value}|${this.matrix}|${this.size}|${this.errorCorrection}|${this.quietZone}|${this.color}|${this.background}`;
     if (sig === this.#lastSig && this.querySelector('svg')) return;
     this.#lastSig = sig;
 
@@ -106,7 +106,7 @@ export class UIQRCode extends UIElement {
 
     const svg = matrixToSVG(matrix, {
       cellSize: 8, // arbitrary internal unit; host CSS controls actual size via [size]
-      margin: Number.isFinite(this.margin) ? this.margin : 4,
+      margin: Number.isFinite(this.quietZone) ? this.quietZone : 4,
       // Hardcoded fallback to black-on-white — the scannable convention.
       // Theme-aware `currentColor` produces light-on-dark in dark mode,
       // which most phone cameras (iPhone Camera in particular) refuse to

package/components/qr-code/qr-code.d.ts

@@ -18,7 +18,7 @@ Output is a single `<svg>` with `viewBox="0 0 N N"`. Crisp-edges
 rendering preserves the scannable cell boundaries at any size.
 Sizing is controlled by the `[size]` prop (host CSS-pixel dimension);
 internal cell size is computed from `size / (matrix-size + 2 ·
-margin)`. ARIA: `role="img"` with `aria-label` (default "QR code"
+quiet-zone)`. ARIA: `role="img"` with `aria-label` (default "QR code"
 or the `[label]` prop).
 
  *
@@ -58,11 +58,6 @@ from more damage at the cost of QR-version size growth.
 better AT context (e.g. "Share link QR code", "2FA setup QR").
  */
   label: string;
-  /** Quiet zone in cells around the QR pattern. QR spec requires a
-minimum 4-cell margin for reliable scanning; smaller values may
-not scan on some devices. Default `4`.
- */
-  margin: number;
   /** BYO precomputed bit matrix as JSON — a 2-D array of 0/1
 (`[[1,0,...],[0,1,...],...]`). When set, the built-in encoder is
 bypassed and this matrix renders directly. Useful for QR variants
@@ -70,9 +65,17 @@ the built-in doesn't support (versions 11–40, alphanumeric mode,
 kanji, etc.) — bring your own encoder, pass the matrix here.
  */
   matrix: string;
+  /** Quiet zone in cells around the QR pattern. QR spec requires a
+minimum 4-cell quiet zone for reliable scanning; smaller values
+may not scan on some devices. Default `4`. (Renamed from
+`[margin]` — that name collided with the framework's global
+`[margin]` Scale attribute; `margin` on `qr-code-ui` now means
+the global spacing attribute, per ADR-0053.)
+ */
+  quietZone: number;
   /** Host display size in CSS pixels (width and height; the SVG is
 always square). Default 200. Internal cell size is computed from
-this divided by `matrix-size + 2·margin`.
+this divided by `matrix-size + 2·quiet-zone`.
  */
   size: number;
   /** The string to encode (URL / text / share link / 2FA seed). When

package/components/qr-code/qr-code.yaml

@@ -25,7 +25,7 @@ description: |
   rendering preserves the scannable cell boundaries at any size.
   Sizing is controlled by the `[size]` prop (host CSS-pixel dimension);
   internal cell size is computed from `size / (matrix-size + 2 ·
-  margin)`. ARIA: `role="img"` with `aria-label` (default "QR code"
+  quiet-zone)`. ARIA: `role="img"` with `aria-label` (default "QR code"
   or the `[label]` prop).
 props:
   value:
@@ -50,7 +50,7 @@ props:
     description: |
       Host display size in CSS pixels (width and height; the SVG is
       always square). Default 200. Internal cell size is computed from
-      this divided by `matrix-size + 2·margin`.
+      this divided by `matrix-size + 2·quiet-zone`.
     type: number
     default: 200
     reflect: true
@@ -64,14 +64,18 @@ props:
     enum: [L, M, Q, H]
     reflect: true
     attribute: error-correction
-  margin:
+  quietZone:
     description: |
       Quiet zone in cells around the QR pattern. QR spec requires a
-      minimum 4-cell margin for reliable scanning; smaller values may
-      not scan on some devices. Default `4`.
+      minimum 4-cell quiet zone for reliable scanning; smaller values
+      may not scan on some devices. Default `4`. (Renamed from
+      `[margin]` — that name collided with the framework's global
+      `[margin]` Scale attribute; `margin` on `qr-code-ui` now means
+      the global spacing attribute, per ADR-0053.)
     type: number
     default: 4
     reflect: true
+    attribute: quiet-zone
   color:
     description: |
       Foreground (dark-cell) color. Any CSS color string (hex, rgb,
@@ -125,7 +129,7 @@ a2ui:
       reason: "Encoder capacity contract."
     - rule: "When QR sits over a non-white surface, set [background] to a solid color. White-on-image QR backgrounds are unreliable for scanners — quiet-zone contrast against the dark cells is the load-bearing visual."
       reason: "Scannability constraint."
-    - rule: "The [margin] (quiet zone) defaults to 4 cells per QR spec. Smaller margins may scan on some devices but not others; do not go below 2."
+    - rule: "The [quiet-zone] defaults to 4 cells per QR spec. Smaller values may scan on some devices but not others; do not go below 2."
       reason: "Quiet-zone requirement."
 anti_patterns:
   - wrong: |
@@ -140,12 +144,12 @@ anti_patterns:
       with a BYO encoder library + pass the [matrix]:
       `<qr-code-ui matrix="[[1,0,1,...],...]"></qr-code-ui>`
   - wrong: |
-      <qr-code-ui value="..." margin="0"></qr-code-ui>
+      <qr-code-ui value="..." quiet-zone="0"></qr-code-ui>
     why: |
-      Zero margin breaks scanning. QR spec requires a 4-cell quiet
+      Zero quiet zone breaks scanning. QR spec requires a 4-cell quiet
       zone for reliable detection.
     fix: |
-      <qr-code-ui value="..." margin="4"></qr-code-ui>
+      <qr-code-ui value="..." quiet-zone="4"></qr-code-ui>
 examples:
   - name: default
     description: Plain URL encoding at default size + ECC-M.

package/components/range/range.css

@@ -69,7 +69,7 @@ range-ui:not([disabled]) [slot="field"]:hover [data-layer="fill"] {
     /* font-family floor — see segment.css rationale. */
     font-family: var(--range-font-family);
     font-size: var(--range-font-size);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     transition:
       border-color var(--range-duration) var(--range-easing),
       background var(--range-duration) var(--range-easing);

package/components/rating/rating.css

@@ -32,7 +32,7 @@ rating-ui:hover [data-rating-symbol] {
     gap: var(--rating-gap);
     cursor: pointer;
     user-select: none;
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
   }
 
   :scope[readonly],

package/components/richtext/richtext.css

@@ -164,7 +164,7 @@
     font-weight: var(--richtext-h4-weight);
     color: var(--richtext-fg-muted);
     text-transform: uppercase;
-    letter-spacing: 0.04em;
+    letter-spacing: var(--a-font-tracking-wide);
     margin: var(--richtext-h4-margin-top) 0 var(--richtext-h4-margin-bottom);
   }
 
@@ -173,7 +173,7 @@
     font-weight: var(--richtext-h4-weight);
     color: var(--richtext-fg-muted);
     text-transform: uppercase;
-    letter-spacing: 0.06em;
+    letter-spacing: var(--a-font-tracking-wider);
     margin: var(--richtext-h4-margin-top) 0 var(--richtext-h4-margin-bottom);
   }
 
@@ -212,7 +212,7 @@
     padding: var(--richtext-pre-inset);
     overflow-x: auto;
     font-size: var(--richtext-code-size);
-    line-height: 1.5;
+    line-height: var(--a-font-leading-relaxed);
     margin: var(--richtext-pre-my) 0;
   }
 

package/components/segment/segment.css

@@ -23,9 +23,10 @@ segment-ui[selected] {
        `line-height: 1` is deliberate, but the label's ::after clips to its
        own line box, so inheriting 1 makes half-leading negative and shears
        descenders (g/j/p/q/y, parentheses) by ~0.93px at the default size —
-       gh#906. Snug (1.3) contains the font's content box at every [size];
-       mirrors --button-label-line-height. */
-    --segment-label-line-height: var(--a-leading-snug);
+       gh#906. Normal (1.35) contains the font's content box at every
+       [size]; mirrors --button-label-line-height. Value-nearest migration
+       from the retired --a-leading-snug (1.3) — ADR-0052. */
+    --segment-label-line-height: var(--a-font-leading-normal);
 
     /* ── Colors ── */
     --segment-fg:              var(--a-ui-text-subtle);
@@ -60,7 +61,7 @@ segment-ui[selected] {
     font-family: var(--segment-font-family);
     font-size: var(--segment-font-size);
     font-weight: var(--segment-font-weight);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     color: var(--segment-fg);
     white-space: nowrap;
     overflow: hidden;