Fair Case

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

compact

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

roomy

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

Variants
PropValueHow it looks
basebelow lgNo surface: the page colour (#FAFDFF light, #00172E dark), full width, no ring, no shadow, no scroll of its own. The document scrolls.
basefrom lgThe 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.
sizecompactFrom lg: 6px in from the top, end and bottom, 12px corners, a soft shadow (0 2px 12px). Its height is the window less 12px.
sizeroomyFrom 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

States
StateHow it looks
restAs the variants describe.
focusFrom 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 lgNo Tab stop, because it does not scroll: a stop would only sit between the menu button and the page.
hovernot written
pressednot written
disablednot written

Props

Import from @repo/ui/app-surface.

Props
PropTypeDefaultWhat 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.
classNamestring | undefinedMerged with cn().
childrenReactNodeThe page: its main, with the padding.
appSurfaceVariantscva functionExported so a surface drawn outside React can wear the same classes.
watchSurfaceFocus(root?: ParentNode) => () => voidKeeps 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) => voidSets or clears the Tab stop once. The docs shell's script calls it on every page change.
SURFACE_QUERYstringThe media query from which the surface scrolls and takes focus: from 1024px.
SURFACEstringThe 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.