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 icon colors
	For reversed text color
	Links and subtle buttons
	Link and subtle buttons hover state
	Links and subtle buttons active state
	Secondary elements
	Secondary elements 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
	Background color on hover for subtle buttons and other links
	Background color on hover for danger buttons

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.5
	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

Page updated on May 8, 2025