@adia-ai/web-components 0.6.35 → 0.6.37

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.37] — 2026-05-25
+
+### Changed — `--a-warning-bg` redirected from `-strong` to `-20-tint` (bright caution-tape amber, scheme-independent)
+
+- **Token-system fix for the muddy warning surface class.** Previously `--a-warning-bg` was an alias for `--a-warning-strong` (= `-50`, mid-tone amber). Paired with `--a-warning-fg` (= `-text-strong` = `-10-shade`, dark brown — per `semantics.css:309` "warning is light-colored — text on warning fills should be dark"), the pair collapsed to brown-on-brown chips. The local fix shipped in `<tag-ui>` / `<badge-ui>` (literal `--a-warning-20-tint` override) is now hoisted to the L3 token layer so every consumer benefits: progress-row, rating, password-strength, agent-artifact, text[color=warning], timeline. `<button-ui color="warning">` updated to read `--a-warning-bg` (was `-strong`) so it joins the fix. Local tag/badge `-20-tint` overrides removed — they now read the canonical `-bg` token cleanly.
+- **`-strong` unchanged** — still the L2 saturated mid-tone, used as a foreground/icon color by alert / chart / code / empty-state / agent-trace (those use it AS a color, not as a surface to put text on, so the `light-dark` swap stays appropriate).
+- **Why `-20-tint` is bright in both schemes**: the lightness math `l-max - 0.2*(l-max - l-min)` is scheme-independent (no `light-dark()` swap), so warning surfaces keep the caution-tape look in dark mode too. Other family `-bg` tokens stay scheme-flipping because they pair with `-fg` (= `-05-tint` near-white) which has enough contrast either way.
+- Files: `styles/colors/semantics.css`, `components/button/button.css`, `components/tag/tag.{css,test.js}`, `components/badge/badge.css`.
+
+### Added — `<tag-ui>` + `<badge-ui>` gain `[tone="outline"]` third chip style
+
+- **Outline tone**: transparent bg + family-colored 1px border + family-colored text. The lightest visual weight; good in dense data tables or faceted filter rows where multiple chips would otherwise compete. Family variants resolve to `--a-{family}-text` + `--a-{family}-border`; neutral default resolves to `--a-fg-muted` + `--a-border`.
+- **Vocabulary mirror across the two primitives**: tag-ui defaults to `solid` tone (filter chip / status pill identity); badge-ui defaults to `muted` (quiet metadata identity). Both accept all three values (`solid` | `muted` | `outline`) so authors can swap shape without learning a new prop. Badge-ui's existing `primary` variant remains as a shortcut for `<badge-ui variant="accent" tone="solid">`.
+- New regression guards: 6 source-grep tests on tag-ui for outline-tone rules.
+- Files: `components/tag/tag.{css,yaml,test.js,examples.html}`, `components/badge/badge.{css,yaml,examples.html}`, regenerated `.a2ui.json` sidecars.
+
+## [0.6.36] — 2026-05-24
+
+### Changed — `<pagination-ui>` composes `<button-ui>` for every cell + adds universal `[size]` thread-through
+
+- **Native-primitive leak closed.** `pagination.class.js:128` previously stamped raw `<button>` for every page / prev / next cell — the exact failure mode `dogfood-sweep` mode 4 audits for, and the same shape that produced the FB-55 silent-failure trap on `<admin-shell>`. Substrate authors reading pagination as the canonical numbered-button pattern would carry the leak into downstream components. Substrate now stamps `<button-ui>` for every cell so chrome / hover / focus-ring / disabled-state / active-fill come from button-ui's token chain (the canonical surface matrix), not a pagination-tier re-impl.
+- **`[size]` prop added** — reflected enum (`sm` | `md` | `lg`, default `md` — aligned with `<button-ui>`'s default since pagination is now a button-ui composite). Threads through to every nested `<button-ui size=…>` so pagination honors the substrate's 24/30/36 px universal size system (with `[density]` modifier). Previously pagination hardcoded `--a-size-sm` (24 px), so consumers on md/lg surfaces had no escape hatch.
+- **Active state now `variant="primary"`** instead of a pagination-tier `[data-active]` + custom-bg-token chain. The filled-accent state inherits from button-ui's primary surface matrix — one token chain, one source of truth.
+- **Prev / Next now use Phosphor `caret-left` / `caret-right`** via `<button-ui icon=…>` (was: `‹` / `›` Unicode glyphs). Declared in `static requiredIcons` so the audit picks them up.
+- **`variant="button"` mode** swaps each non-active cell to `variant="outline"` (the bordered 1×1 mode). `pagination.css` shrunk from 165 → 71 lines — the 94 lines of button styling rules collapsed into button-ui composition.
+- **Constant-width compact-mode layout** — `#buildRange` redesigned around an invariant `W = 2*siblings + 5` (= 7 cells at siblings=1; 9 at siblings=2). Three layouts (near-start / middle / near-end) each yield exactly W cells so the row width stays stable when the current page advances. When `total ≤ W`, every page renders (no ellipsis — compressing wouldn't save horizontal slots). Replaces the "bridge if only 1 is skipped" heuristic from an earlier draft, which produced asymmetric cell counts under page advances (page 3 → 6 cells, page 4 → 7 cells — visibly jumpy).
+- **17 new DOM + source-grep regression tests** (`pagination.test.js`, NEW). Guards: no raw `<button>` in source; `requiredIcons` declared; size threads to every nested button-ui; active page is `variant="primary"`; rest variant tracks the host's `variant=` (ghost/outline); **width invariance under all page positions for total=10 siblings=1 (always 7 cells) and total=20 siblings=2 (always 9 cells)**.
+- Files: `components/pagination/pagination.{class.js,yaml,css,test.js}`, regenerated sidecar + corpus.
+
+### 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.85` (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 18%, transparent)` bg highlight — same color family as the host, not a stark neutral wash. The dismiss `<icon-ui>` now stamps with `weight="bold"` so the X reads crisply at small size on every variant (was implicit regular — too thin against bright bgs like warning amber). 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)

package/components/badge/badge.a2ui.json

@@ -54,6 +54,16 @@
       "description": "Badge display text. Renderer routes this to the `text` attribute via CSS attr(text) on ::after.",
       "$ref": "common_types.json#/$defs/DynamicString"
     },
+    "tone": {
+      "description": "Fill style — orthogonal to [variant]. Badge defaults to `muted`\n(quiet metadata is the primitive's identity — counts, IDs, status\npills in dense rows). Three values:\n  - `muted` (default) — tinted bg + scheme-paired text. Same as\n    the existing family-variant rules.\n  - `solid` — saturated bg + on-strong text. Use for hero badges\n    where the badge IS the state (e.g. a single inline error). The\n    existing `primary` variant is a shortcut for accent + solid.\n  - `outline` — transparent bg + family-colored border + family-\n    colored text. Lightest visual weight; good in dense data rows.\nVocabulary mirrors `<tag-ui>` (which defaults to solid, given its\ndifferent role as filter / autocomplete chip).\n",
+      "type": "string",
+      "enum": [
+        "muted",
+        "solid",
+        "outline"
+      ],
+      "default": "muted"
+    },
     "variant": {
       "description": "Semantic color variant.",
       "type": "string",

package/components/badge/badge.css

@@ -100,5 +100,75 @@
     --badge-fg-default: var(--a-fg);
   }
 
+  /* ── Tone modifier — orthogonal to [variant] ──
+     Badge's default tone is `muted` (the rules above) — quiet metadata is
+     the primitive's identity. `[tone="solid"]` opts into the saturated-fill
+     pair (same shape <tag-ui>'s solid default uses); `[tone="outline"]`
+     into the transparent-fill + colored-ring shape. Same vocabulary as
+     <tag-ui>; different defaults reflecting each primitive's role.
+
+     Warning uses --a-warning-20-tint as bg (a bright amber, scheme-
+     independent) instead of --a-warning-bg — the latter pair collapses
+     to muddy brown-on-brown (-text-strong is dark, -bg is mid-tone).
+     See <tag-ui>'s identical workaround. Token-system follow-up planned. */
+  :scope[tone="solid"][variant="info"] {
+    --badge-bg-default: var(--a-info-bg);
+    --badge-fg-default: var(--a-info-fg);
+  }
+  :scope[tone="solid"][variant="success"] {
+    --badge-bg-default: var(--a-success-bg);
+    --badge-fg-default: var(--a-success-fg);
+  }
+  :scope[tone="solid"][variant="warning"] {
+    /* --a-warning-bg is the bright-amber step (semantics.css L3 redirect
+       to -20-tint) — see also <tag-ui>'s warning solid pair. */
+    --badge-bg-default: var(--a-warning-bg);
+    --badge-fg-default: var(--a-warning-fg);
+  }
+  :scope[tone="solid"][variant="danger"] {
+    --badge-bg-default: var(--a-danger-bg);
+    --badge-fg-default: var(--a-danger-fg);
+  }
+  :scope[tone="solid"][variant="accent"] {
+    --badge-bg-default: var(--a-accent-bg);
+    --badge-fg-default: var(--a-accent-fg);
+  }
+  /* Solid on neutral default → high-contrast inverse stamp. */
+  :scope[tone="solid"]:not([variant="info"]):not([variant="success"]):not([variant="warning"]):not([variant="danger"]):not([variant="accent"]):not([variant="primary"]) {
+    --badge-bg-default: var(--a-fg);
+    --badge-fg-default: var(--a-bg);
+  }
+
+  /* ── `[tone="outline"]` — transparent bg + family-colored border + text ── */
+  :scope[tone="outline"] {
+    --badge-bg-default: transparent;
+    border: 1px solid var(--badge-border, var(--badge-border-default, transparent));
+  }
+  :scope[tone="outline"][variant="info"] {
+    --badge-fg-default:     var(--a-info-text);
+    --badge-border-default: var(--a-info-border);
+  }
+  :scope[tone="outline"][variant="success"] {
+    --badge-fg-default:     var(--a-success-text);
+    --badge-border-default: var(--a-success-border);
+  }
+  :scope[tone="outline"][variant="warning"] {
+    --badge-fg-default:     var(--a-warning-text);
+    --badge-border-default: var(--a-warning-border);
+  }
+  :scope[tone="outline"][variant="danger"] {
+    --badge-fg-default:     var(--a-danger-text);
+    --badge-border-default: var(--a-danger-border);
+  }
+  :scope[tone="outline"][variant="accent"] {
+    --badge-fg-default:     var(--a-accent-text);
+    --badge-border-default: var(--a-accent-border);
+  }
+  /* Outline on neutral — fg-muted text + subtle ring. */
+  :scope[tone="outline"]:not([variant="info"]):not([variant="success"]):not([variant="warning"]):not([variant="danger"]):not([variant="accent"]):not([variant="primary"]) {
+    --badge-fg-default:     var(--a-fg-muted);
+    --badge-border-default: var(--a-border);
+  }
+
   /* Size handled by universal [size] attribute system. */
 }

