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.

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

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.

• Use autogenerated on-background color tokens to render accessible text elements on color backgrounds. More about hem in the foreground colors section.
• Use faded color modifier to ensure there is enough color contrast when using with the same color foreground token.

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.

• background-elevation-base is used for the background of elements displayed directly on the page surface, like Card.
• background-elevation-raised is used for the background of elements that are slightly elevated compared to other elements, like elevated Card.
• background-elevation-overlay is used for elements overlaying other content, like Popover or Modal.

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