Color Tokens

Introduction

Color tokens define the colors of text, surfaces, borders, icons, links, shadows, and gradients. A brand sets the base color of each palette, and the shades, the context colors, and the component colors are derived from these base colors. The context and the component colors follow the theme; the committed themes are light and dark.

The tables list each token with the token it references. A column named light or dark holds the reference of the token in that theme.

Token levels

Color tokens have the three token levels and a fourth group, the primitive colors. The base tokens hold the colors of every theme, and the context tokens select the colors of the current theme. A component color resolves through the three levels:

color.button.default.fg-idle                     component token
  {color.context.default.fg-idle}                context token
    {color.base.context.light.default.fg-idle}   base token of the light theme
      {color.base.context.light.default.fg-main}
        {color.base.primitive.light.neutral.90}
          {color.base.primitive.light.neutral.base}

In the dark theme, color.context.default.fg-idle references {color.base.context.dark.default.fg-idle}, and the rest of the chain follows the dark tokens. The primitive colors select the palette of the current theme in the same way: color.primitive.neutral.90 references {color.base.primitive.light.neutral.90} in the light theme.

The token sets of these groups are in packages/tokens/source/base/.

theme-base.json references the light base tokens, and theme-dark.json replaces these references with the dark ones. See the Tokens Studio guide for the token sets and the groups that select them.

Base tokens

Base tokens hold the colors of every theme at once, under color.base.primitive, color.base.context, and color.base.shadow, each with a light and a dark group. They are the source of the other color tokens and do not follow the theme of an app.

Palettes

A palette is a group of colors that are derived from one base color. The palettes are black, white, primary, secondary, neutral, danger, success, warning, info, brand, and accent. Next to its base color, every palette has a contrast color and a transparent color.

A base token holds a color of its own, and the other tokens of its palette reference it. The token set of a brand, such as packages/tokens/source/brand-chassis/brand-base.json, overrides the base tokens, and it can override a contrast token when the base color needs the other contrast color.

Shades

Shades are lighter and darker steps of the base color, named from 05 for the lightest to 95 for the darkest. Every palette except black and white has them. A shade references the base color with a color modifier of Tokens Studio: lighten mixes the color with white and darken with black in the sRGB color space, by the share that a modify.* token holds.

The shades of the other palettes have the same names and the same modifiers, such as color.base.primitive.light.danger.60.

Transparency colors

Transparency colors are a color of the palette with an opacity token as its alpha value. Their name holds the shade and the opacity level: t-5020 is shade 50 with opacity.level.20. Every palette with shades has the transparency colors of its shade 50.

The black and white palettes have no shades, so their transparency colors are named by the opacity level only, from t-05 to t-95: color.base.primitive.light.black.t-50 is the base color of black with opacity.level.50.

Base context colors

color.base.context.<theme>.<context>.<role> assigns a color of a palette to each role of each context, once per theme. The roles are those of the context tokens. A role references a shade, a transparency color, or another role of its context, alone or with an opacity token as its alpha value.

color.base.shadow.<theme>.<context> holds the shadow color of a context in the same way. The shadow colors of default and alternate reference transparency colors of the black palette, and those of primary, secondary, neutral, danger, success, warning, and info reference t-5040 of their palette.

Primitive colors

Primitive colors are the palettes of the current theme. Each color.primitive.<palette>.<name> references the base token of the same name: color.base.primitive.light.* in the light theme and color.base.primitive.dark.* in the dark theme.

The names after the palette are those of the base tokens: base, contrast, transparent, the shades, and the transparency colors.

Gradients

Gradient tokens are linear gradients from the transparent to the base color of a palette. gradient.primitive.<palette>.l-50-<angle> names the angle in three digits, from 000 to 315 in steps of 45 degrees. The gradients of black and white leave out the shade: gradient.primitive.black.l-090.

The token type of a gradient is color, so the build writes gradients into the color files. See Platform output for their parts on iOS and Android.

Context tokens

Context tokens name a color by its role, such as fg-main for text and bg-main for the surface under it. Every context has the same roles, so a component changes its context without changing the roles it uses.

Roles

A role is the last part of a context token, and its prefix names what it colors: fg for text, bg for surfaces, border, icon, cue, link, and dim. Each role references the base context color of the same name in the current theme. The roles of color.context.default are listed in full; the other contexts, such as color.context.danger.fg-main, have the same roles with the colors of their palette.

The idle, hover, press, and disabled roles are the states of a control. The button colors reference them, and a component without color tokens of its own uses them in the same way.

Shadow colors

Shadow colors are the colors of the layers of a shadow. color.shadow.<context> references the base shadow color of its context in the current theme, and the shadow.elevation.* tokens of the shadow tokens reference the shadow colors.

Utility colors

Utility colors are in the token sets of the themes, but the filters of the build leave color.utility.* out of every file, so no platform has them. Their names start with container, inverter, technical, grid-column, and grid-sidebar, such as color.utility.grid-column-default.

Component tokens

Component tokens assign a context color to a part of a component. Every component color references a token of color.context.*, so it follows the theme, and its reference is the same in every theme.

