@adia-ai/web-components 0.6.34 → 0.6.36

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.36] — 2026-05-24
+
+### Fixed — `<tag-ui>` dismiss X + slotted icons now inherit the variant text color
+
+- **Visible after the solid-default flip**: the dismiss X (`[slot="dismiss"]`) was hardcoded to `--a-fg-muted` (a neutral grey) regardless of the host's variant, so the X disappeared against saturated solid pills — a near-invisible grey X on the Info/Success/Warning/Error bgs. Same trap on any slotted leading icon: tag had no `currentColor` inheritance rule, so `<icon-ui>` children rendered in their own foreground color rather than the variant's.
+- **Fix**: dismiss `color` token now defaults to `currentColor` at `opacity: 0.7` (quieter than the label, but tracks every variant — near-white X on saturated bg, dark X on warning amber, fg-muted X on quiet chrome). Hover restores `opacity: 1` and overlays a `color-mix(in oklch, currentColor 15%, transparent)` bg highlight — same color family as the host, not a stark neutral wash. NEW `:scope > icon-ui { color: currentColor; flex-shrink: 0 }` rule mirrors `<badge-ui>`'s convention so leading-icon legends/status chips read as a single color-coded unit.
+- Two new component tokens for the dismiss opacity (`--tag-dismiss-opacity`, `--tag-dismiss-opacity-hover`) replace the prior color-swap tokens (`--tag-dismiss-fg-hover` removed — opacity-driven hover instead). Files: `components/tag/tag.css`.
+
+### Fixed — `<tag-ui variant="warning">` solid pill: bright amber bg instead of muddy mid-brown
+
+- **Visible after the solid-default flip**: the canonical `--a-warning-bg` + `--a-warning-fg` pair collapses for warning. `--a-warning-fg` resolves to `--a-warning-10-shade` (a dark brown — per `semantics.css:309` "warning is light-colored — text on warning fills should be dark"), but `--a-warning-bg` (= `--a-warning-strong` = `-50`) is a mid-tone amber. Dark text on mid-tone amber gives the muddy brown-on-brown look the user reported. The other family variants (info/success/danger) all have `-text-strong = -05-tint` (near-white) which contrasts cleanly against their `-50` saturated bg, so they don't hit this trap.
+- **Fix at the tag layer**: `:scope[variant="warning"]` now uses the literal `--a-warning-20-tint` step (bright caution-tape amber, scheme-independent) as bg + keeps `--a-warning-fg` as dark text. Restores the bright-amber-with-dark-text shape `semantics.css` intends. Other family variants unchanged. Regression guard added that hard-fails any revert to `--a-warning-bg` for the warning solid bg.
+- **Token-system follow-up flagged (not shipped)**: this is a symptom of `--a-warning-bg` pointing at the wrong step. Same muddy contrast likely surfaces wherever `--a-warning-bg` + `--a-warning-fg` is paired (`button-ui variant="warning"`, `chart-ui` warning bars, `rating-ui` filled fg, `progress-row variant="warning"`). A token-side fix that redirects `--a-warning-bg` to `--a-warning-20-tint` would resolve all consumers in one stroke but needs a visual sweep across those components first. Files: `components/tag/tag.{css,test.js}`.
+
+### Changed — `<tag-ui>` family variants default to **solid** fill (BREAKING-visual)
+
+- **`<tag-ui variant="info|success|warning|danger">` now renders as a saturated bg + on-strong (near-white) text** — the chip IS the state, not a tinted metadata label. Aligns the chip vocabulary so consumers can read tag-ui as a status pill at a glance. Previously: muted tinted bg with `--a-{family}-bg` (saturated solid) text — an off-canonical pair that read as "passive metadata with bold color" and diverged from `<badge-ui>`'s canonical muted pair.
+- **Opt-out**: NEW `[tone="muted"]` attribute drops a family variant back to the canonical muted pair `--a-{family}-muted` + `--a-{family}-text` (scheme-flipping text — the same pair `<badge-ui>` uses as its default). Use on metadata chips in dense lists where the saturated default would compete for attention.
+- **The `default` variant (no family) is unchanged** — it stays as quiet `--a-bg-muted` + `--a-fg` chrome. Opt in to a high-contrast inverse stamp via `<tag-ui tone="solid">` (no variant); resolves to `--a-fg` bg + `--a-bg` fg.
+- **Author migration**: existing `<tag-ui variant="info|success|warning|danger">` markup auto-flips to the new saturated default — every existing tag in the codebase becomes louder. If any specific surface needs the prior look, append `tone="muted"`. 75 occurrences across 30 substrate/app/playground files identified; review per surface.
+- Source-grep regression guards added: 4 family variants verified to use the solid pair as default; 4 `[tone="muted"][variant=…]` rules verified to use the canonical muted pair; `[variant="default"]` verified unchanged; `[tone="solid"]` neutral inverse verified. Files: `components/tag/tag.{css,yaml,test.js,examples.html,a2ui.json}` + regenerated corpus catalog.
+
+### Fixed — placeholder pseudo no longer pushes the caret to its right after type-then-delete
+
+- **Bug report**: with `<input-ui placeholder="Select country…">`, typing text then deleting it left the caret visually at the END of the placeholder text instead of at position 0. Same trap on `<textarea-ui>`, `<combobox-ui>`, and `<tags-input-ui>`. Root cause: the empty-state placeholder is implemented via `[data-empty]::before { content: attr(data-placeholder); }`, rendered as an **inline** pseudo box. When the contenteditable is empty, the caret IS at offset 0 of the empty text node — but the in-flow `::before` pseudo precedes the text content, occupying inline space, so the caret renders to the right of the pseudo's box. (Only happens after type-then-delete because that path leaves the contenteditable focused, making the caret visible at its true position-0 location.)
+- **Fix**: pseudo is now `position: absolute; inset: 0; padding: inherit` — fills the host's content-box without occupying inline-flow space, so the caret renders at the actual content-start where it belongs. Host elements gain `position: relative` as the positioning anchor. For `<tags-input-ui>` + `<combobox-ui>` the pseudo also uses `display: flex; align-items: center` so the placeholder text vertically aligns with the host's flex-centered line-box.
+- Regression guards added to `input.test.js` — three source-grep assertions (`:scope` declares `position: relative`, pseudo declares `position: absolute`, pseudo carries `inset: 0` + `padding: inherit`) that hard-fail if the in-flow shape ever re-appears.
+- Files: `components/input/input.{css,test.js}`, `components/textarea/textarea.css`, `components/tags-input/tags-input.css`, `components/combobox/combobox.css`.
+
+## [0.6.35] — 2026-05-24
+
+### Fixed — `<popover-ui>` + `<menu-ui>` yaml `slots:` blocks declare the canonical `trigger` / `content` vocabulary (FB-62)
+
+- **CSS positioned slots that the yaml said didn't exist.** `popover.yaml` pre-patch line 43: `slots: {}` (empty). But `popover.css` positions `[slot="trigger"]` and `[slot="content"]` across 7 selectors (open/closed states + first/last-child margin guards), and the yaml's own a2ui rule already states "popover-ui wraps a focusable trigger (slot=\"trigger\") + arbitrary interactive content (slot=\"content\")". Parallel case in `menu.yaml`: `slots:` declared only `default`, but the a2ui rule said "MUST have exactly one child with slot=\"trigger\"". Three sources said the slots existed, one source (the structured `slots:` SoT) said they didn't. Surfaced as 6 INFO findings in the adia-ui-kit v3.4.X recipe-staleness audit; suppressed via `KNOWN_PARENT_SLOT_DRIFT`.
+- **Fix**: `popover.yaml` `slots:` now declares `trigger` (focusable element that opens the popover; MUST be focusable for keyboard accessibility — bare `<span>`/`<div>` won't work) and `content` (the body, hoisted to top-layer via `:popover-open`). `menu.yaml` `slots:` adds `trigger` (Required — exactly one child must have `slot="trigger"`; without it the menu cannot open). Pure yaml backfill — no JS, no CSS, no API change. Sidecar `.a2ui.json` files regenerated. Kit's `KNOWN_PARENT_SLOT_DRIFT` allowlist entries can be removed next cycle. Files: `components/popover/popover.{yaml,a2ui.json}`, `components/menu/menu.{yaml,a2ui.json}`.
+
+### Fixed — chat-input + textarea + input substrate prose accurately documents Enter→submit (FB-63)
+
+- **`submit-on-enter` was a documentation phantom across the substrate, and the prose around it carried two adjacent lies.** Three input primitives all dispatch a bubbling `submit` event on Enter (without Shift) unconditionally: `textarea.class.js:97-106`, `input.class.js:713-727`, and `chat-input.js` (which delegates to the inner `<textarea-ui>`'s submit event at line 147). None of them observe a `[submit-on-enter]` attribute — yet the substrate's own demos, yamls, and a2ui rules used `<chat-input-ui submit-on-enter>` as canonical authoring shape. Two adjacent lies discovered in the same cluster: (1) `textarea.yaml` description + a2ui rule + `textarea.examples.html` claimed "Enter inserts a newline — textarea-ui does NOT emit a `submit` event" — false per `textarea.class.js:97-106`. (2) `input.yaml` + `input.examples.html` claimed "only chat-input-ui reflects the [submit-on-enter] attribute" — false, NONE of them reflect it.
+- **Fix**: `submit-on-enter` stripped from `patterns/chat-shell/chat-shell.examples.html` (1 occurrence). `chat-input.yaml` event description + `chat-input.js` docstring now state the truth — Enter→submit is unconditional, delegated from inner `<textarea-ui>`, no opt-in/opt-out. `textarea.yaml` description (line 10-18) + a2ui rule (line 119-123) + `textarea.examples.html:253` corrected: "Enter (without Shift) dispatches a bubbling `submit` event; Shift+Enter inserts a newline. Unconditional — no opt-in/opt-out attribute." `input.yaml` + `input.examples.html` adjacent prose: stripped "only chat-input-ui reflects [submit-on-enter]" claim; replaced with accurate "the plain `<input-ui>` primitive ALSO fires `submit` on Enter (unconditional, no opt-in attribute); `<chat-input-ui>` simply builds on that semantic." Companion strip in `@adia-ai/web-modules` chat-cluster (see its changelog). Sweep-grep `submit-on-enter` in authored sources now returns only the two truth-note phrasings (both say "no `[submit-on-enter]` opt-in/opt-out"). Sidecar `.a2ui.json` files regenerated; corpus catalog + rules text rebuilt. Files: `components/chat-thread/chat-input.{yaml,js,a2ui.json}`, `components/textarea/textarea.{yaml,examples.html,a2ui.json}`, `components/input/input.{yaml,examples.html,a2ui.json}`, `patterns/chat-shell/chat-shell.examples.html`.
+
+### Fixed — `<spinner-ui variant="dots">` dot spacing now even (was lopsided)
+
+- **The pre-fix dots layout used `::before` + `::after` pseudo-elements** as the outer two dots and a `box-shadow` on `::before` to paint the middle dot. Three breakages: (1) the box-shadow middle dot doesn't participate in the host's flex-gap math, so the gap between dot1↔dot2 and dot2↔dot3 was unequal (the screenshot showed two dots close together on the left, then one isolated on the right). (2) The box-shadow dot couldn't carry its own `@keyframes` animation, so the middle stayed at default scale while the outer two bounced — a "middle is anchored" look. (3) The author comment explicitly acknowledged the hack ("simpler, more robust shape is to overlay three identical dot pseudos via a flexbox container of pseudo + two child pseudos isn't possible without a stamped child"). Fix: `class.js` `#syncDots()` now stamps three real `<span data-spinner-dot=N>` children when `variant="dots"`. Flex-gap distributes the row evenly; each child gets `animation-delay: 0 / T/3 / 2T/3` so the bounce reads as a left-to-right wave. Reduced-motion + `[paused]` selectors updated to include `> [data-spinner-dot]`. Files: `components/spinner/class.js`, `components/spinner/spinner.css`, `components/spinner/spinner.test.js`.
+
+### Added — `<spinner-ui variant="knight">` knight-rider sliding-bar variant
+
+- **NEW `knight` variant** — a horizontal track with a thumb that slides back-and-forth via `animation-direction: alternate`. Reads as a determinate-looking bar but is indeterminate by intent (no progress value; same loading semantics as the other variants). Tokens added: `--spinner-bar-track-width` (default `4rem`), `--spinner-bar-track-height` (default `var(--spinner-stroke)` — visual continuity with arc/ring), `--spinner-bar-thumb-ratio` (default `0.3` — thumb is 30% of track). Keyframe math: `translateX((1 / ratio - 1) * 100%)` of thumb-relative width = `(track - thumb)` px regardless of track-width override. Reduced-motion path hides the thumb and falls through to the shared ellipsis fallback. yaml `variant` enum + description updated. Files: `components/spinner/spinner.css`, `components/spinner/spinner.yaml`, `components/spinner/spinner.examples.html`.
+
+### Added — `<integration-card-ui>` demo page now ships a live CRUD drawer wiring
+
+- **`integration-card.examples.html` previously showed cards only as static visual showcases** — clicking `Connect` / `Configure` dispatched the `connect` / `configure` events into the void (no consumer wiring on the docs page). Added a "Wired to drawer (CRUD)" section at the top with three cards (`slack` / `github` / `linear`) bound to a shared `<drawer-ui>` form. NEW `integration-card.examples.js` setup module: listens for bubbled events at the grid level, opens the drawer in `connect` or `configure` mode, persists token to an in-memory store keyed by `provider`, and on Save / Disconnect mutates the originating card's `status` attribute. Demonstrates the full Create / Update / Delete loop expected of consumers per SPEC-062 §134-136. Sitemap entry gains `"setup": ".../integration-card.examples.js"` so the docs router auto-imports the module on route load (same pattern as `agent-feedback-bar`, etc.). Files: `components/integration-card/integration-card.examples.html`, `components/integration-card/integration-card.examples.js` (NEW), `site/sitemap.json`.
+
+### Changed — `<date-range-picker-ui>` trigger surface mirrors `<select-ui>` / `<calendar-picker-ui>`
+
+- **`date-range-picker.css` had only `:scope > [slot="trigger"] { min-width: 14em }`** — the entire trigger chrome relied on `<button-ui variant="outline">`'s defaults, which produced an off-pattern surface vs. the rest of the input/picker family. Trigger now styled with the canonical contract: flex row, `min-height: var(--a-size)`, `padding: 0 var(--a-ui-px)`, `border-radius: var(--a-radius)`, `border: 1px solid var(--a-ui-border)`, `background: var(--a-ui-bg)`, `justify-content: space-between` so leading icon + label sit start, trailing caret sits end. Adds canonical `--date-range-picker-trigger-{height,px,gap,radius,bg,bg-hover,fg,border,border-hover,focus-ring}` token shelf — same tokens `<calendar-picker-ui>` already exposes, so consumers can override either family-side. Hover/focus-visible rules attached for parity. Files: `components/date-range-picker/date-range-picker.css`.
+
+### Fixed — `<spinner-ui>` rotational cadence (was 300ms, now 0.8s)
+
+- **`--spinner-duration-default` retargeted from `var(--a-duration-slow)` (300 ms — interaction-duration scale, tuned for hover/focus transitions) to `0.8s`** — canonical loader cadence. A full revolution at 300 ms reads as a frantic blur; 0.8 s gives smooth, perceptible motion that signals "loading" without alarming the eye. The `--a-duration-*` token family (120 / 250 / 300 ms) is now correctly reserved for state transitions; spinner uses its own rotational tempo. Files: `components/spinner/spinner.css`.
+
+### Fixed — `<modal-ui>` header no longer reserves a phantom flex slot for empty `text=`
+
+- **`modal.css`'s `:scope [slot="header"]::before { content: attr(text); flex: 1 }` rule generated an empty-content pseudo-element with `flex: 1` whenever the host's `text` attr was empty or unset.** That phantom flex slot claimed the row's free space and pushed any slotted header content (e.g., `<confirm-dialog-ui>`'s stamped `<text-ui part="title">` + auto-stamped close button) to the trailing edge — the title rendered tight against the X close button instead of left-aligned. Same drift class as the `tag-ui` / `badge-ui` / `segment-ui` / `button-ui` phantom-gap arc (April–May 2026).
+- **Fix (defense-in-depth)**: CSS gate the `::before` on `[text]:not([text=""])` so the pseudo isn't generated when text is absent or empty; class.js no longer writes `text=""` on the header when `this.text` is falsy. Either side alone would fix the symptom; both prevent recurrence from independent edit paths. Visible effect: `<confirm-dialog-ui>` now renders "Save changes?" left-aligned with X on the right, matching the canonical header pattern. Files: `components/modal/modal.css`, `components/modal/class.js`.
+
+### Added — `<calendar-grid-ui>` `range-start` / `range-end` props for in-range cell highlighting
+
+- **`<calendar-grid-ui>` gains two new reflected string props — `range-start` and `range-end` (ISO `YYYY-MM-DD`).** When both are set + ordered, day cells strictly between the endpoints get `[data-in-range]` stamped on them. New CSS state styles in-range cells with `--calendar-grid-day-bg-in-range` (defaults to `--a-accent-muted` — the muted accent strip) and `--calendar-grid-day-fg-in-range`. The endpoints themselves continue rendering via the `value` prop's `[data-selected]` state (full `--a-accent` fill); the in-range middle is visually subordinate. Per-day cells also get `data-range-start` / `data-range-end` markers for future shape work (rounded caps, etc.).
+- **`<date-range-picker-ui>` now wires this contract**: in `render()`, the effective from/to (pending click-state OR committed value) is pushed onto BOTH calendar-grid panes via `range-start` / `range-end` attributes, so each pane independently lights up its in-range cells. Closes the "selected start + end but no fill between" trap. Files: `components/calendar-grid/calendar-grid.css`, `components/calendar-grid/class.js`, `components/calendar-grid/calendar-grid.yaml`, `components/date-range-picker/class.js`.
+
 ## [0.6.34] — 2026-05-23
 
 ### Added — Wave 1 + Wave 2: 10 P1 components shipped from SPEC pilot

package/color/index.js

@@ -5,7 +5,7 @@
  *
  * §301 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Pure functions; no
  * DOM/runtime side-effects. Pre-§301 these helpers lived inline at
- * `components/color-picker/class.js:34-121`. Extracted into a shared
+ * `components/color-picker/color-picker.class.js:34-121`. Extracted into a shared
  * subpath so consumers (Tokens Studio, custom palette tools) don't
  * re-implement OKLCH math.
  *

package/components/accordion/accordion-item.yaml

@@ -1,9 +1,9 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
-# component already existed as a sibling class in the parent's class.js
+# component already existed as a sibling class in the parent's accordion.class.js
 # + was registered alongside the parent (e.g. UIList + UIListItem both
-# from list/class.js). The catalog just lacked its own entry. With the
+# from list/list.class.js). The catalog just lacked its own entry. With the
 # §172 sibling-yaml scanner, this file gets picked up next to the parent
 # yaml.
 

package/components/accordion/accordion.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAccordion, UIAccordionItem } from './class.js';
+import { UIAccordion, UIAccordionItem } from './accordion.class.js';
 
 defineIfFree('accordion-ui', UIAccordion);
 defineIfFree('accordion-item-ui', UIAccordionItem);

