@adia-ai/web-components 0.8.10 → 0.8.12

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.12] — 2026-07-24
+
+### Changed
+- **`tag-ui` adopts `badge-ui`'s sm/md/lg size system** (`components/tag/{tag.yaml,tag.examples.html}`; PR #401) — the `size` enum was `sm|md` only, one row short of `badge-ui` despite already sharing the identical CSS pattern (both delegate sizing entirely to the universal `[size]` system; neither has any per-size CSS of its own). Added `lg`. No CSS changes required. Also fixed a stale deck paragraph ("Supports status variants and two sizes" → "three sizes") on the compile source for `/site/components/tag`.
+
+## [0.8.11] — 2026-07-23
+
+### Added
+- **`<adia-wordmark-ui>` primitive** (`components/adia-wordmark/`; gh#390, PR #393) — the Adia wordmark as a token-driven, scheme-adaptive brand primitive: inline SVG lockup reading `--a-fg-strong`, height-scaled ladder (`--adia-wordmark-height-*`) with fixed aspect ratio, `inline` mode for text-flow placement. Sits beside `<adia-mark-ui>` (the square mark) with a matching size vocabulary. Dist bundles regenerated with it.
+- **Ancestor `[scale]` sizing context** (`styles/scale.css`, new opt-in layer; `dist/scale.{min.css,sheet.js}`) — six explicit hand-tabled tiers across two bands: `ui-sm` (≡ `[verse]`, byte-identical), `ui-md` (≡ base — a real reset tier), `ui-lg`, `content-sm`, `content-md` (≡ `[prose]`), `content-lg`. Each tier re-declares the full `--a-size/-inset/-gap/-radius/-icon/-caret/-toggle` sm/md/lg families plus all 13 type roles, so the universal `[size]` attribute keeps working inside a scaled subtree: **scale picks the table, size picks the row.** Tiers also re-table the identity-component ladders (`--avatar-size-*`, `--avatar-group-counter-size-*`/`-overlap-*`, `--adia-mark-size-*`, `--adia-wordmark-height-*`), so the removed `xs`/`xl` diameters live on as grid cells — `(ui-sm, sm)` and `(ui-lg, lg)`. `--a-density` is orthogonal and composes unchanged. Tier selectors are written `[scale][scale="…"]` (0-2-0) so they deterministically beat the legacy register attributes; the deduced tiers (`ui-lg`, `content-sm`, `content-lg`) are one-row shifts of their neighbors, tunable.
+- **`icon-ui` free-form `%` values** — `size="100%"` fills the parent box (replaces the removed named `fill` tier); `#isFreeFormSize` accepts `px|rem|em|%`.
+
+### BREAKING
+- **Every component `size` enum is now exactly `sm | md | lg`.** Trimmed: `button-ui`, `badge-ui`, `switch-ui`, `toggle-scheme-ui` (xs/xl — these were **enum-only promises with no CSS backing; they always rendered `md`**), `modal-ui` (xl, same), `avatar-ui`/`avatar-group-ui`/`adia-mark-ui`/`adia-wordmark-ui` (xs/xl — real tiers, now `[scale]` grid cells), and `icon-ui` (named xs/xl/2xl/3xl/4xl/fill → free-form `"12"/"32"/"48"/"64"/"96"/"100%"`; its named sm/md/lg now ride the universal `[size]` → `--a-icon-size` system, same 14/16/20px values). Migration table + mechanical sweep: MIGRATION GUIDE § v0.8.11.
+- **`[verse]` / `[prose]` deprecated** — superseded by `scale="ui-sm"` / `scale="content-md"` (byte-identical tables); the legacy attributes still ship and work until v1.0. `theme-provider`'s `scale` prop takes the six tier names; `scale="verse|prose"` remain as console-warned aliases.
+
+### Changed
+- **Internally stamped ghost/icon affordances tighten `md → sm`** (`select-ui` clear-all + leading marks, `input-ui` clear/reveal, `combobox-ui` clear, `tag-ui` dismiss, `calendar-picker-ui`/`calendar-grid-ui` prev/next) — they declared the fake `size="xs"` tier, so they actually rendered `md`; they now declare `size="sm"` and render one step tighter. `select-ui`'s stamped `adia-mark-ui` leadings keep their former 1.25rem diameter via a scoped parity rule (`select.css`).
+- **`avatar-group-ui` counter/overlap are token families** (`--avatar-group-counter-size-{sm,md,lg}`, `--avatar-group-overlap-{sm,md,lg}`) so `[scale]` tiers can re-table them like the avatar ladder. Same default values.
+
+### Maintenance
+- **`dist/` bundles rebuilt** (`web-components.{min.css,min.js,sheet.js}`, `host.*`, `themes.*`, new `scale.*`) — regenerated from the source changes above.
+- **`patterns/` touched in this release window** (5 file(s), e.g. `comments-and-collaboration/comments-and-collaboration.examples.html`) — carried by the entries above.
+- **`traits/` touched in this release window** (5 file(s), e.g. `count-up/count-up.examples.html`) — carried by the entries above.
+
 ## [0.8.10] — 2026-07-20
 
 ### Added

package/MIGRATION.md

@@ -46,10 +46,68 @@ Version cuts and migration scope:
 
 - **`0.8.0`** — MINOR lockstep cut (2026-07-15). Internal ranges `^0.7.0` → `^0.8.0`. **BREAKING (3 items):** the Material color-token adoption — `--md-sys-color-*` (a static export) is now the color system's source of truth and public API. Removed: the 19 `--a-accent-*` back-compat aliases (→ `--a-primary-*`), the 189 raw per-family `--a-{family}-{0..6}-{tint-|shade-}scrim` primitives (→ the static `--md-sys-color-{family}-scrim-*` ladder), and the `primitives-accent.css` deep-import path (→ `primitives-primary.css`). **Behavioral:** the 8 named `[theme]` presets no longer re-color components (only brand hue + radius/density/shadow knobs still respond). See [§ v0.8.0 section below](#migrating-to-adia-aiv080-2026-07-15).
 
+- **`0.8.11`** — PATCH lockstep cut (2026-07-23). Internal ranges stay at `^0.8.0`. **BREAKING: the size model.** Every component `size` enum is now exactly `sm | md | lg`; the removed tiers (`xs`, `xl`, icon's `2xl/3xl/4xl/fill`) are served by the new ancestor **`[scale]`** context — six hand-tabled tiers (`ui-sm · ui-md · ui-lg · content-sm · content-md · content-lg`): scale picks the table, `size` picks the row. `[verse]`/`[prose]` are deprecated aliases of `ui-sm`/`content-md` (removed at v1.0). Also new: `<adia-wordmark-ui>`. See [§ v0.8.11 section below](#migrating-to-adia-aiv0811-2026-07-23).
+
 Live demos and per-component docs at [ui-kit.exe.xyz/site/](https://ui-kit.exe.xyz/site/). The `adia-ui-migration` skill (in `.agents/skills/`) automates most of the mechanical sweeps in this guide.
 
 ---
 
+## Migrating to `@adia-ai/*@v0.8.11` (2026-07-23)
+
+**PATCH lockstep cut.** Internal ranges stay at `^0.8.0`. One breaking theme: **the size model contracts to `sm | md | lg` everywhere, and an ancestor `[scale]` attribute takes over everything the extra tiers did.** `styles/scale.css` (new, opt-in like verse/prose; `dist/scale.min.css` + `dist/scale.sheet.js`) defines six explicit tiers — `ui-sm` (≡ old `[verse]`), `ui-md` (≡ base), `ui-lg`, `content-sm`, `content-md` (≡ old `[prose]`), `content-lg` — each a full hand-tabled re-declaration of the `--a-size/-inset/-gap/-radius/-icon/-caret/-toggle` families and all 13 type roles. Scale picks the table, `[size]` picks the row; an unscaled page renders byte-identically to v0.8.10.
+
+### Component `size` enums trimmed to `sm | md | lg`
+
+Two very different classes were removed:
+
+- **Fake tiers** (`button-ui`, `badge-ui`, `switch-ui`, `toggle-scheme-ui` `xs`/`xl`; `modal-ui` `xl`) — these had **no CSS behind them and always rendered as `md`**. Dropping the attribute is exact visual parity; remapping to `sm`/`lg` applies the size the author probably intended (a visible change).
+- **Real tiers** (`avatar-ui`, `avatar-group-ui`, `adia-mark-ui`, `adia-wordmark-ui` `xs`/`xl`; `icon-ui` `xs/xl/2xl/3xl/4xl/fill`) — the old pixel values live on exactly as `[scale]` grid cells or free-form icon values (table below).
+
+| old call site | exact new equivalent | escape hatch |
+|---|---|---|
+| `avatar-ui size="xs"` (20px) | `size="sm"` under `scale="ui-sm"` | `style="--avatar-size:1.25rem"` |
+| `avatar-ui size="xl"` (72px) | `size="lg"` under `scale="ui-lg"` (or `content-md`) | `style="--avatar-size:4.5rem"` |
+| `adia-mark-ui` / `adia-wordmark-ui` `xs`/`xl` | same pattern | `--adia-mark-size` / `--adia-wordmark-height` |
+| `icon-ui size="xs"` | `size="12"` | — |
+| `icon-ui size="xl"` / `2xl` / `3xl` / `4xl` | `size="32"` / `"48"` / `"64"` / `"96"` | — |
+| `icon-ui size="fill"` | `size="100%"` (new: `%` accepted as free-form) | `style="--icon-size:100%"` |
+| `button/badge/switch/toggle-scheme size="xs|xl"` | drop the attr (was fake → rendered `md`), or `sm`/`lg` if the intent was real | — |
+| `modal-ui size="xl"` | `size="lg"` (was fake) | `style="--modal-width:…"` |
+| `[verse]` / `[prose]` | `scale="ui-sm"` / `scale="content-md"` (byte-identical tables) | deprecated attrs still ship until v1.0 |
+
+`icon-ui` also went grid-native: its named `sm/md/lg` now ride the universal `[size]` → `--a-icon-size` system (same 14/16/20px values), so icons track an ancestor `[scale]` register automatically.
+
+**Audit:**
+```bash
+git grep -nE 'size="(xs|xl|2xl|3xl|4xl|fill)"'
+git grep -nE '"size": *"(xs|xl|2xl|3xl|4xl|fill)"'   # A2UI/JSON form
+```
+
+**Sweep (mechanical, non-icon tags):**
+```bash
+git grep -lE 'size="(xs|xl)"' | xargs perl -i -pe 's/size="xs"/size="sm"/g; s/size="xl"/size="lg"/g'
+```
+Icon named tiers are a table-driven remap (`xs→"12"`, `xl→"32"`, `2xl→"48"`, `3xl→"64"`, `4xl→"96"`, `fill→"100%"`) — sweep them BEFORE the generic pass, and never touch already-free-form values (`size="48"`).
+
+**Manual review:** call sites that used `xs`/`xl` to express "this whole region is denser/larger" should adopt an ancestor `scale="…"` instead of the per-element remap — that is the new model's point.
+
+### `theme-provider` `scale` prop revalued
+
+`<theme-provider scale="…">` now takes the six tier names (the reflected attribute IS the `[scale]` CSS hook and auto-adopts `dist/scale.sheet.js`). `scale="verse"`/`"prose"` still work as deprecated aliases (console warning; removed at v1.0).
+
+### Internal stamped affordances tightened `md → sm`
+
+The ghost/icon affordances several components stamp internally (`select-ui` clear-all + leading marks, `input-ui` clear/reveal, `combobox-ui` clear, `tag-ui` dismiss, calendar prev/next) declared `size="xs"` — which the fake-tier collapse rendered as `md`. They now declare `size="sm"` and genuinely render one step tighter. No consumer action; noted because it is a visible (intentional) change on dense forms.
+
+### Verify the sweep landed
+
+```bash
+git grep -cE 'size="(xs|xl|2xl|3xl|4xl|fill)"' || echo clean   # expect clean (icon free-form px values remain)
+```
+Then render one dense screen and one long-form screen and confirm register changes come only from `[scale]`/`[size]`.
+
+---
+
 ## Migrating to `@adia-ai/*@v0.8.0` (2026-07-15)
 
 **MINOR cut.** All 9 packages bumped `0.7.x → 0.8.0`; internal `@adia-ai/*` ranges **bump to `^0.8.0`**. The headline: **AdiaUI adopted the Material Design token system as its color source of truth** (`.claude/docs/specs/material-color-bridge-contract.md`, Phases 1–5). `--md-sys-color-*` roles (59 per palette, 8 palettes, static OKLCH literals in `colors/material-static.css`) are the public color API; the `--a-*` semantic layer remains fully functional as a thin alias layer reading FROM it. 3 breaking items + 1 behavioral change.

package/USAGE.md

@@ -1103,17 +1103,15 @@ This section collects 11 docs items (§221a–§221k) that emerged from rounds R
 
 ### §221a — Universal `[size]` prop family
 
-Every interactive primitive accepts `[size]` with `xs | sm | md | lg | xl` (some additionally accept `2xs` / `2xl`). The token wiring is in `themes.css`:
+Every interactive primitive accepts `[size]` with `sm | md | lg` (since v0.8.11 this is the whole vocabulary — the former `xs`/`xl` tiers are served by an ancestor `[scale]` register instead). The token wiring is the universal `[size]` system in `styles/api/sizing.css`:
 
 ```css
-[size="xs"]  { --a-size: 24px; }   /* compact toolbar / inline densities */
-[size="sm"]  { --a-size: 28px; }
-[size="md"]  { --a-size: 32px; }   /* canonical default */
-[size="lg"]  { --a-size: 40px; }
-[size="xl"]  { --a-size: 48px; }   /* hero CTAs, top-level brand */
+[size="sm"] { --a-size: calc(var(--a-density) * 1.5rem); }   /* 24px — dense data UIs */
+/* [size="md"] is the default — 30px */
+[size="lg"] { --a-size: calc(var(--a-density) * 2.25rem); }  /* 36px — hero CTAs */
 ```
 
-Authoring: `<button-ui size="lg" text="Continue">`. The element inherits `--a-size` from the closest `[size]` ancestor when the prop is unset, so a `<row-ui size="sm">` containing 5 controls makes them all small without per-element repeat.
+Authoring: `<button-ui size="lg" text="Continue">`. The element inherits `--a-size` from the closest `[size]` ancestor when the prop is unset, so a `<row-ui size="sm">` containing 5 controls makes them all small without per-element repeat. For a whole region one register denser or larger, set `scale="ui-sm" … "content-lg"` on an ancestor (`styles/scale.css`): scale picks the table, size picks the row.
 
 When in doubt about whether a primitive supports `[size]`: every form-bearing primitive does (input / textarea / select / switch / check / radio / button / range / slider / search). Display primitives that participate in size cascades also do (avatar / badge / tag / icon / chip / card).
 

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

@@ -25,11 +25,9 @@
       "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"
+        "lg"
       ],
       "default": "md"
     }
@@ -65,13 +63,15 @@
       "adia",
       "brand",
       "logo",
-      "wordmark",
       "mark",
       "identity",
-      "favicon"
+      "favicon",
+      "tile",
+      "icon"
     ],
     "name": "UIAdiaMark",
     "related": [
+      "AdiaWordmark",
       "Icon",
       "Avatar",
       "Image"
@@ -95,7 +95,7 @@
         "adia",
         "brand",
         "mark",
-        "wordmark"
+        "tile"
       ]
     },
     "tag": "adia-mark-ui",

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

