Components
Box
A token-aware, polymorphic container for surfaces, spacing, and dimensions.
Box is the general-purpose container. It renders the element you choose, forwards native props and
refs, and maps common design values to semantic tokens.
Box handles surfaces, spacing, borders, and dimensions. Use Stack for one-dimensional layout and Grid for two-dimensional layout. Card semantics belong in a future Card component; Box does not impose a card structure.
Live preview#
import { Box, Stack, Text } from '@orkest/ui';
export function Example() {
return (
<Box
as="section"
aria-label="Project summary"
padding={5}
background="surface-sunken"
radius="xl"
>
<Stack gap={2}>
<Text weight="semibold">Project summary</Text>
<Text size="sm" tone="muted">
Box maps common design values to semantic tokens.
</Text>
</Stack>
</Box>
);
}Dimensions and padding#
Numbers are treated as pixels; use any CSS length string for token-based or relative sizing.
padding accepts the shared spacing scale.
import { Box, Text } from '@orkest/ui';
export function Example() {
return (
<Box width="100%" maxWidth="24rem" padding={4} background="surface-sunken" radius="xl">
<Text size="sm" tone="muted">
maxWidth keeps long content readable.
</Text>
</Box>
);
}Semantic colors#
background and color map to theme-aware semantic variables, so the same Box works in light and
dark themes.
import { Box, Text } from '@orkest/ui';
export function Example() {
return (
<Box padding={4} background="accent-surface" color="accent" radius="xl">
<Text size="sm" weight="medium">
Accent surface
</Text>
</Box>
);
}Props#
| Prop | Type | Default |
|---|---|---|
as | ElementType | 'div' |
| Element or component to render. | ||
width / height | number | string | — |
| Dimensions. Numbers are pixels; strings pass through as CSS. | ||
minWidth / maxWidth | number | string | — |
| Width constraints. Numbers are pixels. | ||
minHeight / maxHeight | number | string | — |
| Height constraints. Numbers are pixels. | ||
padding | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16 | 20 | — |
| Padding step mapped to a --ok-space token. | ||
background | 'transparent' | 'background' | 'surface' | 'surface-raised' | 'surface-sunken' | 'secondary' | 'accent-surface' | 'success-surface' | 'warning-surface' | 'danger-surface' | — |
| Semantic background token. | ||
color | 'inherit' | 'foreground' | 'muted' | 'subtle' | 'accent' | 'success' | 'warning' | 'danger' | 'primary-foreground' | 'secondary-foreground' | — |
| Semantic text color token. | ||
border | boolean | 'subtle' | 'default' | 'strong' | false |
| Border using the default or a named border token. | ||
radius | 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | — |
| Corner radius token. | ||
shadow | 'xs' | 'sm' | 'md' | 'lg' | — |
| Shadow token. | ||
overflow | 'visible' | 'hidden' | 'auto' | 'scroll' | 'clip' | — |
| CSS overflow behavior. | ||
className | string | — |
| Merged with the internal class name. | ||
native attributes | ComponentPropsWithRef<T> | — |
| Inherited from the element selected by as. The style prop wins over token props. | ||
BoxProps<T> and the individual token types are exported for wrapper components. The as prop
drives the available native attributes and the ref type.
Accessibility#
Boxadds no roles, labels, or keyboard behavior.- Choose an element that matches the content, such as
section,nav,article, orul. - Provide an accessible name when the chosen landmark needs one.
- Do not use a clickable Box in place of a native button or link.
- Check color contrast when combining
background,color, and theme variants.