Color palettes and tokens: how to organize a system's color

A palette is the set of tones a brand uses; tokens give them names and functions. How to structure primitive, semantic and theme colors without losing control.

info Quick Definition
A color palette is the set of tones a product can use, and a color token is a named variable that stores one of those values and assigns it a function, such as “error color” or “primary button background”. Separating palette and tokens lets you change the brand, add a dark theme or fix a contrast problem without touching every screen.

What is a color token?

A token is a named decision. Instead of writing #B42318 in twenty components, you write color.error and let the value live in one place. When the team decides the error red must be darker to meet contrast, you change one value and the change reaches the whole product.

The Design Tokens Community Group’s specification puts it simply: a token is an object with a $value property. That property can be a literal value or a reference to another token, which the specification calls an alias. According to its definitions, the same value can have several names.

What is the difference between a palette and a token?

The palette is the inventory: the blues from 50 to 900, the neutral grays, the alert reds. The token is the use: which color goes on a button’s background, on the border of a field in error, on secondary text.

This difference matters because the palette changes with the brand and the token changes with the function. If the team rebrands, it changes the palette, and the tokens still point to the same uses.

How are they structured in layers?

A convention widely used in design teams has three layers:

  1. Primitives. Raw palette values with descriptive names such as blue.600. They do not say what they are for.
  2. Semantic tokens. They assign a function: color.text.primary, color.feedback.error, color.surface.default. They point to a primitive.
  3. Component tokens. They apply a semantic token to a specific piece: button.primary.background. They point to a semantic token.

This separation lets you change a primitive without reviewing components, and change a theme without duplicating files. It is a practice, not a standard rule: other teams use two layers or name them differently. What matters is that the relationship between layers is explicit and documented.

Color tokens also need to be accessible. Before you assign a semantic token to a background and a text, check the contrast of that pair. Color contrast math and the criteria in WCAG explained, in the contrast section, cover exactly that.

How do themes and dark mode work?

Themes are the clearest application of semantic tokens. A dark mode does not need a second set of components: it needs color.surface.default to point to a dark grey in the dark theme and to white in the light one. The components do not change; the reference does.

The DTCG 2025.10 format contemplates this: according to its announcement, it lets you manage light and dark modes, accessibility variants and brand themes without duplicating files. If your system has two themes, define the structure from the start rather than as a patch later.

One detail is often forgotten: the dark theme’s palette is not the inverse of the light one. Accent colors often need adjustment to keep contrast on dark surfaces, so review each combination.

Which format should you use?

The Design Tokens Community Group published the first stable version of its specification, 2025.10, in October 2025. It is a JSON format that defines tokens, groups, aliases and types. Its FAQ clarifies that it defines the exchange format and leaves organizational strategy to design system teams, and that the specification is not on the W3C Standards Track: a community group publishes it.

In version 2025.10 the value of a color is an object with colorSpace (for example srgb, oklch or display-p3) and components; hex is an optional fallback. A token can inherit its $type from a group, and an alias takes the type of the token it points to. An example with an alias:

{
  "$type": "color",
  "blue": {
    "600": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.114, 0.306, 0.847],
        "hex": "#1d4ed8"
      }
    }
  },
  "color": {
    "action": { "$value": "{blue.600}" }
  }
}

Tools such as Style Dictionary take tokens and transform them for different platforms and languages, and they also allow references between tokens with curly braces, such as {blue.600}. For the Figma side of the token flow, see Tokens Studio, and for the overall structure of the system, the token architecture.

Example

Illustrative example: a team has 40 screens with the brand blue typed as a fixed value in each component. They want to add a dark mode and, while reviewing, discover three nearly identical blues. They migrate to three layers: primitives with the blue scale, semantic tokens such as color.action.default and color.surface.default, and components that point to semantic tokens. Dark mode is implemented by changing the surface and text references. When they finish, the team has one place to change the action blue and one contrast check per token pair.

For your next project: review the colors on one screen, note the ones that repeat, and group each by function. If two colors serve the same function, they probably share a token.

Common mistakes

  • Naming tokens by color instead of function: blue-button becomes wrong when the button changes color.
  • Skipping the semantic layer and pointing components straight at primitives.
  • Creating too many tones without a rule, which makes the palette impossible to maintain.
  • Building dark mode by inverting colors without checking contrast.
  • Assigning tokens without testing pairs of background and text.
  • Using fixed values in new components, which breaks the system from the start.

Sources

Frequently asked questions

What is a color token?
It is a named variable that stores a color value, for example color.background.button.error. Using tokens instead of fixed values lets you change a color in one place and apply it across the product.
What is the difference between a palette and a color token?
The palette is the set of available colors, such as a blue scale from 50 to 900. A token gives a color a specific use, such as ‘primary button background’, and points to a value in the palette.
How are color tokens structured?
A common practice is to separate three layers: primitives (raw palette values), semantic tokens (their function, such as error color) and component tokens (application to a button or field). This separation is a team convention, not a mandatory standard.
What format do color tokens use?
The Design Tokens Community Group published version 2025.10 of its format in October 2025. It is JSON-based, uses properties such as $value, supports aliases between tokens and includes color spaces such as Oklch and Display P3.