App shell

The frame around every signed-in screen: a sidebar with the brand tile and grouped navigation, and a blurred glass header with the account menu at its top right. Your own pages render in the main area. Here it holds the home page that buildpad init generates.

What generates this

buildpad init installs the design-system module. It writes components/layout/AuthenticatedShell.tsx from packages/cli/templates/components/layout/AuthenticatedShell.tsx, the sidebar entries in components/layout/navigation.ts, and the .bp-* shell styles in app/globals.css. It also writes the home page, app/[lang]/(authenticated)/page.tsx, from packages/cli/templates/app/authenticated-page.tsx.
buildpad add api-routes adds app/[lang]/(authenticated)/layout.tsx. That layout wraps every page in the route group with the shell. Route modules such as buildpad add users-routes add their own sidebar entries.

Home screen

The generated home page, inside the full shell.

Northwind Ops

Home

Welcome

You're signed in. This is your app home, rendered inside the AuthenticatedShell. Customize the sidebar nav and brand in app/[lang]/(authenticated)/layout.tsx.

Next steps

Install components with npx buildpad add, then build your screens under app/[lang]/(authenticated)/.

Home, desktop. The sidebar (.bp-navbar, 260px in the app) and the 60px glass header (.bp-header) around AppShell.Main. The page itself is the whole generated home: a Title, an intro and one Card with the ink CTA beside a variant="light" color="secondary" button. See the Dashboard template for a populated screen.

Header anatomy

The breadcrumb on the left and the actions on the right, ending with the account menu. Search, notifications and the language switcher can each be turned off with a prop on AuthenticatedShell. In a workspace with several locales the shell adds a LanguageSwitcher, and a ScopeSwitcher passed through headerActions lets a user in several scopes switch between them.

Northwind Ops

Home

Header bar.bp-header: 60px, backdrop-filter: blur(12px) over an 80% white (75% ink in dark) fill with a hairline --ds-border-color bottom edge. It stays pinned while the page scrolls under it.

Northwind Ops

Home

Multi-locale, multi-scope workspaceA ScopeSwitcher passed through headerActions (a size="sm" Select, 220px wide), then the LanguageSwitcher the shell adds once buildpad init --locales sets more than one locale (size="xs", 150px, language icon). The scope select hides itself when the user has a single scope. The search pill is left out and the account menu shown as its avatar so the strip fits.

Northwind Ops

Home

1 · BreadcrumbBrand name, then the active nav item's label in fw=600. Routes outside the sidebar fall back to their first path segment, title-cased.

2 · Search ⌘K.bp-search-button: a pill on --ds-gray-50 with a mono .bp-search-kbd hint. It is presentational only, so wire it to your own search. It is hidden at 768px and below; turn it off with showSearch={false}.

3 · NotificationsSubtle gray ActionIcon with a --ds-danger-500 dot ringed in the surface colour, and a Tooltip (pinned open here). Turn it off with showNotifications={false}.

In light mode

In dark mode

4 · Theme toggleColorSchemeToggle: shows a moon in light mode and a sun in dark mode. Its tooltip names the scheme it switches to. Hover the icons to see it.

5 · Account menu.bp-header-user-button at the far right: the user's Avatar with a --ds-primary-200 ring, then their name and a chevron from sm up (the avatar alone on a phone). It washes to --ds-gray-100 on hover and while open. Click it to open the menu.

No scope assigned — contact your administrator.

No scope accessWhen the user is assigned to no scope, ScopeSwitcher renders a compact color="orange" Alert (p="xs") in its place. A failed scope request shows the same alert in red.

Sidebar anatomy

The brand tile and the grouped navigation (entries without a section go under “Main Menu”).

6 · Brand tile.bp-brand-icon: the initial on the fixed --ds-brand-mark ember gradient with --ds-cta-shadow. The name is set in Inter Tight. Change it with the brand prop.

7 · Sections & linksUppercase dimmed section labels. .bp-nav-link hovers to --ds-gray-100. The active link gets a --ds-primary-50 wash, a hairline --ds-primary-200 ring and an ember icon.

The account menu opens under the avatar at the top right of the header.

Northwind Ops

Home

Account menuMenu position="bottom-end" offset={8} shadow="md" width={240}, right-aligned under the trigger. It opens with the user's name and email, since the trigger shows only the name. Account details and Workspace Settings ship disabled until you build those screens. Logout is a color="red" item that calls /api/auth/logout.

On a phone

Below the sm breakpoint the sidebar collapses behind a burger. Opening it covers the page under the header.

Northwind Ops

Home

Welcome

You're signed in. This is your app home, rendered inside the AuthenticatedShell. Customize the sidebar nav and brand in app/[lang]/(authenticated)/layout.tsx.

Next steps

Install components with npx buildpad add, then build your screens under app/[lang]/(authenticated)/.

Collapsed. Below sm the sidebar is hidden and a Burger leads the header. The search pill drops out at 768px and below, and the account menu shows just the avatar. Tap the burger to open the navigation.

Northwind Ops

Home

Welcome

You're signed in. This is your app home, rendered inside the AuthenticatedShell. Customize the sidebar nav and brand in app/[lang]/(authenticated)/layout.tsx.

Next steps

Install components with npx buildpad add, then build your screens under app/[lang]/(authenticated)/.

Navigation open. AppShell.Navbar fills the width under the header, with the same brand tile and sections. In the app, choosing a link closes it.

Built from

Navigation: sidebar links, the active state and Burger
Overlays: the account Menu and the header Tooltips
Selection: the scope and language Selects
Feedback: the no-scope Alert
Buttons: subtle ActionIcons, the ink CTA and variant="light" color="secondary"
Data display: Avatar and Card
Typography: the Inter Tight brand name, Title and dimmed Text
Layout: Stack, Group and Divider
Page sections pattern: page headers and content blocks for the main area
Foundations: --ds-brand-mark, --ds-primary-50 / -200, --ds-border-color and --ds-gray-50