Design Tokens

The tiny nuggets on which everything else is built

Semantic tokens #

Semantic tokens convey "meaning" by relating primitive token values to how and where they should be used. When looking at how tokens are used to define styles, semantic (or component) tokens should represent the majority of applied tokens.

To understand the difference, it can be helpful to compare how primitive vs. semantic tokens are used in practice. So, looking at an example color token, we may have many primitive tokens for shades of grey. But how do I know as a consumer of the tokens which shade of grey to use for body text? Without semantic tokens, I may choose slightly different shades. With a semantic token however, I can explicitly define which grey relates to the body text.

Another benefit of semantic tokens is that the same token might change situationally. For instance, in light or dark mode, the body text token might shift from black to white.

Foreground colors #

Token	Description	Light Mode	Dark Mode
	For normal text color
	For heading text color
	For reversed text color
	For outline colors
	For icon colors
	For subtle icon colors
	For very quiet icon colors
	For informative icon colors
	For success icon colors
	For warning icon colors
	For danger icon colors
	Links and subtle buttons
	Visited links
	Link and subtle buttons hover state
	Links and subtle buttons active state
	Primary elements
	Primary elements hover state
	Subtle primary elements
	Very transparent primary elements
	Secondary elements
	Secondary elements hover state
	Subtle secondary elements
	Very transparent secondary elements
	Used for informative actions
	Informative actions hover state
	Used for successful actions
	Success actions hover state
	Used for warning actions
	Warning actions hover state
	Danger buttons: used for destructive actions
	Danger buttons hover state

Background colors #

Token	Description	Light Mode	Dark Mode
	The page background
	For highlighting selected elements
	For selected elements hover state
	Used to accentuate elements by adding a mostly transparent overlay
	Used to add contrast between elements by adding a semi-transparent overlay
	Used to add a slightly darker shade in light OR dark mode
	Used to add a darker shade in light OR dark mode
	Used to add a slightly lighter shade in light OR dark mode
	Used to add a lighter shade in light OR dark mode
	Background color on hover for subtle buttons and other links
	Background color on hover for danger buttons
	Background color on code samples
	Background color on cards
	Background color on cards when hovered
	Background color on highlighted text

Gradients #

Gradients can add a dynamic sense of color, light, and motion to static interfaces. Subtle gradients can help draw the user’s eye onward or create an illusion of depth on otherwise flat surfaces.

Token	Description	Light Mode	Dark Mode
	Used mostly for primary buttons in light mode
	Used mostly when hovering primary buttons in light mode
	Used mostly for primary buttons in dark mode
	Used mostly when hovering primary buttons in dark mode
	Not really used yet, but potentially an alternate filled button
	Not really used yet, but potentially a CTA background
	Adds a subtle light fade on a section
	Adds a subtle dark fade on a section
	Adds a subtle angled shine on a section
	Adds a subtle fade from from light to dark over a section

Primitive tokens #

Primitive tokens store raw variable data at its most basic level. They define foundational styles that can be used to construct semantic and component tokens and keep them consistent.

Border radius #

Token	Description	Example
	0 Default, only used to reset
	3-4px Based on `--space-2xs`
	3-4px Left side only
	3-4px Right side only
	6-8px Based on `--space-xs`
	6-8px Left side only
	6-8px Right side only
	19-24px Based on `--space-m`
	50% Container must be square

Border width #

Token	Description	Example
	0
	1px Based on `--space-single`
	2px Based on `--space-3xs`
	3-4px Based on `--space-2xs`
	6-8px Based on `--space-xs`
	10-12px Based on `--space-s`

Font family #

Token	Description	Example
	`system-ui, -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, 'Segoe UI', Ubuntu, ui-sans-serif, Arial, sans-serif`	AaBbCc
	`'Zodiak', Superclarendon, 'Bookman Old Style', 'URW Bookman', 'URW Bookman L', 'Georgia Pro', Georgia, serif`	AaBbCc
	`Menlo, 'Bitstream Vera Sans Mono', 'DejaVu Sans Mono', 'Inconsolata', ui-monospace, Monaco, Consolas, monospace`	AaBbCc

Font size #

Token	Description	Example
	61-76px Depending on viewport	AaBbCc
	49-61px Depending on viewport	AaBbCc
	39-49px Depending on viewport	AaBbCc
	31-39px Depending on viewport	AaBbCc
	25-31px Depending on viewport	AaBbCc
	20-25px Depending on viewport	AaBbCc
	16-20px Depending on viewport	AaBbCc
	12.8-16px Depending on viewport	AaBbCc
	10.2-12.8px Depending on viewport	AaBbCc

Line height #

Token	Description	Example
	1.5rem	Sample text here
	`clamp(1.25rem, calc(1.163rem + 0.4348vw), 1.5rem)`	Sample text here Sample text here Sample text here
	`clamp(1.5rem, calc(1.3261rem + 0.8696vw), 2rem)`	Sample text here Sample text here Sample text here
	`clamp(2rem, calc(1.8261rem + 0.8696vw), 2.5rem)`	AaBbCc
	`clamp(2.5rem, calc(2.3261rem + 0.8696vw), 3rem)`	AaBbCc
	`clamp(3rem, calc(2.6522rem + 1.7391vw), 4rem)`	AaBbCc
	`clamp(4rem, calc(3.6522rem + 1.7391vw), 5rem)`	AaBbCc

Opacity #

Token	Description	Example
	0
	0.1
	0.25
	0.33
	0.5
	0.67
	0.75
	0.9
	1

Shadows #

Token	Description	Example
	`none`
	`0 var(--space-single) var(--space-3xs) var(--c-neutral-black-25)`
	`0 var(--space-3xs) var(--space-2xs) var(--c-neutral-black-25)`
	`0 var(--space-2xs) var(--space-xs) var(--c-neutral-black-50)`
	`0 var(--space-3xs) 0 var(--c-purple-300-25)`

Spacing #

Token	Description	Example
	0
	1px
	2px
	3-4px Depending on viewport
	6-8px Depending on viewport
	10-12px Depending on viewport
	13-16px Depending on viewport
	16-20px Depending on viewport
	19-24px Depending on viewport
	26-32px Depending on viewport
	38-48px Depending on viewport
	58-72px Depending on viewport
	76-96px Depending on viewport
	96-120px Depending on viewport
	115-144px Depending on viewport
	134-168px Depending on viewport
	154-192px Depending on viewport

Page updated on Sep 17, 2026