AppSurface
The inset surface an app shell draws its pages on, beside the sidebar. From 1024px it is a step lighter than the shell, with a hairline ring and a soft shadow, and it is the only thing that scrolls. Below that it is the page itself, full width.
Two sizes
compact is the docs site's: 6px in, 12px corners. roomy is the lawyer platform's: 12px in, 24px corners. The first column of each frame stands in for the sidebar.
The page
Line 1
Line 2
Line 3
Line 4
Line 5
Line 6
Line 7
Line 8
Line 9
Line 10
Line 11
Line 12
Line 13
Line 14
The page
Line 1
Line 2
Line 3
Line 4
Line 5
Line 6
Line 7
Line 8
Line 9
Line 10
Line 11
Line 12
Line 13
Line 14
TSX
<AppSurface size="compact" className="lg:h-auto">
<div className="flex flex-col gap-2 p-6">...</div>
</AppSurface>
<AppSurface size="roomy" className="lg:h-auto">
<div className="flex flex-col gap-2 p-6">...</div>
</AppSurface>Below 1024px
There is no surface and no sidebar column below 1024px. The page sits full width on the page colour and the document scrolls, so a narrow window draws the frames above as plain pages. From 1024px the surface scrolls inside the frame, and takes a Tab stop so a keyboard can scroll it.
Code
TSX
<div className="lg:flex lg:h-dvh lg:overflow-hidden">
<AppSidebar label="Design system" sections={sections} width={240} />
<AppSurface size="compact">
<main className="px-4 pt-6 pb-12 lg:px-6 lg:pt-12 lg:pb-16">
The page
</main>
</AppSurface>
</div>
// From whatever draws the surface: a client effect in a React app,
// or the shell's script on the docs site.
useEffect(() => watchSurfaceFocus(), []);From DocsLayout.astro and app-surface.stories.tsx. It is a div: the caller puts the page's main inside it and sets the padding. The parent is a row of the sidebar and the surface, as tall as the window with overflow hidden.
Variants
| Prop | Value | How it looks |
|---|---|---|
| base | below lg | No surface: the page colour (#FAFDFF light, #00172E dark), full width, no ring, no shadow, no scroll of its own. The document scrolls. |
| base | from lg | The surface colour (#FAFDFF light, #092139 dark) with a 1px inset rule ring (#B2D5FF light, #23446A dark). It scrolls vertically and is the only scroller on the page. |
| size | compact | From lg: 6px in from the top, end and bottom, 12px corners, a soft shadow (0 2px 12px). Its height is the window less 12px. |
| size | roomy | From lg: 12px in from the top, end and bottom, 24px corners, a deeper shadow (0 4px 24px). Its height is the window less 24px. |
States
| State | How it looks |
|---|---|
| rest | As the variants describe. |
| focus | From lg it takes a Tab stop (tabindex 0). Its focus ring is the global 2px one, drawn inside the edge, since the shell clips anything outside it. |
| below lg | No Tab stop, because it does not scroll: a stop would only sit between the menu button and the page. |
| hover | not written |
| pressed | not written |
| disabled | not written |
Props
Import from @repo/ui/app-surface.
| Prop | Type | Default | What it does |
|---|---|---|---|
| size | "compact" | "roomy" | default "compact" | The inset and the corners from lg up. compact is the docs site's, roomy is the lawyer platform's. |
| className | string | undefined | Merged with cn(). | |
| children | ReactNode | The page: its main, with the padding. | |
| appSurfaceVariants | cva function | Exported so a surface drawn outside React can wear the same classes. | |
| watchSurfaceFocus | (root?: ParentNode) => () => void | Keeps the surfaces under root (the document by default) in step with the window, so each has a Tab stop from 1024px and none below. Returns its cleanup. | |
| syncSurfaceFocus | (root: ParentNode, wide: boolean) => void | Sets or clears the Tab stop once. The docs shell's script calls it on every page change. | |
| SURFACE_QUERY | string | The media query from which the surface scrolls and takes focus: from 1024px. | |
| SURFACE | string | The selector that finds a surface: its data-app-surface marker, which AppSurface sets. |
Use it well
Put the page's main inside it and set the padding on the main, not on the surface.
Make its parent a row of the sidebar and the surface, as tall as the window with overflow hidden, so the surface is the window less its two margins.
Call watchSurfaceFocus or syncSurfaceFocus from whatever draws the surface. Focusability cannot follow a media query in CSS, so a page with no links in it would otherwise have no way to scroll from the keyboard.
Use compact for the docs site and roomy for the lawyer platform. A shell takes one size, not both.