@adia-ai/web-modules 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -11,6 +11,31 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [0.4.3] - 2026-05-11
+
+### Documentation
+
+- `README.md` — currency sweep mentioning the `theme` cluster + `@adia-ai/web-modules/theme` subpath export shipped in v0.4.2 (peer-agent cleanup; source unchanged).
+
+### Lockstep
+
+9-package coordinated PATCH cut to v0.4.3. Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry). No source change to any web-module element — `README.md` doc-only. See root [CHANGELOG.md `## [0.4.3]`](../../CHANGELOG.md).
+
+## [0.4.2] - 2026-05-11
+
+### Added
+
+- **`<theme-panel>` module — new `theme/` cluster.** Module-tier appearance-preferences control surface. Owns the three knobs of the AdiaUI theming contract: `[data-theme]` named themes (8 built-in slugs + tolerant for custom), `--a-density` / `--a-radius-k` parametric overrides, and `color-scheme` light/dark switching, plus optional `localStorage` persistence behind a small attribute API ([`packages/web-modules/theme/theme-panel/`](./theme/theme-panel/)). Reflected state — `[active-theme]`, `[active-scheme]`, `[active-density]`, `[active-radius]` — lets external CSS / JS react via `:has(theme-panel[active-scheme="dark"])` patterns without listening to events. One `theme-change` event per user-visible change (source ∈ `theme | slider | preset | scheme | reset | programmatic`). Attribute API: `[themes="slug1 slug2…"]` (override default 8), `[parametric]` (renders density + radius sliders), `[presets]` (renders compact / reset / spacious preset row), `[scheme-toggle]` (renders inline light/dark toggle — absorbs the legacy standalone `#theme-toggle` button per OD-002=A). 23 unit tests. Promoted from the ~30-line inline `#theme-panel` block + ~90 LOC of controller wiring previously duplicated in `site/index.html` and `playgrounds/admin-shell/`. Spec: [`docs/specs/theme-panel-module.md`](../../docs/specs/theme-panel-module.md). Plan: [`docs/plans/theme-panel-module-2026-05-11.md`](../../docs/plans/theme-panel-module-2026-05-11.md). Commits `63d9deb4` (module Phase 1) + `a35d3131` (site consumer migration Phase 2; site.js −90 LOC + index.html −27 inline lines) + `c844aef4` (admin-shell playground consumer migration Phase 3; contents.html −25 lines + contents.js −48 LOC).
+- **New subpath export `@adia-ai/web-modules/theme`** — consumers wanting just this cluster can `import '@adia-ai/web-modules/theme'` instead of the full barrel. `package.json` `exports` / `files` / `sideEffects` updated.
+
+### Fixed
+
+- **`<editor-sidebar>` wrapping a `<pane-ui>` no longer collapses to ~1px in CSS grid `auto`-tracked editor shells.** The wrapper's `ResizeObserver` (already observing the inner pane for `[collapsed]` reflection) now also mirrors `pane.offsetWidth` onto `this.style.width`. Without this mirror, the CSS-grid algorithm's intrinsic-size lookup on the bespoke wrapper does NOT propagate through to the inner `<pane-ui>`'s explicit width — the wrapper's `max-content` is reported as ~1px (the border), the grid `auto` track collapses, and the pane overflows visually into the canvas. Affects every `editor-shell:has(> editor-canvas)` host with bespoke sidebar children (a2ui-editor + construct-canvas; the `smoke:consumers` Playwright probe now verifies both have 240/280 px sidebars and the canvas claims the remainder). The [editor cluster `bespoke.css`](./editor/editor-shell/css/editor-shell.bespoke.css) is unchanged — the bug was always on the JS side of the width contract, not the layout CSS.
+
+### Lockstep
+
+9-package coordinated PATCH cut to v0.4.2 (per [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy)). Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). Source change scoped to one file (`editor/editor-sidebar/editor-sidebar.js`); rides alongside the `@adia-ai/web-components` v0.4.2 `<input-ui type="number">` rewrite. See root [CHANGELOG.md `## [0.4.2]`](../../CHANGELOG.md) for the cut narrative.
+
 ## [0.4.1] - 2026-05-10
 
 ### Added

