@adia-ai/web-modules 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -11,6 +11,36 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [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
+
+- **simple cluster — 4th bespoke shell family** per ADR-0023. Minimal shell for marketing / landing / error pages:
+  - `<simple-shell>` (host) — behavior-only orchestrator. 2 reflected attributes: `[centered]` (vertical center), `[full-bleed]` (drops max-width).
+  - `<simple-content>` (CSS-only) — article body container with token-correct vertical rhythm.
+  - `<simple-hero>` (CSS-only) — optional top strip with 3 named slots (`heading`, `lede`, `actions`).
+- Subpath export: `@adia-ai/web-modules/simple`.
+- 10 unit tests for `<simple-shell>`.
+
+### Changed
+
+- Catalog count: 118 → 121 yamls (+3 from simple cluster children).
+
 ## [0.4.0] - 2026-05-10
 
 **⚠️ BREAKING** — first non-patch release in the 0.x line. Closes the ADR-0023 arc per [ADR-0024](../../.brain/adrs/0024-legacy-shell-shapes-retired.md). All 6 in-repo consumers migrated in v0.3.6; this release retires the legacy authoring shapes from the shell hosts.

package/README.md

@@ -5,6 +5,10 @@ Composite custom elements built from
 into clusters by use case; each cluster ships as a subpath export so
 consumers install only what they need.
 
+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)).
+
 > The patterns directory lived inside `@adia-ai/web-components` as
 > `patterns/` until this package was extracted (see
 > [ADR-0012](../../.brain/adrs/0012-three-tier-architecture-modules.md)).
@@ -13,16 +17,17 @@ consumers install only what they need.
 
 ## Clusters
 
-| Cluster | Elements | What's inside |
-|---|---|---|
-| `shell` | `<admin-shell>` (nav primitives live in `web-components`: `<nav-ui>`, `<nav-group-ui>`, `<nav-item-ui>`) | Admin-shell composition: header, sidebars, command palette. |
-| `chat` | `<chat-shell>` | Conversational surface — messages, streaming, markdown, action bar. |
-| `editor` | `<editor-shell>` | A2UI live-editor surface — JSON ↔ rendered preview. |
-| `runtime` | `<gen-root>`, `<a2ui-root>` | Render roots that turn JSON or gen-UI intents into live DOM. |
+| Cluster | Host | Bespoke children | What's inside |
+|---|---|---|---|
+| `shell` | `<admin-shell>` | `<admin-sidebar>`, `<admin-command>` (JS-bearing); `<admin-content>`, `<admin-topbar>`, `<admin-statusbar>`, `<admin-scroll>`, `<admin-page>`, `<admin-page-header>`, `<admin-page-body>` (CSS-only); 9 children total | Admin-shell composition: sidebars, command palette, page chrome. Resize/collapse/persistence on `<admin-sidebar>`; Cmd+K palette on `<admin-command>`. |
+| `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. |
 
 Future clusters on the strategic horizon: `data` (kanban, filters,
-table-toolbar), `agent` (agent-trace, reasoning panels), `admin`
-(RBAC matrix, approvals).
+table-toolbar), `agent` (agent-trace, reasoning panels).
+
+See [`bespoke-shell-children` skill](../../.agents/skills/bespoke-shell-children/SKILL.md) for the canonical decomposition recipe used by all three families.
 
 ## Quick start
 
@@ -35,17 +40,26 @@ table-toolbar), `agent` (agent-trace, reasoning panels), `admin`
 
 <script type="module">
   import '@adia-ai/web-components';        // primitives + nav family
-  import '@adia-ai/web-modules/shell';     // admin-shell
-  import '@adia-ai/web-modules/chat';      // adia-chat
-  import '@adia-ai/web-modules/runtime';   // gen-ui, a2ui-root
+  import '@adia-ai/web-modules/shell';     // admin-shell + bespoke 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
 </script>
 
+<!-- Bespoke shape (canonical since v0.4.0): -->
 <admin-shell mode="rounded">
-  <aside-ui slot="leading">
-    <header-ui>…</header-ui>
-    <section-ui><nav-ui>…</nav-ui></section-ui>
-  </aside-ui>
+  <admin-sidebar slot="leading" resizable collapsible>
+    <header-ui>
+      <span slot="heading">App</span>
+    </header-ui>
+    <section-ui>
+      <nav-ui>…</nav-ui>
+    </section-ui>
+  </admin-sidebar>
   <main>…</main>
+  <admin-command>
+    <command-ui placeholder="Search..."></command-ui>
+  </admin-command>
 </admin-shell>
 ```
 

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

@@ -11,4 +11,6 @@
 export * from './shell/index.js';
 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,7 +1,7 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.4.0",
-  "description": "AdiaUI composite custom elements \u2014 shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
+  "version": "0.4.2",
+  "description": "AdiaUI composite custom elements — shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {
     ".": "./index.js",
@@ -11,15 +11,21 @@
     "./chat/*": "./chat/*/*.js",
     "./editor": "./editor/index.js",
     "./editor/*": "./editor/*/*.js",
