Design tokens

Design tokens are values used to style the system and your product. In Arcade, we expose tokens for units, fonts, colors and viewport sizes. To keep the tokens available for use in the product without any additional runtime setup, we use design tokens as css variables.

All css variables start with an --arcade prefix to avoid conflicts with external variables.

Colors

All colors exposed from Arcade are not just abstract color palette values. Instead, we're connecting our color tokens to specific component-agnostic UI roles: foreground, border and background. These roles let the token values work for components light and dark mode without adding any additional logic while still staying accessible.

Color token names follow the same structure to keep the naming scalable. Let's take a look at a couple of examples:

  • prefix is always arcade
  • role can be foreground, border, background
  • color can be neutral, primary, critical (usually a hue of red), positive (usually a hue of green)
  • state can be disabled, highlighted or faded (optional)

By combining these value, we get the following tokens:

Foreground colors

Border tokens

Background tokens

Exceptions

There are two colors that preserve their values in both light and dark mode so that they can be used on top of the media content, like images or videos:

Units

Units are values to let you consistently define elements sizes or spacing between them. We use a grid with 4px baseline by default and expose a number multiplied values for quick use.

If you need a custom unit, using the same grid baseline, you can get it by using css calc:

Radius

For the radiuses, we expose 3 tokens that can be used based on the component size:

Border width

Same as for radiuses we expose 3 token for border width:

Typography

Typography in Arcade is responsive based on the viewport sizes. Since that requires defining a group of variables for css properites and CSS doesn't support mixins out-of-the-box, we recommend using Text component for the typography definitions.

Viewports

There is no native support for custom media queries in CSS but we expose multiple media queries by using PostCSS custom media plugin.

Using tokens in JS

Since all variables are defined in CSS, you don't have to call any utilities or hooks to get access to the tokens. Instead, you can use them directly even in your inline styles or css-in-js code.