package/components/action-list/action-item.yaml

@@ -1,9 +1,9 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
-# component already existed as a sibling class in the parent's class.js
+# component already existed as a sibling class in the parent's action-list.class.js
 # + was registered alongside the parent (e.g. UIList + UIListItem both
-# from list/class.js). The catalog just lacked its own entry. With the
+# from list/list.class.js). The catalog just lacked its own entry. With the
 # §172 sibling-yaml scanner, this file gets picked up next to the parent
 # yaml.
 

package/components/action-list/action-list.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIActionList, UIActionItem } from './class.js';
+import { UIActionList, UIActionItem } from './action-list.class.js';
 
 defineIfFree('action-list-ui', UIActionList);
 defineIfFree('action-item-ui', UIActionItem);

package/components/agent-artifact/{class.js → agent-artifact.class.js}

@@ -59,7 +59,7 @@ export class UIAgentArtifact extends UIElement {
   };
 
   // §205 (v0.5.7): dynamic chevron icons stamped on collapse/expand state
-  // transition (class.js:119+188). Per FEEDBACK-16 §1 + §209 slot-11 ternary-
+  // transition (agent-artifact.class.js:119+188). Per FEEDBACK-16 §1 + §209 slot-11 ternary-
   // walker discovery. Note: `this.icon` consumer-supplied — not declared here.
   static requiredIcons = ['caret-right', 'caret-down'];
 

