Skip to content
menu palettetanreidark_modetranslate

Color mode

Contrast

Design system

Showcase systems imitate other design systems to show how far Tanrei can go. They are examples, not designs Tanrei supports.

Copy linkEdit theme
palettetanrei

Color mode

Contrast

Design system

Showcase systems imitate other design systems to show how far Tanrei can go. They are examples, not designs Tanrei supports.

Copy linkEdit theme
Getting startedWebReactSwiftUIJetpack ComposeFlutterReact NativePresetsYour own design systemUsing Tanrei with AI agentsBrandDesign tokensDesign systems and customizationTheme StudioColorTypographyIconsShapeElevationMotionInteraction statesBehaviourLayoutSize and densityAccessibilityWordsColor tokensTypescale tokensShape tokensElevation tokensMotion tokensState tokensSpace and measure tokensComponentsButtonMain action buttonSegmented buttonShipped by cupertino, m3-likeButton groupButton with menuToolbarCopy buttonCheckboxRadio buttonSwitchChipMenuSliderSlider fieldCalendarDateTimePickerField groupRadio groupCheckbox groupSelectSelect fieldMenubarFile uploadFile picker AdvancedDrop zoneRatingText input AdvancedText fieldChip fieldFieldCombobox AdvancedCombobox fieldNumber input AdvancedNumber fieldColor input AdvancedColor fieldOne-time-code input AdvancedOne-time-code fieldEmbedded text input AdvancedChat composerCardDividerModal layer AdvancedDialogListList rowBottom sheetSide sheetCarouselCode blockTablePopoverStepsAccordionDescription listFigureApp shellPage headerTree viewTimelineImage previewHandleResizable frameSplit viewScroll areaSize transitionBadgeProgress indicatorMeterNumber tickerLoading indicatorSnackbarTooltipKeyboard shortcutTagInline codeCalloutAvatarEmpty stateTag groupSkeletonFile itemSwatchMarquee textTabsTab viewApp barNavigation barNavigation drawerSearchLinkPaginationPrevious and next linksStepperBreadcrumbsTable of contentsLink cardFAB menuShipped by m3-likeStatusHow Tanrei is builtContributingLicense and attribution
HomeComponentsApp shell

App shell

Frames a page or an app. It places a header, the navigation, the main content, an aside and a footer, decides from the window's width how each is shown, and lets a keyboard reach the content in one step.

content_copyView as Markdown
Category
Containment
Tokens
comp.app-shell
Level
Base

Overview

Web
tanrei-app-shell
schedule
SwiftUI
TanreiAppShell
radio_button_unchecked
Jetpack Compose
TanreiAppShell
radio_button_unchecked
Flutter
TanreiAppShell
radio_button_unchecked
React Native
AppShell
radio_button_unchecked

Generated from docs/status/status.json, specs/app-shell.spec.json

An app shell is the frame of a window. It places regions and draws none of their content: the header is your app bar, the navigation your navigation drawer, the footer your own layout. What the shell adds is what a hand-made frame forgets: the landmarks, one set of window widths, the space a sticky header takes from a link’s target, and a way past the frame for the keyboard.

A frame is a whole window, so this page has no live example of it: a shell drawn inside a page would take that page’s window class. The fixtures under Specs are listed with their props; each is drawn alone in a window of its own in the tests.

On the web it is <tanrei-app-shell> around your own regions. The element has no shadow root, so a <header> is the page’s banner and the one <main> its main landmark, read without script and by a crawler. The other platforms have not implemented it yet.

Usage

<link rel="stylesheet" href="@tanrei/web/app-shell.css" />

<tanrei-app-shell aside-order="before" aside-label="On this page">
  <a class="tanrei-link" data-standalone slot="skip-link" href="#main">Skip to content</a>
  <header slot="header">
    <tanrei-app-bar headline="Tanrei">
      <tanrei-button slot="navigation" data-app-shell-menu variant="text" label="Menu">
        <span slot="icon">menu</span>
      </tanrei-button>
    </tanrei-app-bar>
  </header>
  <tanrei-navigation-drawer slot="navigation" responsive collapsible label="Documentation">
    …
  </tanrei-navigation-drawer>
  <aside slot="aside">…</aside>
  <main id="main" tabindex="-1">…</main>
  <footer slot="footer">…</footer>
</tanrei-app-shell>

<script type="module">
  import '@tanrei/web/components/app-shell';
</script>
import { AppBar, AppShell, Button, NavigationDrawer } from '@tanrei/react';
import '@tanrei/web/app-shell.css';

<AppShell asideLabel="On this page" onWindowClassChange={(event) => setWindowClass(event.detail.windowClass)}>
  <a className="tanrei-link" data-standalone slot="skip-link" href="#main">Skip to content</a>
  <header slot="header">
    <AppBar headline="Tanrei">
      <Button slot="navigation" data-app-shell-menu variant="text" label="Menu"><span slot="icon">menu</span></Button>
    </AppBar>
  </header>
  <NavigationDrawer slot="navigation" responsive collapsible label="Documentation">…</NavigationDrawer>
  <main id="main" tabIndex={-1}>{children}</main>
  <aside slot="aside">…</aside>
  <footer slot="footer">…</footer>
</AppShell>

@tanrei/web/app-shell.css lays the whole frame out before any script runs, so a page rendered on a server does not move when the script arrives, and the skip link works with scripting off. The element adds the same stylesheet to the page by itself.

What you write

A region is a child with a slot attribute. The main region is the one <main> without one.

Region On the web The shell gives it
Skip link <a class="tanrei-link" data-standalone slot="skip-link" href="#main"> The first stop of the keyboard. It is drawn only while it has keyboard focus.
Announcement <div slot="announcement"> around a callout The frame’s whole width above the header.
Header <header slot="header"> around your app bar The whole width. It stays at the top while the page scrolls.
Navigation <tanrei-navigation-drawer slot="navigation" responsive> The start edge, in one of three presentations.
Main <main id="main" tabindex="-1"> Gutters, a width limit, and the skip link’s destination.
Aside <aside slot="aside">, or a side sheet The end edge in a wide window. Above or below the main content otherwise.
Footer <footer slot="footer"> The end of the page, gutters and space.
Navigation bar <tanrei-navigation-bar slot="navigation-bar"> The bottom edge, in a narrow window only.

Write the regions in the order a keyboard walks them: skip link, announcement, header, navigation, the aside when it comes before the main content, main, the aside when it comes after, footer, navigation bar. The stylesheet places them by name and never reorders focus. A region you leave out takes no space and adds no landmark.

Specs

Anatomy

Part Description
1 container The frame itself: the whole window (or the whole page), filled with the product's surface color. It carries no state and takes no input.
2 skip-link · optional A Link the product gives ("Skip to content") that the shell keeps out of sight until the keyboard reaches it, then shows in a small raised box at the top start corner of the window. The first thing the keyboard reaches; following it moves focus to the main region.
3 announcement · optional A strip across the top of the frame, above the header, for a notice that concerns the whole product (a callout the product places there: an outage, a new version, a page that is not translated).
4 header · optional The region across the top that names the product or the screen and holds its search and its actions: the product's app bar. The page's banner landmark.
5 menu-button · optional An icon-only Button the product puts in its header and marks as the shell's — or, in a frame whose header region is empty, gives in the menu-button slot, where it stands alone in the header's place and stays at the top of the window while the page scrolls, with no band around it (APS-34). The shell shows it in every window class (with menuButtonPlacement drawer, only while the navigation has no place in the layout). It opens and closes the navigation over the content, and where the navigation stands beside the content shows, hides or collapses it.
6 navigation · optional The region at the start edge that holds the product's destinations: a navigation drawer. Beside the main content in a wide window, its column of icons in a narrower one, and over the content in a narrow one — below the header, which stays in view and usable.
7 main The content the page is for, and the page's one main landmark. Inset from the frame by a gutter and, by default, no wider than a readable width.
8 aside · optional Content that supports the main content: an outline of the page, details of the selected thing, related links. Beside the main content at the end edge in a wide window, above or below it in a narrower one. A complementary landmark.
9 footer · optional The region at the end of the page for what belongs to the whole site: its links, its legal line, its language and theme controls. The page's content-information landmark. Shown while the product fills it and has not hidden it (footerHidden).
10 navigation-bar · optional The place at the bottom edge for a navigation bar, shown only in a narrow window, for a product whose three to five top-level destinations stay in reach of the thumb.
11 outline · optional The hairline the shell draws between two regions that touch, where the system parts things with a line and the region's own component draws none: above the footer, and at the edge of an aside that is not a side sheet.

Properties

