@adia-ai/web-modules 0.6.19 → 0.6.20

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.6.20] — 2026-05-21
+
+### Added — `<admin-entity-item>` shell identity-row primitive (FEEDBACK-38)
+
+- **New CSS-only shell-tier primitive: a composable icon + label + badge identity row.** A leading `<icon-ui>` (or `<img>` avatar), a truncating `[slot="label"]`, and an optional trailing `[slot="badge"]` travel as one slottable unit — slot it whole into `[slot="heading"]` of an `<admin-topbar>` / `<admin-statusbar>` for workspace or user identity. Geometry mirrors `<select-ui>`'s trigger row (`icon` ≡ `leading`, `label` ≡ `display`, `badge` ≡ `caret`). Inside a collapsible `<admin-sidebar>` the label + badge hide when the rail collapses and the icon survives, so one markup serves both states — closing the gap consumers were filling with ad-hoc `<span>` / `<div>` wrappers. New files: `shell/admin-entity-item/admin-entity-item.{yaml,a2ui.json,html,examples.html}` + `css/admin-shell.entity-item.css`. `admin-topbar.yaml` / `admin-statusbar.yaml` gain `a2ui.rules` pointing at it.
+
+### Added — `admin-shell` warns when `<admin-topbar>` / `<admin-statusbar>` is missing its slot (FEEDBACK-37)
+
+- **`<admin-shell>` now logs a one-shot `console.warn` when an `<admin-topbar>` or `<admin-statusbar>` is a direct child of `<admin-sidebar>` / `<admin-content>` without `slot="header"` / `slot="footer"`.** Both are CSS-only elements; omitting the slot lands them in the default body slot — rendering them in the content column instead of the chrome band, previously with zero diagnostics. The check runs once at connect, `WeakSet`-guarded per element. Same silent-misuse-warn discipline `drawer-ui` / `chart-ui` / `segmented-ui` received in 0.6.19. Files: `admin-shell.js`.
+
+### Changed — `<admin-page-header>` background rebased to `--a-canvas-0`
+
+- **`--page-content-header-bg` token: `--a-canvas-1` → `--a-canvas-0`.** The sticky page-header band now matches the page-body content surface (`--page-content-bg`), so the header reads as a flush extension of the content area rather than as separate chrome. This is the third iteration of the page-header treatment: v0.6.14 used `--a-canvas-2` (ΔL=0.08, "elevated step over content"); v0.6.16 rebased to `--a-canvas-1` ("shell-chrome continuation"); both still read as not-quite-flush against dense dark-mode layouts. `canvas-0` settles it — fully flush. Consumers who want a raised or contrasting band override `--page-content-header-bg` at `:root`. Files: `admin-shell.tokens.css` (token value + history comment).
+
+### Fixed — `admin-topbar` / `admin-statusbar` inline padding aligns with sibling `<section-ui>`
+
+- **The topbar/statusbar inline padding now matches the sibling `<section-ui>`'s, so chrome and content share one gutter.** In the content column the bars took `--page-header-px` (`a-space-3`) while the content `<section-ui>` uses `--page-content-inset` (`a-space-10`) — the topbar title and the body content were misaligned. They now use `--page-content-inset`. The shared rule also covered the sidebar context, where the sidebar's `<section-ui>` uses the tighter `--page-sidebar-px`; a new `admin-sidebar > :is(admin-topbar, admin-statusbar)` rule scopes that case so each context aligns with its own `<section-ui>`. Files: `css/admin-shell.bespoke.css`.
+
+### Fixed — collapsed sidebar `[slot="heading"]` hide no longer wipes composed wrappers (FEEDBACK-38 addendum)
+
+- **`collapsed.css`'s `[slot="heading"] { display: none }` rail-cleanup rule is now scoped to leaf text headings.** The unscoped rule hid *any* `slot="heading"` child in a collapsed sidebar — including composed wrappers like `<admin-entity-item slot="heading">`, wiping their icon along with the label text. It now matches `:is(span, p, div, h1–h6)[slot="heading"]` plus `[slot="heading"]:not(:has(> [slot]))` — a heading whose children are themselves slotted (a composed unit) survives collapse and manages its own children. Backward-compatible: bare `<span slot="heading">` text labels still hide. Files: `css/admin-shell.collapsed.css`.
+
+### Fixed — `nav-item-ui` collapsed hit area fills the 48px rail (FEEDBACK-39)
+
+- **In a collapsed sidebar, `nav-item-ui` now stretches to the full rail width instead of shrinking to its ~30px icon box.** Previously the centred 30px item left ~9px dead gutters on each side — clicks there hit `section-ui`, not the nav item (~37% of the rail was dead space). `collapsed.css` now sets `width: 100%` on both `nav-item-ui` and `nav-ui` — the latter is required because the collapsed section shrink-wraps its children, so the item's `width: 100%` would otherwise resolve against the 30px content box. `justify-content: center` keeps the glyph centred. Files: `css/admin-shell.collapsed.css`.
+
 ## [0.6.19] — 2026-05-21
 
 ### Added — `./shell/with-css` opt-in export (FEEDBACK-25)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "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/shell/admin-entity-item/admin-entity-item.a2ui.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminEntityItem.json",
+  "title": "AdminEntityItem",
+  "description": "Module-tier shell identity row. CSS-only — no behavior, no JS.\nA composable icon + label + badge unit: a leading icon (or avatar),\na truncating label, and an optional trailing badge that travel\ntogether as one slottable element.\n\nUse it wherever a shell surface shows an entity identity — workspace\nidentity in an <admin-topbar slot=\"header\">, user identity in an\n<admin-statusbar>, the leading item of a breadcrumb, a flyout header,\nor a user row. Inside a collapsible <admin-sidebar> the label and\nbadge hide when the rail collapses; the icon survives — so the same\nmarkup works expanded and collapsed without authoring two shapes.\n\nGeometry mirrors <select-ui>'s trigger row: [slot=\"icon\"] is fixed\n(like [slot=\"leading\"]), [slot=\"label\"] flexes + truncates (like\n[slot=\"display\"]), [slot=\"badge\"] is fixed trailing (like\n[slot=\"caret\"]).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdminEntityItem"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "admin-entity-item",
+      "entity-item",
+      "identity-row",
+      "workspace-identity",
+      "user-identity",
+      "icon-label-badge"
+    ],
+    "name": "AdminEntityItem",
+    "related": [
+      "AdminTopbar",
+      "AdminStatusbar",
+      "AdminSidebar",
+      "Select",
+      "Badge",
+      "Icon"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default content — unslotted children flow inline. Prefer the named slots for the canonical icon + label + badge composition."
+      },
+      "badge": {
+        "description": "Optional trailing chip — environment (staging / beta) or role badge. Fixed width. Hidden when a collapsible sidebar collapses."
+      },
+      "icon": {
+        "description": "Leading visual — an <icon-ui> glyph or an <img> avatar (img is given a circular crop). Fixed width; survives sidebar collapse."
+      },
+      "label": {
+        "description": "Primary text. Flexes to fill the remaining width and truncates with an ellipsis. Hidden when a collapsible sidebar collapses."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, the only state.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "entity-item": [
+        "identity-row",
+        "entity-row",
+        "identity-item"
+      ]
+    },
+    "tag": "admin-entity-item",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,84 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdminEntityItem
+tag: admin-entity-item
+component: AdminEntityItem
+category: layout
+version: 1
+description: |
+  Module-tier shell identity row. CSS-only — no behavior, no JS.
+  A composable icon + label + badge unit: a leading icon (or avatar),
+  a truncating label, and an optional trailing badge that travel
+  together as one slottable element.
+
+  Use it wherever a shell surface shows an entity identity — workspace
+  identity in an <admin-topbar slot="header">, user identity in an
+  <admin-statusbar>, the leading item of a breadcrumb, a flyout header,
+  or a user row. Inside a collapsible <admin-sidebar> the label and
+  badge hide when the rail collapses; the icon survives — so the same
+  markup works expanded and collapsed without authoring two shapes.
+
+  Geometry mirrors <select-ui>'s trigger row: [slot="icon"] is fixed
+  (like [slot="leading"]), [slot="label"] flexes + truncates (like
+  [slot="display"]), [slot="badge"] is fixed trailing (like
+  [slot="caret"]).
+
+props: {}
+
+events: {}
+
+slots:
+  default:
+    description: >-
+      Default content — unslotted children flow inline. Prefer the
+      named slots for the canonical icon + label + badge composition.
+  icon:
+    description: >-
+      Leading visual — an <icon-ui> glyph or an <img> avatar (img is
+      given a circular crop). Fixed width; survives sidebar collapse.
+  label:
+    description: >-
+      Primary text. Flexes to fill the remaining width and truncates
+      with an ellipsis. Hidden when a collapsible sidebar collapses.
+  badge:
+    description: >-
+      Optional trailing chip — environment (staging / beta) or role
+      badge. Fixed width. Hidden when a collapsible sidebar collapses.
+
+states:
+  - name: idle
+    description: Default, the only state.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      admin-entity-item is the canonical icon + label + badge identity
+      row for shell surfaces. Slot it whole into [slot="heading"] of an
+      <admin-topbar> / <admin-statusbar> so the icon + label + badge
+      collapse together inside a collapsible <admin-sidebar>. Do NOT
+      re-implement it with a bare <span> or an ad-hoc flex <div> — those
+      have no shared collapse boundary.
+    - >-
+      For an INTERACTIVE workspace switcher use <select-ui variant="ghost">
+      instead — admin-entity-item is read-only identity display.
+
+keywords:
+  - admin-entity-item
+  - entity-item
+  - identity-row
+  - workspace-identity
+  - user-identity
+  - icon-label-badge
+
+synonyms:
+  entity-item: [identity-row, entity-row, identity-item]
+
+related:
+  - AdminTopbar
+  - AdminStatusbar
+  - AdminSidebar
+  - Select
+  - Badge
+  - Icon

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

