@adia-ai/web-modules 0.6.21 → 0.6.23

package/editor/editor-shell/editor-shell.yaml

@@ -5,55 +5,102 @@ component: EditorShell
 category: container
 version: 1
 description: |
-  Behavior-only editor shell module for design-tool layouts. Author
-  provides the structural DOM — header (topbar), [data-editor-body] with
-  pane-ui children ([data-left], [data-right]), [data-canvas] for the
-  central surface, and a footer (statusbar). editor-shell wires
-  select-ui[data-options] for JSON-parsed option lists.
+  Behavior-only editor shell for design-tool / code-editor / canvas
+  layouts. Canonical authoring shape uses cluster-namespaced bespoke
+  children — <editor-toolbar> at the top, <editor-sidebar
+  slot="leading|trailing"> rails wrapping <pane-ui resizable>,
+  <editor-canvas> as the central work surface (optionally containing
+  <editor-canvas-toolbar> + <editor-canvas-empty>), and
+  <editor-statusbar> at the bottom. The shell coordinates the family,
+  propagates [focus-mode] to children's [full-screen] / [focused],
+  and lets each child own its own state-as-attribute semantics per
+  ADR-0023.
 
-props: {}   # Pure wrapper — no own props.
+  Legacy data-attribute shapes (<header>, <div data-editor-body>,
+  <pane-ui data-left|data-right>, <div data-canvas>, <footer>,
+  <span data-spacer>) were RETIRED in v0.4.0 per ADR-0024 and are no
+  longer recognized. Consumers must use the bespoke vocabulary.
 
-events: {}   # Child interactions bubble through.
+props:
+  focusMode:
+    description: |
+      Reflected — when set, the shell enters distraction-free mode and
+      propagates a matching [full-screen] / [focused] state to its
+      bespoke children (editor-toolbar gains [full-screen], editor-canvas
+      gains [focused]). Typically toggled by a [data-toolbar-action]
+      button inside <editor-toolbar>.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: focus-mode
+
+events: {}   # Child interactions bubble through their own events.
 
 slots:
   default:
     description: >-
-      Author provides header, [data-editor-body] wrapping pane-ui[data-left],
-      [data-canvas], pane-ui[data-right], and an optional footer.
-  icon:
-    description: >-
-      Leading glyph inside <header> or <footer> — status dot, app icon,
-      zoom badge, etc. Muted color, size-aware.
-  heading:
-    description: >-
-      Primary label inside <header> or <footer>. Rendered with
-      --editor-title-weight + the strong foreground token.
-  description:
-    description: >-
-      Secondary metadata inside <header> or <footer> — document name,
-      artboard size, zoom level, etc. Muted color, --a-ui-sm size.
-  action:
-    description: >-
-      Trailing control cluster inside <header> or <footer>. The first
-      [slot="action"] child pushes itself (and siblings) to the end of
-      the bar; subsequent [slot="action"] siblings flow with gap.
-  action-leading:
-    description: >-
-      Leading (inline-start) control cluster inside <header> or <footer>.
-      Pairs with [slot="action"] to produce a dual-cluster bar with
-      space-between alignment (e.g. Back ↔ Cancel/Next, Discard ↔
-      Publish). Replaces the legacy <span data-spacer> hack.
+      Bespoke children compose here in document order — <editor-toolbar>,
+      <editor-sidebar slot="leading">, <editor-canvas>,
+      <editor-sidebar slot="trailing">, <editor-statusbar>. The shell's
+      grid layout reads child tag selectors to place them; no slot=
+      attribute is needed on the children themselves except for the
+      leading / trailing sidebar discriminator.
 
 states:
   - name: idle
-    description: Default.
+    description: Default editing mode.
+  - name: focus-mode
+    attribute: focus-mode
+    description: Distraction-free mode active; chrome children dim or hide per their own [full-screen] / [focused] rules.
 
 traits: []
 
 a2ui:
   rules:
-    - editor-shell is a layout skeleton. Children must follow the documented
-      structural DOM; the element wires behavior, not content.
+    - >-
+      editor-shell takes bespoke editor-* children only. The canonical
+      composition is <editor-toolbar> + <editor-sidebar slot="leading">
+      + <editor-canvas> + <editor-sidebar slot="trailing"> +
+      <editor-statusbar>. Each child is optional except the canvas.
+    - >-
+      Don't nest col-ui / row-ui or generic layout primitives directly
+      inside editor-shell — the shell's CSS reads child tag selectors
+      to lay them out. Generic layout goes inside the bespoke children.
+    - >-
+      <editor-sidebar> WRAPS <pane-ui resizable> rather than implementing
+      drag itself (delegation pattern). Inside each sidebar place a
+      single <pane-ui resizable size="sm"> filled with <header> +
+      <section> slots.
+    - >-
+      For editor-inside-admin nested-shell pages, place the editor-shell
+      inside <admin-page-body> with `flex: 1; min-height: 0` on every
+      ancestor in the flex chain. Without min-height: 0 the inner shell
+      collapses to zero height.
+    - >-
+      Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024.
+      Do not author <div data-editor-body>, <pane-ui data-left|data-right>,
+      <div data-canvas>, <span data-spacer>, or bare <header>/<footer>
+      chrome inside editor-shell.
+
+keywords:
+  - editor-shell
+  - editor
+  - design-tool
+  - code-editor
+  - canvas-shell
+  - workspace-shell
+  - editing-surface
+
+synonyms:
+  editor-shell: [design-tool-shell, code-editor-shell, workspace-shell, canvas-shell]
 
-keywords: [editor-shell, editor, design-tool, canvas-shell]
-related: [Pane, Select, Toolbar]
+related:
+  - EditorToolbar
+  - EditorCanvas
+  - EditorCanvasToolbar
+  - EditorCanvasEmpty
+  - EditorSidebar
+  - EditorStatusbar
+  - Pane
+  - AdminShell
+  - ChatShell

package/editor/editor-sidebar/editor-sidebar.yaml

@@ -84,6 +84,10 @@ a2ui:
       The cluster-distinct localStorage prefix (adia-editor-sidebar-*)
       keeps editor sidebars from colliding with admin (adia-sidebar-*)
       and chat (adia-chat-sidebar-*) sidebars on the same domain.
+    - rule: 'Wraps a SINGLE <pane-ui resizable> as its only structural child; fill the pane with sub-views (nav, inspector, layers panel, etc.).'
+      reason: 'Single-pane composition contract.'
+    - rule: 'For multiple panes (e.g. left nav + right inspector), use two <editor-sidebar> instances at slot="leading" and slot="trailing" of <editor-shell>.'
+      reason: 'Per-sidebar pane discipline.'
 
 keywords:
   - editor-sidebar

package/editor/editor-statusbar/editor-statusbar.yaml

@@ -41,6 +41,10 @@ a2ui:
       editor-statusbar replaces legacy <footer> chrome bar inside
       <editor-shell>. Use named slots for canonical clusters; ad-hoc
       content goes in the default slot.
+    - rule: 'Slots: [slot="status"] for save/sync state, [slot="cursor"] for cursor position, [slot="zoom"] for zoom level, [slot="action"] for actions. All optional.'
+      reason: 'Slot contract — editor-specific status clusters.'
+    - rule: 'Different from <admin-statusbar> (which is for admin-shell); editor-statusbar has editor-specific slot vocabulary (cursor, zoom).'
+      reason: 'Per-cluster status-bar variant.'
 
 keywords:
   - editor-statusbar

package/editor/editor-toolbar/editor-toolbar.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/EditorToolbar.json",
   "title": "EditorToolbar",
-  "description": "Module-tier editor toolbar — replaces legacy <header> chrome bar\ninside <editor-shell> per ADR-0023. Owns the [full-screen] reflected\nattribute (set when host enters focus mode), click-bubble for\n[data-toolbar-action] buttons, and slot vocabulary routing.\n\nSits at the top of <editor-shell>. Authors compose actions + status\nvia slot vocabulary. The host (<editor-shell>) reads either\n<editor-toolbar> or <header> via :is() selector for backwards compat.\n",
+  "description": "Module-tier editor toolbar — replaces legacy <header> chrome bar\ninside <editor-shell> per ADR-0023. Owns the [full-screen] reflected\nattribute (set when host enters focus mode), click-bubble for\n[data-toolbar-action] buttons, and slot vocabulary routing.\n\nSits at the top of <editor-shell>. Authors compose actions + status\nvia slot vocabulary. Replaces the legacy <header> chrome bar per\nADR-0023; the legacy shape was retired in v0.4.0 per ADR-0024 and\nis no longer recognized.\n",
   "type": "object",
   "allOf": [
     {

package/editor/editor-toolbar/editor-toolbar.d.ts

@@ -5,8 +5,9 @@ attribute (set when host enters focus mode), click-bubble for
 [data-toolbar-action] buttons, and slot vocabulary routing.
 
 Sits at the top of <editor-shell>. Authors compose actions + status
-via slot vocabulary. The host (<editor-shell>) reads either
-<editor-toolbar> or <header> via :is() selector for backwards compat.
+via slot vocabulary. Replaces the legacy <header> chrome bar per
+ADR-0023; the legacy shape was retired in v0.4.0 per ADR-0024 and
+is no longer recognized.
 
  *
  * @see https://ui-kit.exe.xyz/site/components/editor-toolbar

package/editor/editor-toolbar/editor-toolbar.yaml

@@ -12,8 +12,9 @@ description: |
   [data-toolbar-action] buttons, and slot vocabulary routing.
 
   Sits at the top of <editor-shell>. Authors compose actions + status
-  via slot vocabulary. The host (<editor-shell>) reads either
-  <editor-toolbar> or <header> via :is() selector for backwards compat.
+  via slot vocabulary. Replaces the legacy <header> chrome bar per
+  ADR-0023; the legacy shape was retired in v0.4.0 per ADR-0024 and
+  is no longer recognized.
 
 props:
   fullScreen:
@@ -63,6 +64,10 @@ a2ui:
       Buttons that should trigger named actions get
       [data-toolbar-action="<name>"]. The toolbar bubbles a single
       'toolbar-action' event up to the host with the name in detail.
+    - rule: 'Different from <admin-topbar> (admin-shell chrome) — editor-toolbar has [full-screen] state + editor-specific [data-toolbar-action] event bubbling.'
+      reason: 'Per-cluster toolbar variant.'
+    - rule: 'Place full-screen toggle buttons inside the toolbar with [data-toolbar-action="toggle-full-screen"]; host reflects [full-screen] up to <editor-shell>.'
+      reason: 'Full-screen mode contract.'
 
 keywords:
   - editor-toolbar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "description": "AdiaUI composite custom elements \u2014 shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {

package/runtime/a2ui-root/a2ui-root.a2ui.json

@@ -117,7 +117,13 @@
         "name": "active"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "a2ui-root": [
+        "a2ui-canvas-host",
+        "a2ui-mount",
+        "doc-root"
+      ]
+    },
     "tag": "a2ui-root",
     "tokens": {},
     "traits": [],

package/runtime/a2ui-root/a2ui-root.yaml

@@ -70,7 +70,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Mount point for an A2UI-rendered composition. Hosts the runtime-emitted DOM tree.'
+      reason: 'A2UI runtime contract.'
+    - rule: 'Different from <gen-root> (which is for the generative-UI lane with LLM-driven streaming).'
+      reason: 'Lane boundary — A2UI is deterministic, gen is generative.'
+    - rule: 'Do not place static children inside; runtime owns the contents.'
+      reason: 'Reserved DOM region.'
 anti_patterns: []
 keywords:
   - a2ui
@@ -85,3 +91,6 @@ keywords:
 related:
   - canvas
   - inspector
+
+synonyms:
+  a2ui-root: [a2ui-canvas-host, a2ui-mount, doc-root]

package/runtime/gen-root/gen-root.a2ui.json

@@ -68,7 +68,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "gen-root": [
+        "gen-ui-root",
+        "gen-ui-mount",
+        "generative-root"
+      ]
+    },
     "tag": "gen-root",
     "tokens": {},
     "traits": [],

