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