package/README.md

@@ -5,6 +5,24 @@ Composite custom elements built from
 into clusters by use case; each cluster ships as a subpath export so
 consumers install only what they need.
 
+## Install
+
+```bash
+npm install @adia-ai/web-modules @adia-ai/web-components
+```
+
+`@adia-ai/web-components` is a peer dependency (modules compose primitives at runtime). Consumers can import the full barrel or a specific cluster subpath:
+
+```js
+import '@adia-ai/web-modules';                  // every cluster
+import '@adia-ai/web-modules/shell';             // admin-shell + admin-sidebar + admin-command
+import '@adia-ai/web-modules/chat';              // chat-shell + chat-thread + chat-composer + …
+import '@adia-ai/web-modules/editor';            // editor-shell + editor-canvas + editor-sidebar + …
+import '@adia-ai/web-modules/simple';            // simple-shell + simple-content + simple-hero
+import '@adia-ai/web-modules/theme';             // theme-panel
+import '@adia-ai/web-modules/runtime';           // gen-root + a2ui-root
+```
+
 Each cluster carries a **shell host** (behavior-only orchestrator) plus
 a **family of bespoke shell-tier children** (cluster-namespaced custom
 elements with state-as-attribute semantics) per [ADR-0023](../../.brain/adrs/0023-bespoke-shell-tier-children.md). The bespoke vocabulary is the only recognized authoring shape since v0.4.0 ([ADR-0024](../../.brain/adrs/0024-legacy-shell-shapes-retired.md)).