package/components/agent-artifact/agent-artifact.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAgentArtifact } from './class.js';
+import { UIAgentArtifact } from './agent-artifact.class.js';
 
 defineIfFree('agent-artifact-ui', UIAgentArtifact);
 

package/components/agent-feedback-bar/agent-feedback-bar.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAgentFeedbackBar } from './class.js';
+import { UIAgentFeedbackBar } from './agent-feedback-bar.class.js';
 
 defineIfFree('agent-feedback-bar-ui', UIAgentFeedbackBar);
 

package/components/agent-questions/agent-questions.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAgentQuestions } from './class.js';
+import { UIAgentQuestions } from './agent-questions.class.js';
 
 defineIfFree('agent-questions-ui', UIAgentQuestions);
 

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

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAgentReasoning } from './class.js';
+import { UIAgentReasoning } from './agent-reasoning.class.js';
 
 defineIfFree('agent-reasoning-ui', UIAgentReasoning);
 

package/components/agent-suggestions/agent-suggestions.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAgentSuggestions } from './class.js';
+import { UIAgentSuggestions } from './agent-suggestions.class.js';
 
 defineIfFree('agent-suggestions-ui', UIAgentSuggestions);
 

package/components/alert/alert.a2ui.json

@@ -23,6 +23,16 @@
       "type": "string",
       "default": ""
     },
