Color values

Simple colors

A simple color is a single literal color value. Unblu accepts the following literal formats:

Hex codes, either six digits (#ffffff) or three digits (#fff).
rgb() and rgba(), for example rgb(255, 255, 255) or rgba(0, 0, 0, 0.5).
hsl() and hsla(), for example hsl(0, 0%, 100%) or hsla(180, 50%, 50%, 0.5).
Named CSS colors, such as transparent.

Complex colors

A complex color is computed from one or more other values. Complex colors appear throughout Unblu’s default theme and in the configuration property reference, where you see them as values such as adjust-color(${com.unblu.theme.color.gray700}, $alpha: -0.95). The sections below describe the forms a complex color can take.

Color references

A complex color can reference another color property instead of using a literal color value. Write the reference as a dollar sign followed by the property’s full key in braces: ${<property-key>}. For example, ${com.unblu.theme.color.error} uses the value of the com.unblu.theme.color.error property.

A reference can point to a property that itself contains a reference or function, which Unblu resolves in turn, up to a maximum depth of 25 levels.

Color functions

Unblu provides three color functions: adjust-color, scale-color, and change-color. Each one takes a base color and changes one or more of its channels, such as its lightness or its opacity. The base color is a literal color, a color reference, or a light-dark() function. Write the base color first, followed by one or more modifiers separated by commas.

Each modifier names the channel to change and the value to apply to it, written $channel: <value>. The channels you can change are:

The RGB channels $red, $green, and $blue. Each takes an integer from 0 to 255 or a percentage.
The HSL channels $hue, $saturation, and $lightness. $hue takes an angle in degrees. $saturation and $lightness take percentages.
The alpha channel $alpha, which sets opacity. It takes a value from 0 to 1.

You can’t change RGB and HSL channels in the same call, but you can combine either set with $alpha.

The three functions differ in how they combine your value with the channel’s existing value in the base color:

adjust-color adds your value to the channel’s existing value. For example, adjust-color(${com.unblu.theme.color.warning700}, $saturation: -90%, $lightness: -4%) desaturates the color and darkens it slightly.
change-color replaces the channel’s value with your value. For example, change-color(${com.unblu.theme.color.gray000}, $alpha: 0.08) sets the gray’s opacity to 0.08.
scale-color moves the channel a percentage of the way toward a limit: toward 0 for a negative value, or toward the channel’s maximum for a positive value. For example, scale-color(${com.unblu.theme.color.backgroundLight}, $lightness: -5%) reduces the background’s lightness by 5 %.

The `light-dark()` function

The light-dark() function supplies separate colors for light and dark mode. It takes exactly two arguments: light-dark(<light-color>, <dark-color>). The first is the color for light mode, the second the color for dark mode.

Each argument can be a literal color, a reference, or a color function. For example, light-dark(${com.unblu.theme.color.neutral050}, ${com.unblu.theme.color.gray900}) uses a light neutral in light mode and a dark gray in dark mode. You can also transform each branch, as in light-dark(adjust-color(${com.unblu.config.nav.ui.backgroundHover}, $lightness: -8%), adjust-color(${com.unblu.theme.color.backgroundStrong}, $lightness: 5%)).

You can’t nest one light-dark() inside another.

For information on how Unblu chooses between the light and dark values, and how to give a theme separate dark colors, refer to Color mode.