Property Type Default Description
scroll page | main "page" What scrolls. page: the whole page scrolls in the window, the header stays at the top (headerPosition) and the navigation and the aside stay in view beside the content; the default, because it is what find-in-page, anchors, the back button's return to where the reader was, and a phone browser's collapsing bars are built for. main: the frame is exactly as tall as the window and only the main region scrolls inside it, for an app whose panes scroll apart from each other (a mail client, an editor).
headerPosition sticky | static "sticky" Whether the header stays at the top of the window while the page scrolls (sticky) or scrolls away with it (static: an article that should have the whole window). Ignored while scroll is main, where the header never moves.
mainWidth contained | full "contained" contained: the main region's content is no wider than the shell's readable width and is centred in the room the region has, for pages that are read. full: it takes all the room inside the gutters, for a table, a board, an editor.
asideOrder after | before "after" Where the aside stands in reading and focus order, and so where it is drawn when it is not beside the main content. after: it follows the main content and is drawn below it (related links, details). before: it precedes the main content and is drawn above it (an outline of the page, which is of use only before the page is read). Beside the main content it is drawn at the end edge either way.
footerHidden boolean false Whether the footer is left out of the frame although the product fills it: a screen that is a task rather than a page of the site (a checkout, a sign-in, an editor, a full-window map) keeps the site's footer markup and shows none. While true the footer takes no space, draws no line, is no landmark and has no stop in focus order, exactly as an empty footer region. The footer is shown only while the product fills the footer slot and this is false: footerHidden never makes a footer of an unfilled slot.
separation auto | divider | gap "auto" How regions that touch are told apart. auto takes the design system's choice through comp.app-shell.separation; divider draws the one hairline; gap draws nothing and leaves the regions' own spaces. It concerns only the edges the shell draws: a component in a region that has an edge of its own (an app bar, a navigation drawer, a side sheet) keeps it.
navigationOpen boolean false Whether the navigation is open: presented over the content — below the header — while it has no place of its own in the layout (or only its column), and shown beside the content while it stands there even where a person hid it. The menu button asks for true and, while it is true, for false; beside the content it asks for false as it hides the navigation and for true as it shows it again (NVD-106); closing the navigation makes it false. A change of the window's class keeps it.
menuButtonPlacement header | drawer "header" Where the one control that shows and hides the navigation lives. header: the menu button in the header, in every window class — it opens and closes the navigation over the content where the navigation has no place (or only its column), and where it stands beside the content hides it and shows it again (NVD-106); the default. drawer: the navigation drawer's own menu button (its first header button) collapses and expands it where it has a place, and the header's menu button is shown only where the navigation has none. WHILE the header region is empty the menu button of the menu-button slot is shown as drawer shows it, whatever this says (APS-34).
asideLabel string "" Names the aside for assistive technology, in the product's language ("On this page"). Required where the aside is filled and what it holds does not name itself (a side sheet is named by its headline).

Slots

Slot Description
default The main region: the page's content. A fixture's content string is plain text.
skip-link The skip link: a standalone Link whose destination is the main region, with the product's words ("Skip to content"). More than one may be given ("Skip to navigation"); each is shown while it has focus.
announcement The notice above the header: a callout the product places, drawn across the frame's width.
header The header: the product's app bar, with its search and its actions, and the menu button in its navigation slot.
menu-button The menu button of a frame whose header region is empty: the menu-button item, which the shell places alone in the header's place and keeps at the top of the window (APS-34). Not shown while the header region holds something, where the menu button belongs in the header. A fixture gives it as its menu-button item, not as a string.
navigation The navigation: a navigation drawer, which draws each of the three presentations itself. Anything else is placed beside the content where the navigation has a place and is not shown where it has none.
aside The aside: the product's supporting content, or a side sheet.
footer The footer: the product's own layout of links, a legal line and controls. The shell gives it a place and an inset and no anatomy.
navigation-bar A navigation bar for the bottom edge of a narrow window.

Events

Event Description
windowClassChange The shell decided the window's class for the first time, or the window's width changed it; carries compact, medium or expanded. A product switches what follows the class and has no setting of its own for it: a search's presentation, a side sheet's variant, the form of an outline.
navigationOpenChange The navigation asks to be presented over the content or to be put away: the menu button was activated while it was closed (true), or the open navigation closed — by its scrim, Escape, the platform's back, a drag, a destination that was activated, the menu button (false); and beside the content, the menu button hid a navigation that was open (false) or showed it again (true). A change of the window's class emits none. Carries the value asked for.

Items

The kinds of item the component repeats. A fixture lists its items in order; each platform names each kind in its own idiom.

menu-button

The one icon-only Button in the header — or, while the header region is empty, in the menu-button slot — that opens the navigation: a Button of the text variant and the medium size with the menu glyph and no label, unless the product sets otherwise, which the shell shows by menuButtonPlacement and does not restyle.

Property Type Default Description
label string "" Its accessible name ("Menu"), as the Button's label. Required.
Slot Description
icon Its glyph, as the Button's icon slot. A fixture item's content is this glyph.
Event Description
click The button was activated, as the Button's click. The shell answers it itself (APS-7); a product need not.
Spec Web SwiftUI Jetpack Compose Flutter React Native
Item tanrei-button TanreiButton TanreiButton TanreiButton Button
label · Property label label contentDescription semanticLabel accessibilityLabel
click · Event click action onClick onPressed onPress
Notes An icon-only <tanrei-button> anywhere inside the header region, marked with the data-app-shell-menu attribute: usually the app bar's slot="navigation" child. In a frame with no header region, the element's own child <tanrei-button slot="menu-button"> (APS-34): the slot is its mark. The glyph is its content. An icon-only TanreiButton in the header, marked .tanreiAppShellMenuButton(); the shell reads the mark from the environment and hides the button outside the modal presentation. An icon-only TanreiButton in the header with Modifier.tanreiAppShellMenuButton(); the shell draws it only in the modal presentation. An icon-only TanreiButton wrapped in TanreiAppShellMenuButton, placed in the header; the wrapper builds nothing outside the modal presentation. An icon-only Button element passed as menuButton; the shell hands it to the header through context (useAppShellMenuButton()) and renders it only in the modal presentation.

States

Behavior

Requirements in EARS form. Every platform implementation is tested against these ids.

