@adia-ai/web-components 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -1,4 +1,37 @@
 # Changelog — @adia-ai/web-components
+
+## [0.8.5] — 2026-07-17
+
+### Added
+- **`<adia-mark-ui>`** (`components/adia-mark/adia-mark.{class.js,css,yaml}`; gh#283): the Adia brand mark as a token-driven primitive — background always reads `--a-canvas-surface-inverse`, the wordmark always reads `--a-fg-inverse`, so one component replaces the four hand-maintained static `agent-ui-{light,dark,light-transparent,dark-transparent}.svg` exports and adapts to scheme changes with zero asset swapping. Delivery shape (inlined custom element, not a bare SVG file or `icon-ui` registry entry) was constrained by the ticket's own finding: an `<img src="...svg">` or CSS `background-image: url(...)` reference cannot resolve the host page's CSS custom properties — only inlined markup can. `size` prop (xs/sm/md/lg/xl) matches `avatar-ui`'s scale. Verified live in both color schemes (Playwright) — background/foreground correctly invert together with no code change. Existing static-asset consumers (`public/icons/*.svg`, the a2ui corpus chunks, `apps/embedded-app`'s CSS-background brand mark) were deliberately left untouched — the static assets aren't deleted, so nothing breaks; migrating those ~35+ call sites is a separate, larger follow-up, out of scope for this ticket's `size:small` label.
+- **`scripts/verify/exports-wildcard-resolution.mjs`** (gh#296, shared with `@adia-ai/web-modules`): live-resolution regression gate asserting every documented short-form CSS/JS subpath specifier resolves to a real on-disk file. Removed the dead `./components/*/*.css` exports-map key — confirmed via live `import.meta.resolve()` testing that it never actually resolved (Node's pattern matching always picked the single-wildcard `./components/*.css` sibling instead). Documented the underlying trap (a redundant nested specifier like `components/button/button.css` silently resolves to a garbage, nonexistent quadrupled path instead of throwing) in `USAGE.md` — not fixable in the exports map itself, since Node's `*` matches across `/` with no way to constrain it to one path segment.
+- **`scripts/dev/audit-template-child-conflict.mjs`** (gh#284): static audit flagging a component whose `static template` is non-null AND whose yaml declares a `slots.default` entry (the container shape — nested CE children silently wiped by `stamp()`'s first-mount `replaceChildren`) or whose usage example shows body-text content (the projected-text shape, advisory). Verified against the current 168 components: zero findings — every component accepting light-DOM children currently uses `static template = () => null`. Catches a FUTURE regression rather than patching `stamp()`/`connectedCallback` itself; wired into `adia-author`'s structural-gate sequence (`npm run audit:template-child-conflict[:strict]`).
+
+### Changed
+- **`button-ui` role-forwarding sweep (gh issue 276 wave 4, operator ruling)**: `button-ui` now defaults `role=button` only when the author set nothing, so composites can stamp `role=tab`/`gridcell` semantics onto the primitive. `components/calendar-grid/calendar-grid.class.js` + `components/calendar-picker/calendar-picker.class.js` stamp `<button-ui variant="ghost">` for all five shapes (prev/next nav, leading/main/trailing day cells), fixing two latent bugs at the root during migration — a `:disabled` pseudo-class selector that only matches native controls (now `[disabled]`), and a today-indicator dot that collided with `button-ui`'s own `::after`-rendered label (relocated to `::before`). `components/agent-questions/agent-questions.class.js` migrates its stamped native `<button role=radio|checkbox>` cards to `option-card-ui`; multi-select mode intercepts click/keydown at the container's capture phase to preserve toggle-off (the primitive is architecturally radio-only). `components/button/button.class.js` + `components/swiper/swiper.class.js`: swiper's pagination dots migrate from a native `<button role=tab>` to `<button-ui variant=ghost role=tab>`. Live-probed in all four components; `scripts/dev/audit-stamped-native-buttons.mjs` SANCTIONED entries removed for swiper and agent-questions.
+
+### Fixed
+- **`icons-phosphor.js`'s auto-discovery glob breaks under pnpm workspace hoisting (gh#287)**: the baked `import.meta.glob('/node_modules/@phosphor-icons/…')` resolved as a literal path join against Vite's configured project root — under pnpm's default (non-hoisted, symlinked) linking, `@phosphor-icons/core` (a transitive dependency of this package, not necessarily the consumer's) is linked only inside this package's own resolution scope, so the glob silently matched zero files and every icon rendered blank. Switched to the entry-file-relative form (`../node_modules/…`, resolved against `icons-phosphor.js`'s own directory, one level inside the package) — confirmed empirically against a real hoisting-gap install (root cause + fix verified with a from-scratch pnpm workspace reproduction, not assumed). Also documented a second, independent failure mode named in the same issue — Vite's dev-server `optimizeDeps` pre-bundling this package empties the glob via a different mechanism (esbuild's scan transforms the glob into a literal empty object, no exception) — with the `optimizeDeps.exclude` fix and a scoped explicit-import fallback, in `icons-phosphor.js`'s JSDoc, `icons.js`'s JSDoc, `icon.class.js`'s fail-loud diagnostic, and `USAGE.md` § Icons.
+- **Every browser-only API call site guarded for SSR (gh#285)**: `UIElement`'s constructor called `attachInternals()` unconditionally — the highest-leverage crash site, throwing before any subclass code runs — now feature-detected with a no-op `ElementInternals` shim server-side. `adoptStyles()`'s write to `document.adoptedStyleSheets` is now guarded on `'adoptedStyleSheets' in document`. Every `new ResizeObserver/IntersectionObserver/MutationObserver/PerformanceObserver` construction site across `core/element.js`, `core/data-stream.js`, and the shipped `components/{chart,color-input,color-picker,field,fields,nav,noodles,page,select,swatch,toolbar,tree}` + `traits/{error-shake,fade-presence,success-checkmark}` sources is now feature-detected (22 sites needed the guard; 10 more were already correctly guarded). Real-browser behavior unchanged — confirmed via Playwright and the full test suite; 4 new `core/element.test.js` cases simulate the actual API absence (deleting the constructors, not mocking).
+
+### Maintenance
+- **`styles/components.css` barrel** gained the `<adia-mark-ui>` `@import` entry (see Added, above) — without it the component would have shipped with zero CSS. **`dist/` bundles rebuilt** (`web-components.min.{css,js}`, `.sheet.js`, `theme-provider.min.js`) to pick up the `<adia-mark-ui>`, exports-map, and SSR-guard source changes above.
+
+## [0.8.4] — 2026-07-16
+
+### Fixed
+- **Focus rings pair with transparent borders** (operator ruling 2026-07-16): a control showing its `--a-focus-ring` box-shadow sets `border-color: transparent` in the same rule — border + gap + ring double-drew the edge (visible on the chat composer). Applied to the 21 ring-bearing controls with visible borders (input, textarea, select, combobox, check, radio, switch, range, tag[tone=outline], tags-input's missing invalid-state half, time/calendar/date-range pickers, upload dropzone, option-card, accordion[contained], agent-artifact header, button, toggle-group, chat-input); the pairing law is stated in `styles/colors/semantics/features.css` and the component-token contract.
+- **Sidebar carets read the universal `--a-caret-size` (14px)**: tree carets were an 8px outlier (`--a-space-2`), accordion carets rode the 1rem icon default, select's trigger caret rode the ambient icon size (admin-shell's 18px bump), timeline's outcomes toggle likewise, and nav-group's collapsed block carried two `var()`-less declarations whose value was the literal token name (silently invalid — removed).
+- **`agent-reasoning-ui` connector spine ~2px right of the dot centers**: the spine read `--timeline-marker-w` from outside timeline-ui's scope (unreachable — always the 1.25rem fallback) while the composed `size="sm"` dots center in a 1rem column; now keyed to the component's own `--agent-reasoning-marker-w`. Probe: 0px delta.
+- **`theme-provider.min.js` inlined a stale foundation sheet**: the bundle embeds the GENERATED `dist/web-components.sheet.js`, and building JS before CSS baked the previous iteration in. `npm run build:bundles` now encodes the css→js order.
+
+### Changed
+- **No native `<button>` in stamped component DOM (gh#276)**: `select-ui` (clear-all / select-all / +N overflow), `tag-ui` (dismiss), `swatch-ui` (copy), `timeline-item-ui` (outcomes toggle), `chat-input-ui` (attachment remove), and `combobox-ui` (clear x) stamp `<button-ui variant="ghost" size="xs">` with token re-points — shape, semantic intent, theme tokens, and focus-ring discipline come from the primitive. Data-hooks, aria-labels, and event wiring unchanged. Parked with reasons (in `scripts/dev/audit-stamped-native-buttons.mjs`, the new CI gate): table, agent-questions option cards, swiper dots, calendar day grids.
+- **`button-ui` respects a consumer-authored `tabindex`** instead of clobbering it with `0` on connect — enables mouse-only affordances (combobox's clear keeps `tabindex="-1"`) and roving-tabindex composition.
+
+### Maintenance
+- **`dist/` bundles rebuilt** (focus-ring/caret/button-ui payloads across `web-components.min.{css,js}`, `web-components.sheet.js`, `theme-provider.min.js`).
+
 ## [0.8.3] — 2026-07-16
 
 ### Maintenance

package/USAGE.md

@@ -50,11 +50,20 @@ import '@adia-ai/web-components/components/button';
 import '@adia-ai/web-components/components/button.css';
 ```
 
-> **No `.js` suffix on component subpaths.** Import the directory name —
-> `…/components/button`, never `…/components/button/button.js`. The
-> `exports` wildcard matches only the directory form; appending the
-> explicit filename fails to resolve under Vite 8 (rolldown). The on-disk
-> filename is irrelevant to the subpath specifier.
+> **Don't repeat the directory name — for `.js` OR `.css` subpaths.**
+> Import the short form — `…/components/button`, never
+> `…/components/button/button.js`; `…/components/button.css`, never
+> `…/components/button/button.css`. Every component lives at
+> `components/<name>/<name>.<ext>` on disk, so the nested form looks like
+> the natural specifier — it isn't. The `exports` wildcard's single `*`
+> captures the WHOLE nested subpath (it matches across `/`, with no way to
+> constrain it to one segment) and pastes it into both `*`s of the target,
+> quadrupling the path. Under Vite 8 (rolldown) the `.js` case fails at
+> bundle time when it tries to read the resulting nonexistent file; the
+> `.css` case resolves to a URL that also doesn't exist, with no clear
+> "wrong specifier" error either way — the on-disk filename repetition is
+> irrelevant to the subpath specifier; use the short form. Tracked as
+> [gh#296](https://github.com/adiahealth/gen-ui-kit/issues/296).
 
 Subpath exports also available:
 
@@ -100,34 +109,60 @@ For the live demo of every component: <https://ui-kit.exe.xyz/site/components/>.
 ## Icons — wiring the registry
 
 `<icon-ui>` (and every component that renders an icon — `<button-ui icon>`,
-`<badge-ui>`, menus, etc.) draws from an **icon registry** that your app
-must wire **once, from your own entry module**. Out of the box the registry
-is empty; an un-wired registry renders every icon **blank**.
-
-**Why the app has to do it.** The zero-config glob in the package's own
-`icons-phosphor.js` uses `import.meta.glob('/node_modules/@phosphor-icons/…')`,
-which is a **build-time macro your bundler rewrites** — and under Vite 8 /
-rolldown that rewrite **does not happen for code imported from inside a
-published dependency**. The glob has to be evaluated in *your* source graph.
-`@phosphor-icons/core` ships as a dependency of this package (so the SVG
-assets resolve), but the glob that reads them must live in your app.
-
-**The one-time wiring (do this in your app entry, before first paint):**
+`<badge-ui>`, menus, etc.) draws from an **icon registry**. Zero-config
+consumers get every Phosphor name for free: the main barrel
+(`import '@adia-ai/web-components'`) side-effect-imports the package's own
+`icons-phosphor.js`, which globs the full Phosphor set at build time. Most
+apps need no wiring at all.
+
+**Two Vite-specific gaps can leave the registry empty (gh#287) — both silent,
+both fixed without touching your component code:**
+
+1. **Vite's dev-server `optimizeDeps` pre-bundles this package.** Vite
+   pre-bundles bare-specifier dependencies with esbuild for faster cold
+   starts, before its own glob transform ever runs — that turns the
+   auto-discovery glob into a literal empty object, no exception, no
+   per-icon warning. Fix in your Vite config:
+
+   ```js
+   // vite.config.js
+   export default defineConfig({
+     optimizeDeps: { exclude: ['@adia-ai/web-components', '@adia-ai/web-modules'] },
+   });
+   ```
+
+2. **A packaging step changes where this file lands, or you're on a version
+   older than this fix.** The auto-glob resolves `@phosphor-icons/core`
+   relative to its own file location, one level inside
+   `@adia-ai/web-components` — hoisting-safe under pnpm's default (non-hoisted)
+   linking, but it assumes the package's own internal layout is preserved. A
+   bundler step that re-nests `core/icons-phosphor.js` elsewhere, a Yarn Berry
+   PnP install, or `@phosphor-icons/core` missing entirely can still leave it
+   empty.
+
+If neither fix applies to your setup — or you want a smaller bundle than the
+full ~9000-chunk auto-discovery set — wire icons explicitly from your own
+entry module instead, with plain bare-specifier imports (never affected by
+`optimizeDeps`, since it's your own first-party source, not a dependency):
 
 ```js
 import { installIconLoaders } from '@adia-ai/web-components/core/icons';
+import caretRight from '@phosphor-icons/core/assets/regular/caret-right.svg?raw';
+import x          from '@phosphor-icons/core/assets/regular/x.svg?raw';
+// ...one import per icon you use
 
 installIconLoaders({
-  regular: import.meta.glob(
-    '/node_modules/@phosphor-icons/core/assets/regular/*.svg',
-    { query: '?raw', import: 'default', eager: true },
-  ),
-  // add other weights only if you use them:
-  // bold:  import.meta.glob('/node_modules/@phosphor-icons/core/assets/bold/*.svg',  { query: '?raw', import: 'default', eager: true }),
-  // fill:  import.meta.glob('/node_modules/@phosphor-icons/core/assets/fill/*.svg',  { query: '?raw', import: 'default', eager: true }),
+  regular: {
+    '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': caretRight,
+    '/node_modules/@phosphor-icons/core/assets/regular/x.svg': x,
+  },
 });
 ```
 
+The map's keys only need to end with `/<weight>/<filename>.svg` — lookup
+matches by suffix — so the `/node_modules/...` prefix above is just for
+consistency with the glob form, not a real path.
+
 `installIconLoaders` is idempotent, may be called before or after the
 elements connect (icons already on the page repaint when it runs), and
 accepts either the per-weight map above or a flat `path → svg-string` map

package/components/accordion/accordion.css

@@ -113,6 +113,7 @@
   :scope[variant="contained"]:has(> :focus-visible),
   :where(accordion-ui[variant="contained"]) > :scope:not([variant="flat"]):has(> :focus-visible) {
     box-shadow: var(--accordion-item-focus-ring);
+    border-color: transparent;
   }
 
   /* ── Header ── */
@@ -172,6 +173,10 @@
   /* ── Caret icon ── */
   :scope [slot="caret"] {
     flex-shrink: 0;
+    /* Universal caret size (14px default) — one caret size across
+       nav-group / tree / accordion (ruling 2026-07-16); unset, the icon
+       rendered at the 1rem icon default and read oversized in sidebars. */
+    --a-icon-size: var(--a-caret-size);
     color: var(--accordion-item-caret-fg);
     transition:
       transform var(--accordion-item-duration) var(--accordion-item-easing),

package/components/adia-mark/adia-mark.a2ui.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdiaMark.json",
+  "title": "AdiaMark",
+  "description": "The Adia brand mark — a rounded square with the \"Adia\" wordmark cut out in a contrasting color. Token-driven: the background always reads as the current scheme's inverse surface, and the wordmark always reads as the current scheme's inverse foreground, so a single asset replaces separate light/dark/transparent static exports (gh#283). Not an `icon-ui` registry entry — icon-ui is the Phosphor-glyph registry only; this is a fixed, one-off brand image, a separate delivery shape.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdiaMark"
+    },
+    "inline": {
+      "description": "Renders as `display:inline-block` instead of the block-level default (ADR-0037) — set this when the mark sits beside a text run (a topbar brand slot) rather than standing alone.",
+      "type": "boolean",
+      "default": false
+    },
+    "size": {
+      "description": "Diameter of the square mark. Matches avatar-ui's size ladder for visual consistency when the two sit side by side (e.g. an app switcher row).",
+      "type": "string",
+      "enum": [
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ],
+      "default": "md"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<adia-mark-ui size=\"sm\"></adia-mark-ui>\n",
+        "why": "icon-ui only resolves Phosphor glyph names from the registry; there\nis no \"adia\" Phosphor icon, and registering one would misuse a\nthird-party glyph set for a proprietary brand mark.\n",
+        "wrong": "<icon-ui name=\"adia\"></icon-ui>\n"
+      },
+      {
+        "fix": "<adia-mark-ui size=\"sm\"></adia-mark-ui>\n",
+        "why": "Hardcoding the fill colors defeats the entire point of gh#283 —\nthe mark is supposed to track the inverse-surface/inverse-foreground\ntokens automatically across scheme changes, not be pinned to one\nscheme's static values.\n",
+        "wrong": "<adia-mark-ui style=\"--adia-mark-bg: #171818; --adia-mark-fg: #E2E3E4;\"></adia-mark-ui>\n"
+      }
+    ],
+    "category": "display",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Small brand mark in an admin-shell topbar, beside the product name.",
+        "a2ui": "[\n  {\n    \"id\": \"brand-row\",\n    \"component\": \"Row\",\n    \"gap\": \"2\",\n    \"align\": \"center\",\n    \"children\": [\"mark\", \"name\"]\n  },\n  {\n    \"id\": \"mark\",\n    \"component\": \"AdiaMark\",\n    \"size\": \"sm\"\n  },\n  {\n    \"id\": \"name\",\n    \"component\": \"Text\",\n    \"variant\": \"heading\",\n    \"text\": \"Adia\"\n  }\n]",
+        "name": "topbar-brand-mark"
+      }
+    ],
+    "keywords": [
+      "adia",
+      "brand",
+      "logo",
+      "wordmark",
+      "mark",
+      "identity",
+      "favicon"
+    ],
+    "name": "UIAdiaMark",
+    "related": [
+      "Icon",
+      "Avatar",
+      "Image"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "The only state — a static, non-interactive brand mark.",
+        "name": "default"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "brand": [
+        "adia",
+        "logo",
+        "mark",
+        "identity"
+      ],
+      "logo": [
+        "adia",
+        "brand",
+        "mark",
+        "wordmark"
+      ]
+    },
+    "tag": "adia-mark-ui",
+    "tokens": {
+      "--adia-mark-bg": {
+        "description": "Background fill — always the inverse surface token, regardless of variant or scheme.",
+        "default": "var(--a-canvas-surface-inverse)"
+      },
+      "--adia-mark-fg": {
+        "description": "Wordmark fill — always the inverse foreground token, regardless of variant or scheme.",
+        "default": "var(--a-fg-inverse)"
+      },
+      "--adia-mark-radius": {
+        "description": "Corner radius of the background square.",
+        "default": "var(--a-radius-lg)"
+      },
+      "--adia-mark-size": {
+        "description": "Width and height of the square mark.",
+        "default": "2.5rem"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/adia-mark/adia-mark.class.js

@@ -0,0 +1,64 @@
+/**
+ * Non-side-effect class export for `<adia-mark-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/adia-mark`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <adia-mark-ui></adia-mark-ui>
+ * <adia-mark-ui size="sm"></adia-mark-ui>
+ * <adia-mark-ui size="xl"></adia-mark-ui>
+ *
+ * The Adia brand mark — a rounded square with the "Adia" wordmark cut
+ * out in a contrasting color. Background and wordmark are ALWAYS the
+ * inverse-surface/inverse-foreground token pair (gh#283); this replaces
+ * the four separate static light/dark/transparent SVG exports
+ * (`public/icons/agent-ui-*.svg`) that had to be hand-maintained per
+ * scheme. Not themeable — see adia-mark.yaml's anti_patterns entry for
+ * why a color/tone override defeats the point.
+ *
+ * Geometry (`viewBox="0 0 100 100"`) is unchanged from the original
+ * static asset — same five wordmark paths, same background square —
+ * only the `fill` values became token references. `[data-mark-glyph]`
+ * marks the five wordmark paths so the CSS token (`--adia-mark-fg`) can
+ * target them without repeating the selector five times.
+ *
+ * Static content, zero props affect the template output — `static
+ * template` returns the same markup every render. Safe under SSR:
+ * `stamp()`'s first-mount `replaceChildren` only ever regenerates
+ * identical, template-owned content (see gh#284's survey — this
+ * component follows the same "template content never depends on
+ * light-DOM children" shape as check-ui/switch-ui, just with zero
+ * interpolated values instead of property-derived ones).
+ */
+
+import { UIElement, html } from '../../core/element.js';
+
+export class UIAdiaMark extends UIElement {
+  static properties = {
+    size:   { type: String,  default: 'md',    reflect: true },
+    inline: { type: Boolean, default: false,   reflect: true },
+  };
+
+  static template = () => html`
+    <svg viewBox="0 0 100 100" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+      <path data-mark-glyph d="M61.3692 41.2755C61.9898 41.8703 62.7139 42.1677 63.5414 42.1677C64.3948 42.1677 65.1189 41.8703 65.7137 41.2755C66.3343 40.6548 66.6446 39.9307 66.6446 39.1032C66.6446 38.2757 66.3343 37.5516 65.7137 36.931C65.1189 36.3103 64.3948 36 63.5414 36C62.7139 36 61.9898 36.3103 61.3692 36.931C60.7744 37.5516 60.477 38.2757 60.477 39.1032C60.477 39.9307 60.7744 40.6548 61.3692 41.2755Z"></path>
+      <path data-mark-glyph d="M61.0588 44.4951V63.8902H66.0628V44.4951H61.0588Z"></path>
+      <path data-mark-glyph fill-rule="evenodd" clip-rule="evenodd" d="M90 44.4929H84.9961V46.7815C83.4962 44.8937 81.3886 43.9498 78.6732 43.9498C76.0872 43.9498 73.8633 44.9454 72.0013 46.9366C70.1652 48.902 69.2472 51.3199 69.2472 54.1904C69.2472 57.0609 70.1652 59.4918 72.0013 61.483C73.8633 63.4484 76.0872 64.431 78.6732 64.431C81.3886 64.431 83.4962 63.4872 84.9961 61.5994V63.888H90V44.4929ZM79.6042 59.6598C78.0526 59.6598 76.7725 59.1556 75.764 58.147C74.7554 57.1126 74.2512 55.7938 74.2512 54.1904C74.2512 52.5871 74.7554 51.2812 75.764 50.2726C76.7725 49.2382 78.0526 48.721 79.6042 48.721C81.1558 48.721 82.4359 49.2382 83.4445 50.2726C84.4789 51.2812 84.9961 52.5871 84.9961 54.1904C84.9961 55.7938 84.4789 57.1126 83.4445 58.147C82.4359 59.1556 81.1558 59.6598 79.6042 59.6598Z"></path>
+      <path data-mark-glyph fill-rule="evenodd" clip-rule="evenodd" d="M51.8676 36.7388H56.8715V63.892H51.8676V61.6034C50.3936 63.4912 48.2989 64.4351 45.5836 64.4351C42.9717 64.4351 40.7348 63.4524 38.8729 61.487C37.0368 59.4958 36.1188 57.0649 36.1188 54.1944C36.1188 51.324 37.0368 48.906 38.8729 46.9407C40.7348 44.9494 42.9717 43.9538 45.5836 43.9538C48.2989 43.9538 50.3936 44.8977 51.8676 46.7855V36.7388ZM42.6355 58.151C43.6699 59.1596 44.9629 59.6639 46.5145 59.6639C48.0662 59.6639 49.3462 59.1596 50.3548 58.151C51.3633 57.1166 51.8676 55.7978 51.8676 54.1944C51.8676 52.5911 51.3633 51.2852 50.3548 50.2766C49.3462 49.2422 48.0662 48.725 46.5145 48.725C44.9629 48.725 43.6699 49.2422 42.6355 50.2766C41.627 51.2852 41.1227 52.5911 41.1227 54.1944C41.1227 55.7978 41.627 57.1166 42.6355 58.151Z"></path>
+      <path data-mark-glyph fill-rule="evenodd" clip-rule="evenodd" d="M28.2314 59.0044L29.8606 63.892H35.6792L26.1368 36.7388H19.5036L10 63.892H15.7797L17.4089 59.0044H28.2314ZM22.8396 42.9065L26.5634 54.0005H19.1157L22.8396 42.9065Z"></path>
+    </svg>
+  `;
+
+  connected() {
+    this.setAttribute('role', 'img');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Adia');
+  }
+}

package/components/adia-mark/adia-mark.css

@@ -0,0 +1,48 @@
+@scope (adia-mark-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --adia-mark-size:   var(--a-size, 2.5rem);
+    --adia-mark-radius: var(--a-radius-lg);
+    /* Fixed by design — always the inverse pairing, never a themeable
+       variant. See adia-mark.yaml's anti_patterns entry. */
+    --adia-mark-bg: var(--a-canvas-surface-inverse);
+    --adia-mark-fg: var(--a-fg-inverse);
+
+    --adia-mark-size-xs: 1.25rem;
+    --adia-mark-size-sm: 1.75rem;
+    --adia-mark-size-md: 2.5rem;
+    --adia-mark-size-lg: 3.5rem;
+    --adia-mark-size-xl: 4.5rem;
+  }
+
+  :scope {
+    /* ADR-0037 — block-level by default; [inline] opts into inline-block
+       for the common "beside a text run" case (a topbar brand slot). */
+    display: block;
+    width: var(--adia-mark-size);
+    height: var(--adia-mark-size);
+    border-radius: var(--adia-mark-radius);
+    background: var(--adia-mark-bg);
+    overflow: hidden;
+    flex-shrink: 0;
+  }
+
+  :scope[inline] { display: inline-block; }
+
+  :scope > svg {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+
+  :scope > svg [data-mark-glyph] {
+    fill: var(--adia-mark-fg);
+  }
+
+  /* ── Size ladder ── */
+  :scope[size="xs"] { --adia-mark-size: var(--adia-mark-size-xs); }
+  :scope[size="sm"] { --adia-mark-size: var(--adia-mark-size-sm); }
+  :scope[size="md"] { --adia-mark-size: var(--adia-mark-size-md); }
+  :scope[size="lg"] { --adia-mark-size: var(--adia-mark-size-lg); }
+  :scope[size="xl"] { --adia-mark-size: var(--adia-mark-size-xl); }
+}

package/components/adia-mark/adia-mark.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `<adia-mark-ui>` — The Adia brand mark — a rounded square with the "Adia" wordmark cut out in a contrasting color. Token-driven: the background always reads as the current scheme's inverse surface, and the wordmark always reads as the current scheme's inverse foreground, so a single asset replaces separate light/dark/transparent static exports (gh#283). Not an `icon-ui` registry entry — icon-ui is the Phosphor-glyph registry only; this is a fixed, one-off brand image, a separate delivery shape.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/adia-mark
+ *
+ * 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 UIAdiaMark extends UIElement {
+  /** Renders as `display:inline-block` instead of the block-level default (ADR-0037) — set this when the mark sits beside a text run (a topbar brand slot) rather than standing alone. */
+  inline: boolean;
+  /** Diameter of the square mark. Matches avatar-ui's size ladder for visual consistency when the two sit side by side (e.g. an app switcher row). */
+  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+}

package/components/adia-mark/adia-mark.examples.md

@@ -0,0 +1,26 @@
+# adia-mark — Examples
+
+## Default
+
+```html
+<adia-mark-ui></adia-mark-ui>
+```
+
+## Sizes
+
+```html
+<adia-mark-ui size="xs"></adia-mark-ui>
+<adia-mark-ui size="sm"></adia-mark-ui>
+<adia-mark-ui size="md"></adia-mark-ui>
+<adia-mark-ui size="lg"></adia-mark-ui>
+<adia-mark-ui size="xl"></adia-mark-ui>
+```
+
+## Topbar brand slot
+
+```html
+<row-ui gap="2" align="center">
+  <adia-mark-ui size="sm"></adia-mark-ui>
+  <text-ui variant="heading">Adia</text-ui>
+</row-ui>
+```

package/components/adia-mark/adia-mark.js

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

package/components/adia-mark/adia-mark.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './adia-mark.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('adia-mark-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('registers adia-mark-ui as a custom element', () => {
+    expect(customElements.get('adia-mark-ui')).toBeDefined();
+  });
+
+  it('defaults to size="md"', async () => {
+    const el = mount('<adia-mark-ui></adia-mark-ui>');
+    await tick();
+    expect(el.size).toBe('md');
+  });
+
+  it('reflects an explicit [size]', async () => {
+    const el = mount('<adia-mark-ui size="xl"></adia-mark-ui>');
+    await tick();
+    expect(el.size).toBe('xl');
+  });
+
+  it('defaults to inline=false and reflects an explicit [inline]', async () => {
+    const a = mount('<adia-mark-ui></adia-mark-ui>');
+    const b = mount('<adia-mark-ui inline></adia-mark-ui>');
+    await tick();
+    expect(a.inline).toBe(false);
+    expect(b.inline).toBe(true);
+    expect(b.getAttribute('inline')).toBe('');
+  });
+
+  it('sets role="img" and a default aria-label on connect', async () => {
+    const el = mount('<adia-mark-ui></adia-mark-ui>');
+    await tick();
+    expect(el.getAttribute('role')).toBe('img');
+    expect(el.getAttribute('aria-label')).toBe('Adia');
+  });
+
+  it('does not overwrite a consumer-authored aria-label', async () => {
+    const el = mount('<adia-mark-ui aria-label="Adia — home"></adia-mark-ui>');
+    await tick();
+    expect(el.getAttribute('aria-label')).toBe('Adia — home');
+  });
+
+  it('stamps the wordmark SVG with five glyph paths, no consumer-content conflict', async () => {
+    const el = mount('<adia-mark-ui></adia-mark-ui>');
+    await tick();
+    const svg = el.querySelector('svg');
+    expect(svg).toBeTruthy();
+    expect(el.querySelectorAll('[data-mark-glyph]').length).toBe(5);
+  });
+
+  it('renders identically regardless of size — static template, no interpolation', async () => {
+    const a = mount('<adia-mark-ui size="sm"></adia-mark-ui>');
+    const b = mount('<adia-mark-ui size="xl"></adia-mark-ui>');
+    await tick();
+    expect(a.innerHTML).toBe(b.innerHTML);
+  });
+});