Color

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 and are not themable. In UIC, 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 UIC, most color tokens belong to 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(--uic-color-border-neutral);
  background: var(--uic-color-background-neutral-faded);
  color: var(--uic-color-foreground-primary);
}

Background color tokens are used for styling the backgrounds of the elements on the page and the page itself. Each background color token has a faded modifier that always has enough contrast ratio to use with foreground color tokens.

Border color tokens are used for the element's borders and separators. Regular border colors ensure color contrast requirements for interactive elements, so they are usually used for styling borders of the form fields borders 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 the 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 color tokens.

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

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

Highlighted color tokens are used whenever a user interacts with an element, as in the button hover states. Having these tokens separated from the standard background colors allows you to control the luminosity of your interactive states of the components differently based on the used theme.

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 when you're disabling elements with transparent background.

To provide dark mode support, UIC follows the concept of elevation of surfaces. This means that some of the 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 — 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 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 mode. That's why UIC 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 uses #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, we would expose just the 0, 0, 0 part for black color.

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

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

Available rgb tokens:

--uic-color-rgb-background-neutral
--uic-color-rgb-background-neutral-faded
--uic-color-rgb-background-neutral-highlighted

--uic-color-rgb-background-primary
--uic-color-rgb-background-primary-faded
--uic-color-rgb-background-primary-highlighted

--uic-color-rgb-background-positive
--uic-color-rgb-background-positive-faded
--uic-color-rgb-background-positive-highlighted

--uic-color-rgb-background-critical
--uic-color-rgb-background-critical-faded
--uic-color-rgb-background-critical-highlighted

--uic-color-rgb-background-disabled
--uic-color-rgb-background-disabled-faded
--uic-color-rgb-background-primary-faded

--uic-color-rgb-background-page
--uic-color-rgb-background-page-faded

--uic-color-rgb-background-base
--uic-color-rgb-background-elevated

--uic-color-rgb-black
--uic-color-rgb-white