ID Requirement
APS-1 THE app shell SHALL fill the window with comp.app-shell.container.color, hand everything it holds comp.app-shell.content.color as the platform's inherited foreground, and place its regions in this order: the announcement across the top; the header across the top below it (WHILE the header region is empty, the menu button of the menu-button slot alone in its place, APS-34); then a row that holds the navigation at the start edge, the main region, and the aside at the end edge; the footer across the bottom of the page; and the navigation bar across the bottom edge of the window. A region that holds nothing, and the footer WHILE footerHidden is true (APS-31), SHALL take no space, draw nothing and add no landmark, and the regions beside it SHALL take its room. THE app shell SHALL draw no elevation and no corner of its own.
APS-2 THE app shell SHALL give the window one of three classes by its width alone: compact WHILE the window is narrower than comp.app-shell.breakpoint.medium, medium WHILE it is at least that wide and narrower than comp.app-shell.breakpoint.expanded, and expanded WHILE it is at least comp.app-shell.breakpoint.expanded wide. It SHALL derive the class anew whenever the width changes, SHALL never store it, and SHALL NOT read the window's height, the device, the pointer or the orientation for it. WHERE the platform measures a window in a unit that grows with the reader's text size (the web's rem) the two widths SHALL be compared in that unit, so that enlarged text moves the frame to a narrower class before its columns become too narrow to read.
APS-3 WHEN the app shell first decides the window's class, and WHEN a change of the window's width changes it, THE app shell SHALL emit windowClassChange exactly once with the class, and SHALL make the present class known to everything it holds through the platform's own channel for inherited values, so that a component inside it can follow the class without measuring the window itself. A change of width inside one class SHALL emit nothing.
APS-4 THE app shell SHALL choose how the navigation is presented from the window's class: WHILE the class is expanded, beside the main region in the form the navigation drawer's expanded gives it (the standard presentation, NVD-53: its full form, its collapsed form, or — for a drawer a person hid there with the menu button, NVD-106 — no place at all, the main region taking its room); WHILE it is medium and what the navigation region holds has a collapsed form (a collapsible navigation drawer), as that collapsed form beside the main region, widening over the content WHILE navigationOpen is true (the column presentation); and otherwise with no place in the layout, presented over the content WHILE navigationOpen is true (the modal presentation). WHILE the header region holds something, the navigation presented over the content — in the column and in the modal presentation alike — SHALL be drawn inside the frame below the header, from the header's bottom edge (from the window's top edge WHILE a static header has scrolled out of view) to the window's bottom edge, and its scrim SHALL cover only that part of the frame, so that the header is never covered or dimmed (APS-7, APS-32); WHILE the header region is empty it SHALL be drawn as APS-34 says. A navigation drawer in the region SHALL be drawn in each presentation exactly as a responsive drawer draws it (NVD-53 to NVD-55), and the two SHALL never disagree, because comp.app-shell.breakpoint.medium and comp.app-shell.breakpoint.expanded and the two widths that drawer reads alias the same window classes of the system (sys.breakpoint.medium, sys.breakpoint.expanded). WHILE the presentation is modal and the region holds something that cannot present itself over the content THE app shell SHALL NOT show it, SHALL keep it from focus and from assistive technology, and in debug builds SHALL report that the navigation of a narrow window needs a navigation drawer.
APS-5 WHILE the navigation has a place in the layout THE app shell SHALL put it at the start edge of the row, as wide as what it holds draws itself (a navigation drawer's width in its present form) and never wider than the room the row leaves it — the window (its width as the page has it: less a scrollbar that takes room in it) less the main region's least width (its start and end insets, APS-8, and sys.target.touch between them) and less the aside WHILE the aside stands beside the main region (APS-9: comp.app-shell.aside.width, or a side sheet's own width as it is drawn, APS-10) — even where what it holds asks for more (a navigation drawer's least width included, NVD-97), so that neither the main region nor the aside is pushed past the window's end and the page never scrolls sideways (WCAG 1.4.10); THE app shell SHALL give the main region all the room that is left, and SHALL add no padding, fill or edge to it. WHEN that room changes (the window's width, an aside added or removed, a side sheet sliding in or out) the navigation SHALL be held to it in every frame it is drawn, with no motion of its own beyond what changes the room. WHILE scroll is page THE app shell SHALL keep the navigation in view while the page scrolls — from below the header WHILE the header is sticky, from below the menu button WHILE a frame without a header shows it (APS-34), else from the top of the window, to the window's bottom edge — and what it holds SHALL scroll inside that height by itself (NVD-61), never the page with it. WHEN the window's scrolling view is pulled past its start or its end (the platform's overscroll) the navigation SHALL stay where it is: only the page's content moves with the pull. WHILE a person changes the width of a navigation drawer the navigation holds (NVD-98 to NVD-101) THE app shell SHALL give the main region the room that is left in every frame the width changes, the main region moving with no motion of its own, and SHALL keep the reader at the same place in the main content as far as the new width allows, as APS-23 does when the class changes.
APS-6 WHILE menuButtonPlacement is header and the navigation region holds a navigation drawer THE app shell SHALL show the menu button where the product put it in the header in every window class and every presentation, whether the navigation is open or not. WHILE menuButtonPlacement is drawer THE app shell SHALL show it only WHILE the presentation is modal, and WHILE it is standard and the drawer is responsive and either has no collapsed form, whether it is shown or hidden, or is hidden there (NVD-106): a drawer with no collapsed form has no menu button of its own (NVD-37), so the control that shows it SHALL stay to hide it again, in the same place, and the control that hid a drawer SHALL stay to show it again; in the column presentation, and in the standard one for a collapsible drawer that is shown, the drawer's own menu button (NVD-37) stands for it. WHEN an activation of the menu button shows or hides a drawer beside the content THE app shell SHALL leave focus on the menu button, which stays where it is. WHERE that activation shows a collapsible drawer again and so takes the menu button away (WHILE menuButtonPlacement is drawer, or the header region is empty), THE app shell SHALL move focus that was on it to the drawer's own menu button (NVD-37), or else to the main region. WHILE the header region is empty THE app shell SHALL show the menu button of the menu-button slot as APS-34 says, whatever menuButtonPlacement says. WHILE the navigation region holds something other than a navigation drawer THE app shell SHALL show the menu button only WHILE the presentation is modal, where APS-4 reports it. WHILE the navigation region is empty, and wherever this sentence does not show it, THE app shell SHALL NOT show the menu button, SHALL keep it from focus and from assistive technology, and SHALL give its place to what is beside it. WHEN menuButtonPlacement names a value the app shell does not define it SHALL be treated as header. THE app shell SHALL NOT restyle the menu button: it SHALL render as the icon-only Button it is, from its own tokens, with its own press, focus ring and minimum target, and its glyph SHALL stay the same while the navigation is open — its expanded state, not its picture, tells that it is.
APS-7 WHEN the menu button is activated THE app shell SHALL ask the navigation drawer in the navigation region for what the drawer's own menu button asks (NVD-37), in every presentation: WHILE the presentation is standard, to hide the navigation where it is shown there and to show it again where it is hidden (NVD-106), whatever its form — the drawer applies it and reports it with standardHiddenChange, and THE app shell SHALL emit navigationOpenChange exactly once WHERE navigationOpen changes with it (false as a drawer that was open is hidden, true as one is shown) and make navigationOpen follow the drawer's open; the main region SHALL take the room the hidden navigation leaves, the drawer's slide resizing it, and nothing SHALL be made inert; WHILE it is column or modal and navigationOpen is false, to open — THE app shell SHALL then emit navigationOpenChange exactly once with true and become open (by setting navigationOpen itself on the web, through its binding where navigationOpen is one, and by the product setting it elsewhere), and the drawer SHALL present itself over the content below the header (APS-4, NVD-19) — over the whole window WHILE the header region is empty (APS-34) — taking focus; and WHILE navigationOpen is true, to close (NVD-20). WHILE the navigation is open over the content below the header THE app shell SHALL keep the announcement and the header as they are — drawn, reachable by pointer and keyboard and exposed to assistive technology, never inert — and SHALL make every other region inert to pointer, touch, keyboard and assistive technology (the skip link, the main region, the aside, the footer and the navigation bar), keeping the page from scrolling under the scrim as a modal layer does (MDL-2). WHEN the open navigation begins to close (NVD-20, NVD-21) THE app shell SHALL at once emit navigationOpenChange exactly once with false, navigationOpen SHALL become false the same way, and the regions it made inert SHALL stop being inert; focus moves as NVD-22 says, to the menu button where the menu button opened the navigation; its scrim is taken away at once (MOT-8), the drawer then leaves by its motion, and nothing SHALL change when that motion ends (NVD-22). THE app shell SHALL expose the menu button as expanded WHILE the navigation is open over the content, and in the standard presentation WHILE the drawer is shown there in either form, and as collapsed otherwise, controlling the navigation WHILE the navigation is shown — open over the content, or standing beside it in either form — and naming nothing WHILE it is not shown (modal and closed, or hidden beside the content), so that the button never names an element that is not exposed. WHEN the menu button hides or shows the navigation beside the content, focus SHALL stay on it (APS-6), and focus that was in the drawer SHALL move to it (NVD-106). A change of the window's class SHALL NOT change navigationOpen and SHALL emit no navigationOpenChange; WHILE the navigation stands beside the content and navigationOpen is true THE app shell SHALL make nothing inert, and WHEN the navigation is presented over the content again WHILE navigationOpen is true it SHALL make the regions under the scrim inert as an opening does (NVD-54 moves focus).
APS-8 THE app shell SHALL inset the main region's content from the region's start and end by the gutter of the window's class — comp.app-shell.gutter.compact, comp.app-shell.gutter.medium or comp.app-shell.gutter.expanded — and from its top and bottom by comp.app-shell.main.padding-block, except, WHILE scroll is page, on a side where an aside stands above or below it, where the two share comp.app-shell.aside.gap instead (APS-9). WHILE mainWidth is contained the content SHALL be no wider than comp.app-shell.main.max-width and SHALL be centred in the room the region has inside its gutters; WHILE mainWidth is full it SHALL take all of that room. THE main region SHALL never be wider than the room the row leaves it: content that cannot shrink (a table, a line of code) SHALL scroll inside its own box (PRS-15), and SHALL NOT widen the frame or make the page scroll sideways. WHILE the navigation region holds a navigation drawer that draws its resize handle beside its end edge (NVD-96) THE app shell SHALL inset the content of the main region, and of an aside stacked in its column, from the region's start by the greater of the gutter and the handle's target across that edge (sys.target.pointer for a fine pointer, sys.target.touch for touch or where the input type cannot be told, HDL-5), so that the target lies over that inset alone and a press meant for the main content never reaches the handle (WCAG 2.5.8); WHILE the drawer draws no handle (resizable false, or the drawer not beside the content) the gutter alone SHALL inset it.
APS-9 WHILE the window's class is expanded THE app shell SHALL place the aside beside the main region at the end edge of the row, comp.app-shell.aside.width wide, its content inset by comp.app-shell.aside.padding-inline at the start and the end and by comp.app-shell.main.padding-block at the top and the bottom, so that its first line stands level with the main content's; WHILE scroll is page it SHALL keep the aside in view while the page scrolls, as APS-5 says of the navigation, and the aside SHALL scroll inside that height by itself when its content is taller, and SHALL stay where it is WHEN the window's scrolling view is pulled past its start or its end. WHILE the class is medium or compact THE app shell SHALL place the aside in the main region's column, with the main region's gutters and, WHILE mainWidth is contained, its width and centring: above the main content WHILE asideOrder is before and below it WHILE asideOrder is after, comp.app-shell.aside.gap from it, scrolling with it. WHILE scroll is page that space SHALL take the place of the main region's inset on that side (APS-8) and SHALL be shared by the two regions, which meet in its middle, where the line of APS-18 stands: neither region's box SHALL reach into the other's, so that a press, a fill the product gives the main region and the outline assistive technology draws around a landmark keep to their own region.
APS-10 WHERE the aside holds a component that takes its own width in the layout and draws its own edge (a standard side sheet, SSH-1 and SSH-7) THE app shell SHALL give the aside that component's width in place of comp.app-shell.aside.width, SHALL add no inset to it and SHALL draw no edge beside it; WHERE it holds a component that presents itself over the content (a modal side sheet) the aside SHALL take no space in any class. THE app shell SHALL NOT change the variant of what the aside holds: a product that wants a sheet beside the content in an expanded window and over it in a narrower one sets the sheet's variant from windowClassChange.
APS-11 WHILE scroll is page THE app shell SHALL place the footer after the row of the navigation, the main region and the aside, across the frame's whole width, so that it is reached at the end of the page and the navigation and the aside stop staying in view where it begins; WHILE scroll is main THE app shell SHALL keep the footer at the bottom of the frame, below the row and above the navigation bar, always in view. THE app shell SHALL inset the footer's content by the gutter of the window's class (APS-8) at the start and the end and by comp.app-shell.footer.padding-block at the top and the bottom, and SHALL lay out nothing inside it: the footer's columns, links and controls are the product's.
APS-31 WHILE footerHidden is true THE app shell SHALL NOT show the footer, whatever the footer slot holds: the footer SHALL take no space, draw no line (APS-18), add no landmark (APS-21) and have no stop in focus order (APS-22), the regions beside it SHALL take its room, and WHILE scroll is page the navigation and the aside SHALL stay in view to the end of the page (APS-5, APS-9). WHILE footerHidden is false THE app shell SHALL show the footer exactly while the product fills the footer slot (APS-1, APS-11): it SHALL NOT draw a footer, or expose a content-information landmark, for a slot the product left unfilled. WHEN footerHidden changes THE app shell SHALL draw the new arrangement at once, without a motion of its own, SHALL keep what the footer slot holds as the product gave it, and IF keyboard focus is in the footer as it is hidden SHALL move focus to the main region.
APS-32 THE app shell SHALL draw each region in a stacking order of its own, so that nothing a region holds — whatever level its own stacking order (a z-index) gives it — is drawn over another region: WHILE scroll is page THE app shell SHALL draw the header and the navigation bar over every other region, the footer included, while the page scrolls under them, and SHALL draw the footer over the navigation and the aside. WHILE the navigation is presented over the content below the header (APS-4, APS-7) THE app shell SHALL draw the navigation and its scrim over the main region, the aside, the footer and the navigation bar and under the announcement and the header, within the frame's own stacking order and not in the platform's layer for overlays, so that the header is never covered or dimmed. WHILE the skip link has keyboard focus THE app shell SHALL draw it over every region (APS-19). THE app shell SHALL itself be one stacking order within the page, so that no level of its parts competes with what the product draws outside the frame. What stands over the whole frame — a menu, a popover, a tooltip, a snackbar, a dialog, a sheet, a modal drawer the app shell does not hold — SHALL be drawn above it by the platform's own layer for overlays, never by a level within a region.
APS-12 WHILE the announcement region holds something THE app shell SHALL place it across the frame's whole width above the header, with no inset of its own, in every class; WHILE scroll is page the announcement SHALL scroll away with the page and a sticky header SHALL then rest at the top of the window, and WHILE scroll is main it SHALL stay above the header. WHEN what the announcement holds is removed or closes (a callout whose open becomes false) THE app shell SHALL give its room back at once.
APS-13 WHILE the window's class is compact and the navigation-bar region holds something THE app shell SHALL keep it at the bottom edge of the window across the frame's whole width, over the bottom system inset as the bar itself lays out (NVB-18), in view while the page scrolls, and SHALL end the page, or the frame, above it so that nothing is covered by it; WHILE the class is medium or expanded THE app shell SHALL NOT show the navigation-bar region, SHALL keep it from focus and from assistive technology, and SHALL give it no space. THE app shell SHALL NOT choose between the bar and the navigation for the product: a product whose bar is its navigation in a compact window gives no menu button.
APS-14 WHILE scroll is page THE app shell SHALL be at least as tall as the window and as tall as its content, SHALL let the window's own scrolling view scroll the page, and SHALL make no region a scrolling view except the navigation and the aside where APS-5 and APS-9 keep them in view; so that the platform's find-in-page, a link to a place in the page, the return to where the reader was, and a browser's collapsing bars work as they do on a page without a shell.
APS-15 WHILE scroll is main THE app shell SHALL be exactly as tall as the window, less the on-screen keyboard where one covers it, SHALL keep the announcement, the header, the footer and the navigation bar in place, and SHALL make the main region the one scrolling view of the frame, reachable and scrollable from the keyboard, with the aside scrolling inside its own height WHILE it is beside the main region and with the main region WHILE it is above or below it. THE window itself SHALL NOT scroll.
APS-16 WHILE scroll is page and headerPosition is sticky THE app shell SHALL keep the header at the top of the window, above the main region, the navigation and the aside, while the page scrolls under it, and SHALL keep it there WHEN the window's scrolling view is pulled past its start or its end (the platform's overscroll): the content moves with the pull and the header does not; WHILE headerPosition is static the header SHALL scroll away with the page. THE app shell SHALL NOT fill, raise or edge the header: an app bar in it draws its own scrolled condition from the scrolling view it is connected to (APB-9), which is the window WHILE scroll is page and the main region WHILE scroll is main.
APS-17 THE app shell SHALL hold the height of what it keeps over the top of the scrolling view — a sticky header's present height, measured again whenever the header changes size, and nothing WHILE headerPosition is static — and SHALL make it known to the scrolling view and to everything it holds, so that a heading or any other place a link or the address moves the view to (PRS-23), and an element that takes keyboard focus, come to rest below the header and never under it; likewise for the navigation bar's height at the bottom; WHILE scroll is main nothing stands over the scrolling view, and those distances are nothing. THE app shell SHALL also make known, whatever scroll is, to what is drawn over the page (a snackbar, SNK-13, SNK-35) how far it reaches over the top of the window — to the bottom edge of the header, or of the menu button of a frame without a header, WHILE that stays in view (WHILE scroll is main it never moves, below an announcement too) — and over its bottom (the navigation bar's height WHILE the bar is shown), so that such a surface stands clear of them. A heading's own space before it (PRS-6) is added to that distance by the prose, not by the shell.
APS-18 WHILE separation is auto THE app shell SHALL part its regions as comp.app-shell.separation names, and WHILE separation is divider or gap as that value says, whatever the token says: divider draws a line comp.app-shell.outline.width thick in comp.app-shell.outline.color along the footer's top edge, along the start edge of an aside that stands beside the main region, and between the main content and an aside that stands above or below it, in the middle of comp.app-shell.aside.gap; gap draws no line and leaves the same spaces. The lines SHALL take no room of their own. THE app shell SHALL draw no line beside a region whose component draws its own edge (APS-10, APS-16) and none around the navigation, the announcement or the navigation bar. WHEN separation names a value the app shell does not define it SHALL be treated as auto.
APS-19 WHILE the skip-link region holds a Link THE app shell SHALL make it the first element the keyboard reaches in the frame, before the announcement and the header, SHALL draw nothing of it while it does not have keyboard focus and still keep it in the focus order and exposed to assistive technology, and WHILE it has keyboard focus SHALL draw it comp.app-shell.skip-link.offset from the top and the start edges of the window, inside the system insets, above every region and every sticky part: in a box filled with comp.app-shell.skip-link.container.color and raised by comp.app-shell.skip-link.container.elevation, with corners comp.app-shell.skip-link.container.shape eased by sys.shape.corner-smoothing, padded by comp.app-shell.skip-link.container.padding-inline and comp.app-shell.skip-link.container.padding-block, its text in comp.app-shell.skip-link.label.typescale; the Link SHALL keep its own color, underline, focus ring and states (LNK-1). The box SHALL appear and go at once, without motion, and SHALL move no other part of the frame.
APS-20 WHEN the skip link is followed THE app shell SHALL move keyboard focus to the main region itself — not to the first control in it — and bring the region's top into view below the header (APS-17) at once, without a scrolling motion, so that the next Tab reaches the first focusable element of the content and a screen reader starts reading there; the main region SHALL take focus only this way and SHALL NOT be a stop of the Tab order.
APS-21 THE app shell SHALL expose each filled region as the landmark it is: the header as the page's banner, the navigation and the navigation bar as what they hold expose (a navigation landmark named by its own label), the main region as the page's one main landmark, the aside as a complementary landmark named by asideLabel (or by what it holds, where that names itself), and the footer as the page's content information; the announcement, the skip link and the menu button of the menu-button slot SHALL add no landmark. IF the frame holds no main region, or more than one, or an aside that has no name, THE app shell SHALL still lay out what it holds, and in debug builds SHALL report it.
APS-22 THE app shell SHALL NOT be focusable and SHALL move focus through its regions in reading order, the same in every class and in either layout direction: the skip link, the announcement, the header (WHILE it is empty, the menu button of the menu-button slot, APS-34), the navigation, the aside WHILE asideOrder is before, the main region's content, the aside WHILE asideOrder is after, the footer, the navigation bar. A region that is not shown (APS-4, APS-6, APS-13, APS-31), and WHILE the navigation is open over the content below the header a region the app shell makes inert (APS-7), SHALL have no stop in that order. THE app shell SHALL NOT keep focus inside any region: WHILE the navigation is open over the content below the header, Tab and Shift+Tab SHALL move through the announcement, the header and the navigation in that order and on to what the platform has beyond the frame, and never reach what lies under the scrim. Only an overlay that stands over the whole frame (APS-32) holds focus inside itself.
APS-23 WHEN the window's class changes THE app shell SHALL draw the new arrangement of every region but the navigation at once, without a motion of its own, and SHALL let the navigation drawer move from its place in the old presentation to its place in the new one by the drawer's own motion (NVD-54), drawn over the main region where the two overlap while it moves; SHALL keep scroll, headerPosition, mainWidth, asideOrder, footerHidden, separation and menuButtonPlacement as they are, and navigationOpen (APS-7, NVD-54); SHALL keep the reader at the same place in the main content as far as the new arrangement allows; and IF keyboard focus is on something the new arrangement does not show (a navigation bar's destination, a menu button that menuButtonPlacement drawer hides) SHALL move it to the main region, unless the navigation it holds has already moved it (NVD-54). WHERE motion is reduced the navigation SHALL take its new place as MOT-6 says, its change of size at once.
APS-24 WHERE the app shell is rendered before the window's width is known or before its own code runs (a page rendered on a server) THE app shell SHALL already be laid out for the window's class by the platform's layout alone — every region in its place, the regions that the class does not show taking no space, the skip link first and working — SHALL present nothing over the content, SHALL make nothing inert, and SHALL emit no event until the class is decided; its own code SHALL then add only what layout cannot: the events, the menu button's opening of the navigation, and the measured distance of APS-17, without moving anything that was already drawn. WHERE a navigation drawer in the navigation region is rendered before its own code runs THE app shell SHALL give it, in an expanded window, the place it will take once its code runs: its expanded width held as NVD-97 holds it (the width the product gave it, between its least and its greatest width); its collapsed column (comp.navigation-drawer.collapsed.container.width.medium, or .compact WHILE density is compact) WHILE it is collapsible and expanded is false or its variant is modal (NVD-30); and no space WHILE it is responsive, standardHidden is true and open is false (NVD-106).
APS-25 WHILE the text size is enlarged THE app shell SHALL keep its gutters and insets, let every region grow with its text, and SHALL need no scrolling in two directions at any width down to 320 points: in a compact window the frame is one column, the main region never narrower than the window less two gutters, and only a block that scrolls in its own box (APS-8) scrolls sideways. THE app shell SHALL NOT fix the height of any region.
APS-26 WHERE the platform's forced-colors or increased-contrast mode replaces the product's colors THE app shell SHALL let the system's colors fill its frame, SHALL draw the lines of APS-18 in the system's text color WHILE they are drawn, and SHALL draw an edge comp.app-shell.outline.width thick in the system's text color around the skip link's box, because the mode removes the fill and the elevation that set it apart.
APS-27 THE app shell SHALL extend its fill under every system inset (status bar, camera cutout, home indicator, window caption) and SHALL keep the main region's, the aside's and the footer's content inside the start, end and bottom insets; the header, the navigation and the navigation bar lay themselves out over the insets at their own edges (APB-10, NVD-25, NVB-18), and the app shell SHALL NOT inset them a second time.
APS-28 THE app shell SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the app shell is shown THE app shell SHALL draw itself for the new direction at once, without a motion of its own, keeping the window's class, navigationOpen and the reader's place in the content. WHERE the layout direction is right-to-left the navigation SHALL stand at the right edge and the aside at the left, the skip link's box at the top right, the menu button where the header puts its start, and the lines of APS-18 on the mirrored edges; the order of APS-22 SHALL NOT change, and nothing a region holds SHALL be mirrored by the shell.
APS-29 WHEN scroll, headerPosition, mainWidth or asideOrder names a value the app shell does not define THE app shell SHALL render with that prop's default, and in debug builds report the unknown value.
APS-30 THE app shell SHALL NOT restyle, resize or re-order what the product puts in a region beyond the place and the insets this spec gives, SHALL NOT decide which page is shown, follow a link, load anything, remember anything beyond its own lifetime (which page, how far a region was scrolled, whether the navigation was collapsed, how wide a person made it) or set the document's title or language; and SHALL NOT scroll anything with motion: every movement it causes (APS-17, APS-20, APS-23) is at once, whether or not motion is reduced.
APS-33 WHILE the navigation region holds a navigation drawer whose filterable is true and whose filterShortcut holds exactly one chord, and either the navigation's presentation is modal and navigationOpen is false or it is standard and the drawer is hidden there (NVD-106), WHEN the person presses that chord anywhere in the window — read as SRC-38 reads a chord and with its exceptions (a press something else has taken, a key repeating while held, an input-method composition and, for a chord without mod, ctrl or alt, focus in an element that takes text) — THE app shell SHALL keep the press from doing anything else, open the navigation as an activation of the menu button does (APS-7: navigationOpenChange with true; where the drawer is hidden beside the content, its standardHidden becoming false), and ask the drawer to focus its filter (NVD-88), so that focus is in the drawer's filter field once it is open. WHILE the drawer is shown — beside the main region, or as its column — the drawer answers the chord itself (NVD-87) and THE app shell SHALL NOT. THE app shell SHALL bind no other key for the navigation.
APS-34 WHILE the header region is empty THE app shell SHALL take the menu button from the menu-button slot and SHALL show it only where APS-6 shows the menu button WHILE menuButtonPlacement is drawer, whatever menuButtonPlacement says — WHILE the navigation's presentation is modal, and WHILE it is standard and the drawer is responsive and either has no collapsed form, whether it is shown or hidden, or is hidden there (NVD-106): in the column presentation, and in the standard one for any other navigation, the navigation stands at the start edge from the top of the frame, below the announcement, to the window's bottom edge (APS-5), and a navigation drawer's own menu button (NVD-37) stands for the shell's. WHILE it is shown THE app shell SHALL place the menu button alone in the header's place — below the announcement, at the start edge of the frame — inset from the top of that place and from the frame's start edge by the gutter of the window's class (APS-8) and kept inside the system insets, SHALL draw no band, fill, edge or elevation around it, and SHALL begin the navigation, the main region and the aside below it, so that the button that shows a drawer beside the content stays in the same place, never covered by the drawer, to hide it again. WHILE scroll is page THE app shell SHALL keep the menu button at the top of the window, the gutter from its top edge, while the page scrolls under it — once an announcement above it has scrolled away (APS-12) — whatever headerPosition says, SHALL draw it over every other region as it draws a sticky header (APS-32), and SHALL keep it where it is WHEN the window's scrolling view is pulled past its start or its end (the platform's overscroll): only the content moves with the pull. WHILE scroll is main it SHALL stay in its place above the main region. THE app shell SHALL hold the gutter above the menu button and its height as what it keeps over the top of the scrolling view, as APS-17 holds a sticky header's, so that an anchor's target and a focused element come to rest below it. The menu button SHALL add no landmark and no region (APS-21), SHALL be reached in the header's place in the order of APS-22, and SHALL keep its keys; activating it SHALL open and close the navigation, or show and hide a drawer beside the content, as APS-7 says, focus staying on it where the drawer stands beside the content as APS-6 says. WHILE the navigation is open over the content THE app shell SHALL let the navigation drawer present itself as it does outside a frame that has a header (NVD-19): over the whole window from its top edge to its bottom edge, its scrim over the menu button and every region, keeping focus inside it and making what lies behind it inert while it is open, and returning focus to the menu button when it closes (NVD-22). WHILE the header region holds something THE app shell SHALL NOT show what the menu-button slot holds, SHALL keep it from focus and from assistive technology, and in debug builds SHALL report that the menu button of a frame with a header belongs in the header.

Platform name mapping

Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.

Spec Web SwiftUI Jetpack Compose Flutter React Native
Component tanrei-app-shell TanreiAppShell TanreiAppShell TanreiAppShell AppShell
scroll · Property scroll scroll scroll scroll scroll
headerPosition · Property headerPosition headerPosition headerPosition headerPosition headerPosition
mainWidth · Property mainWidth mainWidth mainWidth mainWidth mainWidth
asideOrder · Property asideOrder asideOrder asideOrder asideOrder asideOrder
footerHidden · Property footerHidden isFooterHidden footerHidden footerHidden footerHidden
separation · Property separation separation separation separation separation
navigationOpen · Property navigationOpen isNavigationPresented navigationOpen navigationOpen navigationOpen
menuButtonPlacement · Property menuButtonPlacement menuButtonPlacement menuButtonPlacement menuButtonPlacement menuButtonPlacement
asideLabel · Property asideLabel asideLabel asideLabel asideSemanticLabel asideLabel
windowClassChange · Event windowclasschange onWindowClassChange onWindowClassChange onWindowClassChanged onWindowClassChange
navigationOpenChange · Event navigationopenchange isNavigationPresented onNavigationOpenChange onNavigationOpenChanged onNavigationOpenChange
Notes An element and a stylesheet: <tanrei-app-shell> attaches no shadow root, and the package's @tanrei/web/app-shell.css lays out its light-DOM children from the element's name, its attributes and each child's slot attribute alone, so a page rendered on a server is laid out before the element is defined and with scripts off (APS-24). The regions are the product's own semantic elements: <a class="tanrei-link" data-standalone slot="skip-link" href="#main">, <div slot="announcement">, <header slot="header"> around a <tanrei-app-bar>, <tanrei-navigation-drawer slot="navigation" responsive>, the one <main id="main" tabindex="-1"> child without a slot (the default region), <aside slot="aside" aria-label="…">, <footer slot="footer"> and <tanrei-navigation-bar slot="navigation-bar"> (and, in a frame without a header, <tanrei-button slot="menu-button"> in the header's place), written in the order of APS-22; the stylesheet places them on a grid by name and never reorders focus. Attributes: scroll, header-position, main-width, aside-order, footer-hidden, separation, navigation-open, menu-button-placement, aside-label. The window's class is chosen by @media conditions in rem; a custom property cannot stand in a media condition, so the generator writes the two widths into the stylesheet from the active system's tokens (one stylesheet per system that changes them). The menu button is shown at every width while menu-button-placement is header (the default) and the navigation region holds a <tanrei-navigation-drawer>; otherwise it is hidden by the same conditions, with :has(> [slot="navigation"][collapsible]) telling the column presentation from the modal one, and shown again in an expanded window while :has(> tanrei-navigation-drawer[slot="navigation"][responsive]:is(:not([collapsible]), [standard-hidden]:not([open]))) finds a drawer with no collapsed form, shown or hidden, or one a person hid beside the content (APS-6, NVD-106). With no header region the menu button of the menu-button slot is shown by the same conditions as for menu-button-placement="drawer" (APS-34), stands in the header's grid row with justify-self: start, and is position: sticky at the class's gutter (plus env(safe-area-inset-top)) from the top, with a block-start margin of the same so that it rests where it sticks, at z-index: 3 as the header; the element measures it and publishes that margin and its height as the scroll offset (APS-17). A menu-button child of a frame that has a header is display: none, and the element reports it in debug builds. The drawer of a frame without a header is not held by it (NVD-19): it is the top-layer modal <dialog> over the whole window. The parts that stay in view while the page scrolls — the header while header-position is sticky, the menu button of a frame without a header, the navigation and the aside — are position: sticky; the web does not yet follow the part of APS-5, APS-9, APS-16 and APS-34 that keeps them where they are when the document's scroller is pulled past an end: a browser moves a sticky box that is not stuck with the pull, and holds only a position: fixed one still, and the fixed boxes would need the header to rest below an announcement until the page has scrolled past it and the navigation and the aside to end where the footer begins, which takes positioning that follows the scroll (scroll-driven animations are not in every engine, and the element listens to no scroll). The frame and each region are isolation: isolate (APS-32); the footer and the navigation bar are z-index: 1 (the bar comes after the footer, so over it), a navigation drawer that stands over the content — open over it below the header, closing, or moving to a new presentation (the drawer's data-over state attribute) — 2, the header 3 and the focused skip link 4 — levels within the frame, which no z-index inside a region reaches; a navigation drawer that draws its resize handle carries the data-resize state attribute, and while the frame holds one (:has(), asked of the frame) the main region's start padding and a stacked aside's start margin are at least sys.target.pointer, or sys.target.touch under (pointer: coarse) — the drawer's own condition for its handle's target — and, before the drawer is defined, in an expanded window the stylesheet reads the same from its attributes alone (resizable not "false", no variant="modal", and not a responsive drawer written standard-hidden without open) (APS-8, APS-24); the navigation and the aside are align-self: start with a maximum block size of the dynamic viewport height less the scroll offset and overflow: auto with overscroll-behavior: contain; once the element is defined, a non-passive wheel listener on each of them (on the navigation where it is not a navigation drawer, which keeps its own) cancels a wheel turned toward an end the region already stands at, since Gecko keeps to contain only within one wheel transaction and would give a wheel at the end after a pause to the page. scroll="main" makes the host 100dvh high and the <main> the scroller. It does not yet follow the part of APS-15 that has an aside above or below the main region scroll with it: a stylesheet cannot make the <main> and its sibling <aside slot="aside"> one scrolling view, and making the frame itself the scroller in that arrangement would take the scrolling view away from the <main> that the app bar's scroll-target (APS-16) and the skip link (APS-17, APS-20) name, and would need the announcement's and the navigation bar's heights before the element is defined (APS-24). Until it does, a product that uses scroll="main" and wants the aside to scroll with the content in a compact or medium window writes that content inside the <main> for those classes. The stylesheet defines --tanrei-app-shell-scroll-offset on the document's root (until the element is defined: the small app bar's height while the header is sticky, else 0) and sets the root's scroll-padding-block-start from it — or the main element's while scroll is main; once defined, the element measures the header with a ResizeObserver and rewrites the property. The product's own sticky parts (a table's header row) read the same property. What the frame keeps over the window, whatever scrolls (APS-17), is --tanrei-app-shell-window-inset-top and --tanrei-app-shell-window-inset-bottom on the document's root: while the page scrolls, the scroll offsets' values; while scroll is main, the header's (or the menu button's) bottom edge measured from the frame's top (the element watches the announcement's size too) and the navigation bar's height while it is shown. What is drawn over the page reads them (the snackbar host, SNK-13, SNK-35); the stylesheet sets them, until the element is defined, to the small app bar's height while a header stays in view and the navigation bar's in a compact window, as it sets the scroll offset. The scroll offsets are not those: a product's sticky part inside the <main> that scrolls has nothing over it. --tanrei-prose-scroll-offset stays 0 inside a shell: the scroll padding already clears the header, and prose adds only a heading's own space. The upgraded element adds: the read-only windowClass property, reflected as the data-window-class state attribute, and windowclasschange with detail.windowClass, from two matchMedia listeners (no resize listener and no frame loop); the menu button's click, which asks the <tanrei-navigation-drawer> in the navigation region for what its own menu button asks (NVD-37) — hidden or shown again where it stands beside the content (standardHidden and open, NVD-106), open where it is a column or not shown, closing where it is open — sets navigationOpen from the drawer's open, follows that drawer's close, and writes aria-expanded and aria-controls through the Button's element properties; role and aria-label on a region whose element does not already give the landmark (a <tanrei-app-bar slot="header"> with no <header> around it; an aside without a name takes aside-label); tabindex="-1" on a <main> that lacks it; and the debug reports of APS-4, APS-21 and APS-29. It listens to nothing while no region needs it. With scroll="main" the product names the main element's id in the app bar's scroll-target. footer-hidden gives the footer region display: none from the stylesheet (with !important, so a product's own display on its <footer> cannot bring it back): it then has no box, no landmark and no focus stop, its measured height is 0, and the element moves focus that was inside it to the main region. The skip link is hidden with a clip, never display: none, and shown on :focus-visible; under forced-colors: active its box gains a CanvasText border. Insets are env(safe-area-inset-*). A filterable drawer’s chord (APS-33): the element holds one keydown listener on the window while the navigation’s presentation is modal and navigationOpen is false, or the drawer is hidden beside the content, and the drawer in the navigation region is filterable with exactly one chord in filterShortcut (read as the drawer reads it); the chord opens the navigation as the menu button does and then calls the drawer’s focusFilter(). The React wrapper renders the same light DOM on a server. The navigation open over the content (APS-4, APS-7): with a filled header, the drawer is not shown as a top-layer modal <dialog> but drawn in the frame's own stacking order, below the header and over every other region, with its scrim covering only the frame below the header; the element sets inert on the skip link, the <main>, the aside, the footer and the navigation bar while it is open, holds the page's scroll as a modal layer does, and removes both when closing begins. The drawer learns that it is held so from its parent (a <tanrei-app-shell> whose header slot is filled), with no attribute for the product to write. Before a <tanrei-navigation-drawer> in the navigation region is defined (APS-24), the stylesheet places it from its attributes alone, in :not(:defined) rules under the same @media conditions: collapsible, expanded="false", variant="modal", density="compact", responsive, standard-hidden and open choose its column, its width or no space, and its width beside the content is --tanrei-navigation-drawer-width, which the product writes beside width (a stylesheet cannot read a number attribute as a length in every engine), held between comp.navigation-drawer.container.min-width and .max-width; min-width and max-width are read once the drawer is defined. TanreiAppShell(scroll:, headerPosition:, mainWidth:, asideOrder:, isFooterHidden:, separation:, isNavigationPresented: Binding<Bool>, asideLabel:) { main } header: { … } navigation: { … } aside: { … } footer: { … } announcement: { … } navigationBar: { … }. A layout of its own, not NavigationSplitView, whose column widths and collapsing cannot be set from the tokens. The window's class comes from the width of the scene (a GeometryReader at the root, in points; Dynamic Type does not change it) and is published as the environment value \.tanreiWindowClass, which a search or a side sheet inside the shell reads. scroll: .page is one ScrollView holding the announcement, the main content, a stacked aside and the footer, with the header in .safeAreaInset(edge: .top) and the navigation and the aside beside it; .main keeps the footer in .safeAreaInset(edge: .bottom). The header's height is published as \.tanreiAppShellScrollOffset and applied as the scroll view's content margin, so ScrollViewReader.scrollTo rests below it. Regions are exposed with accessibilityElement(children: .contain) and one entry each in a custom rotor, the aside labelled by asideLabel. No skip link: VoiceOver's rotor and Full Keyboard Access's group navigation move between regions. The navigation open over the content is laid out by the shell itself below the header — not as .sheet or a full-screen overlay, which would cover the header's .safeAreaInset(edge: .top) — as a scrim and the drawer in a ZStack over the content area; the covered regions are .accessibilityHidden(true) and kept from focus while it is open, the header is untouched, and the drawer is a container named by its label, not .isModal, since the header stays reachable. TanreiAppShell(navigationOpen, onNavigationOpenChange, modifier, scroll, headerPosition, mainWidth, asideOrder, footerHidden, separation, asideLabel, onWindowClassChange, announcement = {}, header = {}, navigation = {}, aside = {}, footer = {}, navigationBar = {}) { contentPadding -> main }, in the manner of a scaffold with a custom Layout. The window's class comes from LocalWindowInfo.current.containerSize in dp and is provided as LocalTanreiWindowClass. scroll = Page nests the main content, a stacked aside and the footer in one vertical scroll with the header pinned through a nested-scroll connection; the measured header height is provided as LocalTanreiAppShellScrollOffset and as contentPadding. Regions are exposed with Modifier.semantics { isTraversalGroup = true; paneTitle = … }, the aside's from asideLabel. System insets through WindowInsets.safeDrawing. No skip link: TalkBack and keyboard traversal groups move between regions. Not ModalNavigationDrawer, whose scrim and sheet cover the top bar: the shell's Layout places the open drawer and a scrim in the content area below the header; the covered regions take Modifier.semantics { hideFromAccessibility() } and focusProperties { canFocus = false } while it is open, the header keeps its semantics and focus, and a BackHandler closes it. TanreiAppShell({ required Widget main, Widget? announcement, header, navigation, aside, footer, navigationBar, bool navigationOpen, bool footerHidden = false, ValueChanged<bool>? onNavigationOpenChanged, … }), a widget of its own in the manner of a scaffold (CustomMultiChildLayout), not Scaffold, whose drawer and bar slots draw Material's own. The window's class comes from MediaQuery.sizeOf(context).width in logical pixels and is inherited as TanreiWindowClass.of(context). scroll: page is a CustomScrollView with a pinned header sliver; the header's height is inherited as TanreiAppShellScrollOffset.of(context) and applied as scroll padding for Scrollable.ensureVisible. Regions are Semantics(container: true, explicitChildNodes: true, label: …) in a FocusTraversalGroup with an ordered policy (APS-22). Insets from MediaQuery.viewPaddingOf. No skip link, except on Flutter for the web, which is not a target of this package. Not Scaffold.drawer, which covers the app bar: the open drawer and a scrim stand in a Stack over the body below the header; the covered regions are wrapped in ExcludeSemantics and ExcludeFocus while it is open, the header is not, and a PopScope closes it on back. <AppShell navigationOpen onNavigationOpenChange header={…} navigation={…} aside={…} footer={…} footerHidden announcement={…} navigationBar={…} menuButton={…}>{main}</AppShell>. The window's class comes from useWindowDimensions().width and is given by context (useWindowClass()). scroll="page" is one ScrollView with stickyHeaderIndices for the header; the header's height is measured with onLayout and given by context (useAppShellScrollOffset()). Regions carry accessibilityRole where the platform has one (header, menu, summary) and accessibilityLabel; the order of APS-22 is the order of the rendered views. Insets from the safe-area context the package already depends on. The layout direction is the app's. No skip link. The open drawer is an absolutely positioned view below the header's measured height with a pressable scrim over the rest; the covered regions take importantForAccessibility="no-hide-descendants" (Android) and accessibilityElementsHidden (iOS) while it is open — not accessibilityViewIsModal, which would hide the header too — and BackHandler closes it.

