UI layers & terms

App shell, page chrome, surface chrome, and shell regions — one vocabulary

This page aligns with the Chirp guide: UI layers & shell regions (same concepts; Chirp owns thechirp.shell_regionsconstants).

Quick glossary

Term Meaning
App shell Persistent layout fromchirpui/app_shell_layout.html: topbar, sidebar, #main wrapper. Not replaced on navigation; #page-content inside #mainswaps.
Page content The document area:#page-content — what hx-selecttargets for boosted nav.
Page chrome Route-owned UI inside#page-content: titles, tabs, toolbars — not the global topbar.
Shell actions ShellActions → shell_actions_bar, target #chirp-shell-actions. Route-scoped; updates via OOB.
Shell regions Stableids updated by hx-swap-oob (e.g. chirp-shell-actions, chirpui-document-title).
Surface chrome Visual frame of a component (surface, panel, bento): border, padding, scroll — not the app shell.

Avoid: using “chrome” alone for the whole app frame — say app shell or topbar/sidebar.

chirp-ui responsibilities

  • app_shell_layout.html — Defines the shell DOM, registers no extra Python; pairs with Chirp’s use_chirp_ui(app).
  • Shell coherence script — Clears#chirp-shell-actions in htmx:beforeSwapwhen the response includes a shell-actions OOB, so users never see one frame of new page + stale actions (htmx runs primary swap before OOB).
  • Repo: docs/UI-LAYERS.md (duplicate reference for editors)
  • docs/LAYOUT-OVERFLOW.md — keeping the main column stable
  • docs/COMPONENT-OPTIONS.md — components; distinguishes surface chrome from shell