Screen

Local specification source status: preview. Implementation preview pending sign-off.

A full-height route scaffold that paints the surface, applies safe-area insets, and hosts sticky header and footer chrome around a scrolling body. Chrome padding is fixed by the system; only the body's padding is authorable.

import { Screen } from '@cloakedinc/design-system';

Overview

Full-height route scaffold. Use it as the outermost element of a routed screen: it paints the page surface, applies safe-area insets, and hosts sticky Screen.Header / Screen.Footer chrome while Screen.Body owns the scroll.

When to use

Reach for Screen as the top-level wrapper of a routed view — anything that needs a header, a scrolling body, a pinned footer action, or device safe-area handling. Compose the header from the Screen.Header.* sub-parts (Bar, Title, Brand, Task, BackButton, IconButton, Action, Progress).

• A detail, modal, or standalone screen that just needs a centered surface without route chrome? Use Background.
• Laying out content inside a Screen? Use VStack / HStack / Grid.

Chrome padding is fixed

Screen.Header and Screen.Footer take no padding props. The header is 20 / 12 / 8 and the footer is 20 / 16 / 16, on every route, and a padding on the Screen root reaches only the body. Only Screen.Body is authorable, because body content genuinely varies — sectioned lists, full-bleed heroes — while chrome does not.

The props used to exist and every value in them drifted: one app settled on 12 / 8, another copy-pasted 16 / 12 into thirteen files, two chat headers inset their icons to 12 while their own body sat at 20, and seven headers shipped with no paddingX at all, flush to the screen edge.

Screen.Header inset="activity" is the one sanctioned variation: it swaps the 12 top for 32, for a Stackflow activity that renders a header with no Screen root above it and no navigation bar to sit under.

<Screen.Header inset='activity' testId='pack-details-header'>
    <Screen.Header.Bar justify='start'>
        <Screen.Header.BackButton onBack={pop} />
        <Screen.Header.Title>Pack details</Screen.Header.Title>
    </Screen.Header.Bar>
</Screen.Header>

For a bespoke host alignment — a header that must line up with a floating control the app draws outside React — the documented last resort is the slot's style prop, which lands after the constant. Reach for it only when a real host constraint outranks the system box, and say so in a comment.

Overscroll edges

The over-pull (rubber-band) region continues the color of whatever sits at that edge, so a full-bleed footer or colored hero doesn't break into a flat gray bounce. Set the edge color with overscrollTop / overscrollBottom (pass var(--cds-*) tokens) to match the content there — e.g. a colored hero at the top, or a FaqCarousel fullBleed band's var(--cds-feature-<tone>-backdrop) at the bottom. The effect is only visible while bouncing on a touch device.

Solid and grouped bodies

Every screen is one of two shapes, and layout is the only thing that picks between them:

• solid (default) — children flow down one continuous surface inside the page gutter.
• grouped — the grouped-list rhythm. The body drops its gutter, each Screen.Section paints the surface, and the fixed 16px gap between two sections takes the page color. The gap is not a prop — a tunable one re-opens the drift this closes.

Sections paint and position only. They add no inline padding, because content already self-pads to the page gutter (SectionHeader and List.Item both inset 20px). A section that insets its own children makes them double-inset.

The page color is a separator, never a ground. Only the gap between two sections takes it; everything else the body holds keeps the screen surface — the inset the body reserves for a native bar, bottom tab-bar clearance, the slack a short screen leaves under its last section, and both over-pull edges. A grouped body gets that by painting a box that holds only the sections and nests inside the padded one, so no page color ever reaches the boundary of the scrolling content. There is nothing to pair on the Screen root, and no overscrollBottom to set.

Body background

Screen.Body's scroll content is opaque so the overscroll backdrop shows only in the over-pull edges. To give a scrolling body a custom background (e.g. a hero→page gradient), set --screen-scroll-bg on the body — a raw background on the body className is painted over by the scroll content and won't show. See PackDetailsView for the pattern.

Component specification