# Box

> The lowest-level layout primitive: padding, surface, border, radius and shadow from tokens.

Category: Layout · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/box

Box renders any element with spacing and surface styles taken directly from Stance tokens. Use it to build one-off containers without writing CSS. When a pattern repeats, such as a card or a panel, prefer the dedicated component, which carries semantics and states.

## Import

```tsx
import { Box } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Box, Text } from '@bindshq/stance-react';

export function Basic() {
  return (
    <Box padding={6} background="surface" border radius="lg" shadow="sm">
      <Text size="sm">Your organisation has 12 active email signatures.</Text>
    </Box>
  );
}
```

### Surfaces

Each background sets a matching foreground, so text stays legible in every theme.

```tsx
import { Box, Text } from '@bindshq/stance-react';

export function Surfaces() {
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))',
        gap: 12,
        width: '100%',
      }}
    >
      {(['canvas', 'subtle', 'muted', 'surface', 'inverse'] as const).map((bg) => (
        <Box key={bg} padding={4} background={bg} border radius="md">
          <Text size="sm" tone="inherit">
            {bg}
          </Text>
        </Box>
      ))}
    </div>
  );
}
```

### Semantic element

Use `as` to render a landmark or list item while keeping the styling.

```tsx
import { Box, Text } from '@bindshq/stance-react';

export function Semantic() {
  return (
    <Box
      as="aside"
      aria-label="Contract summary"
      paddingX={5}
      paddingY={4}
      background="subtle"
      radius="lg"
      border="subtle"
    >
      <Text size="sm" weight="semibold">
        Master services agreement
      </Text>
      <Text size="sm" tone="muted">
        Renews on 1 March 2027
      </Text>
    </Box>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Box | `as` | `keyof JSX.IntrinsicElements` | `'div'` | Element to render. |
| Box | `padding` | `SpaceKey` | None | Padding on all sides from the space scale. |
| Box | `paddingX` | `SpaceKey` | None | Horizontal padding; overrides padding on the x axis. |
| Box | `paddingY` | `SpaceKey` | None | Vertical padding; overrides padding on the y axis. |
| Box | `background` | `'canvas' \| 'subtle' \| 'muted' \| 'emphasis' \| 'surface' \| 'surface-raised' \| 'inverse'` | None | Semantic surface with a matching foreground. |
| Box | `border` | `boolean \| 'subtle' \| 'default' \| 'strong'` | None | Border strength. true means default. |
| Box | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full'` | None | Corner radius token. |
| Box | `shadow` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | None | Elevation token. Becomes an outline in high contrast. |

## Accessibility

- Box has no role of its own. Choose a semantic element with `as` (section, aside, li) when the content has structure.
- The inverse background flips foreground colour automatically, so contrast is preserved without extra props.

## Guidelines

**Do**

- Use Box for one-off spacing and surfaces.
- Pick backgrounds by meaning (surface, subtle), not by colour.

**Don’t**

- Rebuild Card, Alert or Banner with Box; use the component.
- Override token colours with inline styles.

## Related

- https://stanceui.com/components/stack
- https://stanceui.com/components/card
- https://stanceui.com/components/container