Foundations

Semantic tokens

The names components reference. Each maps to a primitive step. Components never name a primitive directly — that's how the system stays consistent without anyone having to remember.

01The full map

Every semantic token, grouped by family, showing the primitive it resolves to and the role it plays. Wrapper components in @/components/upnext reference only these names.

Surfaces

6 tokens

TokenMaps toHexUsage

--background

→ neutral-50

#fafafa

Page background

--foreground

→ neutral-800

#262626

Default text on background

--card

→ white

#ffffff

Card surface

--card-foreground

→ neutral-800

#262626

Text on card

--popover

→ white

#ffffff

Popover / menu surface

--popover-foreground

→ neutral-800

#262626

Text on popover

Text

6 tokens

TokenMaps toHexUsage

--text-main

→ neutral-800

#262626

Strongest UI text — headings, labels, primary copy. Tailwind: text-main

--text-body

→ neutral-600

#525252

Paragraph prose inside cards / dialogs / popovers — softened for reading. Tailwind: text-body

--text-body-light

→ neutral-400

#a1a1a1

Secondary prose, meta, captions, helper text. Tailwind: text-body-light

--text-disabled

→ neutral-200

#e5e5e5

Disabled state — explicit, semantic. Tailwind: text-disabled

--text-primary

→ primary

—

Brand-colored text — link hovers, accent copy, AI/feature callouts. Tailwind: text-primary

--text-white

→ neutral-50

#fafafa

Pure-white text — for content on solid colored fills (primary button, solid badge, destructive)

Icon

6 tokens

TokenMaps toHexUsage

--icon-main

→ neutral-800

#262626

Strongest icon color — pairs with text-main. Tailwind: icon-main

--icon-body

→ neutral-600

#525252

Icons inline with body prose — pairs with text-body. Tailwind: icon-body

--icon-body-light

→ neutral-400

#a1a1a1

Secondary / meta icons — pairs with text-body-light. Tailwind: icon-body-light

--icon-disabled

→ neutral-200

#e5e5e5

Disabled icon state — pairs with text-disabled. Tailwind: icon-disabled

--icon-primary

→ primary

—

Brand-colored icon — hero / accent icons. Tailwind: icon-primary

--icon-white

→ neutral-50

#fafafa

Pure-white icon — pairs with text-white, used on solid colored fills

Brand

7 tokens

TokenMaps toHexUsage

--primary

→ primary-500

#1464ff

Default brand fill (#1464FF)

--primary-hover

→ primary-600

#004be1

Primary on hover (one step darker)

--primary-active

→ primary-700

#0037b7

Primary pressed / active

--primary-foreground

→ neutral-50

#fafafa

Text on primary fill

--primary-subtle

→ primary-50

#e1efff

Tinted bg (ghost hover, soft chip)

--primary-border

→ primary-200

#8dbcff

Tinted border on subtle surfaces

--primary-ink

→ primary-700

#0037b7

Text on subtle bg

Secondary

9 tokens

TokenMaps toHexUsage

--secondary

→ neutral-100

#f5f5f5

Secondary fill

--secondary-hover

→ neutral-200

#e5e5e5

Secondary on hover — one step darker, not opacity

--secondary-foreground

→ neutral-900

#171717

Text on secondary

--muted

→ neutral-100

#f5f5f5

Muted background

--muted-hover

→ neutral-150

#ededed

Muted bg on hover — one sub-anchor step darker

--muted-foreground

→ neutral-500

#737373

Muted / caption text

--accent

→ neutral-100

#f5f5f5

Hover accent on neutral surfaces

--accent-hover

→ neutral-150

#ededed

Accent on hover — one step darker

--accent-foreground

→ neutral-900

#171717

Text on accent

Status — Success

7 tokens

TokenMaps toHexUsage

--success

→ success-500

#38856d

Solid success fill

--success-hover

→ success-600

#2d755f

Hover

--success-active

→ success-700

#256652

Pressed

--success-foreground

→ neutral-50

#fafafa

Text on success fill

--success-subtle

→ success-50

#e8f4ef

Tinted background (alert)

--success-border

→ success-200

#add3c4

Border on subtle bg

--success-ink

→ success-700

#256652

Text on subtle bg

Status — Error

8 tokens

TokenMaps toHexUsage

--error

→ error-500

#c33d43

Solid error fill

--error-hover

→ error-600

#a8353a

Hover

--error-active

→ error-700

#8e3235

Pressed

--error-foreground

→ neutral-50

#fafafa

Text on error fill

--error-subtle

→ error-50

#faeeed

Tinted background

--error-border

→ error-200

#fcb3b0

Border on subtle bg

--error-ink

→ error-700

#8e3235

Text on subtle bg

--destructive-hover

→ error-600

#a8353a

Destructive on hover (alias of error-hover)

Status — Warning

7 tokens

TokenMaps toHexUsage

--warning

→ warning-500

#bf7a39

Solid warning fill

--warning-hover

→ warning-600

#b67030

Hover

--warning-active

→ warning-700

#ab6624

Pressed

--warning-foreground

→ neutral-50

#fafafa

Text on amber fill (white reads at L 0.563)

--warning-subtle

→ warning-50

#fff6e7

Tinted background

--warning-border

→ warning-200

#f7cda1

Border on subtle bg

--warning-ink

→ warning-800

#844f1e

Text on subtle bg (amber needs darker ink)

Status — Info

7 tokens

TokenMaps toHexUsage

--info

→ info-500

#2c83b3

Solid info fill

--info-hover

→ info-600

#166792

Hover

--info-active

→ info-700

#024c6f

Pressed

--info-foreground

→ neutral-50

#fafafa

Text on info fill

--info-subtle

→ info-50

#f0f9ff

Tinted background

--info-border

→ info-200

#b9d9ef

Border on subtle bg

--info-ink

→ info-700

#024c6f

Text on subtle bg

Editorial — Purple

7 tokens

TokenMaps toHexUsage

--purple

→ purple-500

#8366c3

Solid purple fill

--purple-hover

→ purple-600

#6e52aa

Hover

--purple-active

→ purple-700

#5b4091

Pressed

--purple-foreground

→ neutral-50

#fafafa

Text on purple fill

--purple-subtle

→ purple-50

#f5f2f9

Tinted background

--purple-border

→ purple-200

#d6caee

Border on subtle bg

--purple-ink

→ purple-700

#5b4091

Text on subtle bg

Editorial — Denim

7 tokens

TokenMaps toHexUsage

--denim

→ denim-500

#6a8ee8

Solid denim fill

--denim-hover

→ denim-600

#5a80e3

Hover

--denim-active

→ denim-700

#4b72d9

Pressed

--denim-foreground

→ neutral-50

#fafafa

Text on denim fill

--denim-subtle

→ denim-50

#eef2fb

Tinted background

--denim-border

→ denim-200

#c2d1f3

Border on subtle bg

--denim-ink

→ denim-700

#4b72d9

Text on subtle bg

Editorial — Sage

7 tokens

TokenMaps toHexUsage

--sage

→ sage-500

#558049

Solid sage fill

--sage-hover

→ sage-600

#436d37

Hover

--sage-active

→ sage-700

#2a531e

Pressed

--sage-foreground

→ neutral-50

#fafafa

Text on sage fill

--sage-subtle

→ sage-50

#e9f8e5

Tinted background

--sage-border

→ sage-200

#b7d5af

Border on subtle bg

--sage-ink

→ sage-700

#2a531e

Text on subtle bg

Editorial — Pink

7 tokens

TokenMaps toHexUsage

--pink

→ pink-500

#bb528d

Solid pink fill

--pink-hover

→ pink-600

#a8427c

Hover

--pink-active

→ pink-700

#99366f

Pressed

--pink-foreground

→ neutral-50

#fafafa

Text on pink fill

--pink-subtle

→ pink-50

#fbeef4

Tinted background

--pink-border

→ pink-200

#eec3d7

Border on subtle bg

--pink-ink

→ pink-700

#99366f

Text on subtle bg

Editorial — Cotton Candy

7 tokens

TokenMaps toHexUsage

--cottoncandy

→ cottoncandy-500

#e0609b

Solid cotton-candy fill

--cottoncandy-hover

→ cottoncandy-600

#c14a82

Hover

--cottoncandy-active

→ cottoncandy-700

#a13c6c

Pressed

--cottoncandy-foreground

→ neutral-50

#fafafa

Text on cotton-candy fill

--cottoncandy-subtle

→ cottoncandy-50

#fef5f8

Tinted background

--cottoncandy-border

→ cottoncandy-200

#fdcddf

Border on subtle bg

--cottoncandy-ink

→ cottoncandy-700

#a13c6c

Text on subtle bg

Editorial — Orange

7 tokens

TokenMaps toHexUsage

--orange

→ orange-500

#bd6238

Solid orange fill

--orange-hover

→ orange-600

#ae5429

Hover

--orange-active

→ orange-700

#a24a1f

Pressed

--orange-foreground

→ neutral-50

#fafafa

Text on orange fill

--orange-subtle

→ orange-50

#fff1e7

Tinted background

--orange-border

→ orange-200

#f8c4a9

Border on subtle bg

--orange-ink

→ orange-700

#a24a1f

Text on subtle bg

Editorial — Teal

7 tokens

TokenMaps toHexUsage

--teal

→ teal-500

#009494

Solid teal fill

--teal-hover

→ teal-600

#007e7f

Hover

--teal-active

→ teal-700

#006868

Pressed

--teal-foreground

→ neutral-50

#fafafa

Text on teal fill

--teal-subtle

→ teal-50

#e5f3f2

Tinted background

--teal-border

→ teal-200

#a4dad9

Border on subtle bg

--teal-ink

→ teal-700

#006868

Text on subtle bg

Editorial — Lime

7 tokens

TokenMaps toHexUsage

--lime

→ lime-500

#779b1e

Solid lime fill

--lime-hover

→ lime-600

#61800d

Hover

--lime-active

→ lime-700

#4d670a

Pressed

--lime-foreground

→ neutral-50

#fafafa

Text on lime fill

--lime-subtle

→ lime-50

#f1f9e5

Tinted background

--lime-border

→ lime-200

#c5e292

Border on subtle bg

--lime-ink

→ lime-700

#4d670a

Text on subtle bg

Editorial — Magenta

7 tokens

TokenMaps toHexUsage

--magenta

→ magenta-500

#aa51a4

Solid magenta fill

--magenta-hover

→ magenta-600

#93408e

Hover

--magenta-active

→ magenta-700

#7e3179

Pressed

--magenta-foreground

→ neutral-50

#fafafa

Text on magenta fill

--magenta-subtle

→ magenta-50

#f7edf6

Tinted background

--magenta-border

→ magenta-200

#e3bfdf

Border on subtle bg

--magenta-ink

→ magenta-700

#7e3179

Text on subtle bg

Editorial — Mint

7 tokens

TokenMaps toHexUsage

--mint

→ mint-500

#00937f

Solid mint fill

--mint-hover

→ mint-600

#007d6a

Hover

--mint-active

→ mint-700

#006455

Pressed

--mint-foreground

→ neutral-50

#fafafa

Text on mint fill

--mint-subtle

→ mint-50

#e8f8f5

Tinted background

--mint-border

→ mint-200

#9aded0

Border on subtle bg

--mint-ink

→ mint-700

#006455

Text on subtle bg

Editorial — Slate

7 tokens

TokenMaps toHexUsage

--slate

→ slate-500

#5f7790

Solid slate fill

--slate-hover

→ slate-600

#4d6379

Hover

--slate-active

→ slate-700

#3c4f62

Pressed

--slate-foreground

→ neutral-50

#fafafa

Text on slate fill

--slate-subtle

→ slate-50

#edf1f6

Tinted background

--slate-border

→ slate-200

#c4cfdb

Border on subtle bg

--slate-ink

→ slate-700

#3c4f62

Text on subtle bg

Editorial — Mustard

7 tokens

TokenMaps toHexUsage

--mustard

→ mustard-500

#a17000

Solid mustard fill

--mustard-hover

→ mustard-600

#8b5e00

Hover

--mustard-active

→ mustard-700

#734b00

Pressed

--mustard-foreground

→ neutral-50

#fafafa

Text on mustard fill

--mustard-subtle

→ mustard-50

#f9f3e6

Tinted background

--mustard-border

→ mustard-200

#e7cc9b

Border on subtle bg

--mustard-ink

→ mustard-700

#734b00

Text on subtle bg

Editorial — Deep Violet

7 tokens

TokenMaps toHexUsage

--violet

→ violet-500

#4e3ad2

Solid violet fill

--violet-hover

→ violet-600

#3a24a8

Hover

--violet-active

→ violet-700

#29157d

Pressed

--violet-foreground

→ neutral-50

#fafafa

Text on violet fill

--violet-subtle

→ violet-50

#e9ebfe

Tinted background

--violet-border

→ violet-200

#b3b9fc

Border on subtle bg

--violet-ink

→ violet-700

#29157d

Text on subtle bg

Editorial — Crimson

7 tokens

TokenMaps toHexUsage

--crimson

→ crimson-500

#bf3e59

Solid crimson fill

--crimson-hover

→ crimson-600

#a22544

Hover

--crimson-active

→ crimson-700

#830b30

Pressed

--crimson-foreground

→ neutral-50

#fafafa

Text on crimson fill

--crimson-subtle

→ crimson-50

#f9eded

Tinted background

--crimson-border

→ crimson-200

#efbbc0

Border on subtle bg

--crimson-ink

→ crimson-700

#830b30

Text on subtle bg

Editorial — Canary

7 tokens

TokenMaps toHexUsage

--canary

→ canary-500

#ae8c00

Solid canary fill

--canary-hover

→ canary-600

#937400

Hover

--canary-active

→ canary-700

#775c00

Pressed

--canary-foreground

→ neutral-50

#fafafa

Text on canary fill

--canary-subtle

→ canary-50

#fbf8e9

Tinted background

--canary-border

→ canary-200

#ebdc96

Border on subtle bg

--canary-ink

→ canary-700

#775c00

Text on subtle bg

Editorial — Cobalt

7 tokens

TokenMaps toHexUsage

--cobalt

→ cobalt-500

#0063d3

Solid cobalt fill

--cobalt-hover

→ cobalt-600

#004ab3

Hover

--cobalt-active

→ cobalt-700

#00358e

Pressed

--cobalt-foreground

→ neutral-50

#fafafa

Text on cobalt fill

--cobalt-subtle

→ cobalt-50

#e2f0ff

Tinted background

--cobalt-border

→ cobalt-200

#8bc9ff

Border on subtle bg

--cobalt-ink

→ cobalt-700

#00358e

Text on subtle bg

Editorial — Cocoa

7 tokens

TokenMaps toHexUsage

--cocoa

→ cocoa-500

#936240

Solid cocoa fill

--cocoa-hover

→ cocoa-600

#7a4d2e

Hover

--cocoa-active

→ cocoa-700

#633b1f

Pressed

--cocoa-foreground

→ neutral-50

#fafafa

Text on cocoa fill

--cocoa-subtle

→ cocoa-50

#f6efea

Tinted background

--cocoa-border

→ cocoa-200

#ddc1af

Border on subtle bg

--cocoa-ink

→ cocoa-700

#633b1f

Text on subtle bg

Editorial — Emerald

7 tokens

TokenMaps toHexUsage

--emerald

→ emerald-500

#008e49

Solid emerald fill

--emerald-hover

→ emerald-600

#007537

Hover

--emerald-active

→ emerald-700

#005d28

Pressed

--emerald-foreground

→ neutral-50

#fafafa

Text on emerald fill

--emerald-subtle

→ emerald-50

#e9f4ed

Tinted background

--emerald-border

→ emerald-200

#abd7bb

Border on subtle bg

--emerald-ink

→ emerald-700

#005d28

Text on subtle bg

Editorial — Sky

7 tokens

TokenMaps toHexUsage

--sky

→ sky-500

#0092ab

Solid sky fill

--sky-hover

→ sky-600

#007c93

Hover

--sky-active

→ sky-700

#00667a

Pressed

--sky-foreground

→ neutral-50

#fafafa

Text on sky fill

--sky-subtle

→ sky-50

#eaf6fa

Tinted background

--sky-border

→ sky-200

#a9d9e5

Border on subtle bg

--sky-ink

→ sky-700

#00667a

Text on subtle bg

Data Visualization

17 tokens

TokenMaps toHexUsage

--chart-1

→ cobalt-500

#0063d3

Categorical series 1 — cobalt

--chart-2

→ orange-500

#bd6238

Categorical series 2 — orange

--chart-3

→ teal-500

#009494

Categorical series 3 — teal

--chart-4

→ magenta-500

#aa51a4

Categorical series 4 — magenta

--chart-5

→ lime-500

#779b1e

Categorical series 5 — lime

--chart-6

→ violet-500

#4e3ad2

Categorical series 6 — violet

--chart-7

→ crimson-500

#bf3e59

Categorical series 7 — crimson

--chart-8

→ sky-500

#0092ab

Categorical series 8 — sky

--chart-9

→ cocoa-500

#936240

Categorical series 9 — cocoa

--chart-10

→ pink-500

#bb528d

Categorical series 10 — pink

--chart-11

→ emerald-500

#008e49

Categorical series 11 — emerald

--chart-12

→ mustard-500

#a17000

Categorical series 12 — mustard

--chart-sequential-1

→ cobalt-200

#8bc9ff

Sequential ramp — lowest intensity

--chart-sequential-6

→ cobalt-700

#00358e

Sequential ramp — highest intensity (1–6 available)

--chart-diverging-1

→ crimson-600

#a22544

Diverging — most negative

--chart-diverging-4

→ neutral-200

#e5e5e5

Diverging — neutral midpoint (1–7 available)

--chart-diverging-7

→ cobalt-600

#004ab3

Diverging — most positive

Feedback — Toast

8 tokens

TokenMaps toHexUsage

--toast-surface

→ neutral-900

#171717

Chip surface (light page); lifts to neutral-800 in dark mode

--toast-fg

→ neutral-50

#fafafa

Title text on the chip

--toast-fg-muted

→ neutral-400

#a1a1a1

Description / meta text on the chip

--toast-border

→ neutral-700

#404040

Chip border / edge

--toast-icon-success

→ success-300

#8bbeab

Success icon (ink-on-dark)

--toast-icon-error

→ error-300

#f58e8b

Error icon (ink-on-dark)

--toast-icon-warning

→ warning-300

#f1b277

Warning icon (ink-on-dark)

--toast-icon-info

→ info-300

#92c0de

Info icon (ink-on-dark)

Structure

3 tokens

TokenMaps toHexUsage

--border

→ neutral-200

#e5e5e5

Default 1px divider / outline

--input

→ neutral-200

#e5e5e5

Form control border

--ring

→ primary-500

#1464ff

Focus ring — always brand

02When to add a new semantic

Sparingly. Tokens are public API — once everywhere references them, removing them is painful.

Most design needs are solved by combining existing semantics, not by adding new ones. Reach for a new semantic only when:

  • You're aliasing an existing primitive for clarity — e.g. --tab-active-bg referencing --primary-subtle, useful if "active tab" might want to diverge from "primary subtle bg" later.
  • A new component category needs its own semantic name to keep the system grokkable.
  • You're documenting a state that's currently composed inline and would benefit from a named recipe.

When in doubt, propose in the DS channel before adding. Tokens are commitments.