Tokens

All design tokens are defined as CSS Custom Properties (also known as “CSS Variables”). You should reference these properties when creating custom styles.

This page walks through each type of token and includes examples for each option.

Avoid using CSS variables defined by the stylesheet but not listed here; these aren’t part of the public API and may change in between major releases.

Colors

All colors are prefixed with --color-. The stylesheet defines 2 sets of colors: the standard palette and semantic colors.

Standard Palette

The stylesheet defines multiple shades for each of the following colors: brand, red, orange, yellow, green, teal, blue, purple, magenta, and gray.

There are 9 shades for each color, ranging from 1 to 9, where lower numbers have the most contrast with the page background. In other words, shade 1 is the darkest shade in light mode, but the lightest shade in dark mode. Different design systems have different numbering schemes, but a good mental model for this one is that light mode is the canonical color mode, and the number of a given color refers to its lightness.

There are also 2 transparent variants for each color: transparent and extra-transparent.

The variables for these colors all use the standard --color- prefix, followed by the color name and shade. For example, the color red with lightness 1 is defined as --color-red-1, while red with high transparency is defined as --color-red-extra-transparent. Below is an example of how to reference these colors in a stylesheet:

.red {
  background-color: var(--color-red-1);
}

.transparent-red {
  background-color: var(--color-red-extra-transparent);
}

Below are samples of all the colors in shades 1 through 9:

1 2 3 4 5 6 7 8 9

brand

1 2 3 4 5 6 7 8 9

red

1 2 3 4 5 6 7 8 9

orange

1 2 3 4 5 6 7 8 9

yellow

1 2 3 4 5 6 7 8 9

green

1 2 3 4 5 6 7 8 9

teal

1 2 3 4 5 6 7 8 9

blue

1 2 3 4 5 6 7 8 9

purple

1 2 3 4 5 6 7 8 9

magenta

1 2 3 4 5 6 7 8 9

gray

Semantic Colors

In addition to the standard palette, the stylesheet defines a set of “semantic” colors. These colors are named after their intended use cases:

body

the primary background color for the document

body-alt

the secondary background color, used on surfaces like cards

body-text

the primary text color for the document

body-text-alt

the secondary text color for the document

body-text-invert

color for text on backgrounds that contrast with the page background

shadow

a transparent gray used for box shadows

border

a gray used as the default color for borders

Unlike standard palette colors, these don’t come in multiple shades.

Shadows

The variables for shadows are all prefixed with --shadow-. They are designed to be used with the box-shadow property and are given T-shirt sizes describing how large the shadow should be.

shadow-none

shadow-s

shadow-m

shadow-l

shadow-xl

Font Sizes

The variables for font sizes are all prefixed with --font-size-, which is followed by a T-shirt size between xs and 4xl. For example, the font size m represents a medium size for text and can be referenced as --font-size-m.

Use sizes smaller than m sparingly, as overuse of small fonts can negatively impact the readability of the page and potentially force users to zoom in.

This text has a size of xs.

This text has a size of s.

This text has a size of m.

This text has a size of l.

This text has a size of xl.

This text has a size of 2xl.

This text has a size of 3xl.

This text has a size of 4xl.

Font Weights

The variables for font weights are all prefixed with --font-weight-. For example, the font weight normal can be referenced as --font-weight-normal.

This text has a weight of light.

This text has a weight of normal.

This text has a weight of semibold.

This text has a weight of bold.

This text has a weight of black.

Font Families

The variables for font families are all prefixed with --font-family-. For example, the font family body can be referenced as --font-family-body.

This text has a family of body.

This text has a family of heading.

This text has a family of mono.

Spacing

Most spacing tokens scale with the screen width, becoming slightly more spread out as the screen widens. The variables for spacing are prefixed with --space- and are implemented as T-shirt sizes between 3xs and 3xl, plus 3 additional sizes: none, body-x, and body-y. The none size is used to represent no spacing, while body-x and body-y are used to define the padding around the edges of the app.

none

3xs

2xs

2xl

3xl

body-x

body-y

Radii

The variables for radii are all prefixed with --radius-. They’re designed to be used with the border-radius property.

radius-none

radius-s

radius-m

radius-l

radius-xl

radius-2xl

radius-full

Border Widths

The variables for border widths are all prefixed with --border-. They’re designed to be used with the border-width property.

border-none

border-s

border-m

border-l

border-xl

Easing Functions

The variables for easing functions are all prefixed with --ease-. They’re designed to be used with the animation-timing-function property.

Default

var(--ease-default)

A general-purpose easing function that works well for most use cases.

Out

var(--ease-out)

An easing function that starts fast and slows down at the end.

var(--ease-in)

An easing function that starts slow and speeds up at the end.

Both

var(--ease-both)

An easing function that starts slow, speeds up in the middle, and slows back down at the end.

Both Subtle

var(--ease-both-subtle)

An easing function that is nearly linear but speeds up slightly in the middle.

Spring

var(--ease-spring)

An easing function that moves slightly backwards at the beginning, moves quickly in the middle, and slightly overshoots the target state before settling at the end.

Durations

The variables for durations are all prefixed with --duration-. They’re designed to be used with the animation-duration and transition-duration properties.

Short

var(--duration-short)

Use this duration for small interactions that don’t necessarily need to be animated, but look better with a bit of motion—for example, hovering over a link.

Medium

var(--duration-medium)

Use this duration when you want an animation to be more prominent than it would be with the short duration, but still quick enough to stay out of the user’s way and avoid feeling slow or distracting.

Long

var(--duration-long)

Use this duration for animations that the user should pay attention to. For example, responding to a click or other substantial action could warrant an animation that’s longer and harder to miss.

Extra Long

var(--duration-extra-long)

Use this duration for longer animations. It should be used sparingly, since users generally don’t want to wait this long for animations to complete. However, there are some situations where a longer animation makes sense, especially when paired with specific easing functions.