Box

Usage

Overview

Box is the foundational layout container: padding, margin, gap, display modes, alignment, borders, backgrounds, state washes, sizing, and positioning hooks. It carries no semantic meaning on its own—it organizes content. The mental model is “styled rectangle,” not “interactive control.”

When to use

Grouping related content with consistent spacing tokens.
Building flex or grid-like rows and columns when no higher-level layout component fits.
Applying visual chrome (border, background, radius) to a region without inventing ad hoc wrappers.
Absolute or relative positioning of overlays, sticky regions, or anchored panels inside a composed layout.

When not to use

Primary actions: surface Button or Icon button, not a clickable Box unless wrapped with the correct interactive pattern.
Semantic sections that need headings and landmarks: pair Box with proper headings and roles, or use page-level structure components.
Tables or lists: use Table, Data table, or list patterns so assistive tech gets the right structure.
When a specialized component exists (drawer shell, modal panel, card) prefer that component’s API for consistency.

Variants

Box is configured by props rather than named visual variants. Common combinations:

Configuration	Purpose	Emphasis
`FlexBox` alias	Shorthand flex container	Still token-driven gaps and alignment
Padding / margin scales	Rhythm	Prefer axis shorthand when horizontal and vertical differ
Background + border	Card-like regions	Don’t mimic interactive cards without proper focus semantics
Positioned overlays	Contextual layers	Manage `zIndex` with design tokens; avoid arbitrary stacks

Anatomy

Box renders a container around children. Nesting Boxes is normal; keep depth readable. FlexBox is Box with flex display preset—choose it to reduce boilerplate, not to change semantics.

Content guidelines

Box has no title or copy by itself—place Text or Typography inside.
Spacing: Align to the global scale; avoid one-off pixel margins that break grid alignment.
i18n: Layout should tolerate longer translated strings; prefer gap and wrapping over fixed widths when content varies.

Behavior and states

Non-interactive Box must not steal focus or intercept clicks meant for children.
If the entire Box should activate, use Interactable or a real button pattern with appropriate role and keyboard support—never rely on onClick alone without accessibility parity.
In @prepared911/ui, Box and FlexBox drop pointer, mouse, context-menu, and keyboard handlers. A context-menu region is Interactable inside ContextMenuTrigger. Focus and blur still pass.
Loading or disabled regions can be represented visually, but don’t confuse decorative dimming with disabled controls.

Flex children (item and alignSelf)

Prefer item={FlexItem.*} on Box or FlexBox instead of CSS-module flex shorthand. Recipes bundle grow, shrink, basis, and (for scroll hosts) minHeight, minWidth, and overflow. Use alignSelf when one child breaks out of the parent cross-axis alignment.

`FlexItem`	Typical use
`Fixed`	Toolbars, chips, fixed-width columns (`flex: 0 0 auto`)
`Fill`	Default growing row (`flex: 1 1 auto`)
`FillZeroBasis`	Equal flex siblings (`flex: 1 1 0`)
`FillNoShrink`	Truncation-friendly main pane (`flex: 1 0 auto`)
`FillScroll`	Column body that scrolls in place (BX-3)

For ratio columns (2:1, 3:1, ten equal tracks, queue metric widths), use Grid template={GridTemplate.*} instead of flex basis tricks on Box.

Before and after (module flex → item)

Filling remaining height in a flex column

Give the outer column a definite block size (height={BlockSize.Full} inside a sized parent, or a viewport step). On the row that should absorb leftover space and scroll, set item={FlexItem.FillScroll} (or explicit grow, shrink, minHeight={BlockSize.Zero}, and overflow={Overflow.Auto}). shrink alone only clears the inline-axis minimum; block-axis flex scrolling needs minHeight={BlockSize.Zero}.

Best practices

Co-locate Box with siblings that share the same spacing token for visual consistency.
Use tokens for zIndex, Background, and Border rather than raw values.
Test responsive breakpoints when direction or gap changes across screen sizes.

Don’t

Pass className from apps or remotes to restyle Box; it is deprecated outside the design system. Use enum props, regionClass with a *.region.module.scss file for token-only host paint, shipped parts, or request a prop via the find-pattern skill.
Use Box as a catch-all instead of extracting a named component once a pattern repeats.
Create fake dividers with empty Boxes—use Separator or border tokens intentionally.
Nest scrollable areas without a clear focus order—pair with Scrollable when needed.

State wash (gradient)

gradient={GradientPaint.*} applies Chroma's paint_wash_<id> recipe: a diagonal wash over --color-wash-base, paired light text through --color-fg-on-wash-*, mirrored under right-to-left layout, and dropped under prefers-contrast: more and forced colors. Only blocks inside @prepared911/ui set this prop from their own state enum. Shells and remotes pass state into the block; they do not choose a wash on Box or FlexBox directly. Text and Icon inside a wash use the default foreground tokens; do not add a color prop to force dark ink on the wash. Pair the wash with a label or icon so state is never conveyed by color alone. When a Light wash needs a stroke, use border-transient. Do not set background on the same node as gradient.

