Color

When using design system colors, you would usually start with a color palette consisting of values from 100 to 900, like green600. These values are static and are not themeable. In Reshaped, 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 Reshaped, most color tokens belong to one of three roles: background, border, and foreground. By assigning semantic roles to colors, we achieve predictable theming and dark mode support.

We use generic names for the color tokens, which means that color names don't rely on our component inventory. So you can build your custom components using the same color tokens, and they will still automatically support theming and dark mode.

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

This gives us a final token name:

.element {
  border: 1px solid var(--rs-color-border-neutral);
  background: var(--rs-color-background-neutral-faded);
  color: var(--rs-color-foreground-primary);
}

Background color tokens are used for styling the backgrounds of the elements on the page and the page itself.

When applying a color to your brand assets, you can use a separate brand color token. By default, it inherits the value of the primary background color, but you can change it to another value in your theme to separate it from components like buttons, badges, etc.

Border color tokens are used for the element's borders and dividers. Regular border colors ensure color contrast requirements for interactive elements, so they are usually used for styling borders of form fields or the focus ring outline. Faded border colors are used for decorative outlines. For instance, cards use a neutral-faded border token.

Foreground color tokens are used for text content, icons, and other elements rendered on top of a background. Foreground colors guarantee the contrast ratio when used on top of faded background tokens of the same color.

While foreground tokens are accessible on top of Page, Elevation, and Faded background colors, they won't be accessible on top of more prominent background colors like primary. To address this, we generate on-background color tokens. Their value is dynamically calculated based on the respective background value. You can safely use on-background colors with background color tokens, no matter which color values your theme has.

For example, in Reshaped's default theme, the on-background-primary color token is resolved to white. However, if you use yellow as a primary color, on-background-primary will automatically turn black to maintain contrast ratio.

All color roles have a disabled modifier that can be applied whenever a component gets disabled. The background disabled token also supports a faded modifier for cases when you're disabling elements with a transparent background.

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

There are two 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 modes. That's why Reshaped also supports white and black static color tokens. They are used for shadows, scrim gradients, and text content displayed on top of media content.

When a color value uses #000000 (hex) or rgb(0, 0, 0) in CSS, it becomes challenging 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 values separately. For instance, we would expose just the 0, 0, 0 part for black.

You can use these in your CSS with the rgba function to apply custom opacity.

.element {
  background: rgba(var(--rs-color-rgb-background-primary), 0.16);
}

Available rgb tokens:

--rs-color-rgb-background-neutral
--rs-color-rgb-background-neutral-faded

--rs-color-rgb-background-primary
--rs-color-rgb-background-primary-faded

--rs-color-rgb-background-positive
--rs-color-rgb-background-positive-faded

--rs-color-rgb-background-critical
--rs-color-rgb-background-critical-faded

--rs-color-rgb-background-disabled
--rs-color-rgb-background-disabled-faded
--rs-color-rgb-background-primary-faded

--rs-color-rgb-background-page
--rs-color-rgb-background-page-faded

--rs-color-rgb-background-base
--rs-color-rgb-background-elevated

--rs-color-rgb-black
--rs-color-rgb-white