@@ -13,3 +13,4 @@
 @import "./css/admin-shell.templates.css";
 @import "./css/admin-shell.helpers.css";
 @import "./css/admin-shell.bespoke.css";
+@import "./css/admin-shell.entity-item.css";

package/shell/admin-shell/admin-shell.js

@@ -40,6 +40,10 @@ class AdminShell extends UIElement {
 
   static template = () => null;
 
+  // FEEDBACK-37: one-shot per-element warn for <admin-topbar>/<admin-statusbar>
+  // mounted without their slot. WeakSet so it never pins the element from GC.
+  static #warnedSlots = new WeakSet();
+
   connected() {
     // Apply the v0.6.13 default mode if (and only if) the author did
     // not supply a `mode` attribute on the tag. `hasAttribute` returns
@@ -48,6 +52,7 @@ class AdminShell extends UIElement {
     if (!this.hasAttribute('mode')) this.mode = DEFAULT_MODE;
     this.#wireToggleButtons();
     this.#wireCommandTriggers();
+    this.#checkSlotContracts();
   }
 
   // No #disconnected — children own their own cleanup; the host registers
@@ -95,6 +100,33 @@ class AdminShell extends UIElement {
       if (item) nav.select(item);
     });
   }
+
+  // ── 3. Slot-contract diagnostics (FEEDBACK-37) ──
+  // <admin-topbar>/<admin-statusbar> are CSS-only — placed inside
+  // <admin-sidebar>/<admin-content> without slot="header"/"footer" they
+  // land in the default slot and render in the body column instead of the
+  // chrome band, with no diagnostic. One-shot warn per misused element.
+  // (admin-statusbar folded in — identical failure mode to admin-topbar.)
+  #checkSlotContracts() {
+    const want = { 'admin-topbar': 'header', 'admin-statusbar': 'footer' };
+    for (const parent of this.querySelectorAll('admin-sidebar, admin-content')) {
+      for (const child of parent.children) {
+        const slot = want[child.localName];
+        if (slot
+            && child.getAttribute('slot') !== slot
+            && !AdminShell.#warnedSlots.has(child)) {
+          AdminShell.#warnedSlots.add(child);
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[admin-shell] <${child.localName}> inside <${parent.localName}> is missing ` +
+            `slot="${slot}" — it renders in the default body slot instead of the chrome ` +
+            `band. Add slot="${slot}". See ${child.localName}.yaml.`,
+            child,
+          );
+        }
+      }
+    }
+  }
 }
 
 customElements.define('admin-shell', AdminShell);

package/shell/admin-shell/admin-shell.test.js

@@ -87,7 +87,12 @@ describe('admin-shell.collapsed.css — vanilla HTML fallback (v0.6.17)', () =>
     // text labels don't overflow the 48px rail when the consumer doesn't
     // use AdiaUI <nav-item-ui> primitives.
     expect(collapsedCSS).toMatch(/Vanilla-HTML fallback/);
-    expect(collapsedCSS).toMatch(/\[slot="heading"\]\s*\{[\s\S]*?display:\s*none/);
+    // v0.6.20 (FEEDBACK-38 addendum): the heading-hide rule narrowed from a
+    // blanket `[slot="heading"]` to plain-text headings + headings without
+    // slotted children, so composed wrappers (<admin-entity-item slot="heading">)
+    // survive collapse. The rule still resolves to `display: none`.
+    expect(collapsedCSS).toMatch(/\[slot="heading"\][^{]*\{\s*display:\s*none/);
+    expect(collapsedCSS).toMatch(/\[slot="heading"\]:not\(:has\(>\s*\[slot\]\)\)/);
     expect(collapsedCSS).toMatch(/button\.nav-item/);
     expect(collapsedCSS).toMatch(/text-indent:\s*-9999px/);
   });

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-header-px);
+  padding: 0 var(--page-content-inset);
   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-header-px);
+  padding: 0 var(--page-content-inset);
   height: var(--page-header-height);
   font-size: var(--page-header-font);
   color: var(--page-header-fg-muted);
@@ -56,6 +56,13 @@ admin-sidebar > admin-statusbar {
   flex-shrink: 0;
 }
 
+/* Sidebar header/footer chrome takes the sidebar's tighter inline inset
+   (--page-sidebar-px) so it aligns with the sidebar's own <section-ui>
+   body — not the content column's wider --page-content-inset. */
+admin-sidebar > :is(admin-topbar, admin-statusbar) {
+  padding-inline: var(--page-sidebar-px);
+}
+
 /* ── admin-scroll ≡ <section> child of <main> ── */
 admin-content > admin-scroll {
   flex: 1;

package/shell/admin-shell/css/admin-shell.collapsed.css

@@ -71,6 +71,19 @@
     padding: 0;
     min-height: var(--nav-item-row-height);
     min-width: var(--nav-item-row-height);
+    /* FEEDBACK-39: fill the rail width so the whole 48px column is the hit
+       area — without this the item shrinks to its ~30px icon box, leaving
+       ~9px dead gutters on each side. justify-content keeps the glyph
+       centred within the now-full-width item. */
+    width: 100%;
+  }
+
+  /* FEEDBACK-39: nav-ui itself must fill the rail — the collapsed section
+     centres + shrink-wraps its children, so without an explicit width
+     nav-ui collapses to its ~30px content box and `width: 100%` on the
+     items would resolve against 30px, not the 48px rail. */
+  nav-ui {
+    width: 100%;
   }
 
   /* Button: icon-only mode */
@@ -111,7 +124,13 @@
      <admin-topbar slot="header">) — keeps the rail clean in collapsed mode.
      Authors who want a brand mark visible when collapsed should put an
      <icon-ui> or logo image in [slot="leading"] instead. */
-  [slot="heading"] {
+  /* FEEDBACK-38 (addendum): scope the hide to leaf text headings — a bare
+     <span slot="heading">Brand</span> — not composed wrappers (e.g. an
+     <admin-entity-item slot="heading">) that carry their own internal slot
+     contract. `:not(:has(> [slot]))` preserves any heading element whose
+     children are themselves slotted, so its icon survives collapse. */
+  :is(span, p, div, h1, h2, h3, h4, h5, h6)[slot="heading"],
+  [slot="heading"]:not(:has(> [slot])) {
     display: none;
   }
 

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

@@ -0,0 +1,82 @@
+/* ═══════════════════════════════════════════════════════════════
+   admin-shell — <admin-entity-item>   (FEEDBACK-38)
+
+   CSS-only shell-tier primitive: a composable icon + label + badge
+   identity row. The leading icon, a truncating label, and an
+   optional trailing badge travel as one unit, so they can be
+   slotted whole into <admin-topbar>, <admin-statusbar>, breadcrumb
+   leading items, flyout headers, and user-identity rows.
+
+   Geometry mirrors <select-ui>'s trigger row:
+     [slot="icon"]  ≡ select-ui [slot="leading"]  — fixed, flex-shrink:0
+     [slot="label"] ≡ select-ui [slot="display"]  — flexible, truncates
+     [slot="badge"] ≡ select-ui [slot="caret"]    — fixed trailing
+
+   Collapse: inside a collapsed <admin-sidebar> (@container sidebar,
+   ≤96px) the label + badge hide and the icon survives. This is why
+   the element is a wrapper: collapsed.css's [slot="heading"] hide
+   rule is scoped to preserve any heading that carries slotted
+   children (`:not(:has(> [slot]))`, see FEEDBACK-38 addendum), so a
+   <admin-entity-item slot="heading"> survives collapse and manages
+   its own label/badge here — a bare <span slot="heading"> cannot.
+   ═══════════════════════════════════════════════════════════════ */
+
+admin-entity-item {
+  /* ── tunable tokens ── */
+  --entity-item-gap:         var(--a-space-2);
+  --entity-item-icon-size:   1rem;
+  --entity-item-icon-color:  var(--a-fg-muted);
+  --entity-item-avatar-size: 1.5rem;
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--entity-item-gap);
+  min-width: 0;
+  overflow: hidden;
+}
+
+/* Leading visual — <icon-ui> glyph or <img> avatar. Never shrinks. */
+admin-entity-item > [slot="icon"] {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  line-height: 1;
+  color: var(--entity-item-icon-color);
+  --a-icon-size: var(--entity-item-icon-size);
+}
+
+/* <img slot="icon"> → circular avatar treatment. */
+admin-entity-item > img[slot="icon"] {
+  width: var(--entity-item-avatar-size);
+  height: var(--entity-item-avatar-size);
+  border-radius: var(--a-radius-full);
+  object-fit: cover;
+}
+
+/* Truncating label — takes the remaining width, ellipsises overflow. */
+admin-entity-item > [slot="label"] {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--a-ui-sm);
+  font-weight: var(--a-weight-medium, 500);
+  color: var(--a-fg);
+}
+
+/* Optional trailing badge — environment / role chip. Never shrinks. */
+admin-entity-item > [slot="badge"] {
+  flex-shrink: 0;
+}
+
+/* ── Collapsed sidebar (icon-only rail) ──
+   Hide the label + badge; the icon survives. The enclosing
+   <admin-topbar>/<admin-statusbar> collapsed rule (justify-content:
+   center, in collapsed.css) centres the now-icon-only item. */
+@container sidebar (max-width: 96px) {
+  admin-entity-item > [slot="label"],
+  admin-entity-item > [slot="badge"] {
+    display: none;
+  }
+}

package/shell/admin-shell/css/admin-shell.tokens.css

@@ -38,7 +38,7 @@
 
   /* Content area — scroll region inside main */
   --page-content-bg:        var(--a-canvas-0);       /* content surface (lighter than chrome) */
-  --page-content-header-bg: var(--a-canvas-1);       /* sticky page-header band — matches sidebar/topbar canvas so the shell reads as a continuous L-shape of chrome wrapping the page-body. ΔL=0.04 above body canvas-0. History: v0.6.14 used canvas-2 (ΔL=0.08) under the "elevated step over content" intent, but vision-tests against dense layouts showed the band still read as flush with body. v0.6.15 reframes the page-header as shell-chrome continuation (canvas-1 matches sidebar) rather than as an elevated step — visual cohesion over contrast. Consumers who want a stronger raised band can override this token at :root. */
+  --page-content-header-bg: var(--a-canvas-0);       /* sticky page-header band — canvas-0, matching the page-body content surface (--page-content-bg) so the header reads as a flush extension of the content area, not as separate chrome. History: v0.6.14 used canvas-2 (ΔL=0.08, "elevated step over content"); v0.6.16 rebased to canvas-1 ("shell-chrome continuation"); both still read as not-quite-flush against dense dark-mode layouts, so the band is now canvas-0 — fully flush with the body content surface. Consumers who want a raised/contrasting band override this token at :root. */
   --page-content-radius:    var(--a-radius-lg);      /* used by "rounded" mode */
   --page-content-inset:     var(--a-space-10);       /* padding for header/body/footer */
   --page-content-max-width: 1540px;                   /* max-width for content children */

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

@@ -39,6 +39,7 @@
       "AdminShell",
       "AdminContent",
       "AdminTopbar",
+      "AdminEntityItem",
       "Footer"
     ],
     "slots": {

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

@@ -50,6 +50,17 @@ a2ui:
       admin-statusbar replaces <footer-ui> at shell-tier. Same slot
       vocabulary as <admin-topbar>; visual treatment differs (the
       shell css applies a top-border instead of bottom).
+    - >-
+      When placed inside <admin-sidebar> or <admin-content>, admin-statusbar
+      MUST carry slot="footer". Without it the statusbar lands in the
+      default body slot instead of the chrome footer band. Canonical:
+      <admin-statusbar slot="footer">…</admin-statusbar>. admin-shell logs
+      a one-shot console.warn when the slot is missing.
+    - >-
+      For a user-identity row (avatar + name + role badge), slot a single
+      <admin-entity-item slot="heading"> rather than separate slot="icon" +
+      slot="heading" children — the wrapper collapses the name + badge
+      together inside a collapsible <admin-sidebar>, keeping the avatar.
 
 keywords:
   - admin-statusbar
@@ -65,4 +76,5 @@ related:
   - AdminShell
   - AdminContent
   - AdminTopbar
+  - AdminEntityItem
   - Footer

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

@@ -40,6 +40,7 @@
       "AdminContent",
       "AdminSidebar",
       "AdminStatusbar",
+      "AdminEntityItem",
       "Header"
     ],
     "slots": {

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

@@ -56,6 +56,18 @@ a2ui:
       admin-topbar replaces <header-ui> at shell-tier — use it for
       chrome bars inside admin-shell, admin-content, admin-sidebar.
       Use <header-ui> for primitive containers (Card / Drawer / Modal).
+    - >-
+      When placed inside <admin-sidebar> or <admin-content>, admin-topbar
+      MUST carry slot="header". Without it the topbar lands in the default
+      body slot and renders below the content instead of as the chrome
+      header band. Canonical: <admin-topbar slot="header">…</admin-topbar>.
+      admin-shell logs a one-shot console.warn when the slot is missing.
+    - >-
+      For an icon + label (+ optional badge) identity row — workspace or
+      product identity — slot a single <admin-entity-item slot="heading">
+      rather than separate slot="icon" + slot="heading" children. The
+      wrapper keeps the icon and label as one unit so they truncate and
+      collapse together inside a collapsible <admin-sidebar>.
 
 keywords:
   - admin-topbar
@@ -72,4 +84,5 @@ related:
   - AdminContent
   - AdminSidebar
   - AdminStatusbar
+  - AdminEntityItem
   - Header