Pattern

App shell — Contained

The ABL application frame: a collapsible sidebar on a tinted page, with the page in a raised panel whose header carries title, search, branch and the global menu.

.b-app-shell.b-flow.b-cluster.b-wrapper.b-region

Use for signed-in ABL products where people move between many sections (Product Finder, Projects, Orders…). The sidebar groups sections by job — work, awareness, system — with a divider between groups. Let people collapse it to an icon rail; remember their choice. Source: Figma Beam › App shells › Contained.

Preview

Acuity Brands Lighting

Each kit renders in its own frame and follows the theme and density set in the header. Open full-size ↗

HTML

Layout uses Beam compositions and utilities only. Buttons, inputs, toggles, badges and tables here are stand-ins so the preview renders — in product, use the Cantina components below.

<div class="[ b-app-shell ] [ b-shell-contained ]" data-shell>
  <input class="[ b-shell-toggle ]" type="checkbox" id="shell-collapse">
  <nav data-area="nav" class="[ b-shell-sidebar ]" aria-label="Application">
    <div class="[ b-shell-brand-row ]">
      <div class="[ b-shell-brand ]">
        <span class="[ b-brand-logo ]" role="img" aria-label="Acuity"></span>
        <span class="[ b-shell-subbrand ]">Sub-brand</span>
      </div>
      <label class="[ b-shell-icon-btn b-shell-collapse ]" for="shell-collapse"><i class="fa-duotone fa-light fa-sidebar" aria-hidden="true"></i><span class="[ u-visually-hidden ]">Collapse sidebar</span></label>
    </div>
    <div class="[ b-shell-nav ]">
      <ul class="[ b-shell-nav-group ]" role="list">
        <li><a class="[ b-shell-nav-item ]" href="#" aria-current="page" title="Home"><i class="fa-duotone fa-light fa-house" aria-hidden="true"></i><span class="[ b-shell-label ]">Home</span></a></li>
      </ul>
      <ul class="[ b-shell-nav-group ]" role="list">
        <li><a class="[ b-shell-nav-item ]" href="#" title="Product Finder"><i class="fa-duotone fa-light fa-bag-shopping" aria-hidden="true"></i><span class="[ b-shell-label ]">Product Finder</span></a></li>
        <li><a class="[ b-shell-nav-item ]" href="#" title="Projects"><i class="fa-duotone fa-light fa-folder" aria-hidden="true"></i><span class="[ b-shell-label ]">Projects</span></a></li>
        <li><a class="[ b-shell-nav-item ]" href="#" title="Bids &amp; Quotes"><i class="fa-duotone fa-light fa-sack-dollar" aria-hidden="true"></i><span class="[ b-shell-label ]">Bids &amp; Quotes</span></a></li>
        <li><a class="[ b-shell-nav-item ]" href="#" title="Orders"><i class="fa-duotone fa-light fa-box" aria-hidden="true"></i><span class="[ b-shell-label ]">Orders</span></a></li>
        <li><a class="[ b-shell-nav-item ]" href="#" title="Fulfillment"><i class="fa-duotone fa-light fa-truck" aria-hidden="true"></i><span class="[ b-shell-label ]">Fulfillment</span></a></li>
      </ul>
      <ul class="[ b-shell-nav-group ]" role="list">
        <li><a class="[ b-shell-nav-item ]" href="#" title="Collaboration Center"><i class="fa-duotone fa-light fa-people-group" aria-hidden="true"></i><span class="[ b-shell-label ]">Collaboration Center</span></a></li>
        <li><a class="[ b-shell-nav-item ]" href="#" title="Reports"><i class="fa-duotone fa-light fa-chart-simple" aria-hidden="true"></i><span class="[ b-shell-label ]">Reports</span></a></li>
      </ul>
      <ul class="[ b-shell-nav-group ]" role="list">
        <li><a class="[ b-shell-nav-item ]" href="#" title="Support"><i class="fa-duotone fa-light fa-circle-user-circle-question" aria-hidden="true"></i><span class="[ b-shell-label ]">Support</span></a></li>
        <li><a class="[ b-shell-nav-item ]" href="#" title="Workspace"><i class="fa-duotone fa-light fa-user-key" aria-hidden="true"></i><span class="[ b-shell-label ]">Workspace</span></a></li>
      </ul>
    </div>
    <div class="[ b-shell-appearance ]" role="group" aria-label="Appearance">
      <button type="button" data-theme-set="light" aria-pressed="true"><span class="[ b-shell-sun ]"><i class="fa-duotone fa-light fa-sun" aria-hidden="true"></i></span><span class="[ b-shell-label ]">Light</span></button>
      <button type="button" data-theme-set="dark" aria-pressed="false"><i class="fa-duotone fa-light fa-moon" aria-hidden="true"></i><span class="[ b-shell-label ]">Dark</span></button>
    </div>
  </nav>
  <main data-area="main" class="[ b-shell-panel ]">
    <header class="[ b-shell-header ]">
      <div class="[ b-shell-header-title ]">
        <span class="[ b-shell-title-icon ]"><i class="fa-duotone fa-light fa-house" aria-hidden="true"></i></span>
        <h1 class="[ u-type-h6 ]">Home</h1>
      </div>
      <form class="[ b-shell-search ]" role="search">
        <span class="[ b-shell-icon-box ]"><i class="fa-duotone fa-light fa-search" aria-hidden="true"></i></span>
        <input type="search" placeholder="What would you like to find?" aria-label="Search">
        <span class="[ b-shell-search-tools ]">
          <button class="[ b-shell-icon-box ]" type="button" aria-label="Voice search"><i class="fa-duotone fa-light fa-waveform-lines" aria-hidden="true"></i></button>
          <kbd class="[ b-shell-kbd ]"><i class="fa-duotone fa-light fa-command" aria-hidden="true"></i>K</kbd>
          <button class="[ b-shell-ai ]" type="button" aria-label="Ask AI"><i class="fa-duotone fa-light fa-sparkles" aria-hidden="true"></i></button>
        </span>
      </form>
      <div class="[ b-shell-header-end ]">
        <span class="[ b-shell-branch ]"><span>Branch:</span> <strong>Conyers, GA</strong></span>
        <div class="[ b-shell-global ]">
          <a class="[ b-shell-menu-item ]" href="#" aria-label="Cart, 0 items"><span class="[ b-shell-icon-box ]"><i class="fa-duotone fa-light fa-bag-shopping" aria-hidden="true"></i></span><span class="[ b-shell-badge ]" data-tone="violet">0</span></a>
          <a class="[ b-shell-menu-item ]" href="#" aria-label="Notifications, 5 unread"><span class="[ b-shell-icon-box ]"><i class="fa-duotone fa-light fa-bell" aria-hidden="true"></i></span><span class="[ b-shell-badge ]" data-tone="error" data-dot>5</span></a>
          <button class="[ b-shell-user ]" type="button" aria-haspopup="menu"><span class="[ b-shell-avatar ]">JP</span><span>Jennifer</span><span class="[ b-shell-chevron ]"><i class="fa-duotone fa-light fa-chevron-down" aria-hidden="true"></i></span></button>
          <button class="[ b-shell-icon-box ]" type="button" aria-label="Menu" data-shell-menu><i class="fa-duotone fa-light fa-bars" aria-hidden="true"></i></button>
        </div>
      </div>
    </header>
    <div class="[ b-shell-slot ]"></div>
  </main>