Tokens

Token Aliases Resolved (light)
--tanrei-comp-app-shell-aside-gap sys.space.space300 24px
--tanrei-comp-app-shell-aside-padding-inline sys.space.space200 16px
--tanrei-comp-app-shell-aside-width — 240px
--tanrei-comp-app-shell-breakpoint-expanded sys.breakpoint.expanded 1024px
--tanrei-comp-app-shell-breakpoint-medium sys.breakpoint.medium 600px
--tanrei-comp-app-shell-container-color sys.color.surface #ffffff
--tanrei-comp-app-shell-content-color sys.color.on-surface #1b1b1b
--tanrei-comp-app-shell-footer-padding-block sys.space.space400 32px
--tanrei-comp-app-shell-gutter-compact sys.space.space200 16px
--tanrei-comp-app-shell-gutter-expanded sys.space.space400 32px
--tanrei-comp-app-shell-gutter-medium sys.space.space300 24px
--tanrei-comp-app-shell-main-max-width — 768px
--tanrei-comp-app-shell-main-padding-block sys.space.space400 32px
--tanrei-comp-app-shell-outline-color sys.color.outline-variant #000000 · 8%
--tanrei-comp-app-shell-outline-width sys.border.hairline 1px
--tanrei-comp-app-shell-separation sys.behavior.separation 0
--tanrei-comp-app-shell-skip-link-container-color sys.color.surface-container-high #f3f3f3
--tanrei-comp-app-shell-skip-link-container-elevation sys.elevation.level3 0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 1px 0px rgb(0 0 0 / 0.04), 0px 4px 8px -4px rgb(0 0 0 / 0.04), 0px 16px 24px -8px rgb(0 0 0 / 0.06)
--tanrei-comp-app-shell-skip-link-container-padding-block sys.space.space150 12px
--tanrei-comp-app-shell-skip-link-container-padding-inline sys.space.space200 16px
--tanrei-comp-app-shell-skip-link-container-shape sys.shape.corner.small 6px
--tanrei-comp-app-shell-skip-link-offset sys.space.space100 8px
--tanrei-comp-app-shell-skip-link-label-typescale sys.typescale.label 500 14px/1.4286