@@ -14,7 +14,7 @@
 /**
  * <adia-mark-ui></adia-mark-ui>
  * <adia-mark-ui size="sm"></adia-mark-ui>
- * <adia-mark-ui size="xl"></adia-mark-ui>
+ * <adia-mark-ui size="lg"></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

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

@@ -8,11 +8,12 @@
     --adia-mark-bg: var(--a-canvas-surface-inverse);
     --adia-mark-fg: var(--a-fg-inverse);
 
-    --adia-mark-size-xs: 1.25rem;
+    /* sm/md/lg only — removed xs/xl live on as the ancestor-[scale]
+       grid cells (ui-sm, sm) / (ui-lg, lg); styles/scale.css re-tables
+       this family per tier. */
     --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 {
@@ -40,9 +41,7 @@
   }
 
   /* ── 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

@@ -16,5 +16,5 @@ 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';
+  size: 'sm' | 'md' | 'lg';
 }

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

@@ -9,11 +9,9 @@
 ## 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

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

@@ -25,9 +25,9 @@ describe('adia-mark-ui', () => {
   });
 
   it('reflects an explicit [size]', async () => {
-    const el = mount('<adia-mark-ui size="xl"></adia-mark-ui>');
+    const el = mount('<adia-mark-ui size="lg"></adia-mark-ui>');
     await tick();
-    expect(el.size).toBe('xl');
+    expect(el.size).toBe('lg');
   });
 
   it('defaults to inline=false and reflects an explicit [inline]', async () => {
@@ -62,7 +62,7 @@ describe('adia-mark-ui', () => {
 
   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>');
+    const b = mount('<adia-mark-ui size="lg"></adia-mark-ui>');
     await tick();
     expect(a.innerHTML).toBe(b.innerHTML);
   });

package/components/adia-mark/adia-mark.yaml

@@ -19,11 +19,9 @@ props:
     type: string
     default: md
     enum:
-      - xs
       - sm
       - md
       - lg
-      - xl
     reflect: true
   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.
@@ -54,6 +52,7 @@ a2ui:
     - Use <AdiaMark> for the Adia brand/app-identity mark — a favicon-style app-switcher tile, a splash/loading screen, an about-panel header. Do not use it as a generic icon; it has no [name] prop and always renders the same wordmark.
     - Do not wrap <AdiaMark> in <Icon> or pass it a color/tone override — the background/foreground pairing is fixed by design (always inverse-on-inverse for contrast), not a themeable variant.
     - Prefer <AdiaMark size="sm"> in a nav/topbar brand slot (a Row alongside the product name); reserve larger sizes (lg, xl) for splash screens or empty-state headers. Set [inline] only when the mark sits directly inside a run of prose text, not inside a Row/flex layout (block-level children compose fine as flex items already).
+    - Use <AdiaMark> for the square icon/tile use (app-switcher slot, favicon-style avatar) — always the fixed inverse-on-inverse pairing. Use <AdiaWordmark> instead for the standalone "Adia" text logotype meant to sit directly on a surface with no background chip.
 anti_patterns:
   - wrong: |
       <icon-ui name="adia"></icon-ui>
@@ -100,22 +99,24 @@ keywords:
   - adia
   - brand
   - logo
-  - wordmark
   - mark
   - identity
   - favicon
+  - tile
+  - icon
 synonyms:
   logo:
     - adia
     - brand
     - mark
-    - wordmark
+    - tile
   brand:
     - adia
     - logo
     - mark
     - identity
 related:
+  - AdiaWordmark
   - Icon
   - Avatar
   - Image

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

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdiaWordmark.json",
+  "title": "AdiaWordmark",
+  "description": "The Adia wordmark — the \"Adia\" text logotype rendered as inline SVG. Unlike `adia-mark-ui` (gh#283's fixed inverse-on-inverse square tile), this is a standalone mark meant to sit directly on a surface: its fill defaults to the current scheme's on-surface foreground token (`--a-fg-strong`) rather than a fixed inverse pairing, so it reads correctly wherever it's placed — a login header, a footer, a splash screen — without needing a background chip (gh#390).",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdiaWordmark"
+    },
+    "inline": {
+      "description": "Renders as `display:inline-block` instead of the block-level default (ADR-0037) — set this when the wordmark sits beside a text run rather than standing alone.",
+      "type": "boolean",
+      "default": false
+    },
+    "size": {
+      "description": "Height of the wordmark; width follows via the fixed aspect ratio. Matches adia-mark-ui's size ladder for visual consistency when the two sit side by side.",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<adia-wordmark-ui size=\"sm\"></adia-wordmark-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 wordmark.\n",
+        "wrong": "<icon-ui name=\"adia\"></icon-ui>\n"
+      },
+      {
+        "fix": "<adia-wordmark-ui size=\"sm\"></adia-wordmark-ui>\n",
+        "why": "adia-mark-ui is the fixed inverse-on-inverse SQUARE TILE (gh#283) —\nalways a background chip with the wordmark cut out, sized for an\napp-switcher/favicon slot. It is not interchangeable with the\nstandalone text logotype meant to sit directly on a surface.\n",
+        "wrong": "<adia-mark-ui size=\"sm\"></adia-mark-ui>\n"
+      }
+    ],
+    "category": "display",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Standalone wordmark in a login/marketing header, no background chip needed.",
+        "a2ui": "[\n  {\n    \"id\": \"brand-row\",\n    \"component\": \"Row\",\n    \"gap\": \"2\",\n    \"align\": \"center\",\n    \"children\": [\"wordmark\"]\n  },\n  {\n    \"id\": \"wordmark\",\n    \"component\": \"AdiaWordmark\",\n    \"size\": \"sm\"\n  }\n]",
+        "name": "login-header-wordmark"
+      }
+    ],
+    "keywords": [
+      "adia",
+      "wordmark",
+      "logotype",
+      "text logo",
+      "identity"
+    ],
+    "name": "UIAdiaWordmark",
+    "related": [
+      "AdiaMark",
+      "Icon",
+      "Image"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "The only state — a static, non-interactive wordmark.",
+        "name": "default"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "logotype": [
+        "adia",
+        "wordmark"
+      ],
+      "wordmark": [
+        "adia",
+        "logotype",
+        "text logo"
+      ]
+    },
+    "tag": "adia-wordmark-ui",
+    "tokens": {
+      "--adia-wordmark-fg": {
+        "description": "Wordmark fill — defaults to the on-surface foreground token. Themeable (unlike adia-mark-ui's fixed inverse pairing), since this mark already sits directly on a surface rather than owning its own background chip.",
+        "default": "var(--a-fg-strong)"
+      },
+      "--adia-wordmark-height": {
+        "description": "Height of the wordmark; width follows via aspect-ratio.",
+        "default": "1.5rem"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Non-side-effect class export for `<adia-wordmark-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-wordmark`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <adia-wordmark-ui></adia-wordmark-ui>
+ * <adia-wordmark-ui size="sm"></adia-wordmark-ui>
+ * <adia-wordmark-ui size="lg"></adia-wordmark-ui>
+ *
+ * The Adia wordmark — the "Adia" text logotype rendered as inline SVG.
+ * Unlike `adia-mark-ui` (gh#283's fixed inverse-on-inverse square tile),
+ * this is a standalone mark meant to sit directly on a surface, so its
+ * fill defaults to the current scheme's on-surface foreground token
+ * (`--a-fg-strong`) rather than a fixed inverse pairing (gh#390).
+ *
+ * `[data-wordmark-glyph]` marks the five logotype paths so the CSS token
+ * (`--adia-wordmark-fg`) can target them without repeating the selector
+ * five times — same pattern as `adia-mark-ui`'s `[data-mark-glyph]`.
+ *
+ * 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 UIAdiaWordmark 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 512 182" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+      <path data-wordmark-glyph d="M328.763 33.7659C332.735 37.5729 337.369 39.4764 342.665 39.4764C348.127 39.4764 352.761 37.5729 356.568 33.7659C360.54 29.7935 362.526 25.1589 362.526 19.8623C362.526 14.5657 360.54 9.93116 356.568 5.95869C352.761 1.98623 348.127 0 342.665 0C337.369 0 332.735 1.98623 328.763 5.95869C324.956 9.93116 323.053 14.5657 323.053 19.8623C323.053 25.1589 324.956 29.7935 328.763 33.7659Z"></path>
+      <path data-wordmark-glyph d="M326.777 54.3731V178.513H358.802V54.3731H326.777Z"></path>
+      <path data-wordmark-glyph fill-rule="evenodd" clip-rule="evenodd" d="M512 54.3589H479.975V69.0074C470.375 56.9245 456.887 50.883 439.509 50.883C422.958 50.883 408.725 57.2555 396.808 70.0005C385.058 82.58 379.182 98.056 379.182 116.429C379.182 134.801 385.058 150.36 396.808 163.105C408.725 175.685 422.958 181.974 439.509 181.974C456.887 181.974 470.375 175.933 479.975 163.85V178.498H512V54.3589ZM445.467 151.436C435.537 151.436 427.344 148.208 420.889 141.753C414.435 135.132 411.207 126.691 411.207 116.429C411.207 106.166 414.435 97.8077 420.889 91.3525C427.344 84.7317 435.537 81.4213 445.467 81.4213C455.397 81.4213 463.59 84.7317 470.044 91.3525C476.665 97.8077 479.975 106.166 479.975 116.429C479.975 126.691 476.665 135.132 470.044 141.753C463.59 148.208 455.397 151.436 445.467 151.436Z"></path>
+      <path data-wordmark-glyph fill-rule="evenodd" clip-rule="evenodd" d="M267.953 4.72882H299.978V178.524H267.953V163.876C258.519 175.959 245.113 182 227.735 182C211.019 182 196.703 175.71 184.786 163.131C173.035 150.386 167.16 134.827 167.16 116.454C167.16 98.0817 173.035 82.6057 184.786 70.0262C196.703 57.2812 211.019 50.9087 227.735 50.9087C245.113 50.9087 258.519 56.9502 267.953 69.0331V4.72882ZM208.867 141.779C215.488 148.234 223.763 151.462 233.693 151.462C243.623 151.462 251.816 148.234 258.271 141.779C264.725 135.158 267.953 126.717 267.953 116.454C267.953 106.192 264.725 97.8334 258.271 91.3782C251.816 84.7574 243.623 81.447 233.693 81.447C223.763 81.447 215.488 84.7574 208.867 91.3782C202.413 97.8334 199.185 106.192 199.185 116.454C199.185 126.717 202.413 135.158 208.867 141.779Z"></path>
+      <path data-wordmark-glyph fill-rule="evenodd" clip-rule="evenodd" d="M116.681 147.241L127.108 178.524H164.347L103.275 4.72882H60.8231L0 178.524H36.9904L47.4172 147.241H116.681ZM82.1733 44.2052L106.006 115.213H58.3406L82.1733 44.2052Z"></path>
+    </svg>
+  `;
+
+  connected() {
+    this.setAttribute('role', 'img');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Adia');
+  }
+}

package/components/adia-wordmark/adia-wordmark.css

@@ -0,0 +1,45 @@
+@scope (adia-wordmark-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --adia-wordmark-height: var(--a-size, 1.5rem);
+    /* Meant to sit directly on a surface (gh#390) — defaults to the
+       on-surface foreground token, unlike adia-mark-ui's fixed
+       inverse-on-inverse pairing. Themeable: override this if the
+       wordmark sits on a non-default surface. */
+    --adia-wordmark-fg: var(--a-fg-strong);
+
+    /* sm/md/lg only — removed xs/xl live on as the ancestor-[scale]
+       grid cells (ui-sm, sm) / (ui-lg, lg); styles/scale.css re-tables
+       this family per tier. */
+    --adia-wordmark-height-sm: 1.125rem;
+    --adia-wordmark-height-md: 1.5rem;
+    --adia-wordmark-height-lg: 2rem;
+  }
+
+  :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;
+    height: var(--adia-wordmark-height);
+    width: auto;
+    aspect-ratio: 512 / 182;
+    flex-shrink: 0;
+  }
+
+  :scope[inline] { display: inline-block; }
+
+  :scope > svg {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+
+  :scope > svg [data-wordmark-glyph] {
+    fill: var(--adia-wordmark-fg);
+  }
+
+  /* ── Size ladder ── */
+  :scope[size="sm"] { --adia-wordmark-height: var(--adia-wordmark-height-sm); }
+  :scope[size="md"] { --adia-wordmark-height: var(--adia-wordmark-height-md); }
+  :scope[size="lg"] { --adia-wordmark-height: var(--adia-wordmark-height-lg); }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * `<adia-wordmark-ui>` — The Adia wordmark — the "Adia" text logotype rendered as inline SVG. Unlike `adia-mark-ui` (gh#283's fixed inverse-on-inverse square tile), this is a standalone mark meant to sit directly on a surface: its fill defaults to the current scheme's on-surface foreground token (`--a-fg-strong`) rather than a fixed inverse pairing, so it reads correctly wherever it's placed — a login header, a footer, a splash screen — without needing a background chip (gh#390).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/adia-wordmark
+ *
+ * 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 UIAdiaWordmark extends UIElement {
+  /** Renders as `display:inline-block` instead of the block-level default (ADR-0037) — set this when the wordmark sits beside a text run rather than standing alone. */
+  inline: boolean;
+  /** Height of the wordmark; width follows via the fixed aspect ratio. Matches adia-mark-ui's size ladder for visual consistency when the two sit side by side. */
+  size: 'sm' | 'md' | 'lg';
+}

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

@@ -0,0 +1,23 @@
+# adia-wordmark — Examples
+
+## Default
+
+```html
+<adia-wordmark-ui></adia-wordmark-ui>
+```
+
+## Sizes
+
+```html
+<adia-wordmark-ui size="sm"></adia-wordmark-ui>
+<adia-wordmark-ui size="md"></adia-wordmark-ui>
+<adia-wordmark-ui size="lg"></adia-wordmark-ui>
+```
+
+## Login header
+
+```html
+<row-ui gap="2" align="center">
+  <adia-wordmark-ui size="lg"></adia-wordmark-ui>
+</row-ui>
+```

package/components/adia-wordmark/adia-wordmark.js

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

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

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './adia-wordmark.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-wordmark-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('registers adia-wordmark-ui as a custom element', () => {
+    expect(customElements.get('adia-wordmark-ui')).toBeDefined();
+  });
+
+  it('defaults to size="md"', async () => {
+    const el = mount('<adia-wordmark-ui></adia-wordmark-ui>');
+    await tick();
+    expect(el.size).toBe('md');
+  });
+
+  it('reflects an explicit [size]', async () => {
+    const el = mount('<adia-wordmark-ui size="lg"></adia-wordmark-ui>');
+    await tick();
+    expect(el.size).toBe('lg');
+  });
+
+  it('defaults to inline=false and reflects an explicit [inline]', async () => {
+    const a = mount('<adia-wordmark-ui></adia-wordmark-ui>');
+    const b = mount('<adia-wordmark-ui inline></adia-wordmark-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-wordmark-ui></adia-wordmark-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-wordmark-ui aria-label="Adia — home"></adia-wordmark-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-wordmark-ui></adia-wordmark-ui>');
+    await tick();
+    const svg = el.querySelector('svg');
+    expect(svg).toBeTruthy();
+    expect(el.querySelectorAll('[data-wordmark-glyph]').length).toBe(5);
+  });
+
+  it('renders identically regardless of size — static template, no interpolation', async () => {
+    const a = mount('<adia-wordmark-ui size="sm"></adia-wordmark-ui>');
+    const b = mount('<adia-wordmark-ui size="lg"></adia-wordmark-ui>');
+    await tick();
+    expect(a.innerHTML).toBe(b.innerHTML);
+  });
+});