</div>

Cantina components

header
badge
button
input
dropdown
segmented-button

Open Cantina ↗

Recipe

The rules an agent follows to build this pattern. This is what goes into beam.skill.

Root: <div class="[ b-app-shell ] [ b-shell-contained ]"> with data-area="nav" (sidebar) and data-area="main" (panel). No header/footer areas — the header lives inside the panel.
Drawn at Compact density (Figma body 14 / caption 10 / spacing-lg 8). Sidebar: brand logo (kit --beam-brand-logo) + uppercase light sub-brand with a brand-secondary rule, collapse button, nav groups split by border-neutral-separator dividers, Light/Dark toggle pinned to the bottom.
Nav item: icon + body-role label in text-neutral-secondary; current item = surface-default fill, hairline border-neutral-separator, depth-ring, a pill indicator in fg-brand-secondary and text-brand-secondary.
Collapse needs no JavaScript: a visually hidden checkbox (.b-shell-toggle, first child of the shell) holds the state and the collapse button is its label. Checked → icon rail (icon-size-6 items); labels and sub-brand fade and shrink but stay as accessible names. Width, labels and gaps transition on --beam-duration-slow-1 / --beam-ease-standard. Products that own the state can set data-collapsed instead. Remembering the choice across reloads is the product's job: render the checkbox with checked (or set data-collapsed) from the saved preference.
Panel: background-neutral-primary, border-width-1 border-neutral-tertiary, radius-rounded, depth-high-around (Figma depth/around/high). Header row: title (icon tile + h6) · search (background-neutral-quaternary) · branch pill (radius-pill) · global menu (cart, notifications, user, menu).
Below md the sidebar hides; the header menu button opens it as an overlay.

beam.skill recipe (Markdown)

## Pattern: App shell — Contained
The ABL application frame: a collapsible sidebar on a tinted page, with the page in a raised panel whose header carries title, search, branch and the global menu.

Compositions: .b-app-shell, .b-flow, .b-cluster, .b-wrapper, .b-region
Cantina: header, badge, button, input, dropdown, segmented-button

1. Root: <div class="[ b-app-shell ] [ b-shell-contained ]"> with data-area="nav" (sidebar) and data-area="main" (panel). No header/footer areas — the header lives inside the panel.
2. Drawn at Compact density (Figma body 14 / caption 10 / spacing-lg 8). Sidebar: brand logo (kit --beam-brand-logo) + uppercase light sub-brand with a brand-secondary rule, collapse button, nav groups split by border-neutral-separator dividers, Light/Dark toggle pinned to the bottom.
3. Nav item: icon + body-role label in text-neutral-secondary; current item = surface-default fill, hairline border-neutral-separator, depth-ring, a pill indicator in fg-brand-secondary and text-brand-secondary.
4. Collapse needs no JavaScript: a visually hidden checkbox (.b-shell-toggle, first child of the shell) holds the state and the collapse button is its label. Checked → icon rail (icon-size-6 items); labels and sub-brand fade and shrink but stay as accessible names. Width, labels and gaps transition on --beam-duration-slow-1 / --beam-ease-standard. Products that own the state can set data-collapsed instead. Remembering the choice across reloads is the product's job: render the checkbox with checked (or set data-collapsed) from the saved preference.
5. Panel: background-neutral-primary, border-width-1 border-neutral-tertiary, radius-rounded, depth-high-around (Figma depth/around/high). Header row: title (icon tile + h6) · search (background-neutral-quaternary) · branch pill (radius-pill) · global menu (cart, notifications, user, menu).
6. Below md the sidebar hides; the header menu button opens it as an overlay.