# UI layers & terms

URL: /docs/app-shell/ui-layers/
Section: app-shell

--------------------------------------------------------------------------------

UI layers & terms This page aligns with the Chirp guide: UI layers & shell regions (same concepts; Chirp owns the chirp.shell_regions constants). Quick glossary Term Meaning App shell Persistent layout from chirpui/app_shell_layout.html: topbar, sidebar, #main wrapper. Not replaced on navigation; #page-content inside #main swaps. Page content The document area: #page-content — what hx-select targets 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 Stable ids 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:beforeSwap when the response includes a shell-actions OOB, so users never see one frame of new page + stale actions (htmx runs primary swap before OOB). Related docs 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

--------------------------------------------------------------------------------

Metadata:
- Word Count: 198
- Reading Time: 1 minutes