@adia-ai/web-components 0.6.36 → 0.6.38

package/CHANGELOG.md

@@ -1,11 +1,58 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.38] — 2026-05-26
+
+### Added — Wave 5e cohort: 3 new primitives + slot-vocab-vs-css backlog closed
+
+- **`<mark-ui>`** — inline highlighted text primitive (#357)
+- **`<inline-edit-ui>`** — click-to-edit text in place (#212)
+- **Notification deep-link demo + Mark All Read verify** for `<feed-ui>` (#344/#343)
+
+### Fixed — substrate polish across the v0.6.38 window
+
+- **`<list-item-ui>`**: slot selectors changed from direct-child to descendant — description row now lands on row 2 as intended
+- **`<segmented-ui>`**: stale indicator stripping — duplicate pills on re-render eliminated
+- **`<stat-ui>`**: chart slot bottom-aligns to value baseline; aspect 4:3
+- **`<toolbar-ui>`** mixed-controls demo: `<segment-ui>` (not `<button-ui>`) inside `<segmented-ui>`
+
+### Maintenance — slot-vocab-vs-css audit reached 0 critical findings
+
+- `audit-slot-vocab-vs-css` substrate backlog closed → gate now enforced. Multi-yaml + @scope-aware pairing landed in the audit script.
+- 5 Wave 5a/b/c/d gap-analysis flips landed (substrate-verified as covered; no new code).
+
+## [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.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.
+- **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

package/components/accordion/accordion-item.a2ui.json

@@ -63,6 +63,9 @@
       "action": {
         "description": "§206 (v0.5.7): action buttons inside a custom header (e.g. Copy /\nDownload / settings). Children placed at `[slot=\"action\"]` (or\n`[slot=\"actions\"]`, or marked `[data-no-toggle]`) are excluded from\nthe toggle-on-click cascade — clicking them fires their own handler\nwithout also toggling the section."
       },
+      "body": {
+        "description": "The section's collapsible content. Renders below the header; hidden when `[open]` is unset. Author-fills with prose, lists, embedded forms, or any rich markup the panel needs."
+      },
       "header": {
         "description": "Custom header content. By default `[text]` renders as a plain header\nlabel, but a `[slot=\"header\"]` override lets consumers author rich\nheaders (icon + title + action buttons + caret)."
       }

package/components/accordion/accordion-item.yaml

@@ -39,6 +39,11 @@ slots:
       `[slot="actions"]`, or marked `[data-no-toggle]`) are excluded from
       the toggle-on-click cascade — clicking them fires their own handler
       without also toggling the section.
+  body:
+    description: >-
+      The section's collapsible content. Renders below the header; hidden
+      when `[open]` is unset. Author-fills with prose, lists, embedded
+      forms, or any rich markup the panel needs.
 events:
   toggle:
     description: Fired when the section opens or closes.

package/components/action-list/action-item.a2ui.json

@@ -62,7 +62,11 @@
       "MenuItem",
       "Button"
     ],
-    "slots": {},
+    "slots": {
+      "icon": {
+        "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
+      }
+    },
     "states": [],
     "status": "stable",
     "synonyms": {

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

@@ -37,6 +37,13 @@ props:
     type: boolean
     default: false
 
+slots:
+  icon:
+    description: >-
+      Override the [icon] glyph with a custom slotted element (custom
+      icon-ui, image, avatar). Mutually exclusive with the [icon]
+      attribute — slot child wins.
+
 keywords:
   - action-item
   - command-row

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