Fixtures

Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.

Generated from specs/app-shell.spec.json, tokens/comp/app-shell.tokens.json, design/tokens/

Guidelines

Three window classes

The shell gives the window one of three classes by its width alone.

Class Width Navigation Aside Menu button Navigation bar Gutter
compact Under 600 Over the content, when opened Above or below the main content Shown Shown 16
medium 600 to 1023 The drawer’s column of icons where it is collapsible. Otherwise as compact Above or below Shown Not shown 24
expanded 1024 and wider Beside the content, unless the menu button hid it Beside the content, at the end edge Shown Not shown 32
  • The widths are the tokens sys.breakpoint.medium and sys.breakpoint.expanded. A navigation drawer with responsive reads the same two, so the frame and the drawer change together.
  • On the web the widths are compared in rem. A reader who zooms in gets the narrower arrangement before the columns become too narrow to read.
  • windowclasschange tells you the class, and windowClass holds it. Switch from it what the shell does not: a search’s presentation, a side sheet’s variant, the form of an outline.
  • On the web everything in the frame also inherits --tanrei-app-shell-window-class, so a stylesheet can follow the class with a style container query and no script.

The menu button

Put one icon-only Button in the header and mark it with data-app-shell-menu. The shell shows it in every window class, in the same place. Where the navigation has no place in the layout, or only its column of icons, pressing it opens the drawer over the content and moves focus into it, and closing the drawer puts focus back on the button. Where the navigation stands beside the content, pressing it hides the drawer and the main content takes its width; pressing it again shows the drawer. Focus stays on the button. The button says whether the navigation is shown.

