AppShell
The dashboard frame: skip link, the sidebar slot (which keeps its width while the aside itself is fixed to the viewport), the main column (header, then <main>), and the phone tab bar + nav sheet. Three tiers (decision Q4): >1024 full sidebar, 860–1024 a 72px icon rail that expands over the content (Escape or the scrim closes it), <860 no sidebar: a tab bar, the header's menu button and a modal sheet (with the sidebar's card and user row, so they stay reachable). Picking a destination closes every overlay. No routing, fetching or app types inside: the nav is data and onNavigate reports the pick.
import { AppShell } from '@ergasti/bricks';Examples
A whole app frame
Sidebar, header and content area; the sidebar becomes an icon rail on tablets and a bottom bar with a "More" sheet on phones. The frame here is contained and sized to a desktop.
Code
import { useState } from 'react';
import { AppHeader, AppShell, Button, Card, SidebarCard, useLanguage, type NavItem } from '@ergasti/bricks';
import { brandMark, brandNav } from './nav';
function Frame() {
const language = useLanguage();
const [active, setActive] = useState('home');
const item = brandNav.flatMap((g) => g.items).find((i) => i.id === active);
const title = item ? (typeof item.label === 'string' ? item.label : item.label[language]) : '';
return (
<AppShell
brand={brandMark}
nav={brandNav}
activeId={active}
onNavigate={(next: NavItem) => setActive(next.id)}
header={<AppHeader title={title} subtitle={language === 'ar' ? 'اللي مستنيك النهارده' : 'What needs you today'} />}
sidebarCard={<SidebarCard title={language === 'ar' ? 'محتاج مساعدة؟' : 'Need a hand?'} action={<Button size="sm">{language === 'ar' ? 'كلّم TRNDR' : 'Contact TRNDR'}</Button>}>{language === 'ar' ? 'مدير حسابك بيتابع معاك.' : 'Your account manager handles approvals for you.'}</SidebarCard>}
>
<Card><Card.Header title={title} sub="The page content goes here." /></Card>
</AppShell>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses AppShell. Written in docs/content/components/AppShell.md; the props above are read from the code, which wins where the two disagree.
The dashboard frame: skip link, the dark sidebar (or icon rail, or phone tab bar and nav sheet), the header slot and the <main> region; use it once at the root of every Brand dashboard and PR Portal screen.
It is both mocks' .app layout: a fixed 252px dark sidebar (248px in the PR theme) beside a main column with the top bar and the page. It adapts across three tiers (decision Q4): above 1024px the full sidebar; 860–1024px a 72px icon rail that expands over the content; under 860px no sidebar, a bottom tab bar, a menu button in the header and a modal nav sheet. It does no routing or fetching: the nav is data and onNavigate reports the pick.
Anatomy
- Skip link (
.kit-shell-skip): "Skip to main content", visible on focus, moves focus to<main>without touching the URL. - Sidebar slot (
.kit-shell-slot): reserves the sidebar width while theSidebaritself is fixed to the viewport (top to bottom, scrolls on its own). - Main column (
.kit-shell-col, padding--shell-main-pad, 24px 32px 56px): theheader(AppHeader), then<main id="main-content" tabIndex={-1}>(.kit-shell-main, a 16px-gap column). - Tablet: the rail, its expand/collapse toggle and, while expanded, a scrim.
- Phone:
BottomNav(fixed, 64px) andMobileNavSheet.
Variants
| Tier | Width | Navigation | How to get it |
|---|---|---|---|
desktop | > 1024px | Full sidebar with brand, nav, sidebarCard, sidebarFooter | Automatic, or tier="desktop". |
tablet | 860–1024px | 72px icon rail; toggle expands it over the content (shadow, scrim; Escape or the scrim closes) | Automatic, or tier="tablet". |
mobile | < 860px | Bottom tab bar (four items + More), header menu button, nav sheet with sheetFooter | Automatic, or tier="mobile". |
| PR Portal look | — | 248px sidebar, PR nav colours | Wrap in data-bricks-theme="pr". |
States
| State | How |
|---|---|
| Active destination | activeId (the item gets aria-current="page"). |
| Route change | When routeKey (default activeId) changes, focus moves to <main> (not on first render). |
| Rail expanded | Tablet toggle; picking an item or leaving the tier collapses it. |
| Sheet open | Phone menu button or More; picking an item closes it. Leaving the tier closes it. |
| Empty screen | Render EmptyView as the children (story EmptyScreen). |
Types
ShellBrand (brand): { mark?, name, label, tagline? }: the sidebar's brand block and the sheet's title.
ViewportTier (tier): 'desktop' | 'tablet' | 'mobile'.
Usage
const nav: NavGroup[] = [
{ id: 'main', items: [
{ id: 'home', label: { en: 'Home', ar: 'الرئيسية' }, icon: 'home' },
{ id: 'find', label: { en: 'Find creators', ar: 'اكتشف صنّاع المحتوى' }, icon: 'find', badge: { label: { en: 'NEW', ar: 'جديد' }, tone: 'new' } },
{ id: 'creators', label: { en: 'Creators', ar: 'صنّاع المحتوى' }, icon: 'creators', count: 304 },
{ id: 'coupons', label: { en: 'Coupons', ar: 'الكوبونات' }, icon: 'coupons', count: 304 },
{ id: 'motivation', label: { en: 'Motivation', ar: 'التحفيز' }, icon: 'motivation', count: 2 },
{ id: 'payments', label: { en: 'Payments', ar: 'المدفوعات' }, icon: 'payments' },
{ id: 'analytics', label: { en: 'Analytics', ar: 'التحليلات' }, icon: 'analytics' },
{ id: 'log', label: { en: 'Activity log', ar: 'سجل النشاط' }, icon: 'log' },
{ id: 'settings', label: { en: 'Settings', ar: 'الإعدادات' }, icon: 'settings' },
] },
];
<BricksProvider preset={trndrPreset} language={language}>
<AppShell
brand={{ name: <>TRNDR<span className="kit-shell-accent">.</span>HushUp</>, label: 'TRNDR.HushUp', tagline: 'Brand dashboard' }}
nav={nav}
activeId={route}
onNavigate={(item) => navigate(`/${item.id}`)}
header={<AppHeader title="Home" subtitle="What needs you today, and what the program earned" onToggleLanguage={toggle} />}
sidebarCard={<SidebarCard title="Need a hand?" action={<Button size="sm">Contact TRNDR</Button>}>Your TRNDR account manager handles approvals, coupons and payouts for you.</SidebarCard>}
sheetFooter={<LogoutButton onLogout={signOut}>Sign out</LogoutButton>}
>
<KpiGrid>…</KpiGrid>
<div className="scr-grid scr-grid--2">…</div>
</AppShell>
</BricksProvider>import { AppHeader, AppShell, Avatar, Icon, LogoutButton, SidebarUser, type NavGroup, type NavItem, type ShellBrand } from '@ergasti/bricks';
declare const PR_NAV: NavGroup[];
declare const prBrand: ShellBrand;
// PR Portal: the theme, a nav with headings and indented children, a user row at the bottom
export function PrFrame({ go, signOut, children }: { go: (item: NavItem) => void; signOut: () => void; children: React.ReactNode }) {
return (
<div data-bricks-theme="pr">
<AppShell brand={prBrand} nav={PR_NAV} activeId="challenges" onNavigate={go}
header={<AppHeader breadcrumbs={<><a href="/programs">Campaigns</a> / Challenges</>} title="Challenges" />}
sidebarFooter={<SidebarUser avatar={<Avatar name="Mona Adel" seed={1} size="sm" />} name="Mona Adel" detail="PR team"
action={<LogoutButton className="kit-shell-me-out" onLogout={signOut}><Icon name="logout" /><span className="kit-sr">Sign out</span></LogoutButton>} />}>
{children}
</AppShell>
</div>
);
}Where it appears
- Every Brand dashboard screen. Screens: Home, Find creators, Creators, Coupons, Motivation, Payments › Wallet, Analytics, Settings, and Build an app frame (the minimal pattern).
- Every PR Portal screen (
PrScreenFrame). Screens: PR · Home, PR · Approvals, PR · Brands, PR · Brand, PR · Creators, PR · Tiers, PR · Affiliate programs, PR · Gift stock, PR · Gift analytics.
Guidelines
Do
- Keep the nav as data; route in
onNavigate. - Pass
headerrather than renderingAppHeaderinside the children, so it sits above<main>. - Give every top-level item an icon, so the rail and tab bar have glyphs.
- Use
routeKeywhen the view changes withoutactiveIdchanging (a drawer route, a tab).
Don't
- Don't nest shells or put the shell in a scrolling container: the sidebar and tab bar are fixed to the viewport.
- Don't put more than four items in
bottomNavIds. - Don't hide nav items per tier; the sheet always has the whole nav.
RTL and Arabic
language="ar"setsdir="rtl"andlang="ar"on the frame: the sidebar moves to the right, the sheet slides from the right, the rail toggle glyph mirrors.- Nav labels take
{ en, ar }; headings drop uppercase and letter-spacing in Arabic.
Tokens
--sidebar-width-desktop (252px; PR 248px), --sidebar-width-rail (72px), --bottom-nav-height (64px), --shell-main-pad, --shell-top-offset, --shell-side-bg / --color-sidebar, --shell-side-ink, --shadow-drawer, --card, --ink, --rasp (skip link border).
Accessibility
- Landmarks: the sidebar
<nav aria-label="Sidebar navigation">, the header's<header>,<main>, and on phones<nav aria-label="Bottom navigation">. - Skip link first in tab order; focus moves to
<main>on route change so screen readers start at the new view. - The phone sheet is a modal dialog (focus trap, Escape, the page behind inert); the tablet rail closes on Escape.
- Nav items, sign-out and menu items are at least 44px tall on touch tiers (≤1024px). On desktop, nav items are about 42px (11px padding + a 14px × 1.45 line; about 40px in the PR theme, 10px padding).
Found in the source
- ARIA attributes set:
aria-label. - Keys the code handles: Escape.
- It moves focus in code.
- Its tests cover: “closes the expanded rail on Escape and on the scrim”; “has a skip link to the one main landmark, and following it focuses main without touching the hash”; “moves focus to main on a route change, not on the first render”; “routeKey drives the focus move when the route is finer than the nav item (a tab inside a screen)”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
Sidebar,NavGroups,BottomNav,MobileNavSheet: the parts it composes.AppHeader: theheaderslot.ScreenErrorBoundary: wrap each screen inside the shell so one crash keeps the frame.EmptyView: a screen with nothing yet.
See also: useViewportTier · useLanguage · SidebarCard · Button · Card · BrandMark
Source
src/shell/AppShell.tsx (line 59) on GitHub.