@atlaskit/primitives/constellation/box/examples.mdx

Primitives are token-backed low-level building blocks.

---
title: Box
description: A box is a generic container that provides managed access to design tokens.
order: 0
---

import BoxBasic from '../../examples/constellation/box/basic';
import BoxPadding from '../../examples/constellation/box/padding';
import BoxBackgroundColor from '../../examples/constellation/box/background-color';
import BoxXcss from '../../examples/constellation/box/xcss';
import BoxConditional from '../../examples/constellation/box/conditional-styles';
import BoxPracticalUseCase from '../../examples/constellation/box/practical-use-case';

import { CodeDocsHeader } from '@af/design-system-docs-ui';

<CodeDocsHeader
  name="@atlaskit/primitives"
  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
  directoryName="primitives"
/>

## Basic

Box is a general-purpose container that allows for controlled use of design tokens. Use the given props to configure display behavior and styling that aligns with the Atlassian Design System.
Use [XCSS](/components/primitives/xcss/usage) to style primitive components safely with tokens.

<Example Component={BoxBasic} packageName="@atlaskit/primitives/box" />

## Padding

Use padding props to access spacing design tokens and control internal layout. The following example demonstrates how each prop works with space tokens.

<Example Component={BoxPadding} packageName="@atlaskit/primitives/box" />

The nomenclature used by these props follows [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties). This naming is used to support different [writing modes](https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode) in Atlassian products.

## Background color

Box accepts a wide variety of background colors, referenced as semantic design tokens. For the full list of color tokens, visit the [token list](/components/tokens/all-tokens).

<Example
  Component={BoxBackgroundColor}
  packageName="@atlaskit/primitives/box"
/>

## XCSS

Box exposes an `xcss` prop. This prop accepts `xcss` function calls that contain a subset of permitted styles. When used with `Box`, `xcss` accepts most CSS properties, and when a token exists, the rule accepts that token as a value.

For more information on XCSS, see the dedicated [XCSS documentation](/components/primitives/xcss).

<Example Component={BoxXcss} packageName="@atlaskit/primitives/box" />

## Conditional styles

To achieve conditional styles, it is usually simpler to apply conditional behavior at the `xcss` object level, rather than applying conditional behavior to individual properties.

<Example Component={BoxConditional} packageName="@atlaskit/primitives/box" />

## Practical use case

Box is designed to be used in conjunction with the inline and stack components to create layouts. This example demonstrates how these can be used to create familiar components and patterns.

<Example
  Component={BoxPracticalUseCase}
  packageName="@atlaskit/primitives/box"
/>