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.
This will give us a final token name:
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.
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 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.
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 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.
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.
Note, that in light mode, all elevation colors usually resolve to white color, while in dark mode they are different.
There are 2 tokens for separately controlling the global application background.
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.
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.