Box
The surface primitive. A block with token-valued padding, background, border and radius — the only way a layout gets a background or an inset without a component of its own.
Basic usage
Install the package:
pnpm add @design-schema/react @design-schema/tokensImport the stylesheet once for the app, then the component:
import '@design-schema/tokens/calm-precise/css';
import '@design-schema/react/index.css';
import { Box } from '@design-schema/react';Examples
import { Box, Text } from '@design-schema/react';
<Box inset="md" surface="subtle" radius="md">{typeof 'A panel of settings' === 'string' ? <Text>{'A panel of settings'}</Text> : 'A panel of settings'}</Box>Props
8 rows| Prop | Type | Default | Description |
|---|---|---|---|
| children required | content | — | Any content. Box does not space its children; put a Stack inside for that. A string given as `children` in an example is wrapped in the system Text by its story on every platform (`<ds-text>` on Lit, where slotted content cannot be an arg): one meta-level render wraps only string children in a Text at its defaults, so each example story keeps exactly its `given` as args. The Default story uses the `highlighted-panel` props, since a Box at its schema defaults draws nothing; meta args may still list the schema defaults (`border: false`, `element: div`) as controls, but only defaults of props the platform declares (React Native has no `element`) and never the `highlighted-panel` props, which go on the Default story alone. Meta args that equal the schema defaults count as "exactly its `given`". Besides one story per enum value, the `border` boolean gets one `Border` story (`border: true`) and a `WithOverrides` story shows `overrides`. On React Native the behavior tests render through the stories' meta render, since a bare string child inside a View throws there. Behavior scenarios render the Default story's args with their `given` on top, which is intended: they assert only renders and roles. |
| inset | none | sm | md | lg | xl | none | Padding on all sides, from the layout inset presets. Use `insetBlock`/`insetInline` when the axes differ. |
| insetBlock | none | sm | md | lg | xl | — | Vertical padding, overriding `inset` on that axis. It has no default: unset means `inset` applies, which keeps an explicit `none` distinct from an absent value. |
| insetInline | none | sm | md | lg | xl | — | Horizontal padding, overriding `inset` on that axis. Unset means `inset` applies, as with insetBlock. |
| surface | none | default | subtle | strong | none | Background. `none` is transparent; `default` is the page background (use to lift content off a subtle parent); `subtle` and `strong` step up. |
| border | boolean | false | A thin default border. |
| radius | none | sm | md | lg | full | none | Corner radius from the theme's presets. |
| element | div | section | article | aside | header | footer | main | nav | div | Element to render. Sectioning elements only when the box is a semantic region; prefer Landmark for page regions. There is no native counterpart, so a screen that ports to React Native uses Landmark for the region instead of this prop. |
Accessibility
No implicit ARIA role — the component is styling and structure, and adds nothing to the accessibility tree.
Anatomy
What generation guarantees
Contrast — Text and meaningful non-text contrast meets WCAG AA; the pairs are listed below.
This component does not animate, so it has no reduced-motion behaviour to describe.