Color tokens help to communicate hierarchy of the content, its meaning and brand presense.

When using design systems colors, you would usually start with a color palette consisting of values from 100 to 900, like green600. These values are static values and are not themable. In Arcade we intentionally skip this core layer and instead work with the semantic color tokens.

Semantic color tokens represent not just a color value but also a semantic role it's used for. In Arcade, majority of color tokens belong to one of three main roles: background, border and foreground. By assigning semantic roles to colors we achieve predictable theming and dark mode support out of the box.

Color naming is still built to be quite generic, which means that color names don't rely on our component inventory. You can build you custom components using the same color tokens and they will still automatically support features like dark mode.

Every color token follows the same naming convention that is easy to follow.

  • Start with a prefix that includes the system name and the token type arcade-color.
  • Pick a semantic role to use the color for, for instance background.
  • Pick a color name you want to use, like primary or positive.
  • Pick an optional modifier for the color, like faded or highlighted.

This will give us a final token name:

Background colors

Background color tokens are used for backgrounds of all elements on the page. Each background color token has a faded modifier which you can use together with any foreground color token ensuring its contrast ratio.

Border colors

Background color tokens are used for the elements outline color styles. They can be combined together with background color tokens.

Regular border colors ensure color contrast requirements for interactive elements, so they are usually used for the form fields borders or focus ring outline. Faded border colors are used for decorative outlines. For instance, neutral-faded border is used for cards.

Foreground colors

Foreground color tokens are used for the content displayed on the surfaces, like text or icons. Foreground colors ensure the contrast ratio of them when used on top of background color tokens.

Additionally to regular foreground color tokens, we also dynamically generate on tokens. Their value is dynamically calculated based on the respective background value. This means that these on colors can be safely used on backgrounds, no matter which theme you have created.

For example, in Arcade default theme all these color tokens are resolved to white color. In case we would use yellow as our primary color, on-background-primary will automatically turn black.

Disabled colors

All color roles have a disabled modifier that can be applied whenever a component gets disabled. Same as in other roles, it supports faded modifiers for the cases like when you're disabling elements non-colored background.

Highlighted colors

Highlighted color tokens are used whenever an element is being interacted with, as in hover states of buttons. Having these tokens separated from the regular background colors, allows you to control the luminosity of your interactive states of the components differently based on the used theme.

Elevation colors

To provide dark mode support, Arcade follows the concept of elevation of surfaces. This means that some of the elements of the page can be displayed higher on the z-axis. Elevating an element changes its shadow token, but since it's not prominent in dark mode – background color change can help users understand the hierarchy of the elements.

  • base elevation is used for background of elements displayed directly on the page surface.
  • elevated background is used for elements displayed on top of other elements, like Popover or DropdownMenu.

Note, that in light mode, all elevation colors usually resolve to white color, while in dark mode they are different.

Page colors

There are 2 tokens for separately controlling the global application background.

Static colors

When working with media content, like images or videos and rendering content on top of it, colors should preserve their values in both light and dark mode. That's why Arcade also supports white and black static color tokens. They are used for shadows, scrim gradients and text content displayed on top of them.

RGB color values

When a color value is using #000000 (hex) or rgb(0, 0, 0) in CSS it becomes a challenge to apply opacity just to the color value without making the whole component transparent. That's why for background color tokens we also expose their RGB value as separate values. For instance, for black color, we would expose just the 0, 0, 0 part.

This means that you can use it in your CSS with rgba function to apply custom opacity.