+    "./simple": "./simple/index.js",
+    "./simple/*": "./simple/*/*.js",
     "./runtime": "./runtime/index.js",
     "./runtime/*": "./runtime/*/*.js",
+    "./theme": "./theme/index.js",
+    "./theme/*": "./theme/*/*.js",
     "./package.json": "./package.json"
   },
   "files": [
     "shell/",
     "chat/",
     "editor/",
+    "simple/",
     "runtime/",
+    "theme/",
     "index.js",
     "README.md",
     "CHANGELOG.md"
@@ -30,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/simple/index.js

@@ -0,0 +1,2 @@
+export { SimpleShell } from './simple-shell/simple-shell.js';
+// simple-content and simple-hero are CSS-only — no JS export needed.

package/simple/simple-content/simple-content.a2ui.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/SimpleContent.json",
+  "title": "SimpleContent",
+  "description": "Module-tier article-body container. CSS-only — no JS, no state.\nSits inside <simple-shell> as the main content surface with\ntoken-correct vertical rhythm and prose-friendly max-width.\n\nCompanion to <simple-hero> (optional top strip) per ADR-0023\nbespoke shell-tier children.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "SimpleContent"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "shells",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "simple-content",
+      "article",
+      "body",
+      "prose",
+      "main-content",
+      "landing-body",
+      "marketing-body"
+    ],
+    "name": "SimpleContent",
+    "related": [
+      "SimpleShell",
+      "SimpleHero"
+    ],
+    "slots": {
+      "default": {
+        "description": "Article body content — prose, code blocks, illustrations. Authors compose freely; <simple-content> provides only the container with sensible defaults (vertical rhythm, max-width, typography token application)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, visible.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "simple-content": [
+        "page-content",
+        "article-body",
+        "prose-container",
+        "main-body"
+      ]
+    },
+    "tag": "simple-content",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/simple/simple-content/simple-content.css

@@ -0,0 +1,29 @@
+/* ═══════════════════════════════════════════════════════════════
+   simple-content — Article body container
+
+   CSS-only structural child of <simple-shell>. Provides token-correct
+   vertical rhythm + prose-friendly max-width for article body content.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (simple-content) {
+  :scope {
+    display: flex;
+    flex-direction: column;
+    gap: var(--a-density-4, 1.5rem);
+    width: 100%;
+    color: var(--a-text);
+  }
+
+  /* Typographic rhythm for prose children */
+  :scope > h1,
+  :scope > h2,
+  :scope > h3 {
+    margin: 0;
+    color: var(--a-text-heading, var(--a-text));
+  }
+
+  :scope > p {
+    margin: 0;
+    line-height: var(--a-line-height-prose, 1.6);
+  }
+}

package/simple/simple-content/simple-content.examples.html

@@ -0,0 +1,13 @@
+<h1>simple-content — article body container</h1>
+
+<p>CSS-only structural child of <code>&lt;simple-shell&gt;</code>. Provides vertical rhythm and prose-friendly max-width.</p>
+
+<simple-shell style="border: 1px solid var(--a-border); border-radius: var(--a-radius-3); min-height: 50dvh;">
+  <simple-content>
+    <h1>Article body</h1>
+    <p>simple-content is the main article surface. It applies token-correct vertical rhythm (the gap between children uses <code>--a-density-4</code>) and uses prose typography for paragraphs and headings.</p>
+    <h2>Section heading</h2>
+    <p>Headings cascade naturally. h1 / h2 / h3 receive heading colors via <code>--a-text-heading</code>.</p>
+    <p>Body paragraphs use a prose line-height (<code>--a-line-height-prose</code>) for comfortable reading.</p>
+  </simple-content>
+</simple-shell>