package/runtime/gen-root/gen-root.yaml

@@ -44,6 +44,13 @@ traits: []
 a2ui:
   rules:
     - gen-root is an integration shell. Prefer admin-shell for admin UIs; use gen-root only for chat+canvas tooling.
+    - rule: 'Hosts <chat-thread-ui>, <canvas-ui>, and <inspector-ui> children via named slots — chat slot for the conversation lane, canvas slot for the artifact lane, inspector slot for the dev-tools lane.'
+      reason: 'Composition contract — three-pane integration shell.'
+    - rule: 'Mode attribute (chat-only|split|canvas-only) controls layout; transitions are CSS-animated.'
+      reason: 'Layout-mode knob.'
 
 keywords: [gen-ui, generative-ui, chat-canvas, agent-shell]
 related: [AppShell, Chat]
+
+synonyms:
+  gen-root: [gen-ui-root, gen-ui-mount, generative-root]

package/shell/admin-command/admin-command.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminCommand.json",
   "title": "AdminCommand",
-  "description": "Module-tier command palette wrapper — wraps a native <dialog> and the\ninner <command-ui>. Owns the keyboard shortcut listener, focus\nmanagement, and dismiss handlers. Reflects [open].\n\nSits inside <admin-shell> as a direct child. The host wires\n[data-command-trigger] elements to <admin-command>.show() via lookup.\n\nThis is the bespoke web-component replacement for the legacy\n<dialog data-command> shape. <admin-shell> still recognizes the\nlegacy shape via :is() selector. New code should prefer <admin-command>.\n",
+  "description": "Module-tier command palette wrapper — wraps a native <dialog> and the\ninner <command-ui>. Owns the keyboard shortcut listener, focus\nmanagement, and dismiss handlers. Reflects [open].\n\nSits inside <admin-shell> as a direct child. The host wires\n[data-command-trigger] elements to <admin-command>.show() via lookup.\n\nThis is the bespoke web-component replacement for the legacy\n<dialog data-command> shape per ADR-0023. The legacy shape was\nretired in v0.4.0 per ADR-0024 and is no longer recognized.\n",
   "type": "object",
   "allOf": [
     {

package/shell/admin-command/admin-command.d.ts

@@ -7,8 +7,8 @@ Sits inside <admin-shell> as a direct child. The host wires
 [data-command-trigger] elements to <admin-command>.show() via lookup.
 
 This is the bespoke web-component replacement for the legacy
-<dialog data-command> shape. <admin-shell> still recognizes the
-legacy shape via :is() selector. New code should prefer <admin-command>.
+<dialog data-command> shape per ADR-0023. The legacy shape was
+retired in v0.4.0 per ADR-0024 and is no longer recognized.
 
  *
  * @see https://ui-kit.exe.xyz/site/components/admin-command

package/shell/admin-command/admin-command.yaml

@@ -14,8 +14,8 @@ description: |
   [data-command-trigger] elements to <admin-command>.show() via lookup.
 
   This is the bespoke web-component replacement for the legacy
-  <dialog data-command> shape. <admin-shell> still recognizes the
-  legacy shape via :is() selector. New code should prefer <admin-command>.
+  <dialog data-command> shape per ADR-0023. The legacy shape was
+  retired in v0.4.0 per ADR-0024 and is no longer recognized.
 
 props:
   open:
@@ -83,6 +83,10 @@ a2ui:
       Place admin-command as a direct child of admin-shell, NOT inside
       a sidebar or main column. The host coordinates triggers
       ([data-command-trigger]) by reaching across siblings.
+    - rule: 'For inline content-region command surfaces use <command-ui> directly; admin-command is the modal wrapper that opens the palette as an overlay.'
+      reason: 'Modal vs inline decision rule.'
+    - rule: 'Triggers anywhere in the shell via [data-command-trigger] attribute on any element; the host wires the open/close cycle.'
+      reason: 'Triggering convention — no manual event wiring.'
 
 keywords:
   - admin-command

package/shell/admin-content/admin-content.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminContent.json",
   "title": "AdminContent",
-  "description": "Module-tier shell main-column container. CSS-only — no behavior, no\nJS. Sits inside <admin-shell> as the center column between leading\nand trailing sidebars. Authors compose chrome bars + scroll surface\nvia slot vocabulary.\n\nThis is the bespoke replacement for the legacy raw <main> element\ninside admin-shell. Both shapes still render correctly per ADR-0023\nPhase 1 backwards-compat; new code should prefer <admin-content>.\n",
+  "description": "Module-tier shell main-column container. CSS-only — no behavior, no\nJS. Sits inside <admin-shell> as the center column between leading\nand trailing sidebars. Authors compose chrome bars + scroll surface\nvia slot vocabulary.\n\nThis is the bespoke replacement for the legacy raw <main> element\ninside admin-shell per ADR-0023. The legacy shape was retired in\nv0.4.0 per ADR-0024 and is no longer recognized.\n",
   "type": "object",
   "allOf": [
     {

package/shell/admin-content/admin-content.yaml

@@ -12,8 +12,8 @@ description: |
   via slot vocabulary.
 
   This is the bespoke replacement for the legacy raw <main> element
-  inside admin-shell. Both shapes still render correctly per ADR-0023
-  Phase 1 backwards-compat; new code should prefer <admin-content>.
+  inside admin-shell per ADR-0023. The legacy shape was retired in
+  v0.4.0 per ADR-0024 and is no longer recognized.
 
 props: {}
 
@@ -44,6 +44,10 @@ a2ui:
       admin-content is the bespoke replacement for raw <main> inside
       admin-shell. CSS-only; the shell's css/main.css selectors target
       both shapes via :is(main, admin-content).
+    - rule: 'Place as a direct child of <admin-shell>, not inside a sidebar or topbar; admin-content owns the center column.'
+      reason: 'Shell hierarchy constraint.'
+    - rule: 'Hosts <admin-page> children OR raw page content via the default slot; for chrome bars use <admin-topbar slot="header">.'
+      reason: 'Composition contract — page surface.'
 
 keywords:
   - admin-content

package/shell/admin-entity-item/admin-entity-item.yaml

@@ -63,6 +63,10 @@ a2ui:
     - >-
       For an INTERACTIVE workspace switcher use <select-ui variant="ghost">
       instead — admin-entity-item is read-only identity display.
+    - rule: 'Slot whole into [slot="heading"] of <admin-topbar>/<admin-statusbar>; do not nest inside other admin-entity-items.'
+      reason: 'Single-cell identity row; no recursion.'
+    - rule: 'Flat hierarchy: icon + label + badge in three slots, no extra wrapping. For full-width metadata strips compose multiple inside <row-ui> instead.'
+      reason: 'Cardinality + composition discipline.'
 
 keywords:
   - admin-entity-item

package/shell/admin-page/admin-page.yaml

@@ -44,6 +44,10 @@ a2ui:
       admin-page is the bespoke replacement for <article data-content-root>.
       Provides the page-content named container query so descendants
       can use @container page-content (max-width: 720px) etc.
+    - rule: 'Hosts a single page surface via [slot="body"] (typically <admin-page-body>) with optional [slot="header"] (<admin-page-header>) and [slot="footer"].'
+      reason: 'Slot contract — header/body/footer triad.'
+    - rule: 'Sits inside <admin-content>''s default slot; do not place outside admin-shell.'
+      reason: 'Shell hierarchy.'
 
 keywords:
   - admin-page

package/shell/admin-page-body/admin-page-body.yaml

@@ -34,6 +34,10 @@ a2ui:
       admin-page-body is the centered body band of <admin-page>.
       Wraps an inner <section-ui> for centered reading-column
       rhythm; can host full-bleed content directly to opt out.
+    - rule: 'Wraps an inner <section-ui> by default for centered reading-column rhythm; for full-bleed content (tables, canvas grids) use [data-full-bleed] on the section.'
+      reason: 'Reading-column vs full-bleed knob.'
+    - rule: 'Always inside <admin-page slot="body">; do not place admin-page-body outside admin-page.'
+      reason: 'Composition constraint.'
 
 keywords:
   - admin-page-body

package/shell/admin-page-header/admin-page-header.yaml

@@ -32,6 +32,10 @@ a2ui:
     - >-
       admin-page-header is the sticky top band of <admin-page>.
       Wraps an inner <header-ui> for centered reading-column rhythm.
+    - rule: 'Wraps an inner <header-ui> for centered reading-column rhythm; admin-page-header owns sticky positioning + border, header-ui owns the content layout.'
+      reason: 'Sticky chrome vs content layout separation.'
+    - rule: 'Always inside <admin-page slot="header">; for shell-tier chrome use <admin-topbar> instead.'
+      reason: 'Page-tier vs shell-tier distinction.'
 
 keywords:
   - admin-page-header

package/shell/admin-scroll/admin-scroll.yaml

@@ -36,6 +36,10 @@ a2ui:
       admin-scroll is the bespoke replacement for the legacy <section>
       child of <main> inside admin-shell. Single child convention —
       typically wraps an <admin-page> for sticky-band layout.
+    - rule: 'Wraps a single <admin-page> child typically; do not place multiple admin-pages side-by-side as siblings here.'
+      reason: 'Single-axis vertical scroll only.'
+    - rule: 'For horizontal scrolling regions (data grids, canvas surfaces) use overflow on the inner content instead — admin-scroll is vertical-only.'
+      reason: 'Scroll-axis discipline.'
 
 keywords:
   - admin-scroll

package/shell/admin-shell/admin-shell.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AppShell.json",
   "title": "AppShell",
-  "description": "Behavior-only application shell. Wires sidebar toggles, resize handles,\na Cmd+K command palette, and a ResizeObserver that drives responsive\nsidebar collapse. Author supplies the DOM (aside[data-sidebar], main,\ndialog[data-command]); admin-shell binds the interactions.\n",
+  "description": "Behavior-only application shell. Canonical authoring shape uses\ncluster-namespaced bespoke children — <admin-topbar> at the top,\n<admin-sidebar slot=\"leading|trailing\"> rails, <admin-content> for\nthe main content region, <admin-command> for the Cmd+K palette, and\noptional <admin-statusbar> at the bottom. The shell wires sidebar\ntoggle forwarding, command-palette triggers, and the ResizeObserver\nthat drives responsive sidebar collapse; each bespoke child owns\nits own resize / collapse / open state-as-attribute semantics per\nADR-0023.\n\nLegacy data-attribute shapes (<aside data-sidebar>, <dialog\ndata-command>, [data-resize], <aside-ui slot=>, <span data-spacer>,\n<div data-actions>) were RETIRED in v0.4.0 per ADR-0024 and are no\nlonger recognized. Consumers must use the bespoke vocabulary.\n",
   "type": "object",
   "allOf": [
     {
@@ -74,19 +74,19 @@
         "description": "Secondary metadata inside any chrome bar. Muted + --a-ui-sm size."
       },
       "default": {
-        "description": "Author-supplied page DOM. Expected structure — aside[data-sidebar] for navigation, main for content, optional dialog[data-command] for Cmd+K."
+        "description": "Bespoke children compose here in document order — <admin-topbar>, <admin-sidebar slot=\"leading\">, <admin-content> (containing <admin-page> / <admin-page-header> / <admin-page-body>), <admin-sidebar slot=\"trailing\">, <admin-command>, optional <admin-statusbar>. The shell's grid layout reads child tag selectors to place them."
       },
       "action": {
-        "description": "Trailing control cluster inside any chrome bar. The first [slot=\"action\"] child pushes itself (and siblings) to the end; subsequent siblings flow with gap. Coexists with legacy <span data-spacer> / <div data-actions> hooks for one release — new code should prefer slots."
+        "description": "Trailing control cluster inside any chrome bar. The first [slot=\"action\"] child pushes itself (and siblings) to the end; subsequent siblings flow with gap."
       },
       "action-leading": {
-        "description": "Leading (inline-start) control cluster inside any chrome bar. Pairs with [slot=\"action\"] for dual-cluster chrome (e.g. back button + breadcrumb on the left, primary actions on the right). Replaces the legacy <span data-spacer> hack."
+        "description": "Leading (inline-start) control cluster inside any chrome bar. Pairs with [slot=\"action\"] for dual-cluster chrome (e.g. back button + breadcrumb on the left, primary actions on the right)."
       },
       "heading": {
         "description": "Primary label inside any chrome bar. Medium-weight + strong fg."
       },
       "icon": {
-        "description": "Leading glyph inside any chrome bar — > main > header / footer and [data-sidebar] > header / footer. Muted color, flex-align."
+        "description": "Leading glyph inside any chrome bar (<admin-topbar>, <admin-statusbar>, <admin-sidebar> header/footer). Muted color, flex-align."
       }
     },
     "states": [

package/shell/admin-shell/admin-shell.d.ts

@@ -1,8 +1,18 @@
 /**
- * `<admin-shell-ui>` — Behavior-only application shell. Wires sidebar toggles, resize handles,
-a Cmd+K command palette, and a ResizeObserver that drives responsive
-sidebar collapse. Author supplies the DOM (aside[data-sidebar], main,
-dialog[data-command]); admin-shell binds the interactions.
+ * `<admin-shell-ui>` — Behavior-only application shell. Canonical authoring shape uses
+cluster-namespaced bespoke children — <admin-topbar> at the top,
+<admin-sidebar slot="leading|trailing"> rails, <admin-content> for
+the main content region, <admin-command> for the Cmd+K palette, and
+optional <admin-statusbar> at the bottom. The shell wires sidebar
+toggle forwarding, command-palette triggers, and the ResizeObserver
+that drives responsive sidebar collapse; each bespoke child owns
+its own resize / collapse / open state-as-attribute semantics per
+ADR-0023.
+
+Legacy data-attribute shapes (<aside data-sidebar>, <dialog
+data-command>, [data-resize], <aside-ui slot=>, <span data-spacer>,
+<div data-actions>) were RETIRED in v0.4.0 per ADR-0024 and are no
+longer recognized. Consumers must use the bespoke vocabulary.
 
  *
  * @see https://ui-kit.exe.xyz/site/components/admin-shell

package/shell/admin-shell/admin-shell.yaml

@@ -5,10 +5,20 @@ component: AppShell
 category: layout
 version: 1
 description: |
-  Behavior-only application shell. Wires sidebar toggles, resize handles,
-  a Cmd+K command palette, and a ResizeObserver that drives responsive
-  sidebar collapse. Author supplies the DOM (aside[data-sidebar], main,
-  dialog[data-command]); admin-shell binds the interactions.
+  Behavior-only application shell. Canonical authoring shape uses
+  cluster-namespaced bespoke children — <admin-topbar> at the top,
+  <admin-sidebar slot="leading|trailing"> rails, <admin-content> for
+  the main content region, <admin-command> for the Cmd+K palette, and
+  optional <admin-statusbar> at the bottom. The shell wires sidebar
+  toggle forwarding, command-palette triggers, and the ResizeObserver
+  that drives responsive sidebar collapse; each bespoke child owns
+  its own resize / collapse / open state-as-attribute semantics per
+  ADR-0023.
+
+  Legacy data-attribute shapes (<aside data-sidebar>, <dialog
+  data-command>, [data-resize], <aside-ui slot=>, <span data-spacer>,
+  <div data-actions>) were RETIRED in v0.4.0 per ADR-0024 and are no
+  longer recognized. Consumers must use the bespoke vocabulary.
 
 props:
   mode:
@@ -46,12 +56,17 @@ events:
 slots:
   default:
     description: >-
-      Author-supplied page DOM. Expected structure — aside[data-sidebar] for
-      navigation, main for content, optional dialog[data-command] for Cmd+K.
+      Bespoke children compose here in document order — <admin-topbar>,
+      <admin-sidebar slot="leading">, <admin-content> (containing
+      <admin-page> / <admin-page-header> / <admin-page-body>),
+      <admin-sidebar slot="trailing">, <admin-command>, optional
+      <admin-statusbar>. The shell's grid layout reads child tag
+      selectors to place them.
   icon:
     description: >-
-      Leading glyph inside any chrome bar — > main > header / footer and
-      [data-sidebar] > header / footer. Muted color, flex-align.
+      Leading glyph inside any chrome bar (<admin-topbar>,
+      <admin-statusbar>, <admin-sidebar> header/footer). Muted color,
+      flex-align.
   heading:
     description: >-
       Primary label inside any chrome bar. Medium-weight + strong fg.
@@ -62,15 +77,12 @@ slots:
     description: >-
       Trailing control cluster inside any chrome bar. The first
       [slot="action"] child pushes itself (and siblings) to the end;
-      subsequent siblings flow with gap. Coexists with legacy
-      <span data-spacer> / <div data-actions> hooks for one release —
-      new code should prefer slots.
+      subsequent siblings flow with gap.
   action-leading:
     description: >-
       Leading (inline-start) control cluster inside any chrome bar.
       Pairs with [slot="action"] for dual-cluster chrome (e.g. back
       button + breadcrumb on the left, primary actions on the right).
-      Replaces the legacy <span data-spacer> hack.
 
 states:
   - name: idle
@@ -87,9 +99,27 @@ traits: []
 a2ui:
   rules:
     - >-
-      admin-shell is a behavior wrapper; its children are native HTML landmarks
-      (aside, main, header). Don't wrap them in col-ui/row-ui — app-shell.css
-      handles grid layout based on [data-sidebar] attributes.
+      admin-shell takes bespoke admin-* children only. The canonical
+      composition is <admin-topbar> + <admin-sidebar slot="leading">
+      + <admin-content> + <admin-sidebar slot="trailing"> +
+      <admin-command> + optional <admin-statusbar>. The shell's CSS
+      grid reads child tag selectors to place them.
+    - >-
+      Don't nest col-ui / row-ui or generic layout primitives directly
+      inside admin-shell — app-shell.css handles grid layout based on
+      bespoke child tags. Generic layout goes inside <admin-content>
+      or inside <admin-page-body>.
+    - >-
+      Click forwarding patterns — [data-sidebar-toggle="<name>"] on a
+      button forwards to <admin-sidebar[slot="<name>"]>.toggle();
+      [data-command-trigger] on a button forwards to
+      <admin-command>.show(). The shell doesn't need to know about
+      the buttons; the bespoke children own the behavior.
+    - >-
+      Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024.
+      Do not author <aside data-sidebar>, <dialog data-command>,
+      [data-resize], <aside-ui slot=>, <span data-spacer>, or
+      <div data-actions> inside admin-shell.
 
 keywords: [app-shell, shell, layout, admin, dashboard, sidebar, nav]
 synonyms:

package/shell/admin-shell/css/admin-shell.bespoke.css

@@ -34,7 +34,7 @@ admin-sidebar > admin-topbar {
   display: flex;
   align-items: center;
   gap: var(--page-header-gap);
-  padding: 0 var(--page-content-inset);
+  padding: 0 var(--a-space-3);
   height: var(--page-header-height);
   font-size: var(--page-header-font);
   border-bottom: var(--page-border);
@@ -48,7 +48,7 @@ admin-sidebar > admin-statusbar {
   display: flex;
   align-items: center;
   gap: var(--page-header-gap);
-  padding: 0 var(--page-content-inset);
+  padding: 0 var(--a-space-3);
   height: var(--page-header-height);
   font-size: var(--page-header-font);
   color: var(--page-header-fg-muted);