Cloaked Design SystemLayout

Background

A detail-screen container that paints a surface, fills height, and aligns its content with token-scale padding and safe-area insets.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

10 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/layout/Background/Background.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

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

A detail-screen container that paints a surface, fills height, and aligns its content with token-scale padding and safe-area insets.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

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

BackgroundBackgroundProps

packages/design-system/src/components/layout/Background/Background.tsx:53

Prop	Type	Presence	Notes
`surface`	`BackgroundSurface \| undefined`	Optional	Background token the surface paints. Defaults to `page`.Source default: `'page'`
`align`	`BackgroundAlign \| undefined`	Optional	Horizontal alignment of content. Defaults to `center`.Source default: `'center'`
`justify`	`BackgroundJustify \| undefined`	Optional	Vertical distribution of content. Defaults to `start` (top).Source default: `'start'`
`fill`	`boolean \| undefined`	Optional	Fill the available height (`min-height: 100%`). Defaults to true.Source default: `true`
`safeArea`	`BackgroundSafeArea \| undefined`	Optional	Adds safe-area insets to padding edges. Defaults to `'none'`.Source default: `'none'`
`style`	`React.CSSProperties \| undefined`	Optional
`className`	`string \| undefined`	Optional
`children`	`React.ReactNode`	Optional
`testId`	`string \| undefined`	Optional	Optional test selector, placed on the root element.
`padding`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Padding on all four sides.
`paddingX`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Horizontal padding (left + right). Overrides `padding` on the X axis.
`paddingY`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Vertical padding (top + bottom). Overrides `padding` on the Y axis.
`paddingTop`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Top padding. Overrides `paddingY` and `padding`.
`paddingRight`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Right padding. Overrides `paddingX` and `padding`.
`paddingBottom`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Bottom padding. Overrides `paddingY` and `padding`.
`paddingLeft`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Left padding. Overrides `paddingX` and `padding`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

Parent container for detail, modal, and standalone screens: it paints a page / surface background, fills the available height, and centers its content by default.

When to use

Reach for Background when a screen needs a surface plus alignment but not the sticky route chrome of Screen — a confirmation, paywall, or empty state. It is a flex column, so align is the horizontal (cross) axis and justify the vertical (main) axis; justify="between" pins content to the top and bottom edges.

Building a full route with a header, scrolling body, and footer? Use Screen.
Laying out the content inside the surface? Use VStack / HStack / Grid.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: root
Label: Root
Description: Flex column that paints the surface and lays out content. Structural container.
Required: true

Allowed Design Choices

Variants

Container

Label: Container
Description: The single background container.

Sizes

Surfaces

Page

Label: Page
Description: Paints the page background.

Surface

Label: Surface
Description: Paints the raised surface background.

Alignments

Start

Label: Start

Center

Label: Center

End

Label: End

Stretch

Label: Stretch

Justifications

Start

Label: Start

Center

Label: Center

End

Label: End

Between

Label: Between

Variants

Id: container
Label: Container
Description: Surface-painting layout container.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: content-padding
Label: Content padding
Kind: example-only
Token: --cds-space-24
Value: 24
Unit: px
Applies To: root
Notes: Representative value: padding is author-configurable and accepts any step on the spacing scale. 24 is the value rendered and verified by the WithPadding story.

Layout

Alignment: align sets the horizontal (cross) axis; justify sets the vertical (main) axis.
Flow: A flex column that fills height by default and centers content.
Notes: Use Screen when a route needs sticky header/footer chrome; use Background for a plain centered surface.

Typography And Color

Typography

Label: Inherited
Description: Background sets no type; children own their text. Ramp noted for parity.
Token: --cds-type-body-size

Colors

Label: Page surface
Description: The page surface paints the page background.
Token: --cds-bg-page

Label: Raised surface
Description: The surface option paints the raised background.
Token: --cds-bg-surface

States

Id: page
Label: Page
Description: Page background surface.

Id: surface
Label: Surface
Description: Raised background surface.

Id: not-filled
Label: Not filled
Description: fill=false sizes the surface to its content.

Behavior

Label: Fill
Description: fill (default) makes the surface fill the parent height.

Label: Safe area
Description: safeArea adds env(safe-area-inset-*) on top of the configured padding.

Accessibility

Label: Presentational
Description: Background is a layout container and adds no roles.

Label: Safe insets
Description: Safe-area insets keep content clear of the notch and home indicator.

Content Adaptation

Label: Alignment
Description: justify=between with align=stretch pins a header to the top and a footer to the bottom.

Label: Per-edge padding
Description: Per-edge padding overrides layer on top of the uniform padding.

Motion Haptics

Motion

Label: None
Description: Background does not animate on its own.

Haptics

Label: None
Description: A layout container requests no haptics.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1