@@ -23,6 +41,7 @@ elements with state-as-attribute semantics) per [ADR-0023](../../.brain/adrs/002
 | `chat` | `<chat-shell>` | `<chat-thread>`, `<chat-composer>`, `<chat-sidebar>` (JS-bearing); `<chat-empty>`, `<chat-header>`, `<chat-status>` (CSS-only); 6 children total | Conversational surface — streaming messages, composer with `[disabled]` propagation, scroll-to-bottom thread, `[streaming]` reflected. |
 | `editor` | `<editor-shell>` | `<editor-toolbar>`, `<editor-canvas>`, `<editor-sidebar>` (JS-bearing); `<editor-statusbar>`, `<editor-canvas-empty>` (CSS-only); 5 children total | Design-tool surface — toolbar with `[full-screen]`, central canvas with `[focused]`/`[empty]`, sidebar wraps `<pane-ui resizable>` for delegation. |
 | `runtime` | `<gen-root>`, `<a2ui-root>` | — | Render roots that turn JSON or gen-UI intents into live DOM. |
+| `theme` | — (controls-only) | `<theme-panel>` (JS-bearing); 1 child total | Appearance-preferences control surface — `[data-theme]` named themes, `--a-density` / `--a-radius-k` parametric overrides, `color-scheme` light/dark, opt-in `[persist]`. Drops into any consumer's `<popover-ui slot="content">` topbar. Spec: [`docs/specs/theme-panel-module.md`](../../docs/specs/theme-panel-module.md). |
 
 Future clusters on the strategic horizon: `data` (kanban, filters,
 table-toolbar), `agent` (agent-trace, reasoning panels).
@@ -44,6 +63,7 @@ See [`bespoke-shell-children` skill](../../.agents/skills/bespoke-shell-children
   import '@adia-ai/web-modules/chat';      // chat-shell + bespoke children
   import '@adia-ai/web-modules/editor';    // editor-shell + bespoke children
   import '@adia-ai/web-modules/runtime';   // gen-root, a2ui-root
+  import '@adia-ai/web-modules/theme';     // theme-panel (appearance prefs)
 </script>
 
 <!-- Bespoke shape (canonical since v0.4.0): -->
@@ -118,6 +138,8 @@ web-modules/
 ├── runtime/
 │   ├── gen-ui/         <gen-ui> render root
 │   └── a2ui-root/      <a2ui-root> A2UI render root
+├── theme/
+│   └── theme-panel/    <theme-panel> appearance-preferences control surface
 └── index.js            barrel re-export of every cluster
 ```
 

package/editor/editor-shell/css/editor-shell.bespoke.css

@@ -71,6 +71,13 @@ editor-shell > editor-canvas {
   min-width: 0;
   display: flex;
   flex-direction: column;
+  /* Stretch children to full width (layout.css's editor-shell editor-canvas
+     rule sets align-items: center for an empty-state placeholder, which
+     would otherwise leave #canvas-host at its min-width: 320px centered
+     inside the canvas region — leaving large empty space on either side.
+     The empty-state child handles its own centering separately. */
+  align-items: stretch;
+  justify-content: flex-start;
   position: relative;
   overflow: auto;
   background: var(--editor-canvas-bg, var(--a-bg-subtle));

package/editor/editor-shell/css/editor-shell.layout.css

@@ -81,8 +81,13 @@ editor-shell > header > [slot="action-leading"] {
   margin-inline-end: auto;
 }
 
-/* ── Body: pane | canvas | pane ── */
-editor-shell >  {
+/* ── Body: pane | canvas | pane ──
+   Legacy raw-children body wrapper (pre-bespoke, when editor-shell was a
+   single flex column with a [data-body] wrapper around the pane/canvas
+   row). With <editor-canvas> + <editor-sidebar> bespoke children, the
+   grid layout in bespoke.css owns the body shape. This rule is kept
+   for any non-bespoke consumer still passing raw inner content. */
+editor-shell > [data-body] {
   display: flex;
   flex: 1;
   min-width: 0;
@@ -94,8 +99,14 @@ editor-shell editor-canvas {
   flex: 1;
   min-width: 0;
   display: flex;
-  align-items: center;
-  justify-content: center;
+  /* Children stretch to fill; the empty-state placeholder
+     (editor-canvas-empty) does its own centering via bespoke.css.
+     align-items: center here would shrink-wrap children to their
+     intrinsic width and center them — which leaves a 320px-min
+     #canvas-host centered inside a wide canvas region with empty
+     bands on both sides. */
+  align-items: stretch;
+  justify-content: flex-start;
   background: var(--editor-canvas-bg);
   color: var(--editor-canvas-fg);
 }

package/editor/editor-sidebar/editor-sidebar.js

@@ -77,8 +77,20 @@ class EditorSidebar extends UIElement {
     // Restore persisted width
     this.#restoreWidth();
 
-    // Observe inner pane width to maintain [collapsed] reflected
-    this.#ro = new ResizeObserver(() => this.#syncCollapsed());
+    // Observe inner pane width to (a) maintain [collapsed] reflected and
+    // (b) mirror the width onto this wrapper so the parent's grid track
+    // sizes correctly. Without the mirror, an `auto`/`max-content` grid
+    // track on the wrapping editor-sidebar collapses to ~1px because the
+    // intrinsic-size lookup doesn't propagate through to <pane-ui>'s
+    // explicit width — the pane then overflows out of the sidebar and
+    // visually overlaps the canvas.
+    this.#ro = new ResizeObserver((entries) => {
+      this.#syncCollapsed();
+      // Use offsetWidth so the sidebar wraps the full pane border-box
+      // (contentRect would be 1px short on side="leading|trailing").
+      const w = this.#pane.offsetWidth;
+      if (w > 0) this.style.width = `${w}px`;
+    });
     this.#ro.observe(this.#pane);
 
     // Track resize via pointerdown on resize-handle children of the pane

package/index.js

@@ -13,3 +13,4 @@ export * from './chat/index.js';
 export * from './editor/index.js';
 export * from './simple/index.js';
 export * from './runtime/index.js';
+export * from './theme/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "AdiaUI composite custom elements — shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {
@@ -15,6 +15,8 @@
     "./simple/*": "./simple/*/*.js",
     "./runtime": "./runtime/index.js",
     "./runtime/*": "./runtime/*/*.js",
+    "./theme": "./theme/index.js",
+    "./theme/*": "./theme/*/*.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -23,6 +25,7 @@
     "editor/",
     "simple/",
     "runtime/",
+    "theme/",
     "index.js",
     "README.md",
     "CHANGELOG.md"
@@ -33,7 +36,8 @@
     "./shell/**/*.js",
     "./chat/**/*.js",
     "./editor/**/*.js",
-    "./runtime/**/*.js"
+    "./runtime/**/*.js",
+    "./theme/**/*.js"
   ],
   "peerDependencies": {
     "@adia-ai/web-components": "^0.4.0",

package/shell/admin-shell/css/admin-shell.main.css

@@ -122,6 +122,41 @@ admin-shell > main > :is(section, section-ui) {
 
 admin-shell > main > :is(section, section-ui)::-webkit-scrollbar { display: none; }
 
+/* ── Subnav rail layout ──
+   When the main section contains an `[data-subnav]` aside (the
+   left-rail nav pattern — `<aside data-subnav>` followed by the
+   `[data-content-root]` article), grid-layout the section so the
+   rail sits on the inline-start side and the content fills the
+   rest. Mirrors the docs-site convention (site.css `:has(#subnav-rail)`)
+   so consumer apps using admin-shell + the subnav-rail authoring
+   shape get the canonical layout for free. */
+admin-shell > main > :is(section, section-ui):has(> [data-subnav]:not([hidden])) {
+  display: grid;
+  grid-template-columns: var(--subnav-width, 14rem) 1fr;
+  grid-template-rows: minmax(0, 1fr);
+  gap: 0;
+}
+
+admin-shell > main > :is(section, section-ui) > [data-subnav] {
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  border-inline-end: 1px solid var(--a-border-subtle);
+  padding-block: var(--a-space-2);
+  padding-inline: var(--a-space-2);
+}
+
+/* Mobile: collapse to single column; subnav stacks above content. */
+@container (max-width: 40rem) {
+  admin-shell > main > :is(section, section-ui):has(> [data-subnav]:not([hidden])) {
+    grid-template-columns: 1fr;
+  }
+  admin-shell > main > :is(section, section-ui) > [data-subnav] {
+    border-inline-end: none;
+    border-block-end: 1px solid var(--a-border-subtle);
+  }
+}
+
 /* ── Main > footer (status bar) ──
    Legacy pattern: last-child auto-pushed to trailing edge via
    margin-inline-start: auto (works when authors use a simple

package/theme/index.js

@@ -0,0 +1 @@
+export { ThemePanel } from './theme-panel/theme-panel.js';

package/theme/theme-panel/theme-panel.a2ui.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ThemePanel.json",
+  "title": "ThemePanel",
+  "description": "Module-tier appearance-preferences control surface. Owns the three knobs\nof the AdiaUI theming contract: [data-theme=<slug>] named themes,\n--a-density / --a-radius-k parametric overrides, and color-scheme\nlight/dark switching, plus optional localStorage persistence behind a\nsmall attribute API.\n\nDrops into any consumer's <popover-ui slot=\"content\"> (the canonical\ncomposition) or directly into a sidebar section. Eight named themes\nship by default; section visibility flips on/off via boolean attributes\n([parametric], [presets], [scheme-toggle]).\n\nPromoted from the duplicated <div id=\"theme-panel\"> block in site/ and\nplaygrounds/admin-shell/ — see docs/specs/theme-panel-module.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "active-density": {
+      "description": "Reflected — mirrors the current --a-density value on the target\nelement. Stringified number.\n",
+      "type": "string",
+      "default": ""
+    },
+    "active-radius": {
+      "description": "Reflected — mirrors the current --a-radius-k value on the target\nelement. Stringified number.\n",
+      "type": "string",
+      "default": ""
+    },
+    "active-scheme": {
+      "description": "Reflected — the resolved color-scheme (auto collapsed to a\nconcrete value). Either \"light\" or \"dark\".\n",
+      "type": "string",
+      "default": ""
+    },
+    "active-theme": {
+      "description": "Reflected — the currently selected theme slug. Empty string when\nunset (default theme). Read-only externally; use .apply({theme})\nto change.\n",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "ThemePanel"
+    },
+    "parametric": {
+      "description": "Renders the density + radius slider block. Sliders bind to\n--a-density and --a-radius-k on the target element.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "persist": {
+      "description": "Persists selections to localStorage. Defaults to ephemeral so\nplaygrounds and embedded demos do not silently mutate a user's\ndocs-shell preferences.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "presets": {
+      "description": "Renders the compact / reset / spacious preset row. Each preset\napplies a (density, radius) pair; \"default\" also clears the\n[data-theme] attribute.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "scheme": {
+      "description": "Initial color-scheme. \"auto\" follows prefers-color-scheme via a\nmatchMedia listener; user clicks on the scheme toggle promote to\nan explicit light or dark choice.\n",
+      "type": "string",
+      "enum": [
+        "light",
+        "dark",
+        "auto"
+      ],
+      "default": "auto"
+    },
+    "scheme-toggle": {
+      "description": "Renders an integrated light/dark <segmented-ui> at the top of the\npanel. When absent, the panel omits scheme entirely — consumers\ncan still drive scheme via the .apply({scheme}) public method.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "storage-prefix": {
+      "description": "Namespace for localStorage keys when [persist] is set. Four keys\nare written: {prefix}theme, {prefix}scheme, {prefix}density,\n{prefix}radius.\n",
+      "type": "string",
+      "default": "adia-theme-"
+    },
+    "target": {
+      "description": "CSS selector for the element that receives [data-theme] and\n--a-density / --a-radius-k writes. Defaults to :root (the\n<html> element). Scoped targets are useful for preview-pane\ndemos.\n",
+      "type": "string",
+      "default": ":root"
+    },
+    "themes": {
+      "description": "Space-separated list of theme slugs to render as buttons. Author\nmay restrict ([themes=\"default ocean\"]) or extend. Tolerant —\nunknown slugs render a button; clicking applies [data-theme=slug]\nregardless of whether themes.css has a matching block.\n",
+      "type": "string",
+      "default": "default ocean forest sunset lavender rose slate midnight"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {
+      "theme-change": {
+        "description": "Bubbles when any user-visible state changes (theme click, slider\ninput, preset click, scheme flip, reset). One event per change.\nNo event on auto-rehydrate-from-storage at boot.\n",
+        "detail": {
+          "theme": "string",
+          "density": "number",
+          "radius": "number",
+          "scheme": "string",
+          "source": "string"
+        }
+      }
+    },
+    "examples": [],
+    "keywords": [
+      "theme",
+      "theme-panel",
+      "palette",
+      "density",
+      "radius",
+      "scheme",
+      "dark-mode",
+      "light-mode",
+      "color-scheme",
+      "preferences",
+      "settings",
+      "color",
+      "appearance",
+      "skin"
+    ],
+    "name": "ThemePanel",
+    "related": [
+      "Popover",
+      "Button",
+      "Slider",
+      "Field",
+      "Divider",
+      "Text",
+      "Segmented",
+      "AdminShell"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default — panel rendered, awaiting input.",
+        "name": "idle"
+      },
+      {
+        "description": "[persist] is set; selections write to localStorage under\n[storage-prefix].\n",
+        "attribute": "persist",
+        "name": "persisted"
+      },
+      {
+        "description": "[scheme=\"auto\"] and no user override this session; a\nprefers-color-scheme listener reapplies on system flip.\n",
+        "name": "scheme-auto"
+      }
+    ],
+    "synonyms": {
+      "theme": [
+        "palette",
+        "skin",
+        "appearance"
+      ],
+      "density": [
+        "compactness",
+        "spacing-scale"
+      ],
+      "radius": [
+        "corner-roundness",
+        "border-radius"
+      ],
+      "scheme": [
+        "mode",
+        "color-scheme",
+        "dark-mode"
+      ]
+    },
+    "tag": "theme-panel",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/theme/theme-panel/theme-panel.css

@@ -0,0 +1,50 @@
+/* ═══════════════════════════════════════════════════════════════
+   <theme-panel> — appearance-preferences control surface.
+   Replaces the inline style= attributes from the two consumers.
+   Two-block @scope pattern per component-token-contract.md.
+   Zero raw color values (repo hard rule); leans on global tokens.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── 1. Token declarations ── */
+
+theme-panel {
+  --theme-panel-gap:       var(--a-space-3);
+  --theme-panel-pad:       var(--a-space-3);
+  --theme-panel-min-width: 260px;
+  --theme-panel-row-gap:   var(--a-space-1);
+  --theme-panel-preset-gap: var(--a-space-2);
+}
+
+/* ── 2. Scoped layout ── */
+
+@scope (theme-panel) {
+  :scope {
+    display: flex;
+    flex-direction: column;
+    gap: var(--theme-panel-gap);
+    padding: var(--theme-panel-pad);
+    min-width: var(--theme-panel-min-width);
+  }
+
+  [part="scheme"] {
+    display: flex;
+  }
+
+  [part="scheme"] > segmented-ui {
+    flex: 1;
+  }
+
+  [part="themes"] {
+    display: flex;
+    gap: var(--theme-panel-row-gap);
+    flex-wrap: wrap;
+  }
+
+  [part="presets"] {
+    display: flex;
+    gap: var(--theme-panel-preset-gap);
+    flex-wrap: wrap;
+  }
+
+  /* field-ui already provides its own label + layout; nothing extra here */
+}

package/theme/theme-panel/theme-panel.examples.html

@@ -0,0 +1,104 @@
+<header>
+  <div>
+    <h1>Theme Panel</h1>
+    <div data-actions>
+      <tag-ui size="sm">theme-panel</tag-ui>
+    </div>
+  </div>
+  <p>Module-tier appearance-preferences control surface — eight named themes, parametric density &amp; radius sliders, three presets, optional light/dark scheme toggle, and opt-in <code>localStorage</code> persistence. Drop into any <code>&lt;popover-ui slot="content"&gt;</code> in your shell's topbar.</p>
+</header>
+
+<section data-section>
+  <h2 variant="section">Minimal — themes only</h2>
+  <p data-note>Default theme grid. No sliders, no presets, no scheme toggle. Suitable for embedded demos where only theme swapping is offered.</p>
+  <code-ui language="html">&lt;theme-panel&gt;&lt;/theme-panel&gt;</code-ui>
+  <theme-panel></theme-panel>
+</section>
+
+<section data-section>
+  <h2 variant="section">With parametric sliders</h2>
+  <p data-note>Adds the density + radius slider block. Selecting a theme also reads the theme's computed knob values back into the sliders.</p>
+  <code-ui language="html">&lt;theme-panel parametric&gt;&lt;/theme-panel&gt;</code-ui>
+  <theme-panel parametric></theme-panel>
+</section>
+
+<section data-section>
+  <h2 variant="section">Full panel — parametric + presets + scheme toggle</h2>
+  <p data-note>The docs-shell configuration. Theme + scheme + parametric + presets, all surfaces visible. <code>persist</code> is set so refreshing the page restores your selections.</p>
+  <code-ui language="html">&lt;theme-panel parametric presets scheme-toggle persist&gt;&lt;/theme-panel&gt;</code-ui>
+  <theme-panel parametric presets scheme-toggle persist></theme-panel>
+</section>
+
+<section data-section>
+  <h2 variant="section">Restricted theme list</h2>
+  <p data-note>The <code>[themes]</code> attribute is tolerant — any space-separated list of slugs renders as buttons. Pass a subset to limit choices, or extend with custom slugs (you supply the matching CSS).</p>
+  <code-ui language="html">&lt;theme-panel themes="default ocean midnight" parametric&gt;&lt;/theme-panel&gt;</code-ui>
+  <theme-panel themes="default ocean midnight" parametric></theme-panel>
+</section>
+
+<section data-section>
+  <h2 variant="section">Inside a popover (canonical composition)</h2>
+  <p data-note>The usual shape — a palette-icon button trigger pops the panel from a topbar. This is how <code>site/</code> and <code>playgrounds/admin-shell/</code> consume the module.</p>
+  <code-ui language="html">&lt;popover-ui placement="bottom-end"&gt;
+  &lt;button-ui icon="palette" variant="ghost" size="sm" slot="trigger"&gt;&lt;/button-ui&gt;
+  &lt;theme-panel slot="content" parametric presets scheme-toggle&gt;&lt;/theme-panel&gt;
+&lt;/popover-ui&gt;</code-ui>
+  <popover-ui placement="bottom-end">
+    <button-ui icon="palette" variant="ghost" size="sm" slot="trigger"></button-ui>
+    <theme-panel slot="content" parametric presets scheme-toggle></theme-panel>
+  </popover-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">Scoped target — preview pane</h2>
+  <p data-note>By default, the panel writes to <code>:root</code> (the <code>&lt;html&gt;</code> element). Pass <code>[target]</code> to scope theming to a region — useful for editor previews and component playgrounds.</p>
+  <code-ui language="html">&lt;theme-panel target="#preview-pane" parametric&gt;&lt;/theme-panel&gt;
+&lt;div id="preview-pane"&gt;…preview content…&lt;/div&gt;</code-ui>
+  <theme-panel target="#preview-pane" parametric></theme-panel>
+  <div id="preview-pane" style="margin-top:var(--a-space-3); padding:var(--a-space-4); border:1px solid var(--a-border); border-radius:calc(var(--a-radius-2) * var(--a-radius-k, 1));">
+    <strong>Preview pane</strong> — theming applied here only.
+  </div>
+</section>
+
+<section data-section>
+  <h2 variant="section">Attributes</h2>
+  <table>
+    <thead><tr><th>Attribute</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead>
+    <tbody>
+      <tr><td><code>themes</code></td><td>string</td><td>8 named slugs</td><td>Space-separated theme slug list.</td></tr>
+      <tr><td><code>parametric</code></td><td>boolean</td><td><code>false</code></td><td>Renders density + radius sliders.</td></tr>
+      <tr><td><code>presets</code></td><td>boolean</td><td><code>false</code></td><td>Renders compact / reset / spacious row.</td></tr>
+      <tr><td><code>scheme-toggle</code></td><td>boolean</td><td><code>false</code></td><td>Renders integrated light/dark switch.</td></tr>
+      <tr><td><code>persist</code></td><td>boolean</td><td><code>false</code></td><td>Writes selections to localStorage.</td></tr>
+      <tr><td><code>storage-prefix</code></td><td>string</td><td><code>adia-theme-</code></td><td>LS key namespace when persisting.</td></tr>
+      <tr><td><code>target</code></td><td>string (selector)</td><td><code>:root</code></td><td>Element to receive writes.</td></tr>
+      <tr><td><code>scheme</code></td><td>enum</td><td><code>auto</code></td><td><code>light</code> / <code>dark</code> / <code>auto</code>.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Reflected state</h2>
+  <p>Read-only externally; use <code>.apply()</code> to mutate. Style with <code>:has(theme-panel[active-scheme="dark"])</code>.</p>
+  <table>
+    <thead><tr><th>Attribute</th><th>Notes</th></tr></thead>
+    <tbody>
+      <tr><td><code>active-theme</code></td><td>Currently selected slug; empty for default.</td></tr>
+      <tr><td><code>active-scheme</code></td><td>Resolved scheme (auto collapsed to light or dark).</td></tr>
+      <tr><td><code>active-density</code></td><td>Current <code>--a-density</code> on target.</td></tr>
+      <tr><td><code>active-radius</code></td><td>Current <code>--a-radius-k</code> on target.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Events &amp; methods</h2>
+  <table>
+    <thead><tr><th>Surface</th><th>Shape</th><th>Notes</th></tr></thead>
+    <tbody>
+      <tr><td><code>theme-change</code> event</td><td><code>{ theme, scheme, density, radius, source }</code></td><td>Bubbles. <code>source</code> ∈ <code>theme | slider | preset | scheme | reset | programmatic</code>.</td></tr>
+      <tr><td><code>.apply(partial)</code></td><td><code>(p: { theme?, scheme?, density?, radius? }) =&gt; void</code></td><td>Programmatic write; emits <code>theme-change</code> with <code>source: 'programmatic'</code>.</td></tr>
+      <tr><td><code>.reset()</code></td><td><code>() =&gt; void</code></td><td>Clears all state; emits <code>theme-change</code> with <code>source: 'reset'</code>.</td></tr>
+    </tbody>
+  </table>
+</section>

package/theme/theme-panel/theme-panel.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Theme Panel — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../../web-components/styles/resets.css">
+  <link rel="stylesheet" href="../../../web-components/styles/tokens.css">
+  <link rel="stylesheet" href="../../../web-components/styles/themes.css">
+
+  <!-- Primitive CSS used inside the panel -->
+  <link rel="stylesheet" href="../../../web-components/components/button/button.css">
+  <link rel="stylesheet" href="../../../web-components/components/popover/popover.css">
+  <link rel="stylesheet" href="../../../web-components/components/slider/slider.css">
+  <link rel="stylesheet" href="../../../web-components/components/field/field.css">
+  <link rel="stylesheet" href="../../../web-components/components/divider/divider.css">
+  <link rel="stylesheet" href="../../../web-components/components/text/text.css">
+  <link rel="stylesheet" href="../../../web-components/components/segmented/segmented.css">
+  <link rel="stylesheet" href="../../../web-components/components/segment/segment.css">
+  <link rel="stylesheet" href="../../../web-components/components/icon/icon.css">
+  <link rel="stylesheet" href="../../../web-components/components/code/code.css">
+  <link rel="stylesheet" href="../../../web-components/components/tag/tag.css">
+
+  <!-- Module CSS -->
+  <link rel="stylesheet" href="./theme-panel.css">
+
+  <!-- Primitive JS -->
+  <script type="module" src="../../../web-components/components/button/button.js"></script>
+  <script type="module" src="../../../web-components/components/popover/popover.js"></script>
+  <script type="module" src="../../../web-components/components/slider/slider.js"></script>
+  <script type="module" src="../../../web-components/components/field/field.js"></script>
+  <script type="module" src="../../../web-components/components/divider/divider.js"></script>
+  <script type="module" src="../../../web-components/components/text/text.js"></script>
+  <script type="module" src="../../../web-components/components/segmented/segmented.js"></script>
+  <script type="module" src="../../../web-components/components/icon/icon.js"></script>
+  <script type="module" src="../../../web-components/components/code/code.js"></script>
+  <script type="module" src="../../../web-components/components/tag/tag.js"></script>
+
+  <!-- Module JS -->
+  <script type="module" src="./theme-panel.js"></script>
+
+  <style>
+    :where(html, body) {
+      margin: 0; min-height: 100vh;
+      background: var(--a-bg);
+      color: var(--a-fg);
+      font-family: var(--a-font);
+    }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./theme-panel.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load theme-panel.examples.html — ${err.message}</p>`;
+      console.error('[theme-panel.html]', err);
+    }
+  </script>
+
+</body>
+</html>