navigationOpen (navigation-open) holds that state, and navigationopenchange tells you when a person changed it. A change of the window’s class keeps it: open navigation stands beside the content in a wide window and is over the content again, still open, when the window narrows.

What the button chose in a wide window is kept too. A drawer you showed with it is open, so it is over the content when the window narrows. A drawer you hid is closed in a narrow window and hidden again when the window is wide. The drawer holds that choice in standardHidden, and standardhiddenchange tells you when a person changed it, so you can keep it between visits.

What scrolls

scroll What scrolls Use for
page (default) The window scrolls the page. The header is sticky, and the navigation and the aside stay in view beside the content. Pages that are read: documentation, articles, settings.
main The frame is exactly the window and only the main region scrolls. An app whose panes scroll apart: a mail client, an editor.
  • Prefer page. Find-in-page, links to a heading, the return to where a reader was and a phone browser’s collapsing bars all work as on a page without a shell.
  • headerPosition: static lets the header scroll away with the page.
  • With scroll: main on the web, name the main element’s id in the app bar’s scroll-target.
  • With scroll: main on the web, an aside drawn above or below the main content (in a compact or medium window) stays in place while the main region scrolls; it does not yet scroll with it. Content that should scroll with the page belongs inside the <main>.
  • On the web the JavaScript property is scrolls, because every element already has a scroll() method. The attribute is scroll.