Accessibility

Box does not imply role; surrounding heading hierarchy still matters.
On ordinary tinted background fills, ensure contrast for text. On a state wash, the recipe applies the fg-on-wash ladder; still pair the wash with a label or icon (BX-8).
If Box clips content (overflow: hidden), verify keyboard users can still reach hidden interactive elements or provide another path.
Motion or overlays inside Box should respect reduced-motion preferences.
State washes drop under increased contrast and forced colors; verify copy remains understandable without the gradient.

Animated Number / Accessibility

Box / API and Development

On this page

Flex children (item and alignSelf)

Before and after (module flex → item)

Filling remaining height in a flex column

Best practices

State wash (gradient)

Accessibility

Related Components

Box

Usage

Overview

When to use

Grouping related content with consistent spacing tokens.
Building flex or grid-like rows and columns when no higher-level layout component fits.
Applying visual chrome (border, background, radius) to a region without inventing ad hoc wrappers.
Absolute or relative positioning of overlays, sticky regions, or anchored panels inside a composed layout.

When not to use

Primary actions: surface Button or Icon button, not a clickable Box unless wrapped with the correct interactive pattern.
Semantic sections that need headings and landmarks: pair Box with proper headings and roles, or use page-level structure components.
Tables or lists: use Table, Data table, or list patterns so assistive tech gets the right structure.
When a specialized component exists (drawer shell, modal panel, card) prefer that component’s API for consistency.

Variants

Box is configured by props rather than named visual variants. Common combinations:

Configuration	Purpose	Emphasis
`FlexBox` alias	Shorthand flex container	Still token-driven gaps and alignment
Padding / margin scales	Rhythm	Prefer axis shorthand when horizontal and vertical differ
Background + border	Card-like regions	Don’t mimic interactive cards without proper focus semantics
Positioned overlays	Contextual layers	Manage `zIndex` with design tokens; avoid arbitrary stacks

Anatomy

Box renders a container around children. Nesting Boxes is normal; keep depth readable. FlexBox is Box with flex display preset—choose it to reduce boilerplate, not to change semantics.

Content guidelines

Box has no title or copy by itself—place Text or Typography inside.
Spacing: Align to the global scale; avoid one-off pixel margins that break grid alignment.
i18n: Layout should tolerate longer translated strings; prefer gap and wrapping over fixed widths when content varies.

Behavior and states

Non-interactive Box must not steal focus or intercept clicks meant for children.
If the entire Box should activate, use Interactable or a real button pattern with appropriate role and keyboard support—never rely on onClick alone without accessibility parity.
In @prepared911/ui, Box and FlexBox drop pointer, mouse, context-menu, and keyboard handlers. A context-menu region is Interactable inside ContextMenuTrigger. Focus and blur still pass.
Loading or disabled regions can be represented visually, but don’t confuse decorative dimming with disabled controls.

Flex children (item and alignSelf)

`FlexItem`	Typical use
`Fixed`	Toolbars, chips, fixed-width columns (`flex: 0 0 auto`)
`Fill`	Default growing row (`flex: 1 1 auto`)
`FillZeroBasis`	Equal flex siblings (`flex: 1 1 0`)
`FillNoShrink`	Truncation-friendly main pane (`flex: 1 0 auto`)
`FillScroll`	Column body that scrolls in place (BX-3)

For ratio columns (2:1, 3:1, ten equal tracks, queue metric widths), use Grid template={GridTemplate.*} instead of flex basis tricks on Box.

Before and after (module flex → item)

Filling remaining height in a flex column

Best practices

Co-locate Box with siblings that share the same spacing token for visual consistency.
Use tokens for zIndex, Background, and Border rather than raw values.
Test responsive breakpoints when direction or gap changes across screen sizes.

Don’t

Pass className from apps or remotes to restyle Box; it is deprecated outside the design system. Use enum props, regionClass with a *.region.module.scss file for token-only host paint, shipped parts, or request a prop via the find-pattern skill.
Use Box as a catch-all instead of extracting a named component once a pattern repeats.
Create fake dividers with empty Boxes—use Separator or border tokens intentionally.
Nest scrollable areas without a clear focus order—pair with Scrollable when needed.

State wash (gradient)

Accessibility

Box does not imply role; surrounding heading hierarchy still matters.
On ordinary tinted background fills, ensure contrast for text. On a state wash, the recipe applies the fg-on-wash ladder; still pair the wash with a label or icon (BX-8).
If Box clips content (overflow: hidden), verify keyboard users can still reach hidden interactive elements or provide another path.
Motion or overlays inside Box should respect reduced-motion preferences.
State washes drop under increased contrast and forced colors; verify copy remains understandable without the gradient.

Animated Number / Accessibility

Box / API and Development

On this page

Flex children (item and alignSelf)

Before and after (module flex → item)

Filling remaining height in a flex column

Best practices

State wash (gradient)

Accessibility

Related Components