Theme it

“No skin” shows the neutral library baseline. Your application owns its theme and can override only the values that need to change. Refined and the other named presets remain optional starting points.

Apply bg-background to your document’s <html> element so overscroll and viewport gaps use the active theme. The Next.js starter includes this root background. Keep the skin and color-mode attributes on the same theme boundary.

With a named skin on <html data-skin>, SkinProvider applies the config's motion and colorScheme to the root. A skin that declares a fixed colorScheme holds the page in that mode while it is mounted, whatever the theme toggle asks for. A skin scoped to a wrapper spreads skinScopeAttributes(skin) on that element and follows the page mode. Create a skin shows both installs.

Set sidebarLayout: "page" in your skin config, or use <Sidebar variant="page"> for one layout. An explicit variant takes precedence over the skin default. Page removes the sidebar divider, the SidebarHeader divider line, and the inset frame while retaining the fixed desktop navigation, collapse controls, resize rail, and mobile drawer. Inset drops the header divider too, since the content panel already separates the sidebar.

Use AppShell once in your persistent layout. It includes SidebarProvider, so collapse, resize, keyboard shortcuts, mobile navigation, and the skip link keep the same state while routes change. The host application owns authentication, routing, and data fetching.

scroll="page" keeps native document scrolling and fills short pages to the bottom of the viewport. scroll="inset" bounds the shell to the viewport and lets PageLayout scroll below the persistent header. scroll="none" bounds the shell for independently scrolling workspace panes, such as an inbox. PageLayout inherits this policy unless its scroll prop is explicit. Do not mix a document-scrolling page with a bounded shell. With scroll="auto", the skin chooses page or inset scrolling.

Use layout="contained" inside an already sized parent, such as a preview or embedded workspace. Sidebar appearance remains a separate choice through its variant prop or the skin. Loading and empty states belong inside the same PageLayout as the loaded content. Replace the data region with a meaningful skeleton while keeping the page title, actions, and frame stable.

Hover colors and hover-following highlights update immediately, as do desktop sidebar toggles. Press feedback, selection indicators, and popup entrances retain their motion tokens and respect reduced-motion preferences.

Group neighboring tooltips in one TooltipProvider: the first hover waits 500 ms, then neighboring tooltips open immediately within Base UI’s 400 ms grouping window. Use the provider’s delay and timeout props when your interaction needs different timing.

A theme is one file — <short-name>.control-ui-theme.json, format control-ui-theme/v1 — with tokens split into shared, light, and dark. Color-valued tokens go in light and dark; everything else in shared. A token left out inherits the base skin, so the artifact composes onto the pack instead of forking it.

Contrast is a property of the theme, not a follow-up audit. Normal and small text clears 4.5:1 after alpha compositing in both modes; focus indicators and control boundaries clear 3:1.

The accessibility page checks the canonical colors plus what the components actually paint — popups, badges, active tabs — and the same checks run from the CLI, on every commit, over the baseline and every preset mode.