XCSS

With components support xcss prop, xcss utility function should be used to wrap the XCSS style definition before passing it to the component.

1
2
import { xcss } from "@forge/react";

Description

XCSS is a styling API that utilizes Atlassian Design Tokens to style primitive components safely with tokens.

Key features

• XCSS restricts nested selectors completely from usage.
• Pseudo class / element selectors are supported currently.
• The majority of style attributes will be restricted to Atlassian Design Token based values to ensure safety and consistency.

Supported components

XCSS support is currently available on the Box and Pressable components.

Supported properties

• Border
• Color
• Opacity
• Shadow
• Size
• Layout
• Typography
• Space

Props

Border

Border color

Border color related properties accept border color tokens. Learn about applying the right color tokens by understanding color roles and referring to accessibility guidelines.

Border radius

Border width

Border style

Color

The colour related properties are used to style and enhance the text and background colours of the elements. Learn about applying the right color tokens by understanding color roles and referring to accessibility guidelines.

Typography

Opacity

Shadow

Size

Layout

Space

Examples

Basic

XCSS can pull together different types of interactions and UI in a safer, more composable way.

1
2
import React from "react";

import { Heading, Box, Stack, xcss } from "@forge/react";

const textStyle = xcss({
  color: "color.text",
});

const cardStyle = xcss({
  backgroundColor: "color.background.accent.purple.subtlest",
  padding: "space.200",
  borderColor: "color.border.discovery",
  borderWidth: "border.width",
  borderStyle: "solid",
  borderRadius: "radius.small",
  width: "240px",
});

export const Basic = () => (
  <Box xcss={cardStyle}>
    <Stack space="space.100">
      <Heading as="h3" level="h600">
        Heading
      </Heading>
      <Box xcss={textStyle}>Description</Box>
    </Stack>
  </Box>
);

Interactivity

To enable interactivity, use familiar selectors like :hover.

1
2
import React from "react";

import { Heading, Box, Stack, Link, xcss } from "@forge/react";

const textStyle = xcss({
  color: "color.text",
  marginBottom: "space.200",
});

const cardStyle = xcss({
  backgroundColor: "elevation.surface",
  padding: "space.200",
  borderColor: "color.border",
  borderWidth: "border.width",
  borderStyle: "solid",
  borderRadius: "radius.small",
  ":hover": {
    backgroundColor: "elevation.surface.hovered",
  },
});

const GetStartedCard = ({ header, description }) => {
  return (
    <Box xcss={cardStyle}>
      <Stack space="space.100" alignInline="start">
        <Heading as="h3" level="h600">
          {header}
        </Heading>
        <Box xcss={textStyle}>{description}</Box>
        <Link href="/">Get started</Link>
      </Stack>
    </Box>
  );
};

export const InteractivityExample = () => (
  <Inline space="space.200">
    <GetStartedCard
      header="Set up"
      description="Create a project and add tasks"
    />
    <GetStartedCard
      header="Plan project"
      description="Assign tasks and set timelines"
    />
  </Inline>
);