+    "amount": {
+      "description": "Dunning mode only — the unpaid amount as a decimal major-unit number (`24.50`, not minor units like `2450`). Formatted via `Intl.NumberFormat` using [currency] and [lang]. Ignored when [pattern] is not `dunning`.",
+      "type": "number",
+      "default": 0
+    },
+    "cardLast4": {
+      "description": "Dunning mode only — last 4 digits of the declined card. Rendered as \"ending 4242\". Ignored when [pattern] is not `dunning`. Attribute spelling: `card-last4`.",
+      "type": "string",
+      "default": ""
+    },
     "closable": {
       "description": "Whether a close button is displayed. Alias [dismissible] is also accepted (same semantics, different spelling — the corpus and many libraries use both; both map to the same state).",
       "type": "boolean",
@@ -31,16 +41,47 @@
     "component": {
       "const": "Alert"
     },
+    "currency": {
+      "description": "Dunning mode only — ISO 4217 currency code driving the `Intl.NumberFormat` style=\"currency\" rendering. Defaults to `USD`.",
+      "type": "string",
+      "default": "USD"
+    },
     "dismissible": {
       "description": "Public alias for [closable] — same semantics. Both attributes render the close button. Use whichever spelling matches your authoring style.",
       "type": "boolean",
       "default": false
     },
+    "dueAt": {
+      "description": "Dunning mode only — ISO 8601 due / failed-at timestamp. Formatted via `Intl.DateTimeFormat`. Ignored when [pattern] is not `dunning`. Attribute spelling: `due-at`.",
+      "type": "string",
+      "default": ""
+    },
     "icon": {
       "description": "Icon identifier displayed before the message content",
       "type": "string",
       "default": ""
     },
+    "pattern": {
+      "description": "Domain pattern mode. Default is empty (standard alert). Setting `pattern=\"dunning\"` switches to billing dunning render mode — stamps a formatted amount + due-date + decline-reason from props and re-dispatches descendant `[data-dunning-action]` button clicks as a unified `dunning-action` event. Spec: SPEC-006.",
+      "type": "string",
+      "enum": [
+        "",
+        "dunning"
+      ],
+      "default": ""
+    },
+    "reason": {
+      "description": "Dunning mode only — decline reason. Drives the leading icon (declined → `x-circle`, expired → `clock`, insufficient → `wallet`, network → `wifi-slash`). One of: `declined`, `expired`, `insufficient`, `network`, or empty.",
+      "type": "string",
+      "enum": [
+        "",
+        "declined",
+        "expired",
+        "insufficient",
+        "network"
+      ],
+      "default": ""
+    },
     "text": {
       "description": "Single-line alert message. For two-line \"headline + body\" alerts, use [title] + [description] instead. For rich content (links, formatting), use the [slot=\"content\"] slot.",
       "type": "string",
@@ -66,12 +107,26 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
-    "anti_patterns": [],
+    "anti_patterns": [
+      {
+        "fix": "<alert-ui pattern=\"dunning\" variant=\"danger\">",
+        "why": "Dunning is always a failure surface; info mis-signals severity.",
+        "wrong": "<alert-ui pattern=\"dunning\" variant=\"info\">"
+      },
+      {
+        "fix": "<alert-ui pattern=\"dunning\" amount=\"24.50\" currency=\"USD\" due-at=\"2026-05-20\">",
+        "why": "Amount baked into title defeats Intl formatting + telemetry.",
+        "wrong": "<alert-ui pattern=\"dunning\" title=\"Payment failed $24.50\">"
+      }
+    ],
     "category": "container",
     "composes": [],
     "events": {
       "close": {
         "description": "Fired when the close button is clicked"
+      },
+      "dunning-action": {
+        "description": "Dunning pattern only — fired when a descendant button with `[data-dunning-action]` is clicked. Detail shape `{ action, amount, currency, dueAt }`; the action string is the value of the `data-dunning-action` attribute (typically `\"update\"` or `\"retry\"`)."
       }
     },
     "examples": [
@@ -84,6 +139,11 @@
         "description": "Card with error alert and a retry button for error state display.",
         "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"alert\"\n    ]\n  },\n  {\n    \"id\": \"alert\",\n    \"component\": \"Alert\",\n    \"variant\": \"error\",\n    \"title\": \"Something went wrong\",\n    \"description\": \"We encountered an error while loading the data. Please try again.\"\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"retry\"\n    ]\n  },\n  {\n    \"id\": \"retry\",\n    \"component\": \"Button\",\n    \"text\": \"Retry\",\n    \"icon\": \"refresh\",\n    \"variant\": \"primary\"\n  }\n]",
         "name": "error-state"
+      },
+      {
+        "description": "Billing dunning banner — declined card with retry + update-card actions (SPEC-006).",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Alert\",\n    \"pattern\": \"dunning\",\n    \"variant\": \"danger\",\n    \"amount\": 24.5,\n    \"currency\": \"USD\",\n    \"dueAt\": \"2026-05-20T00:00:00Z\",\n    \"cardLast4\": \"4242\",\n    \"reason\": \"declined\",\n    \"children\": [\"btn-update\", \"btn-retry\"]\n  },\n  {\n    \"id\": \"btn-update\",\n    \"component\": \"Button\",\n    \"text\": \"Update payment method\",\n    \"variant\": \"primary\",\n    \"slot\": \"actions\"\n  },\n  {\n    \"id\": \"btn-retry\",\n    \"component\": \"Button\",\n    \"text\": \"Retry charge\",\n    \"variant\": \"outline\",\n    \"slot\": \"actions\"\n  }\n]",
+        "name": "dunning-payment-failed"
       }
     ],
     "keywords": [
@@ -112,6 +172,9 @@
       "action": {
         "description": "Optional trailing action button (e.g. \"Refresh\", \"Status page\"). Right-aligned in the flex layout. See system-banners pattern for examples."
       },
+      "actions": {
+        "description": "Dunning pattern only — action button stack (typically two `<button-ui>` with `data-dunning-action=\"update\"` and `data-dunning-action=\"retry\"`). Sits below the formatted message in the col layout when `pattern=\"dunning\"`."
+      },
       "close": {
         "description": "Close button. Stamped automatically when `closable` is set; the stamped element is `<button-ui slot=\"close\" icon=\"x\" variant=\"ghost\" size=\"sm\">`. Override by passing a custom `slot=\"close\"` button."
       },

package/components/alert/{class.js → alert.class.js}

@@ -50,6 +50,17 @@ export class UIAlert extends UIElement {
     closable:    { type: Boolean, default: false, reflect: true },
     dismissible: { type: Boolean, default: false, reflect: true },
     icon:        { type: String,  default: '', reflect: true },
+    /* SPEC-006 dunning pattern \u2014 billing payment-failed mode. When
+       `pattern="dunning"`, the alert stamps an Intl-formatted amount +
+       due-date + decline-reason from the props below and re-dispatches
+       descendant `[data-dunning-action]` button clicks as a unified
+       `dunning-action` event. See SPEC-006 for the full rationale. */
+    pattern:     { type: String,  default: '', reflect: true },
+    amount:      { type: Number,  default: 0,  reflect: true },
+    currency:    { type: String,  default: 'USD', reflect: true },
+    dueAt:       { type: String,  default: '', reflect: true, attribute: 'due-at' },
+    cardLast4:   { type: String,  default: '', reflect: true, attribute: 'card-last4' },
+    reason:      { type: String,  default: '', reflect: true },
   };
 
   static parts = {
@@ -62,6 +73,15 @@ export class UIAlert extends UIElement {
     close:   '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
   };
 
+  /* SPEC-006 \u2014 decline-reason \u2192 leading icon map. Used when
+     `pattern="dunning"` and no explicit [icon] override is set. */
+  static #DUNNING_ICONS = {
+    declined: 'x-circle',
+    expired: 'clock',
+    insufficient: 'wallet',
+    network: 'wifi-slash',
+  };
+
   static template = () => null;
 
   /**
@@ -100,7 +120,28 @@ export class UIAlert extends UIElement {
   }
 
   #onPress = (e) => {
-    if (e.target.closest('[slot="close"]')) this.#close();
+    if (e.target.closest('[slot="close"]')) {
+      this.#close();
+      return;
+    }
+    // SPEC-006 — dunning action delegation. Re-dispatch as a unified
+    // `dunning-action` event so downstream telemetry only listens once.
+    if (this.pattern === 'dunning') {
+      const trigger = e.target.closest('[data-dunning-action]');
+      if (trigger && this.contains(trigger)) {
+        const action = trigger.getAttribute('data-dunning-action') || '';
+        this.dispatchEvent(new CustomEvent('dunning-action', {
+          bubbles: true,
+          composed: true,
+          detail: {
+            action,
+            amount: this.amount,
+            currency: this.currency,
+            dueAt: this.dueAt,
+          },
+        }));
+      }
+    }
   };
 
   connected() {
@@ -108,7 +149,7 @@ export class UIAlert extends UIElement {
     this.#updateRole();
 
     // Stamp default DOM if nothing was provided
-    if (this.icon) this.ensure('leading');
+    if (this.icon || (this.pattern === 'dunning' && this.reason)) this.ensure('leading');
     this.ensure('content');
     if (this.closable) this.ensure('close');
 
@@ -120,6 +161,15 @@ export class UIAlert extends UIElement {
   }
 
   render() {
+    // SPEC-006 — dunning pattern: branch into a separate render path
+    // that stamps Intl-formatted amount + due-date + reason into the
+    // content slot. The standard alert render path below is skipped.
+    if (this.pattern === 'dunning') {
+      this.#renderDunning();
+      this.#updateRole();
+      return;
+    }
+
     // Icon
     if (this.icon) {
       const leading = this.ensure('leading');
@@ -182,6 +232,143 @@ export class UIAlert extends UIElement {
     this.#updateRole();
   }
 
+  /**
+   * SPEC-006 — dunning render path.
+   *
+   * Stamps the content slot with a bolded title (per-reason copy) +
+   * a metadata line ("Card ending 4242 · declined May 20, 2026") +
+   * an Intl-formatted amount. The leading icon is selected from
+   * `#DUNNING_ICONS` keyed by the [reason] attribute (or [icon] if
+   * the consumer explicitly overrode).
+   *
+   * Re-runs on every render — formatting is stable + idempotent so a
+   * re-stamp produces the same DOM. We rebuild the content subtree
+   * each render to keep the auto-stamp markers from drifting between
+   * the dunning path and the standard path if [pattern] is toggled
+   * at runtime.
+   */
+  #renderDunning() {
+    // Leading icon — explicit [icon] beats the reason map
+    const iconName = this.icon || UIAlert.#DUNNING_ICONS[this.reason] || 'x-circle';
+    const leading = this.ensure('leading');
+    if (leading) leading.setAttribute('name', iconName);
+
+    // Content
+    const content = this.ensure('content');
+    if (!content) return;
+    content.setAttribute('data-alert-auto', 'dunning');
+    content.replaceChildren();
+
+    // Title line — explicit [title] beats the per-reason default
+    const titleText = this.title || this.#defaultDunningTitle();
+    if (titleText) {
+      const strong = document.createElement('strong');
+      strong.setAttribute('data-dunning-title', '');
+      strong.textContent = titleText;
+      content.appendChild(strong);
+    }
+
+    // Body line — formatted amount + metadata. We put amount first
+    // (it's the most-scanned datum) followed by the meta string.
+    const amountText = this.#formatAmount();
+    const metaText = this.#dunningMeta();
+    if (amountText || metaText) {
+      content.appendChild(document.createTextNode(' '));
+      if (amountText) {
+        const amt = document.createElement('span');
+        amt.setAttribute('data-dunning-amount', '');
+        amt.textContent = amountText;
+        content.appendChild(amt);
+      }
+      if (amountText && metaText) {
+        content.appendChild(document.createTextNode(' '));
+      }
+      if (metaText) {
+        const meta = document.createElement('span');
+        meta.setAttribute('data-dunning-meta', '');
+        meta.textContent = metaText;
+        content.appendChild(meta);
+      }
+    }
+
+    // Composed accessible name — title + amount + meta in DOM order
+    const aria = [titleText, amountText, metaText].filter(Boolean).join('. ');
+    if (aria) this.setAttribute('aria-label', aria);
+
+    // Close button — dismissible-on-dunning is advisory-not-blocked
+    // (SPEC-006 OD-002 lean A). Pass through.
+    if (this.closable || this.dismissible) {
+      this.ensure('close');
+    } else {
+      this.drop('close');
+    }
+  }
+
+  #defaultDunningTitle() {
+    switch (this.reason) {
+      case 'expired': return 'Card expired';
+      case 'insufficient': return 'Insufficient funds';
+      case 'network': return 'Network error';
+      case 'declined': return 'Payment failed';
+      default: return this.variant === 'warning' ? 'Payment due soon' : 'Payment failed';
+    }
+  }
+
+  #formatAmount() {
+    if (!this.amount && this.amount !== 0) return '';
+    if (this.amount === 0) return '';
+    try {
+      const lang = this.getAttribute('lang') || this.lang || undefined;
+      return new Intl.NumberFormat(lang, {
+        style: 'currency',
+        currency: this.currency || 'USD',
+      }).format(this.amount);
+    } catch {
+      // Fallback if Intl rejects the currency code
+      return `${this.currency || ''} ${this.amount}`.trim();
+    }
+  }
+
+  #formatDueDate() {
+    if (!this.dueAt) return '';
+    const d = new Date(this.dueAt);
+    if (Number.isNaN(d.getTime())) return '';
+    try {
+      const lang = this.getAttribute('lang') || this.lang || undefined;
+      return new Intl.DateTimeFormat(lang, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      }).format(d);
+    } catch {
+      return d.toDateString();
+    }
+  }
+
+  #dunningMeta() {
+    const parts = [];
+    if (this.cardLast4) parts.push(`Card ending ${this.cardLast4}`);
+    if (this.reason && this.reason !== 'declined') {
+      parts.push(this.#reasonLabel());
+    }
+    const date = this.#formatDueDate();
+    if (date) {
+      const prefix = this.variant === 'warning' ? 'due' : 'failed';
+      parts.push(`${prefix} ${date}`);
+    }
+    return parts.join(' · ');
+  }
+
+  #reasonLabel() {
+    switch (this.reason) {
+      case 'expired': return 'expired';
+      case 'insufficient': return 'insufficient funds';
+      case 'network': return 'network error';
+      case 'declined': return 'declined';
+      default: return '';
+    }
+  }
+
   #updateRole() {
     const role = (this.variant === 'danger' || this.variant === 'warning') ? 'alert' : 'status';
     this.setAttribute('role', role);