# Mode 5, Admin-shell composition: the 13 canonical parts

Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
`audit:shell-composition{,:strict,:all}`. Static AST walk over
`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html`, no browser needed; pre-commit fast. The script's own `PARTS` array is the
mechanical census, it has grown past this list (count it in
`scripts/dev/audit-shell-composition.mjs`, never from a hand-typed number
here); this numbered list is the human review standard, and the findings
table below samples common symptoms rather than the script's full roster.
Canonical source: the monorepo's `site/index.html`, the markup that renders
the live admin-dashboard example.

1. `<admin-shell mode="rounded borderless">` outer (canonical mode attr)
2. `<admin-sidebar slot="leading" resizable collapsible>` (left rail)
3. Sidebar `<admin-topbar slot="header">` with
   `<select-ui avatar="…" value="…" variant="ghost">` context switcher, NOT `<menu-ui>` (legacy pattern), ★ commonly mis-implemented
4. Sidebar nav wrap around `<nav-ui>`, `<section>` (per the examples),
   `<section-ui>` (card-style chrome), or `<page-scroll>` all accepted;
   a bare `<nav-ui>` direct child overflows long lists
5. Sidebar `<admin-statusbar slot="footer">` with `<select-ui avatar="…">`
   (user menu), ★ commonly missing
6. Sidebar `<div data-sidebar-resize></div>`, REQUIRED when `resizable` is on
7. `<admin-content>` inner `<admin-topbar>` containing
   `<button-ui data-sidebar-toggle="leading" icon="sidebar">` +
   `<breadcrumb-ui>` + `<span data-spacer>` + `<div data-actions>`, ★ spacer + actions commonly missing
8. `[data-actions]` contains `<popover-ui>` + `<theme-panel slot="content">`
   (there is no `<theme-picker-ui>`)
9. `<page-scroll>` wrapping optional `<aside data-subnav hidden>` +
   `<router-ui>` (or `<page-ui band>` directly for non-routed)
   **[deleted, ADR-0098 / gh#3745]** `admin-scroll` was a wholesale
   rename to `page-scroll` (both modes carried over); its one-release
   deprecation window has closed and the module is deleted (gh#3745).
   The `admin-page` family (`admin-page`/`admin-page-header`/
   `admin-page-body`) is deleted outright per ADR-0098, no compat alias.
   `page-scroll` wrapping `page-ui[band]` is the sole successor for the
   routed and non-routed case alike.
10. `<admin-page>` with `<admin-page-header>` + `<admin-page-body>`
    **[deleted, ADR-0098]** The `admin-page` family is deleted outright,
    no compat alias and no open deprecation window, in favor of
    `page-ui[band]`; `page-ui` is now the one canonical page-chrome
    primitive (item 9 above shows the live composition: `page-scroll`
    wrapping `page-ui[band]`). This item is kept only so this anatomy
    still recognizes the retired shape when auditing legacy surfaces
    that predate the migration; never author it in new surfaces.
11. `<admin-statusbar>` at content footer (version strip), ★ commonly missing
12. Second `<admin-sidebar slot="trailing">` (inspector rail, hidden by
    default), strongly recommended
13. `<admin-command>` with `<command-ui>` (cmd-K palette, top-level child), strongly recommended

## Severity mapping

- **critical**, `<admin-shell>` present but structurally broken (no
  `<admin-content>` / no sidebar). Halt; re-author the outer composition from
  the canonical source before continuing.
- **warning**, a commonly-missing part (3, 5, 6, 7 spacer/actions, 8, 11)
  absent, or the wrong primitive used (`menu-ui` context switcher, native
  `<section>` where chrome was wanted).
- **info**, parts 12–13 absent; `data-shell-opt-out=` declared.

## What the script flags (mechanical subset)

| Symptom | Diagnosis |
|---|---|
| `<admin-shell>` with no `<admin-content>` | critical, broken outer composition |
| sidebar missing `<admin-statusbar slot="footer">` | warning, part 5 |
| content topbar missing `[data-spacer]` / `[data-actions]` | warning, part 7 |
| content missing trailing `<admin-statusbar>` | warning, part 11 |
| sidebar topbar contains only plain text | warning, part 3 context switcher |
| `<page-scroll>` missing around `<page-ui band>` | critical, part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+chrome wrapper the content renders flush with the topbar, no margins). **[deleted, ADR-0098 / gh#3745]** `admin-scroll` and the `admin-page` family are both deleted outright, no compat alias; the successor is `page-scroll` wrapping `page-ui[band]` |

## Opt-out contract

A deliberately-incomplete shell (marketing hero, modal preview, one-feature
playground) annotates the outer tag:
`<admin-shell mode="rounded" data-shell-opt-out="marketing hero, no sidebar">`.
The audit skips structural checks and emits an info finding naming the reason
for reviewers to sanity-check.

## Triage

- Canonical product surface (`apps/*` admin pages, `catalog/page-shells/*`) →
  fix mandatory; these ARE the reference other agents copy.
- Playground isolating ONE narrow feature → fix optional; annotating the
  opt-out is acceptable.
- Never point this audit at `/site/components/*` demos (single-primitive
  spotlights, every one would "miss" an admin shell) or at consumer repos
  (substrate-side tooling; consumers get the factory's forward-time pattern
  gate instead).
- `:strict` is the CI/publish posture; keep the warn-only default while
  iterating locally.