package/components/badge/badge.yaml

@@ -70,6 +70,26 @@ props:
       - primary
       - muted
       - neutral
+  tone:
+    description: |
+      Fill style — orthogonal to [variant]. Badge defaults to `muted`
+      (quiet metadata is the primitive's identity — counts, IDs, status
+      pills in dense rows). Three values:
+        - `muted` (default) — tinted bg + scheme-paired text. Same as
+          the existing family-variant rules.
+        - `solid` — saturated bg + on-strong text. Use for hero badges
+          where the badge IS the state (e.g. a single inline error). The
+          existing `primary` variant is a shortcut for accent + solid.
+        - `outline` — transparent bg + family-colored border + family-
+          colored text. Lightest visual weight; good in dense data rows.
+      Vocabulary mirrors `<tag-ui>` (which defaults to solid, given its
+      different role as filter / autocomplete chip).
+    type: string
+    default: muted
+    enum:
+      - muted
+      - solid
+      - outline
 events: {}
 slots: {}
 states:

package/components/blockquote/blockquote.a2ui.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Blockquote.json",
+  "title": "Blockquote",
+  "description": "Styled quotation block with a left visual indicator (border rule) +\nitalic body text + optional `cite` attribution line. Use for pull-quotes,\ntestimonials, or inline citations within prose. The default visual\nfollows the prose typography family — pair with `<text-ui>` body\nvariants inside, or pass raw text in the default slot. The optional\n[cite] attribute (or [slot=cite]) renders a small attribution line\nbelow the quote prefixed with an em-dash. Semantic blockquote element\nwith `role=\"blockquote\"` implied via tag name (do NOT wrap in a native\n`<blockquote>` — that produces nested-blockquote semantics).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "cite": {
+      "description": "Source attribution shown beneath the quote (small, muted, em-dash\nprefix). For richer attribution (links, multi-line), use the\n`[slot=\"cite\"]` content slot instead — when both are set, the slot\ncontent wins. Plain-string convenience prop for the common case.\n",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "Blockquote"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "display",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Pull-quote with em-dash attribution.",
+        "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"Blockquote\",\n    \"cite\": \"Steve Jobs, Stanford Commencement, 2005\",\n    \"content\": \"Stay hungry. Stay foolish.\"\n  }\n]\n",
+        "name": "default"
+      },
+      {
+        "description": "Blockquote with a linked citation via slot.",
+        "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"Blockquote\",\n    \"children\": [\"body\", \"src\"]\n  },\n  {\n    \"id\": \"body\",\n    \"component\": \"Text\",\n    \"textContent\": \"The best way to predict the future is to invent it.\"\n  },\n  {\n    \"id\": \"src\",\n    \"component\": \"Link\",\n    \"slot\": \"cite\",\n    \"href\": \"https://en.wikipedia.org/wiki/Alan_Kay\",\n    \"text\": \"Alan Kay (1971)\"\n  }\n]\n",
+        "name": "rich-attribution"
+      }
+    ],
+    "keywords": [
+      "blockquote",
+      "quote",
+      "pull-quote",
+      "quotation",
+      "testimonial",
+      "citation",
+      "cite"
+    ],
+    "name": "UIBlockquote",
+    "related": [
+      "text",
+      "link",
+      "card"
+    ],
+    "slots": {
+      "default": {
+        "description": "The quote body. Plain text or composed `<text-ui>` / inline elements."
+      },
+      "cite": {
+        "description": "Optional citation override. Use for rich attribution (linked source,\nperson + role pairing) where [cite] string is insufficient.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for reading.",
+        "name": "idle"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "quote": [
+        "blockquote",
+        "quotation",
+        "pull-quote"
+      ],
+      "testimonial": [
+        "blockquote",
+        "quote"
+      ]
+    },
+    "tag": "blockquote-ui",
+    "tokens": {
+      "--blockquote-cite-fg": {
+        "description": "Citation text color (muted).",
+        "default": "var(--a-fg-muted)"
+      },
+      "--blockquote-cite-size": {
+        "description": "Citation font size.",
+        "default": "var(--a-ui-sm)"
+      },
+      "--blockquote-fg": {
+        "description": "Quote text color.",
+        "default": "var(--a-fg-subtle)"
+      },
+      "--blockquote-pad-block": {
+        "description": "Vertical padding inside the blockquote.",
+        "default": "var(--a-space-2)"
+      },
+      "--blockquote-pad-inline": {
+        "description": "Inline padding between the rule and the quote text.",
+        "default": "var(--a-space-3)"
+      },
+      "--blockquote-rule-color": {
+        "description": "Color of the left indicator rule.",
+        "default": "var(--a-border-strong)"
+      },
+      "--blockquote-rule-width": {
+        "description": "Width of the left indicator rule.",
+        "default": "2px"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/blockquote/blockquote.class.js

@@ -0,0 +1,68 @@
+/**
+ * Non-side-effect class export for `<blockquote-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the
+ * tag. Useful for test isolation, subclassing with tag-name override,
+ * or selective composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/blockquote`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <blockquote-ui cite="Alan Kay">
+ *   The best way to predict the future is to invent it.
+ * </blockquote-ui>
+ *
+ * Layout:
+ *   │ italic quote body                              ← left rule indicator
+ *   │ — citation line                                ← em-dash prefix
+ *
+ * Two attribution paths:
+ *   • [cite="..."] attribute → renders a small em-dashed line below
+ *   • <span slot="cite">...</span> slot → richer attribution (links, etc.)
+ *     Slot content overrides the attribute when both are present.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIBlockquote extends UIElement {
+  static properties = {
+    cite: { type: String, default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    // Implicit semantic role — the tag name carries blockquote meaning,
+    // but assistive tech doesn't infer from custom-element tag names.
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'blockquote');
+  }
+
+  render() {
+    // Stamp the citation line from [cite] only when no [slot="cite"]
+    // content is provided. Slot wins on conflict (per the contract).
+    const slotted = this.querySelector('[slot="cite"]:not([data-cite-stamped])');
+    const stamped = this.querySelector('[slot="cite"][data-cite-stamped]');
+    if (slotted) {
+      // Author supplied richer attribution — drop any stamped version.
+      stamped?.remove();
+      return;
+    }
+    if (this.cite) {
+      if (stamped) {
+        stamped.textContent = this.cite;
+      } else {
+        const el = document.createElement('span');
+        el.setAttribute('slot', 'cite');
+        el.setAttribute('data-cite-stamped', '');
+        el.textContent = this.cite;
+        this.appendChild(el);
+      }
+    } else if (stamped) {
+      stamped.remove();
+    }
+  }
+}

package/components/blockquote/blockquote.css

@@ -0,0 +1,46 @@
+/* ═══════════════════════════════════════════════════════════════
+   BLOCKQUOTE-UI — Styled quotation block with left rule + cite line.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (blockquote-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --blockquote-rule-color-default:  var(--a-border-strong);
+    --blockquote-rule-width-default:  2px;
+    --blockquote-pad-inline-default:  var(--a-space-3);
+    --blockquote-pad-block-default:   var(--a-space-2);
+    --blockquote-fg-default:          var(--a-fg-subtle);
+    --blockquote-cite-fg-default:     var(--a-fg-muted);
+    --blockquote-cite-size-default:   var(--a-ui-sm);
+    --blockquote-cite-mt-default:     var(--a-space-2);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    padding-inline-start: var(--blockquote-pad-inline, var(--blockquote-pad-inline-default));
+    padding-block: var(--blockquote-pad-block, var(--blockquote-pad-block-default));
+    border-inline-start: var(--blockquote-rule-width, var(--blockquote-rule-width-default))
+                        solid
+                        var(--blockquote-rule-color, var(--blockquote-rule-color-default));
+    color: var(--blockquote-fg, var(--blockquote-fg-default));
+    font-style: italic;
+    /* Reset native margin if a consumer wraps in a native <blockquote>
+       (not recommended — see yaml a2ui rule #3) so nesting renders
+       reasonably. */
+    margin: 0;
+  }
+
+  /* Cite line — em-dash prefix + small + muted + non-italic */
+  [slot="cite"] {
+    display: block;
+    margin-top: var(--blockquote-cite-mt, var(--blockquote-cite-mt-default));
+    font-style: normal;
+    font-size: var(--blockquote-cite-size, var(--blockquote-cite-size-default));
+    color: var(--blockquote-cite-fg, var(--blockquote-cite-fg-default));
+  }
+
+  [slot="cite"]::before {
+    content: "— ";
+  }
+}

package/components/blockquote/blockquote.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `<blockquote-ui>` — Styled quotation block with a left visual indicator (border rule) +
+italic body text + optional `cite` attribution line. Use for pull-quotes,
+testimonials, or inline citations within prose. The default visual
+follows the prose typography family — pair with `<text-ui>` body
+variants inside, or pass raw text in the default slot. The optional
+[cite] attribute (or [slot=cite]) renders a small attribution line
+below the quote prefixed with an em-dash. Semantic blockquote element
+with `role="blockquote"` implied via tag name (do NOT wrap in a native
+`<blockquote>` — that produces nested-blockquote semantics).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/blockquote
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIBlockquote extends UIElement {
+  /** Source attribution shown beneath the quote (small, muted, em-dash
+prefix). For richer attribution (links, multi-line), use the
+`[slot="cite"]` content slot instead — when both are set, the slot
+content wins. Plain-string convenience prop for the common case.
+ */
+  cite: string;
+}

package/components/blockquote/blockquote.js

@@ -0,0 +1,17 @@
+/**
+ * `<blockquote-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIBlockquote } from '@adia-ai/web-components/components/blockquote/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIBlockquote } from './blockquote.class.js';
+
+defineIfFree('blockquote-ui', UIBlockquote);
+
+export { UIBlockquote };

package/components/blockquote/blockquote.yaml

@@ -0,0 +1,124 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIBlockquote
+tag: blockquote-ui
+status: stable
+component: Blockquote
+category: display
+version: 1
+description: |
+  Styled quotation block with a left visual indicator (border rule) +
+  italic body text + optional `cite` attribution line. Use for pull-quotes,
+  testimonials, or inline citations within prose. The default visual
+  follows the prose typography family — pair with `<text-ui>` body
+  variants inside, or pass raw text in the default slot. The optional
+  [cite] attribute (or [slot=cite]) renders a small attribution line
+  below the quote prefixed with an em-dash. Semantic blockquote element
+  with `role="blockquote"` implied via tag name (do NOT wrap in a native
+  `<blockquote>` — that produces nested-blockquote semantics).
+props:
+  cite:
+    description: |
+      Source attribution shown beneath the quote (small, muted, em-dash
+      prefix). For richer attribution (links, multi-line), use the
+      `[slot="cite"]` content slot instead — when both are set, the slot
+      content wins. Plain-string convenience prop for the common case.
+    type: string
+    default: ""
+    reflect: true
+events: {}
+slots:
+  default:
+    description: The quote body. Plain text or composed `<text-ui>` / inline elements.
+  cite:
+    description: |
+      Optional citation override. Use for rich attribution (linked source,
+      person + role pairing) where [cite] string is insufficient.
+states:
+  - name: idle
+    description: Default, ready for reading.
+traits: []
+tokens:
+  --blockquote-rule-color:
+    description: Color of the left indicator rule.
+    default: var(--a-border-strong)
+  --blockquote-rule-width:
+    description: Width of the left indicator rule.
+    default: 2px
+  --blockquote-pad-inline:
+    description: Inline padding between the rule and the quote text.
+    default: var(--a-space-3)
+  --blockquote-pad-block:
+    description: Vertical padding inside the blockquote.
+    default: var(--a-space-2)
+  --blockquote-fg:
+    description: Quote text color.
+    default: var(--a-fg-subtle)
+  --blockquote-cite-fg:
+    description: Citation text color (muted).
+    default: var(--a-fg-muted)
+  --blockquote-cite-size:
+    description: Citation font size.
+    default: var(--a-ui-sm)
+a2ui:
+  rules:
+    - rule: "Use for pull-quotes, testimonials, or inline citations. Renders italic body text with a left rule indicator + optional em-dash attribution line."
+      reason: "Quote-display primitive with semantic chrome."
+    - rule: "Set [cite] for plain-string attribution; use [slot=\"cite\"] for rich attribution (linked source, role pairing). Slot content overrides the [cite] prop when both are set."
+      reason: "Two attribution paths — string for the common case, slot for richness."
+    - rule: "Do NOT wrap blockquote-ui in a native <blockquote> element — that produces nested-blockquote semantics. The tag IS the blockquote."
+      reason: "Avoid double-wrapping."
+anti_patterns: []
+examples:
+  - name: default
+    description: Pull-quote with em-dash attribution.
+    a2ui: |
+      [
+        {
+          "id": "q",
+          "component": "Blockquote",
+          "cite": "Steve Jobs, Stanford Commencement, 2005",
+          "content": "Stay hungry. Stay foolish."
+        }
+      ]
+  - name: rich-attribution
+    description: Blockquote with a linked citation via slot.
+    a2ui: |
+      [
+        {
+          "id": "q",
+          "component": "Blockquote",
+          "children": ["body", "src"]
+        },
+        {
+          "id": "body",
+          "component": "Text",
+          "textContent": "The best way to predict the future is to invent it."
+        },
+        {
+          "id": "src",
+          "component": "Link",
+          "slot": "cite",
+          "href": "https://en.wikipedia.org/wiki/Alan_Kay",
+          "text": "Alan Kay (1971)"
+        }
+      ]
+keywords:
+  - blockquote
+  - quote
+  - pull-quote
+  - quotation
+  - testimonial
+  - citation
+  - cite
+synonyms:
+  quote:
+    - blockquote
+    - quotation
+    - pull-quote
+  testimonial:
+    - blockquote
+    - quote
+related:
+  - text
+  - link
+  - card

package/components/button/button.css

@@ -161,15 +161,23 @@ button-ui[color="danger"]:not([disabled]):hover {
     --button-fg-default: var(--button-fg-danger, var(--button-fg-danger-default));
   }
   :scope[color="success"] {
-    --button-bg-default: var(--a-success-strong);
+    /* Consume the L3 `-bg` alias, not the L2 `-strong` step. Currently
+       resolves identically (both = `-50`), but consuming `-bg` future-
+       proofs if the surface-step ever redirects (as -warning-bg did
+       in v0.6.36 to fix muddy contrast). */
+    --button-bg-default: var(--a-success-bg);
     --button-fg-default: var(--a-success-fg);
   }
   :scope[color="info"] {
-    --button-bg-default: var(--a-info-strong);
+    --button-bg-default: var(--a-info-bg);
     --button-fg-default: var(--a-info-fg);
   }
   :scope[color="warning"] {
-    --button-bg-default: var(--a-warning-strong);
+    /* `--a-warning-bg` (bright amber, scheme-independent) not
+       `-strong` (mid-tone). The pair `-strong` + `-fg` gives muddy
+       brown-on-brown — the L3 `-bg` is the canonical solid-warning
+       surface paired with `-fg` (dark text). */
+    --button-bg-default: var(--a-warning-bg);
     --button-fg-default: var(--a-warning-fg);
   }
 

package/components/calendar-picker/calendar-picker.a2ui.json

@@ -66,6 +66,21 @@
       "type": "string",
       "default": "Select date..."
     },
+    "placement": {
+      "description": "Popover placement relative to the trigger. Default `bottom` centers the calendar panel under the trigger (ADR-0034 Rule 2 — calendar panel wider than trigger).",
+      "type": "string",
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end"
+      ],
+      "default": "bottom"
+    },
     "value": {
       "description": "Selected date (ISO string)",
       "type": "string",