@adia-ai/web-modules 0.8.39 → 0.8.41

package/billing/plan-picker/plan-picker.class.js

@@ -5,15 +5,25 @@
  * marketing pricing page (SPEC-012). Each plan card is composed from
  * <option-card-ui> (radio semantics) decorated with a price block,
  * feature list, and CTA button derived from the plan record. The
- * optional cycle toggle is a <segmented-ui> that swaps monthly /
- * annual prices in place across every card.
+ * optional cycle toggle is a <field-ui label="Billing interval">
+ * wrapping a <segmented-ui> — the canonical billing-interval chain
+ * from apps/saas/app/billing/billing.contents.html — that swaps
+ * monthly / annual prices in place across every card.
+ *
+ * Internal layout composes the framework layout primitives (gh#1519):
+ * the plans host is a <grid-ui columns="auto-fit">, each card body is
+ * a <col-ui> of <row-ui data-price-row> + <divider-ui> + a
+ * <col-ui data-features> of <row-ui> feature lines — mirroring the
+ * canonical's col-ui/row-ui feature-list grammar instead of raw
+ * div/ul/li.
  *
  * SPEC: .claude/docs/specs/implementation-ready/SPEC-011-plan-picker-in-app-upgrade.md
  * WAI-APG: https://www.w3.org/WAI/ARIA/apg/patterns/radio/
  *
  * Architecture (light-DOM, ADR-0033):
- *   This composite stamps a four-region skeleton once on first connect:
- *     [data-toggle] · [data-plans] · [data-skeleton] · [data-empty]
+ *   This composite stamps a region skeleton once on first connect:
+ *     [data-toggle] · [data-toggle-divider] · [data-plans] ·
+ *     [data-skeleton] · [data-empty]
  *   Then mutates per-card DOM by id-keyed in-place diff on every
  *   `plans` / `value` / `current` / `cycle` change. The diff preserves
  *   focus-within during re-render (replacing children would break the
@@ -116,8 +126,10 @@ export class PlanPicker extends UIFormElement {
   #stamped = false;
   #cleanups = [];
   #toggleHost = null;        // <div data-toggle> wrapper
-  #toggleSegmented = null;   // <segmented-ui> inside toggle host
-  #plansHost = null;         // <div data-plans role=radiogroup>
+  #toggleField = null;       // <field-ui> inside toggle host (canonical chain)
+  #toggleSegmented = null;   // <segmented-ui> inside the field
+  #toggleDivider = null;     // <divider-ui data-toggle-divider> after the toggle
+  #plansHost = null;         // <grid-ui data-plans role=presentation>
   #skeletonHost = null;      // <div data-skeleton>
   #emptyHost = null;         // <empty-state-ui data-empty>
   #cardsById = new Map();    // id → <option-card-ui>
@@ -285,10 +297,11 @@ export class PlanPicker extends UIFormElement {
       this.removeAttribute('empty');
     }
 
-    // Toggle visibility / contents.
+    // Toggle visibility / contents (divider tracks the toggle).
     if (this.#toggleHost) {
       const show = this.cycleToggle && plans.length > 0;
       this.#toggleHost.hidden = !show;
+      if (this.#toggleDivider) this.#toggleDivider.hidden = !show;
       if (show) this.#renderToggle();
     }
 
@@ -321,12 +334,24 @@ export class PlanPicker extends UIFormElement {
     this.appendChild(toggle);
     this.#toggleHost = toggle;
 
-    // Plans host — the radiogroup container the option-card-ui kids
-    // live in. We give it role="presentation" because the OUTER host
-    // already carries role="radiogroup" and nesting two radiogroups
-    // would confuse AT.
-    const plansHost = document.createElement('div');
+    // Divider between the interval toggle and the plan list — the
+    // canonical change-plan grammar separates the two groups with a
+    // <divider-ui> (billing.contents.html drawer). Visible only when
+    // the toggle is.
+    const toggleDivider = document.createElement('divider-ui');
+    toggleDivider.setAttribute('data-toggle-divider', '');
+    toggleDivider.hidden = true;
+    this.appendChild(toggleDivider);
+    this.#toggleDivider = toggleDivider;
+
+    // Plans host — a <grid-ui> (the framework grid primitive; the
+    // [layout] mode overrides its columns via plan-picker.css) that
+    // the option-card-ui kids live in as DIRECT children. We give it
+    // role="presentation" because the OUTER host already carries
+    // role="radiogroup" and nesting two radiogroups would confuse AT.
+    const plansHost = document.createElement('grid-ui');
     plansHost.setAttribute('data-plans', '');
+    plansHost.setAttribute('columns', 'auto-fit');
     plansHost.setAttribute('role', 'presentation');
     this.appendChild(plansHost);
     this.#plansHost = plansHost;
@@ -354,9 +379,16 @@ export class PlanPicker extends UIFormElement {
     if (!this.#toggleHost) return;
     let seg = this.#toggleSegmented;
     if (!seg) {
+      // Canonical billing-interval chain: <field-ui label="Billing
+      // interval"> wrapping the <segmented-ui> (billing.contents.html
+      // "Current plan" region).
+      const field = document.createElement('field-ui');
+      field.setAttribute('label', 'Billing interval');
       seg = document.createElement('segmented-ui');
       seg.setAttribute('aria-label', 'Billing cycle');
-      this.#toggleHost.appendChild(seg);
+      field.appendChild(seg);
+      this.#toggleHost.appendChild(field);
+      this.#toggleField = field;
       this.#toggleSegmented = seg;
       // Stamp segments — known cycles in display order.
       for (const cycleKey of ['monthly', 'annual']) {
@@ -443,8 +475,9 @@ export class PlanPicker extends UIFormElement {
     // bodies show always.
     let body = card.querySelector(':scope > [data-plan-body]');
     if (!body) {
-      body = document.createElement('div');
+      body = document.createElement('col-ui');
       body.setAttribute('data-plan-body', '');
+      body.setAttribute('gap', '3');
       card.appendChild(body);
     }
     this.#decorateBody(body, plan);
@@ -478,9 +511,11 @@ export class PlanPicker extends UIFormElement {
     // Wipe + restamp body (small DOM; cycle / feature-list / cta).
     body.replaceChildren();
 
-    // Price row.
-    const priceRow = document.createElement('div');
+    // Price row — <row-ui> per the canonical inline-cluster grammar.
+    const priceRow = document.createElement('row-ui');
     priceRow.setAttribute('data-price-row', '');
+    priceRow.setAttribute('gap', '1');
+    priceRow.setAttribute('align', 'baseline');
     const cycle = KNOWN_CYCLES.has(this.cycle) ? this.cycle : 'monthly';
     const prices = plan.prices || {};
     const priceRec = prices[cycle] || prices.monthly || null;
@@ -513,20 +548,33 @@ export class PlanPicker extends UIFormElement {
       body.appendChild(note);
     }
 
-    // Feature list.
+    // Feature list — the canonical feature-line grammar:
+    // <col-ui gap="1"> of <row-ui gap="2"><icon-ui/><span/></row-ui>
+    // (billing.contents.html trial-banner / what's-included blocks),
+    // separated from the price block by a <divider-ui>.
     if (Array.isArray(plan.features) && plan.features.length) {
-      const list = document.createElement('ul');
+      const divider = document.createElement('divider-ui');
+      divider.setAttribute('data-body-divider', '');
+      body.appendChild(divider);
+
+      const list = document.createElement('col-ui');
       list.setAttribute('data-features', '');
+      list.setAttribute('gap', '1');
+      list.setAttribute('role', 'list');
       for (const feature of plan.features) {
-        const li = document.createElement('li');
+        const line = document.createElement('row-ui');
+        line.setAttribute('data-feature', '');
+        line.setAttribute('gap', '2');
+        line.setAttribute('align', 'start');
+        line.setAttribute('role', 'listitem');
         const icon = document.createElement('icon-ui');
         icon.setAttribute('name', 'check');
         icon.setAttribute('aria-hidden', 'true');
-        li.appendChild(icon);
+        line.appendChild(icon);
         const label = document.createElement('span');
         label.textContent = String(feature);
-        li.appendChild(label);
-        list.appendChild(li);
+        line.appendChild(label);
+        list.appendChild(line);
       }
       body.appendChild(list);
     }

package/billing/plan-picker/plan-picker.css

@@ -53,7 +53,8 @@ plan-picker-ui {
     background: var(--plan-picker-bg);
   }
 
-  /* ── Toggle row ── */
+  /* ── Toggle row — <field-ui label="Billing interval"> wrapping the
+        <segmented-ui> (canonical billing-interval chain). ── */
   :scope > [data-toggle] {
     display: flex;
     justify-content: var(--plan-picker-toggle-justify);
@@ -61,19 +62,21 @@ plan-picker-ui {
   :scope > [data-toggle][hidden] {
     display: none;
   }
+  :scope > [data-toggle-divider][hidden] {
+    display: none;
+  }
 
-  /* ── Plans grid ── */
+  /* ── Plans grid — a <grid-ui columns="auto-fit"> primitive; we only
+        forward this composite's min/gap tokens into grid-ui's own
+        contract (--grid-min-col / --grid-gap). ── */
   :scope > [data-plans] {
-    display: grid;
-    grid-template-columns: repeat(
-      auto-fit,
-      minmax(var(--plan-picker-grid-min), 1fr)
-    );
-    gap: var(--plan-picker-grid-gap);
+    --grid-min-col: var(--plan-picker-grid-min);
+    --grid-gap: var(--plan-picker-grid-gap);
     align-items: stretch;
   }
 
-  /* List layout — single-column rows for in-app settings. */
+  /* List layout — single-column rows for in-app settings (mode
+     attribute; overrides grid-ui's auto-fit template). */
   :scope[layout="list"] > [data-plans] {
     grid-template-columns: 1fr;
   }
@@ -131,12 +134,8 @@ plan-picker-ui {
     display: none;
   }
 
-  /* ── Price row ── */
-  :scope [data-price-row] {
-    display: flex;
-    align-items: baseline;
-    gap: var(--a-space-1);
-  }
+  /* ── Price row — a <row-ui gap="1" align="baseline">; the primitive
+        owns the flex geometry, we style only the text chrome. ── */
   :scope [data-price] {
     font-size: var(--plan-picker-price-size);
     color: var(--plan-picker-price-fg);
@@ -152,39 +151,23 @@ plan-picker-ui {
     color: var(--plan-picker-cycle-fg);
   }
 
-  /* ── Features list ── */
-  :scope ul[data-features] {
-    list-style: none;
-    margin: 0;
-    padding: 0;
-    display: flex;
-    flex-direction: column;
-    gap: var(--plan-picker-features-gap);
+  /* ── Features list — <col-ui data-features> of <row-ui data-feature>
+        lines (canonical feature-line grammar); the layout primitives own
+        the stack/row geometry, we forward gap + text/icon chrome. ── */
+  :scope [data-features] {
+    --col-gap: var(--plan-picker-features-gap);
   }
-  :scope ul[data-features] > li {
-    display: flex;
-    align-items: flex-start;
-    gap: var(--a-space-2);
-    /* Override the docs feature-list indent (site.css adds
-       `padding-left: 24px` + a ::before checkmark to ul[data-features] li);
-       the slotted <icon-ui> IS our bullet, so the row aligns flush-left. */
-    padding-inline-start: 0;
+  :scope [data-features] > [data-feature] {
     color: var(--md-sys-color-neutral-on-surface);
     font-size: var(--a-text-sm, 0.875rem);
     line-height: 1.4;
   }
-  :scope ul[data-features] > li > icon-ui {
+  :scope [data-features] > [data-feature] > icon-ui {
     flex-shrink: 0;
     color: var(--plan-picker-feature-icon-fg);
     --a-icon-size: 1rem;
     margin-block-start: 0.125rem;
   }
-  /* The feature check is the slotted <icon-ui>. Suppress any inherited
-     ::before checkmark (the docs admin-page feature-list style adds a green
-     "✓" to every ul[data-features] li) so the bullet doesn't double up. */
-  :scope ul[data-features] > li::before {
-    content: none;
-  }
 
   /* ── CTA button — full-width, anchored to the body's bottom edge so a
         row of cards keeps their CTAs aligned regardless of feature count. ── */

package/billing/plan-picker/plan-picker.yaml

@@ -34,6 +34,11 @@ composes:
   - option-card-ui
   - segmented-ui
   - segment-ui
+  - field-ui
+  - grid-ui
+  - col-ui
+  - row-ui
+  - divider-ui
   - button-ui
   - icon-ui
   - text-ui

package/chat/chat-composer/chat-composer.a2ui.json

@@ -48,6 +48,7 @@
       "conversation-input"
     ],
     "name": "ChatComposer",
+    "parts": {},
     "related": [
       "ChatShell",
       "ChatThread",

package/chat/chat-empty/chat-empty.a2ui.json

@@ -22,6 +22,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ChatThread"
+    ],
     "anti_patterns": [],
     "category": "feedback",
     "composes": [],
@@ -34,6 +37,7 @@
       "no-messages"
     ],
     "name": "ChatEmpty",
+    "parts": {},
     "related": [
       "ChatShell",
       "ChatThread",

package/chat/chat-empty/chat-empty.yaml

@@ -39,6 +39,8 @@ states:
 traits: []
 
 a2ui:
+  allowedParents:
+    - ChatThread
   rules:
     - >-
       chat-empty is the bespoke replacement for legacy

package/chat/chat-header/chat-header.a2ui.json

@@ -22,6 +22,10 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ChatShell",
+      "ChatSidebar"
+    ],
     "anti_patterns": [],
     "category": "layout",
     "composes": [],
@@ -34,6 +38,7 @@
       "app-header"
     ],
     "name": "ChatHeader",
+    "parts": {},
     "related": [
       "ChatShell",
       "ChatStatus",

package/chat/chat-header/chat-header.yaml

@@ -47,6 +47,9 @@ states:
 traits: []
 
 a2ui:
+  allowedParents:
+    - ChatShell
+    - ChatSidebar
   rules:
     - >-
       chat-header replaces the legacy <header> chrome bar inside

package/chat/chat-shell/chat-shell.a2ui.json

@@ -52,6 +52,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "Surface"
+    ],
     "anti_patterns": [],
     "category": "container",
     "composes": [
@@ -118,6 +121,7 @@
       "assistant"
     ],
     "name": "ChatShell",
+    "parts": {},
     "related": [
       "ChatThread",
       "ChatComposer",

package/chat/chat-shell/chat-shell.yaml

@@ -126,6 +126,8 @@ states:
 traits: []
 
 a2ui:
+  allowedParents:
+    - Surface
   rules:
     - >-
       chat-shell takes bespoke chat-* children only. The canonical

package/chat/chat-shell/css/chat-shell.tokens.css

@@ -61,7 +61,7 @@
 
   /* Typography */
   --chat-font-size:             var(--a-ui-size);
-  --chat-line-height:           var(--a-leading-normal);
+  --chat-line-height:           var(--a-font-leading-relaxed);
   --chat-weight-semibold:       var(--a-weight-semibold);
 
   /* Header typography */

package/chat/chat-sidebar/chat-sidebar.a2ui.json

@@ -52,6 +52,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ChatShell"
+    ],
     "anti_patterns": [],
     "category": "layout",
     "composes": [],
@@ -83,6 +86,7 @@
       "inspector"
     ],
     "name": "ChatSidebar",
+    "parts": {},
     "related": [
       "ChatShell",
       "ChatComposer",

package/chat/chat-sidebar/chat-sidebar.yaml

@@ -108,6 +108,8 @@ states:
 traits: []
 
 a2ui:
+  allowedParents:
+    - ChatShell
   rules:
     - >-
       chat-sidebar is the bespoke replacement for legacy

package/chat/chat-status/chat-status.a2ui.json

@@ -22,6 +22,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ChatHeader"
+    ],
     "anti_patterns": [],
     "category": "feedback",
     "composes": [],
@@ -34,6 +37,7 @@
       "streaming-indicator"
     ],
     "name": "ChatStatus",
+    "parts": {},
     "related": [
       "ChatShell",
       "ChatHeader",

package/chat/chat-status/chat-status.yaml

@@ -32,6 +32,8 @@ states:
 traits: []
 
 a2ui:
+  allowedParents:
+    - ChatHeader
   rules:
     - >-
       chat-status replaces legacy <span data-chat-status> for the

package/chat/chat-thread/chat-thread.a2ui.json

@@ -32,6 +32,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ChatShell"
+    ],
     "anti_patterns": [],
     "category": "container",
     "composes": [],
@@ -45,6 +48,7 @@
       "scroll-surface"
     ],
     "name": "ChatThread",
+    "parts": {},
     "related": [
       "ChatShell",
       "ChatEmpty",

package/chat/chat-thread/chat-thread.yaml

@@ -58,6 +58,8 @@ states:
   description: Zero message children — empty state visible.
 traits: []
 a2ui:
+  allowedParents:
+    - ChatShell
   rules:
   - chat-thread is the bespoke replacement for legacy <section data-chat-messages> inside <chat-shell>. Use it for the message
     scroll surface; the host appends dynamic message divs as children.

package/dashboard/dashboard-layout/dashboard-layout.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "bandGap": {
+      "description": "Override band-to-band vertical gap. Empty string = the\ndensity-modulated default. Numeric `1`..`6` selects the\ncorresponding --a-space-N step. Renamed from `[gap]` (gh#1335) —\nthis attribute set the component-local `--dashboard-layout-gap`\ntoken directly, never composing with the ambient\n`[size]`→`--a-gap` cascade the global Scale-grammar `[gap]`\nattribute uses, and covers a narrower numeric range (1-6 vs. the\nglobal 0-16) — a genuinely distinct, band-scoped concept kept\nunder its own namespaced name rather than converged.\n",
+      "type": "string",
+      "default": ""
+    },
     "chart-split": {
       "description": "Chart-band column split. Empty string = single full-width chart;\n`2` = two equal columns; `2:1` / `3:2` / `3:1` = asymmetric\nratios. Collapses to single column at narrow widths (≤48em).\n",
       "type": "string",
@@ -29,21 +34,15 @@
       "const": "DashboardLayout"
     },
     "density": {
-      "description": "Spacing scale — propagates --a-density to descendant primitives\nvia CSS custom-property cascade. Empty string inherits whatever\ndensity is in effect on an ancestor (the default — respects an\napp-level density theme). `compact` / `comfortable` / `spacious`\nexplicitly override.\n",
+      "description": "Spacing scale — propagates --a-density to descendant primitives\nvia CSS custom-property cascade. Empty string inherits whatever\ndensity is in effect on an ancestor (the default — respects an\napp-level density theme). `compact` / `spacious` explicitly\noverride. `comfortable` retired (gh#1335) — verified dead code:\nit set `--a-density: 1` with no gap-token override, functionally\nidentical to the \"\" (unset/ambient) state, not to `spacious`\n(`--a-density: 1.15` + wider gap tokens) — so it converges onto\n\"\" (the closest matching real behavior) rather than a\n`comfortable`→`spacious` rename, which would have silently\nchanged behavior for any existing consumer.\n",
       "type": "string",
       "enum": [
         "",
-        "comfortable",
         "compact",
         "spacious"
       ],
       "default": ""
     },
-    "gap": {
-      "description": "Override band-to-band vertical gap. Empty string = the\ndensity-modulated default (--a-space-4 at comfortable). Numeric\n`1`..`6` selects the corresponding --a-space-N step.\n",
-      "type": "string",
-      "default": ""
-    },
     "kpi-columns": {
       "description": "Target column count for the KPI band at desktop width. Range 2-6;\nout-of-range values fall back to 4. Container-query collapse\nreduces this at narrower widths (≤48em → 2; ≤32em → 1).\n",
       "type": "string",
@@ -101,7 +100,7 @@
         "description": "Fired when [density] changes (programmatic or via setDensity()).\nBubbles; detail.density carries the new value.\n",
         "detail": {
           "density": {
-            "description": "The new density value (comfortable / compact / spacious).",
+            "description": "The new density value (\"\" / compact / spacious).",
             "type": "string"
           }
         }
@@ -146,6 +145,7 @@
       "layout-container"
     ],
     "name": "UIDashboardLayout",
+    "parts": {},
     "related": [
       "AdminPageBody",
       "AdminPage",

package/dashboard/dashboard-layout/dashboard-layout.css

@@ -119,10 +119,10 @@ dashboard-layout-ui {
 
   /* ── Density variants — override TOKEN values only ──
      Per the contract: variants change tokens; modes change layout.
-     Density is a token-override, not a layout-shape change. */
-  :scope[density="comfortable"] {
-    --a-density: 1;
-  }
+     Density is a token-override, not a layout-shape change.
+     `comfortable` retired (gh#1335) — verified dead code: it set only
+     --a-density:1 with no gap-token override, functionally identical
+     to the unset/"" state below (no selector needed), not to `spacious`. */
   :scope[density="compact"] {
     --dashboard-layout-gap:     var(--dashboard-layout-gap-compact);
     --dashboard-layout-kpi-gap: var(--dashboard-layout-kpi-gap-compact);

package/dashboard/dashboard-layout/dashboard-layout.js

@@ -30,7 +30,7 @@ import { untracked } from '@adia-ai/web-components/core/signals';
 
 // ── Validation tables ────────────────────────────────────────────
 
-const VALID_DENSITIES   = new Set(['', 'comfortable', 'compact', 'spacious']);
+const VALID_DENSITIES   = new Set(['', 'compact', 'spacious']);
 const VALID_KPI_COLUMNS = new Set(['2', '3', '4', '5', '6']);
 const VALID_CHART_SPLIT = new Set(['', '2', '2:1', '3:2', '3:1']);
 const REGION_SLOTS      = ['toolbar', 'kpis', 'charts', 'table', 'aside'];
@@ -44,7 +44,7 @@ export class UIDashboardLayout extends UIElement {
       'kpi-columns': { type: String,  default: '4',    reflect: true, attribute: 'kpi-columns' },
       'chart-split': { type: String,  default: '',     reflect: true, attribute: 'chart-split' },
       loading:       { type: Boolean, default: false,  reflect: true },
-      gap:           { type: String,  default: '',     reflect: true },
+      bandGap:       { type: String,  default: '',     reflect: true, attribute: 'band-gap' },
     };
   }
 
@@ -76,7 +76,7 @@ export class UIDashboardLayout extends UIElement {
    * Programmatic equivalent of setting the [density] attribute.
    * Fires `density-change` once with the new value.
    *
-   * @param {string} value — '' | 'comfortable' | 'compact' | 'spacious'
+   * @param {string} value — '' | 'compact' | 'spacious'
    */
   setDensity(value) {
     const next = VALID_DENSITIES.has(value) ? value : '';
@@ -118,7 +118,7 @@ export class UIDashboardLayout extends UIElement {
     // changes flow through attributeChangedCallback below.
     this.#syncAriaBusy();
 
-    // Apply the [gap] override → public token if set.
+    // Apply the [band-gap] override → public token if set.
     this.#applyGapAttr();
 
     // Watch for region-empty transitions. Children are arbitrary
@@ -195,7 +195,7 @@ export class UIDashboardLayout extends UIElement {
       return;
     }
 
-    if (name === 'gap' && oldVal !== newVal) {
+    if (name === 'band-gap' && oldVal !== newVal) {
       this.#applyGapAttr();
       return;
     }
@@ -237,12 +237,13 @@ export class UIDashboardLayout extends UIElement {
   }
 
   /**
-   * Map the [gap="N"] attribute to the public --dashboard-layout-gap
-   * custom property. The CSS reads `var(--dashboard-layout-gap, …)`
-   * so empty / unset falls back to the density-modulated default.
+   * Map the [band-gap="N"] attribute (renamed from [gap], gh#1335) to the
+   * public --dashboard-layout-gap custom property. The CSS reads
+   * `var(--dashboard-layout-gap, …)` so empty / unset falls back to the
+   * density-modulated default.
    */
   #applyGapAttr() {
-    const g = (this.gap || '').trim();
+    const g = (this.bandGap || '').trim();
     if (g === '') {
       this.style.removeProperty('--dashboard-layout-gap');
       return;

package/dashboard/dashboard-layout/dashboard-layout.yaml

@@ -40,13 +40,18 @@ props:
       Spacing scale — propagates --a-density to descendant primitives
       via CSS custom-property cascade. Empty string inherits whatever
       density is in effect on an ancestor (the default — respects an
-      app-level density theme). `compact` / `comfortable` / `spacious`
-      explicitly override.
+      app-level density theme). `compact` / `spacious` explicitly
+      override. `comfortable` retired (gh#1335) — verified dead code:
+      it set `--a-density: 1` with no gap-token override, functionally
+      identical to the "" (unset/ambient) state, not to `spacious`
+      (`--a-density: 1.15` + wider gap tokens) — so it converges onto
+      "" (the closest matching real behavior) rather than a
+      `comfortable`→`spacious` rename, which would have silently
+      changed behavior for any existing consumer.
     type: string
     default: ""
     enum:
       - ""
-      - comfortable
       - compact
       - spacious
     reflect: true
@@ -91,13 +96,20 @@ props:
     default: false
     reflect: true
 
-  gap:
+  bandGap:
     description: |
       Override band-to-band vertical gap. Empty string = the
-      density-modulated default (--a-space-4 at comfortable). Numeric
-      `1`..`6` selects the corresponding --a-space-N step.
+      density-modulated default. Numeric `1`..`6` selects the
+      corresponding --a-space-N step. Renamed from `[gap]` (gh#1335) —
+      this attribute set the component-local `--dashboard-layout-gap`
+      token directly, never composing with the ambient
+      `[size]`→`--a-gap` cascade the global Scale-grammar `[gap]`
+      attribute uses, and covers a narrower numeric range (1-6 vs. the
+      global 0-16) — a genuinely distinct, band-scoped concept kept
+      under its own namespaced name rather than converged.
     type: string
     default: ""
+    attribute: band-gap
     reflect: true
 
 events:
@@ -108,7 +120,7 @@ events:
     detail:
       density:
         type: string
-        description: The new density value (comfortable / compact / spacious).
+        description: The new density value ("" / compact / spacious).
 
   region-empty:
     description: |