The shell measures the sticky header and gives the page’s scrolling view that much padding. A link to a heading, and an element that takes keyboard focus, come to rest below the header, never under it. On the web the same distance is --tanrei-app-shell-scroll-offset on the root, and the navigation bar’s height is --tanrei-app-shell-scroll-offset-end, for your own sticky parts such as a table’s header row. With scroll: main the shell sets neither: nothing stands over the main region as it scrolls. Inside a shell, leave --tanrei-prose-scroll-offset at 0.

Overlays stay clear of the frame

Whatever scroll is, the shell also writes on the root how far the frame reaches over the window. --tanrei-app-shell-window-inset-top is the distance from the top of the window to the bottom of the header (or of the menu button, in a frame without a header) while that stays in view; with scroll: main the header never moves, and an announcement above it counts. --tanrei-app-shell-window-inset-bottom is the navigation bar’s height while the bar is shown. They are for what is drawn over the page: a snackbar reads them to stand clear of the header and the navigation bar, and an overlay or a fixed element of your own can do the same.

What stands over what

  • The header and the navigation bar stand over everything that scrolls under them, the footer included. Nothing in the main region, the aside or the footer rises over them, whatever its z-index: each region stacks what it holds inside itself.
  • Menus, popovers, tooltips, snackbars, dialogs and sheets stand over the whole frame. Tanrei’s draw themselves there: on the web, in the browser’s top layer. Draw an overlay of your own the same way, as a popover or a <dialog> opened with showModal(), never with a large z-index.
  • On the web the frame is a stacking context of its own, so no level inside it competes with what your page draws outside it.

