This document describes the technical specification for design token color values and opacity.
This specification was published by the Design Tokens Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.
This is a snapshot of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C or the Design Tokens Community Group Membership. Don't cite this document other than as work in progress.
This document has been published to facilitate Wide Review.
This document was produced by the Design Tokens Community Group, and contributions to this draft are governed by Community Contributor License Agreement (CLA), as specified by the W3C Community Group Process.
GitHub Issues are preferred for discussion of this specification.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and MUST NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Color tokens can be used to represent colors in different color spaces. Colors represented in tokens can then be converted to other color spaces by translation tools.
Generally speaking, this module uses CSS Color Module Level 4 for reference to concepts and terminology. CSS Color Module Level 4 is a W3C Working Draft and is not a final specification. It is subject to change and may not be implemented in all browsers or platforms.
This section provides a high-level overview of the terminology used in the specification and how it relates to color science and colorimetry.
Color space
A color space is a specific organization of colors, which helps in the reproduction of color in both physical and digital realms. It defines a range of colors that can be represented and manipulated.
Color model
A color model is a mathematical representation of colors within a specific color space. It defines how colors are represented as numerical values, typically using components.
Color gamut
A color gamut is the complete range of colors that can be represented in a specific color space. It defines the limits of color reproduction for that space.
Component
A component is a single value that defines a part of a color in a specific color space. For example, in the RGB color space, the components are red, green, and blue.
Hue
Hue is the attribute of a color that allows it to be classified as red, green, blue, etc. In many color spaces, hue is represented as an angle on a color wheel. Different color spaces may position colors differently on the wheel.
Saturation
Saturation is the colorfulness of a color relative to its own brightness. It describes how much gray is present in a color. A fully saturated color has no gray, while a desaturated color appears more grayish. It is inherently tied to both chroma and lightness, especially in models like HSL or HSV. A color can be highly saturated but still appear light or dark depending on its lightness.
Lightness
Lightness is the perceived brightness of a color. It describes how light or dark a color appears.
Chroma
Chroma refers to the colorfulness of a color relative to the brightness of a similarly illuminated white. It measures how pure or intense a color appears. In the CIE LCH color model (Lightness, Chroma, Hue), Chroma is independent of lightness and expresses how far a color is from neutral gray along the chromatic axis.
Alpha
Alpha is a component that represents the transparency of a color. It defines how opaque or transparent a color is, with the minimum value (usually 0) being fully transparent and the maximum value (usually 1) being fully opaque.
Represents a color.
For color tokens, the $type property MUST be set to the string color.
The $value property can then be used to specify the details of the color, The $value object contains the following properties:
colorSpace (required): A string that specifies the color space or color model. For supported color spaces, see the supported color spaces section below.components (required): An array representing the color components. The number of components depends on the color space. Each element of the array MUST be either:alpha (optional): A number that represents the alpha value of the color. This value is between 0 and 1, where 0 is fully transparent and 1 is fully opaque. If omitted, the alpha value of the color MUST be assumed to be 1 (fully opaque).hex (optional): A string that represents a fallback value of the color. The fallback color MUST be formatted in 6 digit CSS hex color notation format to avoid conflicts with the provided alpha value.When specifying a color in some color spaces, a value of 0 could be ambiguous. For example, in the HSL color space, colors with a hue of 0 are red; while a single color like hsl(0, 0, 50) would not be rendered as red, it may be treated as a completely desaturated red when interpolated with other colors. Therefore, in certain color spaces, 0 is insufficient to indicate that there is no value for a given component.
CSS Color Module Level 4 has introduced the none keyword to indicate that a component is missing, or not applicable. For example, in the HSL color space, the none keyword may be used to indicate that there is no angle value for the color; a color with a hue value of none MAY be rendered differently from a color with a hue angle of 0, or result in different colors when interpolating.
The none keyword MAY be used in the components array to indicate that a component is not applicable or not specified.
Contrast this with the following example where the Hue is specified as 0:
While both examples will render as white, the first example is more explicit about the fact that the hue is not applicable. This is important when interpolating between colors or mixing colors, where using colors with components of 0 or none can yield different results.
The following values are supported for the colorSpace property. The components array will vary depending on the color space.
| Color Space | Key | Values | |
|---|---|---|---|
| sRGB | "srgb" |
Red | [0 - 1] |
| Green | [0 - 1] | ||
| Blue | [0 - 1] | ||
| sRGB linear | "srgb-linear" |
Red | [0 - 1] |
| Green | [0 - 1] | ||
| Blue | [0 - 1] | ||
| HSL | "hsl" |
Hue | [0 - 360) |
| Saturation | [0 - 100] | ||
| Lightness | [0 - 100] | ||
| HWB | "hwb" |
Hue | [0 - 360) |
| Whiteness | [0 - 100] | ||
| Blackness | [0 - 100] | ||
| CIELAB | "lab" |
Lightness | [0 - 100] |
| A | [-Infinity - Infinity]* | ||
| B | [-Infinity - Infinity]* | ||
| LCH | "lch" |
Lightness | [0 - 100] |
| Chroma | [0 - Infinity]** | ||
| Hue | [0 - 360) | ||
| OKLAB | "oklab" |
Lightness | [0 - 1] |
| A | [-Infinity - Infinity]† | ||
| B | [-Infinity - Infinity]† | ||
| OKLCH | "oklch" |
Lightness | [0 - 1] |
| Chroma | [0 - Infinity]‡ | ||
| Hue | [0 - 360) | ||
| Display P3 | "display-p3" |
Red | [0 - 1] |
| Green | [0 - 1] | ||
| Blue | [0 - 1] | ||
| A98 RGB | "a98-rgb" |
Red | [0 - 1] |
| Green | [0 - 1] | ||
| Blue | [0 - 1] | ||
| ProPhoto RGB | "prophoto-rgb" |
Red | [0 - 1] |
| Green | [0 - 1] | ||
| Blue | [0 - 1] | ||
| Rec 2020 | "rec2020" |
Red | [0 - 1] |
| Green | [0 - 1] | ||
| Blue | [0 - 1] | ||
| XYZ-D65 | "xyz-d65" |
X | [0 - 1] |
| Y | [0 - 1] | ||
| Z | [0 - 1] | ||
| XYZ-D50 | "xyz-d50" |
X | [0 - 1] |
| Y | [0 - 1] | ||
| Z | [0 - 1] | ||
sRGB was the standard color space for all CSS colors before CSS Color Module 4. It is the most widely used color space on the web, and is the default color space for most design tools.
[Red, Green, Blue]
0 and 1 representing the red component of the color.0 and 1 representing the green component of the color.0 and 1 representing the blue component of the color.For more information on the sRGB color space, see Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB.
sRGB linear is a linearized version of sRGB. It is used in some design tools to represent colors in a linear color space.
[Red, Green, Blue]
0 and 1 representing the red component of the color.0 and 1 representing the green component of the color.0 and 1 representing the blue component of the color.For more information on the sRGB linear color space, see Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB.
HSL is a color model that is a polar transformation of sRGB, supported as early as CSS Color Level 3.
[Hue, Saturation, Lightness]
0 up to (but not including) 360, but representing the hue angle of the color on the color wheel.0 and 100 representing the percentage of color saturation.0 and 100 representing the percentage of lightness.For more information on the HSL color space, see HSL: light vs saturation.
Another color model, a polar transformation of sRGB.
[Hue, Whiteness, Blackness]
0 up to (but not including) 360 representing the angle of the color on the color wheel.0 and 100 representing the percentage of white in the color.0 and 100 representing the percentage of black in the color.For more information on the HWB color space, see HWB — A More Intuitive Hue-Based Color Model.
CIELAB is a color space that is designed to be perceptually uniform.
[L, A, B]
0 and 100 representing the percentage of lightness of the color.A and B are theoretically unbounded, but in practice don't exceed -160 to 160.
For more information on the CIELAB color space, see ISO/CIE 11664-4:2019(E): Colorimetry — Part 4: CIE 1976 L*a*b* colour space.
LCH is a cylindrical representation of CIELAB.
[L, C, Hue]
0 and 100 representing the percentage of lightness of the color.0 up to (but not including) 360 representing the angle of the color on the color wheel.The minimum value of C is 0, which represents a neutral color (gray), and its maximum is theoretically unbounded, but in practice doesn't exceed 230.
For more information on the LCH color space, see the CIELAB and LCH section of CSS Color Module Level 4.
OKLAB is a perceptually uniform color space that is designed to be more accurate than CIELAB.
[L, A, B]
0 and 1 representing the lightness of the color.Like in CIELAB, A and B are theoretically unbounded, but in practice don't exceed -0.5 to 0.5.
For more information on the OKLAB color space, see OKLAB: A Perceptually Uniform Color Space.
OKLCH is a cylindrical color model of OKLAB.
[L, Chroma, Hue]
0 and 1 representing the lightness of the color.0 up to (but not including) 360 representing the angle of the color on the color wheel.Like in LCH, the minimum value of Chroma is 0, which represents a neutral color (gray), and its maximum is theoretically unbounded, but in practice doesn't exceed 0.5.
For more information on the OKLCH color space, see OKLAB: A Perceptually Uniform Color Space.
Display P3 is a color space that is designed to be used in displays with a wide color gamut. It is based on the P3 color space used in digital cinema.
[Red, Green, Blue]
0 and 1 representing the red component of the color.0 and 1 representing the green component of the color.0 and 1 representing the blue component of the color.For more information on the Display P3 color space, see the definition of Display P3.
A98 RGB is a color space that is designed to be used in displays with a wide color gamut. It is based on the Adobe RGB color space.
[Red, Green, Blue]
0 and 1 representing the red component of the color.0 and 1 representing the green component of the color.0 and 1 representing the blue component of the color.To learn more about the A98 color space, see the Adobe RGB color space article on Wikipedia.
ProPhoto RGB is a color space that is designed to be used in displays with a wide color gamut. It is based on the ProPhoto RGB color space.
[Red, Green, Blue]
0 and 1 representing the red component of the color.0 and 1 representing the green component of the color.0 and 1 representing the blue component of the color.For more information on the ProPhoto RGB color space, see Design and Optimization of the ProPhoto RGB Color Encodings .
Rec 2020 is a color space that is designed to be used in displays with a wide color gamut. It is based on the Rec 2020 color space.
[Red, Green, Blue]
0 and 1 representing the red component of the color.0 and 1 representing the green component of the color.0 and 1 representing the blue component of the color.For more information on the Rec 2020 color space, see Recommendation ITU-R BT.2020-2: Parameter values for ultra-high definition television systems for production and international programme exchange .
XYZ-D65 is a color space that is designed to be able to represent all colors that can be perceived by the human eye. It is a fundamental color space — all other spaces can be converted to and from XYZ. It is based on the CIE 1931 color space, using the D65 illuminant. XYZ is not commonly used in design tools, but is useful for color conversions.
[X, Y, Z]
0 and 1 representing the X component of the color.0 and 1 representing the Y component of the color.0 and 1 representing the Z component of the color.For more information on the XYZ-D65 color space, see Colorimetry, Fourth Edition. CIE 015:2018.
XYZ-D50 is similar to XYZ-D65, but uses the D50 illuminant.
[X, Y, Z]
0 and 1 representing the X component of the color.0 and 1 representing the Y component of the color.0 and 1 representing the Z component of the color.For more information on the XYZ-D50 color space, see Colorimetry, Fourth Edition. CIE 015:2018.
Future versions of this spec may add support for additional color spaces, depending on adoption and support in design tools.
This section is non-normative.
Gamut mapping is the process of converting colors from one color space to another.
Gamut mapping is necessary when the source color space has a larger gamut than the target color space. This can happen when converting colors from a wide-gamut color space (like Display-P3) to a smaller gamut color space (like sRGB). Gamut mapping ensures that the colors are represented accurately in the target color space, even if some colors cannot be represented exactly.
When transforming colors, translation tools MAY use the gamut mapping algorithm that best fits the use case. For example, if the goal is to preserve the appearance of colors, a perceptual gamut mapping algorithm may be used. If the goal is to preserve the exact color values, a saturation or relative colorimetric gamut mapping algorithm may be used.
Token authors should be aware that the choice of gamut mapping algorithm can significantly affect the appearance of colors in the target color space. If colors need to be transformed between color spaces, it's important to validate the output of the translation tool to ensure that the colors are represented accurately and consistently.
This section is non-normative.
In many cases, colors may be interpolated, or blended, to create new colors. For example, when creating a gradient, colors are often interpolated between two or more key colors.
Interpolation can be done in different color spaces, and the choice of color space can affect the appearance of the resulting colors. Translation tools MAY use different interpolation methods depending on the color space and the desired effect. Authors should be aware of the implications of interpolation in different color spaces and validate interpolated colors to ensure they meet design requirements.
This section is non-normative.
There are 3 main categories of design tokens that we will continue to reference in this specification.
Base tokens are the lowest level tokens.
A design token’s value MAY be a reference to another token. The same value MAY have multiple names or aliases.
Component-specific tokens provide design decisions at the component level and improve the separation of concerns in your token architecture.
There are many naming options when it comes to design tokens, especially color type tokens. We’ve identified two that seem to be most commonly implemented, descriptive and numerical.
For Base tokens, here’s how they MAY be represented in each version:
Descriptive names can be more emotional and human-friendly because they often relate to tangible things that people interact with, like grass or watermelon.
| Pros | Cons |
|---|---|
| Easier for some people to identify with, could be used to distinguish brand colors from product colors | Harder to determine the scale of colors (for example: which ones are lighter vs. darker? How well do they pair together?) |
| Names may not be easily recognized by non-English speakers. For teams working across languages, this may not be a good choice |
Numerical tokens often follow a scale to help delineate how the colors progress. For example, when using an ordered scale, color.blue.500 may be the base color, where the lightest color value is color.blue.100, and the darkest value could be color.blue.900, and these values are ordered in increments of 100s in between. We recommend not using sequential numbers (ex: 1, 2, 3, 4) for scalability in case future colors need to be added in between two existing colors.
Numerical token names can also allow for further specificity when needed. For example, when creating neutral palette tokens (like grays), the scale may increase by increments of 25 instead of 100 at the lightest values, and then increment by 100 thereafter.
Numerical tokens can also be named through bounded scales. These tokens utilize a distinguishing value based on the actual color used for the token, such as in HSL’s lightness value to vary shades of a tint.
Token names MAY also be generated by tools, where the user specifies the base name, and the tool appends scale numbers based on changes to the underlying value.
| Pros | Cons |
|---|---|
| Easy mapping between different tokens for color contrast. For example, all 100-400 tokens pair with 500-900 tokens in order to create accessible color combinations. | Less memorable and less obvious difference between tokens |
| If using bounded scales, the token name can help indicate something about the underlying value |
For Alias Tokens, we recommend grouping tokens with similar intentions by prioritizing the category + property within the name. For example, all background color Alias tokens would likely start with color.background.XXX.
We recommend avoiding abbreviations. For example, use “background” instead of “bg”, to help with clarity.
Here’s how alias tokens may be represented:
Color alias tokens could also be grouped by concept, like so:
Component-specific names should start with the component they support and be located close to the component code. They commonly refer to alias tokens and can be helpful when trying to use consistent styles across components while still maintaining separation of concerns.
There are no issues listed in this specification.
Referenced in: