App shell

Guidance and accessibility

When to use

• Use one app shell as the frame of an application: navigation, a header, and scrollable content.
• Narrow, the nav is a native popover: the toggle opens it, Escape and a click outside close it and focus returns to the button. No script.

Layouts are data

Every part owns a named grid area (nav, header, main), and --ca-shell-template on the root holds the whole grid-template shorthand. The default is a full-height nav column at the inline start, but the same markup rearranges into any layout by setting the variable — grid areas follow the document direction, so start and end mirror automatically in RTL:

/* Nav at the inline end — and dock the drawer there too with ms-auto */
.my-shell {
  --ca-shell-template:
    "header nav" auto
    "main nav" 1fr /
    1fr auto;
}

Extra regions work the same way: name an area in your template and give your element a plain [grid-area:*] utility — no contract class needed:

/* Three columns plus a status bar, for elements with
   [grid-area:aside] and [grid-area:footer] */
.my-shell {
  --ca-shell-template:
    "nav header aside" auto
    "nav main aside" 1fr
    "nav footer footer" auto /
    auto 1fr auto;
}

Collapsing the nav

Collapse is host state — the contract styles it, your app owns it. Set data-collapsed on the root (any button plus one line of script; persist it however you like) and the docked nav shrinks to zero width. Add ca-app-shell--rail to shrink to a 3.5rem icon rail instead; label text clips away and icons stay. Widths come from --ca-shell-nav-w (16rem) and --ca-shell-collapsed-w (0, or the rail width).

The toggle is for the drawer only — it hides when the nav is docked, so a collapse button on wide screens is your own element.

Accessibility

• Put the nav column in a <nav> with an aria-label, such as “App”, so it is listed as a landmark. Keep it early in DOM order — grid areas move the box, not the reading order.
• The drawer button needs a name, such as aria-label="Menu". Browsers tell screen readers whether the drawer is open.
• Mark the current page inside the nav with aria-current="page".