Accordion

Accordion colors cover the item, its title in the idle and the active state, the indicator, and the border between items.

Button

Button colors are named color.button.<context>.<part>-<state>, with the parts fg, bg, and border and the states idle, disabled, hover, and press. Every context has its button colors: default, alternate, black, white, primary, secondary, neutral, danger, success, warning, and info.

The fg and bg tokens of the other contexts reference the role of the same name in their context: color.button.danger.bg-hover references {color.context.danger.bg-hover}. Only default and alternate have a visible border. The border tokens of the other contexts reference the transparent-color of their context in every state.

Date picker

Date picker colors are in the group color.datepicker. A pair of fg and bg tokens colors a day in each of its states, and fg-main, bg-main, border-main, and border-subtle color the picker itself.

Dropdown

Dropdown colors set the text, the background, and the icon of a menu item in the idle, hover, active, and disabled state. The header of a group of items and the menu itself have their own tokens.

Form input

Form input colors are named color.form-input.<state>.<part>, with the states idle, focus, error, success, and disabled. Every state has the same parts, which the idle state shows.

The focus, error, and success states change the border and the help text and keep the other references of idle. The disabled state changes every part.

List

List colors set the icon of a list item and its disclosure indicator.

Map

Map colors set the marker, the paths, the points, and the start and the end of a trip.

Message

Message colors set the chat surface, the form, and the pairs of fg and bg tokens of received, sent, embedded, and status messages.

Page

Page colors set the background of the body and of a section. An app can override them in its token set, as packages/tokens/source/base/app-demo.json does, so the table has a column for each committed app, docs and demo.

Pagination

Pagination colors set the dots of a pagination in the idle and the active state.

Progress

Progress colors set the text, the background, and the border of a step, for the steps in the past, the current step, and the next steps.

Section

Section colors set the text and the icon of a section in the sizes large, medium, and small.

Segment

Segment colors set the bar of a segmented control and its segments in the idle and the active state.

Table

Table colors set the head and the data cells, the rows in the alternating, hover, active, and edit state, and the border and the sort icon.

Usage

Choose the token of the most specific level that fits, because only the context and the component tokens follow the theme.

• Use a component token for a part of its component: color.table.bg-alt for the alternating rows of a table.
• Use a context token for everything that has no component token. Choose the context by meaning (danger for an error) and the role by function (fg-main for text, border-subtle for a divider).
• Use a primitive color only when no role has the shade, as the gradients do with color.primitive.primary.base.
• Do not use color.base.* in an app. A base token such as color.base.context.light.default.fg-main keeps the color of the light theme in the dark theme.

Accessibility

Foreground and background roles are made to be used in pairs. Take both roles of a pair from the same context.

In color.context.default, fg-subtle and fg-slight are fg-main with the alpha value of an opacity token, so their contrast is lower than that of fg-main on every background. The contrast of a pair depends on the base colors of the brand, on the context, and on the theme, so measure the pairs of a brand in each theme.

Platform output

Colors print as hex or rgba() values on the web, as UIColor on iOS, and as <color> resources on Android.

The build writes the primitive colors, the context colors, and the gradients into the color file of each theme, such as color-light.scss and color-dark.scss. The component and the shadow colors are in these files too, and on the web the shadow tokens with the colors of the theme. The main file has the base colors, and the component and the shadow colors of the first theme.

The values in the examples are those of the chassis brand in the current version and differ in other brands.

With the web platform, a color that references a context or a primitive color prints the custom property of Chassis CSS instead of its value, so every component color is a var(--…) reference. The build writes these lines into color-light.scss:

$cx-color-context-default-fg-main: #161a1b !default;
$cx-color-context-default-fg-subtle: rgba(22, 26, 27, 0.5) !default;
$cx-color-button-default-fg-idle: var(--default-fg-idle) !default;

On iOS, the channels have three decimals. The build writes these constants into ColorLight.swift:

    public static let ColorContextDefaultFgMain = UIColor(red: 0.086, green: 0.102, blue: 0.106, alpha: 1)
    public static let ColorContextDefaultFgSubtle = UIColor(red: 0.086, green: 0.102, blue: 0.106, alpha: 0.5)

Color.swift has the same names with colors that follow the appearance of the device: a constant whose colors differ between the light and the dark theme is a dynamic UIColor that holds both.

On Android, the alpha value comes first, in the first two digits of the hex number. The build writes these resources into color_light.xml:

  <color name="color_context_default_fg_main">#ff161a1b</color>
  <color name="color_context_default_fg_subtle">#80161a1b</color>

A gradient prints as a linear-gradient() value on the web. On iOS and Android the build splits it into an angle and, for each stop, a color and a position: GradientPrimitivePrimaryL50090Angle, GradientPrimitivePrimaryL50090Stop1Color, and GradientPrimitivePrimaryL50090Stop1Position on iOS, gradient_primitive_primary_l_50_090_angle, gradient_primitive_primary_l_50_090_stop_1_color, and gradient_primitive_primary_l_50_090_stop_1_position on Android.

See the web, iOS, and Android docs for the files that hold these names.