@adia-ai/web-components 0.6.45 → 0.6.46

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.46] — 2026-05-29
+
+### Added — declarative `traits="..."` Quick start sections on all 56 trait pages
+
+- **`traits/*/\*.examples.html`** — every trait page now opens with a "Quick start" section before the hero demo showing `traits="traitname"` on a real `*-ui` host element. No JS, no import — the declarative attribute is the primary example. Variants shown where config attrs exist. Hallucinated config attr names corrected in 13 pages (agents invented plausible-sounding names; fixed against JS source: e.g. `data-snap-grid` not `data-grid-size`, `data-noise-strength` not `data-noise-opacity`, `data-intersection-threshold` not `data-threshold`, etc.).
+
+### Added — expanded slot vocabulary for `header-ui`, `footer-ui`, `card-ui`
+
+- **`components/header/header.yaml`** — added `icon`, `heading`, `description` slots (previously only `default` + `action` were declared, but the parent container's `@scope` activates a 5-slot grid vocabulary when these are present). Each description explains the parent-`@scope` activation contract.
+- **`components/footer/footer.yaml`** — added `heading`, `description`, `action`, `action-leading` slots (all were styled by card/drawer/modal `@scope` but absent from the yaml; footer `heading`/`description` is the trend-stat / KPI pattern).
+- **`components/card/card.yaml`** — added `media` slot (full-bleed hero image/video region); updated `heading`, `description`, `action`, `action-leading` descriptions to accurately state they work in both `<header>` AND `<footer>` context, not just "in the header".
+
+### Fixed — spurious `bleed` removed from 31 section elements
+
+- **`patterns/kanban-board/kanban-board.examples.html`** and **`traits/confetti|magnetic-hover|tilt-hover/...examples.html`** — removed `bleed` from `<section bleed>` where the direct first child was `text-ui`, `stack-ui`, or `list-ui` without `divider`. `bleed` removes the card section's inset padding and is only correct for edge-to-edge content (tables, charts, code, divider-lists); it was being cargo-culted onto text sections that needed normal padding.
+
+### Fixed — stale token references in shipped examples
+
+- **`components/skeleton/skeleton.examples.html`**: `var(--ui-border)` → `var(--a-border)` (dead token; border was rendering colorless).
+- **`styles/overview.examples.html`**: token tier documentation table updated — `--ui-primary` → `--a-primary`, `--button-bg: var(--ui-primary)` → `var(--a-primary)` (the actual semantic token and component wiring).
+
+### Maintenance
+
+- **`packages/web-components/README.md`** — CDN example URLs updated from frozen `@0.6.30` to `@0.6` minor-range; `check:cdn-pins` guard added to `npm run check` aggregate.
+- **`dist/web-components.min.{js,css}` + `dist/icons-manifest.js`** — bundle rebuild.
+
 ## [0.6.45] — 2026-05-29
 
 ### Fixed — `<canvas-ui>` lazy `a2ui-root` import uses a bare specifier (FEEDBACK-85, follow-up to FB-81)

package/README.md

@@ -38,12 +38,14 @@ Since **v0.6.30**, this package ships pre-flattened + minified bundles under `di
 
 ```html
 <!-- CSS: all primitives, tokens, resets (443 KB raw / ~50 KB gzipped) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6.30/dist/web-components.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6/dist/web-components.min.css">
 
 <!-- JS: registers all 95 primitives (~250 KB gzipped via Brotli) -->
-<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6.30/dist/web-components.min.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6/dist/web-components.min.js"></script>
 ```
 
+The `@0.6` range tracks the latest `0.6.x` patch automatically (won't jump to a breaking `0.7`). For reproducible builds, pin an exact version instead — e.g. `@adia-ai/web-components@0.6.45/dist/web-components.min.css`.
+
 For composite shells, add the corresponding bundle from `@adia-ai/web-modules` — see [its README](../web-modules/#cdn-no-bundler--codepen-marketing-pages-static-html) or the [CDN usage guide](https://ui-kit.exe.xyz/site/cdn-usage). The kitchen-sink path is `@adia-ai/web-modules/dist/everything.min.js` (all primitives + all 4 shells; ~190 KB gzipped) — one tag for CodePen demos.
 
 **Pick ONE bundle path.** Mixing (e.g. `everything.min.js` + a separate `web-components.min.js`) causes `customElements.define` to throw "name already defined" on dup-load. The choice tree:

package/components/card/card.a2ui.json

@@ -115,19 +115,22 @@
     ],
     "slots": {
       "description": {
-        "description": "Optional descriptive text beneath the heading. Renders in the header slot at body-subtle typography. Use for short metadata lines (timestamp, author, status sentence)."
+        "description": "Secondary metadata — grid row 2 beneath the heading inside `<header>`, or a period/caption line beneath a metric inside `<footer>` (e.g. \"Jan – Mar 2024\"). Also accepts bare `<p>` / `<small>` / body-variant `<text-ui>` as direct children without slot=\"description\". Triggers space-between layout in the footer when combined with slot=\"action\"."
       },
       "action": {
-        "description": "Trailing action cluster in the header (e.g. icon-buttons, menu trigger, more-options). Aligns to the header's flex-end edge."
+        "description": "Trailing control cluster inside `<header>` (icon-buttons, menu trigger, more-options) or the primary action cluster inside `<footer>` (e.g. Save, Confirm). Aligns to the flex-end edge in both contexts. Pair with slot=\"action-leading\" for dual-cluster footers."
       },
       "action-leading": {
-        "description": "Leading action cluster in the header (e.g. back button, switcher, breadcrumb-context). Aligns to the header's flex-start edge, before the icon/heading column."
+        "description": "Leading control cluster — inline-start edge of the header or footer. In the header: back button, breadcrumb context, or workspace switcher, before the icon/heading column. In the footer: secondary action (e.g. Back) opposite the primary cluster."
       },
       "heading": {
-        "description": "Card title. Renders in the header slot with title typography. Typically a short noun phrase or document/object name."
+        "description": "Primary title — grid row 1 inside `<header>`, or the prominent metric value inside `<footer>` (trend-stat / KPI pattern). Also accepts bare `<h1>`–`<h6>` tags as direct children without slot=\"heading\". A slot=\"heading\" wrapper can contain inline badges or metadata alongside the title text."
       },
       "icon": {
-        "description": "Optional leading icon for the card header (status / brand / type marker). Renders next to the heading. Use `<icon-ui name=\"…\">` or any inline icon element."
+        "description": "Leading icon for the card header — status, brand, or type marker. Placed in column 1 of the 3-column header grid when present; heading + description shift to column 2. Use `<icon-ui name=\"…\">`, `<avatar-ui>`, or any inline icon element as a DIRECT child of the `<header>` with slot=\"icon\" (not inside a wrapper — direct-child only, per the :has(> [slot=\"icon\"]) gate)."
+      },
+      "media": {
+        "description": "Full-bleed media region — placed before the first `<header>` or `<section>` as the card's hero image / video / illustration slot. Stretches edge-to-edge (negative margin equal to the card's inset); first-child `[slot=\"media\"]` gets zero border-radius on the top corners so it sits flush with the card border."
       }
     },
     "states": [

package/components/card/card.yaml

@@ -61,27 +61,45 @@ events: {}
 slots:
   icon:
     description: >-
-      Optional leading icon for the card header (status / brand / type
-      marker). Renders next to the heading. Use `<icon-ui name="…">` or
-      any inline icon element.
+      Leading icon for the card header — status, brand, or type marker.
+      Placed in column 1 of the 3-column header grid when present;
+      heading + description shift to column 2. Use `<icon-ui name="…">`,
+      `<avatar-ui>`, or any inline icon element as a DIRECT child of the
+      `<header>` with slot="icon" (not inside a wrapper — direct-child
+      only, per the :has(> [slot="icon"]) gate).
   heading:
     description: >-
-      Card title. Renders in the header slot with title typography.
-      Typically a short noun phrase or document/object name.
+      Primary title — grid row 1 inside `<header>`, or the prominent metric
+      value inside `<footer>` (trend-stat / KPI pattern). Also accepts bare
+      `<h1>`–`<h6>` tags as direct children without slot="heading". A
+      slot="heading" wrapper can contain inline badges or metadata alongside
+      the title text.
   description:
     description: >-
-      Optional descriptive text beneath the heading. Renders in the
-      header slot at body-subtle typography. Use for short metadata
-      lines (timestamp, author, status sentence).
+      Secondary metadata — grid row 2 beneath the heading inside `<header>`,
+      or a period/caption line beneath a metric inside `<footer>` (e.g.
+      "Jan – Mar 2024"). Also accepts bare `<p>` / `<small>` / body-variant
+      `<text-ui>` as direct children without slot="description". Triggers
+      space-between layout in the footer when combined with slot="action".
   action:
     description: >-
-      Trailing action cluster in the header (e.g. icon-buttons, menu
-      trigger, more-options). Aligns to the header's flex-end edge.
+      Trailing control cluster inside `<header>` (icon-buttons, menu
+      trigger, more-options) or the primary action cluster inside `<footer>`
+      (e.g. Save, Confirm). Aligns to the flex-end edge in both contexts.
+      Pair with slot="action-leading" for dual-cluster footers.
   action-leading:
     description: >-
-      Leading action cluster in the header (e.g. back button, switcher,
-      breadcrumb-context). Aligns to the header's flex-start edge,
-      before the icon/heading column.
+      Leading control cluster — inline-start edge of the header or footer.
+      In the header: back button, breadcrumb context, or workspace switcher,
+      before the icon/heading column. In the footer: secondary action (e.g.
+      Back) opposite the primary cluster.
+  media:
+    description: >-
+      Full-bleed media region — placed before the first `<header>` or
+      `<section>` as the card's hero image / video / illustration slot.
+      Stretches edge-to-edge (negative margin equal to the card's inset);
+      first-child `[slot="media"]` gets zero border-radius on the top
+      corners so it sits flush with the card border.
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/footer/footer.a2ui.json

@@ -61,8 +61,20 @@
       "table"
     ],
     "slots": {
+      "description": {
+        "description": "Caption or period text rendered beneath slot=\"heading\" — small, muted. Triggers space-between layout when combined with slot=\"action\". Also accepts bare <p> / <small> elements as direct children without slot=\"description\"."
+      },
       "default": {
-        "description": "Default slot — primary child content."
+        "description": "Default slot — primary child content. Typically flat <button-ui> children laid out by the `justify` prop. Prefer flat children; a nested <row-ui> double-applies layout and breaks the chrome's gap."
+      },
+      "action": {
+        "description": "Trailing action cluster — self-aligns to the inline-end edge of the footer. Pair with slot=\"action-leading\" for dual-cluster footers (e.g. Back on the left, Save on the right). Activated by card-ui, drawer-ui, and modal-ui @scope rules."
+      },
+      "action-leading": {
+        "description": "Leading action cluster — self-aligns to the inline-start edge of the footer. Typically a Back or secondary action that needs to sit opposite the primary cluster. Activated by drawer-ui @scope; also works in card-ui footers via the same slot selector."
+      },
+      "heading": {
+        "description": "Metric or period label — rendered prominently at the leading edge of the footer chrome (e.g. \"$12.4k\" / \"Jan – Mar 2024\"). When present the parent's @scope switches to a heading + description layout. Pairs with slot=\"description\" for a caption line below the value (trend-stat footer pattern). Activated by card-ui and drawer-ui @scope rules."
       }
     },
     "states": [

package/components/footer/footer.yaml

@@ -21,7 +21,35 @@ props:
 events: {}
 slots:
   default:
-    description: "Default slot — primary child content."
+    description: >-
+      Default slot — primary child content. Typically flat <button-ui>
+      children laid out by the `justify` prop. Prefer flat children; a
+      nested <row-ui> double-applies layout and breaks the chrome's gap.
+  heading:
+    description: >-
+      Metric or period label — rendered prominently at the leading edge of
+      the footer chrome (e.g. "$12.4k" / "Jan – Mar 2024"). When present
+      the parent's @scope switches to a heading + description layout. Pairs
+      with slot="description" for a caption line below the value (trend-stat
+      footer pattern). Activated by card-ui and drawer-ui @scope rules.
+  description:
+    description: >-
+      Caption or period text rendered beneath slot="heading" — small,
+      muted. Triggers space-between layout when combined with slot="action".
+      Also accepts bare <p> / <small> elements as direct children without
+      slot="description".
+  action:
+    description: >-
+      Trailing action cluster — self-aligns to the inline-end edge of the
+      footer. Pair with slot="action-leading" for dual-cluster footers (e.g.
+      Back on the left, Save on the right). Activated by card-ui, drawer-ui,
+      and modal-ui @scope rules.
+  action-leading:
+    description: >-
+      Leading action cluster — self-aligns to the inline-start edge of the
+      footer. Typically a Back or secondary action that needs to sit opposite
+      the primary cluster. Activated by drawer-ui @scope; also works in
+      card-ui footers via the same slot selector.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/header/header.a2ui.json

@@ -55,11 +55,20 @@
       "alert"
     ],
     "slots": {
+      "description": {
+        "description": "Secondary metadata — grid row 2 beneath the heading, spanning the heading and action columns. Also accepts bare <p> / <small> / body-variant <text-ui> as direct children without slot=\"description\". Renders muted + small."
+      },
       "default": {
-        "description": "Default slot — primary child content."
+        "description": "Default slot — primary child content. When no named slot= attributes are used, all children flow here as a block. Most card/drawer/modal usages prefer the named vocabulary below so the parent's @scope grid activates."
       },
       "action": {
-        "description": "Action region — buttons or badges on the right."
+        "description": "Trailing control cluster — placed in the last column of the parent container's header grid. Use for icon-buttons, menu triggers, or badge/button combinations. The first [slot=\"action\"] child pushes itself to the grid's end; subsequent siblings flow with gap."
+      },
+      "heading": {
+        "description": "Primary title — grid row 1 of the header grid. Also accepts bare <h1>–<h6> tags as direct children without slot=\"heading\". Renders at title weight + size per the parent's @scope. A slot=\"heading\" wrapper element can contain inline badges or metadata alongside the title text."
+      },
+      "icon": {
+        "description": "Leading icon column — placed in column 1 of the parent container's header grid (card-ui / drawer-ui / modal-ui / page-ui). Use <icon-ui name=\"...\">, <avatar-ui>, or any inline icon element. The grid activates only when this slot is present; without it the heading spans the full width."
       }
     },
     "states": [

package/components/header/header.yaml

@@ -17,9 +17,37 @@ props:
 events: {}
 slots:
   default:
-    description: "Default slot — primary child content."
+    description: >-
+      Default slot — primary child content. When no named slot= attributes
+      are used, all children flow here as a block. Most card/drawer/modal
+      usages prefer the named vocabulary below so the parent's @scope grid
+      activates.
+  icon:
+    description: >-
+      Leading icon column — placed in column 1 of the parent container's
+      header grid (card-ui / drawer-ui / modal-ui / page-ui). Use
+      <icon-ui name="...">, <avatar-ui>, or any inline icon element.
+      The grid activates only when this slot is present; without it the
+      heading spans the full width.
+  heading:
+    description: >-
+      Primary title — grid row 1 of the header grid. Also accepts bare
+      <h1>–<h6> tags as direct children without slot="heading". Renders
+      at title weight + size per the parent's @scope. A slot="heading"
+      wrapper element can contain inline badges or metadata alongside
+      the title text.
+  description:
+    description: >-
+      Secondary metadata — grid row 2 beneath the heading, spanning the
+      heading and action columns. Also accepts bare <p> / <small> /
+      body-variant <text-ui> as direct children without slot="description".
+      Renders muted + small.
   action:
-    description: "Action region — buttons or badges on the right."
+    description: >-
+      Trailing control cluster — placed in the last column of the parent
+      container's header grid. Use for icon-buttons, menu triggers, or
+      badge/button combinations. The first [slot="action"] child pushes
+      itself to the grid's end; subsequent siblings flow with gap.
 states:
   - name: idle
     description: Default, ready for interaction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.45",
+  "version": "0.6.46",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",