package/simple/simple-content/simple-content.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Simple Content — AdiaUI</title>
+
+  <link rel="stylesheet" href="../../../web-components/styles/resets.css">
+  <link rel="stylesheet" href="../../../web-components/styles/tokens.css">
+  <link rel="stylesheet" href="../simple-shell/simple-shell.css">
+  <link rel="stylesheet" href="../simple-content/simple-content.css">
+  <link rel="stylesheet" href="../simple-hero/simple-hero.css">
+  <link rel="stylesheet" href="../../../web-components/components/button/button.css">
+
+  <script type="module" src="../simple-shell/simple-shell.js"></script>
+  <script type="module" src="../../../web-components/components/button/button.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('./simple-content.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 simple-content.examples.html — ${err.message}</p>`;
+      console.error('[simple-content.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/simple/simple-content/simple-content.yaml

@@ -0,0 +1,54 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: SimpleContent
+tag: simple-content
+component: SimpleContent
+category: shells
+version: 1
+description: |
+  Module-tier article-body container. CSS-only — no JS, no state.
+  Sits inside <simple-shell> as the main content surface with
+  token-correct vertical rhythm and prose-friendly max-width.
+
+  Companion to <simple-hero> (optional top strip) per ADR-0023
+  bespoke shell-tier children.
+
+props: {}
+
+events: {}
+
+slots:
+  default:
+    description: >-
+      Article body content — prose, code blocks, illustrations.
+      Authors compose freely; <simple-content> provides only the
+      container with sensible defaults (vertical rhythm, max-width,
+      typography token application).
+
+states:
+  - name: idle
+    description: Default, visible.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      simple-content is the article surface inside simple-shell. Use
+      for primary page body. Sibling to <simple-hero> (optional).
+
+keywords:
+  - simple-content
+  - article
+  - body
+  - prose
+  - main-content
+  - landing-body
+  - marketing-body
+
+synonyms:
+  simple-content: [page-content, article-body, prose-container, main-body]
+
+related:
+  - SimpleShell
+  - SimpleHero

package/simple/simple-hero/simple-hero.a2ui.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/SimpleHero.json",
+  "title": "SimpleHero",
+  "description": "Module-tier hero strip for the top of marketing / landing / error\npages. CSS-only — no JS, no state. Three named slots (heading, lede,\nactions) carry the canonical hero composition.\n\nSits inside <simple-shell> above <simple-content>. Companion to\n<simple-content> per ADR-0023 bespoke shell-tier children.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "SimpleHero"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "shells",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "simple-hero",
+      "hero",
+      "splash",
+      "landing-hero",
+      "marketing-hero",
+      "intro",
+      "page-title"
+    ],
+    "name": "SimpleHero",
+    "related": [
+      "SimpleShell",
+      "SimpleContent"
+    ],
+    "slots": {
+      "default": {
+        "description": "Optional inline content if the named slots are insufficient."
+      },
+      "actions": {
+        "description": "Action row (button-ui, link-ui) for primary CTAs."
+      },
+      "heading": {
+        "description": "Large display heading (h1) — the page title."
+      },
+      "lede": {
+        "description": "Lead paragraph below heading — short summary or CTA tagline."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, visible.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "simple-hero": [
+        "page-hero",
+        "splash-hero",
+        "landing-hero",
+        "intro-strip"
+      ]
+    },
+    "tag": "simple-hero",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/simple/simple-hero/simple-hero.css

@@ -0,0 +1,45 @@
+/* ═══════════════════════════════════════════════════════════════
+   simple-hero — Optional top strip for landing / error / splash pages
+
+   CSS-only. Three named slots (heading, lede, actions) compose the
+   canonical hero layout. Authors can omit any slot.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (simple-hero) {
+  :scope {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    text-align: center;
+    gap: var(--a-density-3, 1rem);
+    width: 100%;
+    padding-block: var(--a-density-6, 3rem);
+  }
+
+  /* Heading slot — large display size */
+  :scope [slot="heading"] {
+    margin: 0;
+    font-size: var(--a-font-size-display, 2.5rem);
+    line-height: var(--a-line-height-tight, 1.2);
+    color: var(--a-text-heading, var(--a-text));
+    font-weight: var(--a-font-weight-bold, 600);
+  }
+
+  /* Lede slot — muted, larger than body */
+  :scope [slot="lede"] {
+    margin: 0;
+    font-size: var(--a-font-size-lede, 1.25rem);
+    line-height: var(--a-line-height-prose, 1.5);
+    color: var(--a-text-muted);
+    max-width: 42rem;
+  }
+
+  /* Actions slot — flex row */
+  :scope [slot="actions"] {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--a-density-2, 0.75rem);
+    justify-content: center;
+    margin-top: var(--a-density-2, 0.75rem);
+  }
+}

package/simple/simple-hero/simple-hero.examples.html

@@ -0,0 +1,33 @@
+<h1>simple-hero — hero strip for landing / error / splash pages</h1>
+
+<p>CSS-only. Three named slots: heading, lede, actions. Authors can omit any slot.</p>
+
+<h2>All three slots</h2>
+
+<simple-shell style="border: 1px solid var(--a-border); border-radius: var(--a-radius-3); min-height: 50dvh;">
+  <simple-hero>
+    <h1 slot="heading">Build with AdiaUI</h1>
+    <p slot="lede">Zero dependencies. Production-ready primitives. LLM-native generative UI.</p>
+    <div slot="actions">
+      <button-ui variant="solid" color="accent">Get started</button-ui>
+      <button-ui variant="outline">Read the docs</button-ui>
+    </div>
+  </simple-hero>
+</simple-shell>
+
+<h2>Heading + lede only</h2>
+
+<simple-shell style="border: 1px solid var(--a-border); border-radius: var(--a-radius-3); min-height: 40dvh;">
+  <simple-hero>
+    <h1 slot="heading">Thank you</h1>
+    <p slot="lede">Your message has been received. We'll get back to you within 24 hours.</p>
+  </simple-hero>
+</simple-shell>
+
+<h2>Heading only — minimal error page</h2>
+
+<simple-shell centered style="border: 1px solid var(--a-border); border-radius: var(--a-radius-3); min-height: 30dvh;">
+  <simple-hero>
+    <h1 slot="heading">Maintenance in progress</h1>
+  </simple-hero>
+</simple-shell>