Prepared Docs

Overview

Box is the foundational layout container: padding, margin, gap, display modes, alignment, borders, backgrounds, 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.
Loading or disabled regions can be represented visually, but don’t confuse decorative dimming with disabled controls.

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

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.

Accessibility

Box does not imply role; surrounding heading hierarchy still matters.
Ensure contrast for text placed on tinted backgrounds.
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.

Animated Number / Accessibility

Box / API and Development

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.
Loading or disabled regions can be represented visually, but don’t confuse decorative dimming with disabled controls.

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

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.

Accessibility

Box does not imply role; surrounding heading hierarchy still matters.
Ensure contrast for text placed on tinted backgrounds.
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.

Animated Number / Accessibility

Box / API and Development