@atlaskit/primitives/constellation/xcss/usage.mdx

Primitives are token-backed low-level building blocks.

---
title: XCSS
description: XCSS is a safer, tokens-first approach to CSS-in-JS.
order: 0
---

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

XCSS is an Atlassian Design System styling API that natively integrates with Atlassian's [design tokens](/tokens) and [primitives](/components/primitives).

The XCSS utility behaves similarly to the `css` utility in libraries like `styled-components`, `@compiled` or `@emotion`. If you've used these libraries, XCSS will feel familiar, with a few additional features and constraints.

Familiar features:

- XCSS generates a `className` that is applied to the components
- XCSS provides key-value pairs of CSS properties in an object format
- XCSS supports style precedence and conditional styles

Key differences:

- XCSS has type-safety that ensures token name usage for all CSS properties represented by design tokens.
- XCSS restricts nested selectors completely from usage

## Usage

To get started, import the function from `@atlaskit/primitives` and create a style:

```tsx
import { xcss } from '@atlaskit/primitives';

// Creates a basic style
const someStyles = xcss({
  display: 'block',
});
```

Apply this style to a component through the `xcss` prop:

```tsx
import { Box, xcss } from '@atlaskit/primitives';

// Creates a basic style
const someStyles = xcss({
  display: 'block',
});

const MyBox = () => {
  return <Box xcss={someStyles} />;
};
```

The `xcss` prop and the `xcss` function are direct complements and are designed to be used together.

It is important to note that styles generated from `xcss` cannot be applied directly to the `className` property or `css` as they are with other CSS-in-JS libraries.

### Type safety

XCSS uses strongly-typed values generated from design token definitions, making it simpler to apply the right token to the right CSS property.
This is intended to be more ergonomic and intuitive, but also prevent the misapplication of tokens to the wrong properties.

Any [valid token name](/components/tokens/all-tokens) is available to be applied against its
matching CSS property. For example, the token name `space.200`
is a valid value below for `padding` but will not appear
as a color, or a font.

```tsx
import { xcss } from '@atlaskit/primitives';

const someStyles = xcss({
  padding: 'space.200', // <--- works
  color: 'space.200', // <--- invalid and will error
  borderRadius: 'border.radius.100', // <--- also valid
});
```

### Restricted nesting

XCSS is flexible enough to implement any design, but it does restrict the application of styles in one key way.
Selectors cannot be nested or target elements beyond the element on which styles are applied.
This restriction is intended to encourage better component encapsulation, reduce side-effects and make the codebase more resilient to change.

```tsx
import { xcss } from '@atlaskit/primitives';

const someStyles = xcss({
  ':hover': {
    transform: 'scale(1)', // this is okay
  },
  // This is not okay as this selector affects any nested div in
  // the component tree.
  'div:hover': {
    transform: 'scale(1)',
  },
  // Neither is this
  '> * > div:hover': {
    transform: 'scale(1)',
  },
});
```

These unsafe selectors will throw a type error if applied.
Find richer examples of how to use XCSS in the [XCSS examples](/components/primitives/xcss/examples).

### Media Queries

XCSS can create responsive layouts at predefined breakpoints that are consistent with the Atlassian Design System. To enable responsive behavior, XCSS exposes the following pre-defined breakpoints:

<MediaQueriesTable />

Media queries can be applied through keys imported from `@atlaskit/primitives/responsive`.
Find more in depth examples on how to enable responsive behavior in the [responsive documentation](/components/primitives/xcss/examples#responsiveness).

The objects defined at each breakpoint behave in much the same way as a normal XCSS object, and can apply responsiveness to any CSS.
The only limitation is that a media query can't contain another media query. This is to prevent arbitrary nesting.

Additionally, pseudo-selectors can't contain media queries. To use media queries and pseudos, the media query must contain the pseudo.

```
import { xcss } from '@atlaskit/primitives';
import { media } from '@atlaskit/primitives/responsive';

const someStyles = xcss({
  // This is okay, since media queries can contain pseudos
  [media.above.md]: {
    ':hover': {
      backgroundColor: 'color.background.primary.hovered'
    }
  },

  // This is not okay, since pseudos can't contain media queries
  ':hover': {
    [media.above.md]: {
      backgroundColor: 'color.background.primary.hovered'
    }
  },

  // This is not okay, since media queries can't contain media queries
  [media.above.md]: {
    [media.above.xs]: {
      backgroundColor: 'color.background.primary.hovered'
    }
  },
});
```

## Related

- [Use box for a generic container with access to design tokens](/components/primitives/box/usage)
- [Manage horizontal layout using an inline component](/components/primitives/inline/usage)
- [Manage vertical layout using a stack component](/components/primitives/stack/usage)