The main region’s width

  • mainWidth: contained (default) keeps the content no wider than 768 and centres it in its room. Use it for pages that are read.
  • mainWidth: full takes all the room inside the gutters. Use it for a table, a board or an editor.
  • Content that cannot shrink, such as a wide table or a line of code, scrolls inside its own box. It never widens the frame.

The aside

  • In an expanded window the aside stands beside the main content, 240 wide, and stays in view while the page scrolls.
  • In a narrower window it joins the main content’s column. asideOrder: before draws it above the main content, which suits an outline of the page. after (default) draws it below, which suits related links.
  • asideOrder is also the reading order. On the web, write the <aside> on that side of the <main> in the markup.
  • Name the aside with asideLabel, in your language.
  • A side sheet in the aside keeps its own width and edge. Set its variant from windowclasschange.
  • The footer is shown while you fill the footer region. Leave it out, and there is no footer and no landmark.
  • footerHidden (footer-hidden) hides a footer you have filled, without taking it out of the markup. Use it on a screen that is a task rather than a page of the site: a checkout, a sign-in, an editor. The footer then takes no space, draws no line, is no landmark and has no stop of the keyboard, and the navigation and the aside stay in view to the end of the page.
  • Hiding the footer while focus is in it moves focus to the main region.

Lines between regions

separation Draws
auto (default) What the design system chose: lines in the default system.
divider A hairline above the footer, at the start edge of an aside beside the content, and between the main content and a stacked aside.
gap No line. The same spaces.

The lines take no room. The shell draws none around the header, the navigation, the announcement or the navigation bar: those components draw their own edges. The app bar in the header draws its bottom edge at rest, as the edge of a region that stays, and keeps it while the page scrolls under it; set the bar’s dividerVisibility to scroll to show it only once content is under the bar.

  • Give every page one <main>, and give it the id the skip link names.
  • Write the skip link’s words in your language. Tanrei ships no words.
  • Use a navigation drawer with responsive in the navigation region.

Don’t

  • Don’t put the page’s title, description or actions in the shell. They are a page header, first in the main region.
  • Don’t put the footer of an article (previous and next, an edit link) in the footer region. It ends the main content. The footer region is for what belongs to the whole site.
  • Don’t reorder regions with CSS. The order of the markup is the order of focus.

Accessibility

Role
none
Labeling
The shell has no role and no name. Its regions are the page's landmarks: banner (the header), navigation (named by the label of the navigation drawer or the navigation bar it holds), main (exactly one, unnamed), complementary (the aside, named by asideLabel or by the side sheet's headline) and content information (the footer, while it is shown: an unfilled or hidden footer is no landmark). The skip link is named by its own text and the menu button by its label, both in the product's language: Tanrei ships no words.
Minimum target
The hit area meets the minimum target size even when the visual size is smaller. minimum 36px · pointer 36px · spacing 8px · touch 36px

Keyboard

Keys Action
Tab or Shift Tab Moves through the frame in reading order: the skip link, the announcement, the header (or, while the header region is empty, the menu button of the menu-button slot), the navigation, the main content and the aside in the order asideOrder gives, the footer, the navigation bar. The shell itself is not a stop. While the navigation is open over the content below the header, only the announcement, the header and the navigation have stops; in a frame without a header the open navigation is a modal drawer that keeps focus inside it.
Enter , on the skip link Moves focus to the main region and brings its top into view below the header.
Enter or Space , on the menu button Opens the navigation over the content, below the header (over the whole window in a frame without a header, APS-34), and moves focus into it; while it is open, closes it. Where the navigation stands beside the content, hides it and shows it again, the main content taking its room while it is hidden; focus stays on the menu button, which stays where it is. Escape in the open navigation closes it and returns focus to the menu button (the navigation drawer's own keys).
/ (a filterable drawer's chord, in a narrow window) Opens the navigation over the content and moves focus to the drawer's filter field (APS-33). Where the drawer is shown, the drawer answers it.

Notes

  • The shell takes no input: the skip link is a Link and the menu button an icon-only Button, and each meets the minimum target by its own spec (LNK-17, BTN-5).
  • The skip link is what lets a keyboard pass the header and the navigation in one step (WCAG 2.4.1); the landmarks let a screen reader do the same. Both are needed: a sighted keyboard user has no landmark list.
  • Focus is never hidden by the frame (WCAG 2.4.11): the scrolling view keeps the height of the sticky header and of the navigation bar clear when it brings a focused element into view (APS-17).
  • While the navigation is open over the content it is drawn below the header and stays the navigation landmark the expanded menu button controls; it is not a modal dialog, because the header stays usable and a dialog would tell assistive technology that everything else is inert. The regions under the scrim are made inert instead, so nothing that cannot be seen can be reached (the disclosure pattern for a site's navigation, with the covered content inert).
  • Reading order, focus order and the order of the markup are one order in every window class (APS-22), which is why the aside's place is a setting (asideOrder) and not something the layout rearranges by width.
  • Reflow (WCAG 1.4.10): at 320 points the frame is one column; the widths that decide the class grow with the text on the web (APS-2), so 200 % text in a 1280 window is laid out as a medium one.
  • A second navigation landmark is not an error: a navigation drawer, a navigation bar, breadcrumbs and a pagination each name themselves, and only one of the drawer and the bar is shown at a time unless the product keeps both.
  • On SwiftUI, Compose, Flutter and React Native there is no skip link: each platform's assistive technology moves between regions by its own gesture or rotor, and the shell marks the regions for it.

Generated from specs/app-shell.spec.json, tokens/sys/measure.tokens.json

What the component handles

  • Each filled region is its landmark: banner, navigation, main, complementary and content information. A region whose element does not give the landmark is given the role.
  • The skip link is the first stop of the keyboard. Following it moves focus to the main region itself, with its top in view below the header. The next Tab reaches the first control of the content.
  • Tab walks the regions in reading order, the same in every window class and in either layout direction, left-to-right or right-to-left. A region that is not shown has no stop.
  • A link’s target and a focused element are never left under the sticky header or the navigation bar.
  • When the window’s class changes and focus was on something that is no longer shown, such as the menu button, focus moves to the main region.
  • A hidden footer (footerHidden) is not in the accessibility tree and has no stop of the keyboard.
  • With text at 200% in a window 320 wide the frame is one column and nothing scrolls sideways.
  • In forced colors the lines and the skip link’s box are drawn in the system’s text color.
  • In a right-to-left layout the navigation stands at the right and the aside at the left. The order of focus does not change.

What you need to do

  • Exactly one <main> per page. A debug build reports none, or more than one.
  • A name for the aside (asideLabel), and a label on the navigation drawer and on the navigation bar. Two navigation landmarks on a page need two names.
  • The words of the skip link and the label of the menu button.
  • One heading of level 1 per page, in the main region: the page header’s title.