Semantic Colors
Use-case tokens for surface, ink, and outline. They map to the palette and swap with the theme.
surface
Use for cards, panels, page chrome, alert backgrounds. Steps from soft (gray-1) to inverted (gray-7).
bg-surface-base → neutral-white
bg-surface-gray-1 → gray-50
bg-surface-gray-2 → gray-100
bg-surface-gray-3 → gray-200
bg-surface-gray-4 → gray-300
bg-surface-gray-5 → gray-400
bg-surface-gray-6 → gray-500
bg-surface-gray-7 → gray-600
bg-surface-gray-8 → gray-700
bg-surface-gray-9 → gray-800
bg-surface-gray-10 → gray-900
bg-surface-sidebar → gray-50
bg-surface-elevation-1 → neutral-white
bg-surface-elevation-2 → neutral-white
bg-surface-elevation-3 → neutral-white
bg-surface-red-1 → red-50
bg-surface-red-2 → red-100
bg-surface-red-3 → red-200
bg-surface-red-4 → red-300
bg-surface-red-5 → red-400
bg-surface-red-6 → red-500
bg-surface-red-7 → red-600
bg-surface-red-8 → red-700
bg-surface-red-9 → red-800
bg-surface-red-10 → red-900
bg-surface-blue-1 → blue-50
bg-surface-blue-2 → blue-100
bg-surface-blue-3 → blue-200
bg-surface-blue-4 → blue-300
bg-surface-blue-5 → blue-400
bg-surface-blue-6 → blue-500
bg-surface-blue-7 → blue-600
bg-surface-blue-8 → blue-700
bg-surface-blue-9 → blue-800
bg-surface-blue-10 → blue-900
bg-surface-green-1 → green-50
bg-surface-green-2 → green-100
bg-surface-green-3 → green-200
bg-surface-green-4 → green-300
bg-surface-green-5 → green-400
bg-surface-green-6 → green-500
bg-surface-green-7 → green-600
bg-surface-green-8 → green-700
bg-surface-green-9 → green-800
bg-surface-green-10 → green-900
bg-surface-amber-1 → amber-50
bg-surface-amber-2 → amber-100
bg-surface-amber-3 → amber-200
bg-surface-amber-4 → amber-300
bg-surface-amber-5 → amber-400
bg-surface-amber-6 → amber-500
bg-surface-amber-7 → amber-600
bg-surface-amber-8 → amber-700
bg-surface-amber-9 → amber-800
bg-surface-amber-10 → amber-900
bg-surface-violet-1 → violet-50
bg-surface-violet-2 → violet-100
bg-surface-violet-3 → violet-200
bg-surface-violet-4 → violet-300
bg-surface-violet-5 → violet-400
bg-surface-violet-6 → violet-500
bg-surface-violet-7 → violet-600
bg-surface-violet-8 → violet-700
bg-surface-violet-9 → violet-800
bg-surface-violet-10 → violet-900
bg-surface-yellow-1 → yellow-50
bg-surface-yellow-2 → yellow-100
bg-surface-yellow-3 → yellow-200
bg-surface-yellow-4 → yellow-300
bg-surface-yellow-5 → yellow-400
bg-surface-yellow-6 → yellow-500
bg-surface-yellow-7 → yellow-600
bg-surface-yellow-8 → yellow-700
bg-surface-yellow-9 → yellow-800
bg-surface-yellow-10 → yellow-900
bg-surface-orange-1 → orange-50
bg-surface-orange-2 → orange-100
bg-surface-orange-3 → orange-200
bg-surface-orange-4 → orange-300
bg-surface-orange-5 → orange-400
bg-surface-orange-6 → orange-500
bg-surface-orange-7 → orange-600
bg-surface-orange-8 → orange-700
bg-surface-orange-9 → orange-800
bg-surface-orange-10 → orange-900
bg-surface-teal-1 → teal-50
bg-surface-teal-2 → teal-100
bg-surface-teal-3 → teal-200
bg-surface-teal-4 → teal-300
bg-surface-teal-5 → teal-400
bg-surface-teal-6 → teal-500
bg-surface-teal-7 → teal-600
bg-surface-teal-8 → teal-700
bg-surface-teal-9 → teal-800
bg-surface-teal-10 → teal-900
bg-surface-cyan-1 → cyan-50
bg-surface-cyan-2 → cyan-100
bg-surface-cyan-3 → cyan-200
bg-surface-cyan-4 → cyan-300
bg-surface-cyan-5 → cyan-400
bg-surface-cyan-6 → cyan-500
bg-surface-cyan-7 → cyan-600
bg-surface-cyan-8 → cyan-700
bg-surface-cyan-9 → cyan-800
bg-surface-cyan-10 → cyan-900
bg-surface-purple-1 → purple-50
bg-surface-purple-2 → purple-100
bg-surface-purple-3 → purple-200
bg-surface-purple-4 → purple-300
bg-surface-purple-5 → purple-400
bg-surface-purple-6 → purple-500
bg-surface-purple-7 → purple-600
bg-surface-purple-8 → purple-700
bg-surface-purple-9 → purple-800
bg-surface-purple-10 → purple-900
bg-surface-pink-1 → pink-50
bg-surface-pink-2 → pink-100
bg-surface-pink-3 → pink-200
bg-surface-pink-4 → pink-300
bg-surface-pink-5 → pink-400
bg-surface-pink-6 → pink-500
bg-surface-pink-7 → pink-600
bg-surface-pink-8 → pink-700
bg-surface-pink-9 → pink-800
bg-surface-pink-10 → pink-900
bg-surface-alert-button-default → neutral-white
bg-surface-alert-button-info → neutral-white
bg-surface-alert-button-success → neutral-white
bg-surface-alert-button-warning → neutral-white
bg-surface-alert-button-error → neutral-white
surface-alpha
Use when a surface needs transparency over variable backgrounds, overlays, or layered chrome.
bg-surface-alpha-base → neutral-white
bg-surface-alpha-gray-1 → gray-alpha-50
bg-surface-alpha-gray-2 → gray-alpha-100
bg-surface-alpha-gray-3 → gray-alpha-200
bg-surface-alpha-gray-4 → gray-alpha-300
bg-surface-alpha-gray-5 → gray-alpha-400
bg-surface-alpha-gray-6 → gray-alpha-500
bg-surface-alpha-gray-7 → gray-alpha-600
bg-surface-alpha-gray-8 → gray-alpha-700
bg-surface-alpha-gray-9 → gray-alpha-800
bg-surface-alpha-gray-10 → gray-alpha-900
bg-surface-alpha-sidebar → gray-50
bg-surface-alpha-elevation-1 → neutral-white
bg-surface-alpha-elevation-2 → neutral-white
bg-surface-alpha-elevation-3 → neutral-white
bg-surface-alpha-gray-2-overlay → overlay-black-50
ink
Use for typography, icons, and any glyph-style fill. gray-8 is body text; gray-4/5 is secondary.
text-ink-base → neutral-white
text-ink-gray-1 → gray-200
text-ink-gray-2 → gray-300
text-ink-gray-3 → gray-400
text-ink-gray-4 → gray-500
text-ink-gray-5 → gray-600
text-ink-gray-6 → gray-700
text-ink-gray-7 → gray-800
text-ink-gray-8 → gray-900
text-ink-gray-9 → gray-950
text-ink-red-1 → neutral-white
text-ink-red-2 → red-100
text-ink-red-3 → red-200
text-ink-red-4 → red-300
text-ink-red-5 → red-400
text-ink-red-6 → red-500
text-ink-red-7 → red-600
text-ink-red-8 → red-700
text-ink-red-9 → red-800
text-ink-red-10 → red-900
text-ink-blue-1 → neutral-white
text-ink-blue-2 → blue-100
text-ink-blue-3 → blue-200
text-ink-blue-4 → blue-300
text-ink-blue-5 → blue-400
text-ink-blue-6 → blue-500
text-ink-blue-7 → blue-600
text-ink-blue-8 → blue-700
text-ink-blue-9 → blue-800
text-ink-blue-10 → blue-900
text-ink-green-1 → neutral-white
text-ink-green-2 → green-100
text-ink-green-3 → green-200
text-ink-green-4 → green-300
text-ink-green-5 → green-400
text-ink-green-6 → green-500
text-ink-green-7 → green-600
text-ink-green-8 → green-700
text-ink-green-9 → green-800
text-ink-green-10 → green-900
text-ink-amber-1 → neutral-white
text-ink-amber-2 → amber-100
text-ink-amber-3 → amber-200
text-ink-amber-4 → amber-300
text-ink-amber-5 → amber-400
text-ink-amber-6 → amber-500
text-ink-amber-7 → amber-600
text-ink-amber-8 → amber-700
text-ink-amber-9 → amber-800
text-ink-amber-10 → amber-900
text-ink-violet-1 → neutral-white
text-ink-violet-2 → violet-100
text-ink-violet-3 → violet-200
text-ink-violet-4 → violet-300
text-ink-violet-5 → violet-400
text-ink-violet-6 → violet-500
text-ink-violet-7 → violet-600
text-ink-violet-8 → violet-700
text-ink-violet-9 → violet-800
text-ink-violet-10 → violet-900
text-ink-yellow-1 → neutral-white
text-ink-yellow-2 → yellow-100
text-ink-yellow-3 → yellow-200
text-ink-yellow-4 → yellow-300
text-ink-yellow-5 → yellow-400
text-ink-yellow-6 → yellow-500
text-ink-yellow-7 → yellow-600
text-ink-yellow-8 → yellow-700
text-ink-yellow-9 → yellow-800
text-ink-yellow-10 → yellow-900
text-ink-orange-1 → neutral-white
text-ink-orange-2 → orange-100
text-ink-orange-3 → orange-200
text-ink-orange-4 → orange-300
text-ink-orange-5 → orange-400
text-ink-orange-6 → orange-500
text-ink-orange-7 → orange-600
text-ink-orange-8 → orange-700
text-ink-orange-9 → orange-800
text-ink-orange-10 → orange-900
text-ink-teal-1 → neutral-white
text-ink-teal-2 → teal-100
text-ink-teal-3 → teal-200
text-ink-teal-4 → teal-300
text-ink-teal-5 → teal-400
text-ink-teal-6 → teal-500
text-ink-teal-7 → teal-600
text-ink-teal-8 → teal-700
text-ink-teal-9 → teal-800
text-ink-teal-10 → teal-900
text-ink-cyan-1 → neutral-white
text-ink-cyan-2 → cyan-100
text-ink-cyan-3 → cyan-200
text-ink-cyan-4 → cyan-300
text-ink-cyan-5 → cyan-400
text-ink-cyan-6 → cyan-500
text-ink-cyan-7 → cyan-600
text-ink-cyan-8 → cyan-700
text-ink-cyan-9 → cyan-800
text-ink-cyan-10 → cyan-900
text-ink-purple-1 → neutral-white
text-ink-purple-2 → purple-100
text-ink-purple-3 → purple-200
text-ink-purple-4 → purple-300
text-ink-purple-5 → purple-400
text-ink-purple-6 → purple-500
text-ink-purple-7 → purple-600
text-ink-purple-8 → purple-700
text-ink-purple-9 → purple-800
text-ink-purple-10 → purple-900
text-ink-pink-1 → neutral-white
text-ink-pink-2 → pink-100
text-ink-pink-3 → pink-200
text-ink-pink-4 → pink-300
text-ink-pink-5 → pink-400
text-ink-pink-6 → pink-500
text-ink-pink-7 → pink-600
text-ink-pink-8 → pink-700
text-ink-pink-9 → pink-800
text-ink-pink-10 → pink-900
text-ink-alert-button-default → gray-900
text-ink-alert-button-info → gray-900
text-ink-alert-button-success → gray-900
text-ink-alert-button-warning → gray-900
text-ink-alert-button-error → gray-900
text-ink-blue-link → blue-500
outline
Use for borders, dividers, focus rings, outlined controls.
border-outline-base → neutral-white
border-outline-gray-1 → gray-200
border-outline-gray-2 → gray-300
border-outline-gray-3 → gray-400
border-outline-gray-4 → gray-500
border-outline-gray-5 → gray-600
border-outline-gray-6 → gray-700
border-outline-gray-7 → gray-800
border-outline-gray-8 → gray-900
border-outline-gray-9 → gray-950
border-outline-red-1 → red-100
border-outline-red-2 → red-200
border-outline-red-3 → red-300
border-outline-red-4 → red-400
border-outline-red-5 → red-500
border-outline-red-6 → red-600
border-outline-red-7 → red-700
border-outline-red-8 → red-800
border-outline-red-9 → red-900
border-outline-red-10 → red-950
border-outline-blue-1 → blue-100
border-outline-blue-2 → blue-200
border-outline-blue-3 → blue-300
border-outline-blue-4 → blue-400
border-outline-blue-5 → blue-500
border-outline-blue-6 → blue-600
border-outline-blue-7 → blue-700
border-outline-blue-8 → blue-800
border-outline-blue-9 → blue-900
border-outline-blue-10 → blue-950
border-outline-green-1 → green-100
border-outline-green-2 → green-200
border-outline-green-3 → green-300
border-outline-green-4 → green-400
border-outline-green-5 → green-500
border-outline-green-6 → green-600
border-outline-green-7 → green-700
border-outline-green-8 → green-800
border-outline-green-9 → green-900
border-outline-green-10 → green-950
border-outline-amber-1 → amber-100
border-outline-amber-2 → amber-200
border-outline-amber-3 → amber-300
border-outline-amber-4 → amber-400
border-outline-amber-5 → amber-500
border-outline-amber-6 → amber-600
border-outline-amber-7 → amber-700
border-outline-amber-8 → amber-800
border-outline-amber-9 → amber-900
border-outline-amber-10 → amber-950
border-outline-violet-1 → violet-100
border-outline-violet-2 → violet-200
border-outline-violet-3 → violet-300
border-outline-violet-4 → violet-400
border-outline-violet-5 → violet-500
border-outline-violet-6 → violet-600
border-outline-violet-7 → violet-700
border-outline-violet-8 → violet-800
border-outline-violet-9 → violet-900
border-outline-violet-10 → violet-950
border-outline-yellow-1 → yellow-100
border-outline-yellow-2 → yellow-200
border-outline-yellow-3 → yellow-300
border-outline-yellow-4 → yellow-400
border-outline-yellow-5 → yellow-500
border-outline-yellow-6 → yellow-600
border-outline-yellow-7 → yellow-700
border-outline-yellow-8 → yellow-800
border-outline-yellow-9 → yellow-900
border-outline-yellow-10 → yellow-950
border-outline-orange-1 → orange-100
border-outline-orange-2 → orange-200
border-outline-orange-3 → orange-300
border-outline-orange-4 → orange-400
border-outline-orange-5 → orange-500
border-outline-orange-6 → orange-600
border-outline-orange-7 → orange-700
border-outline-orange-8 → orange-800
border-outline-orange-9 → orange-900
border-outline-orange-10 → orange-950
border-outline-teal-1 → teal-100
border-outline-teal-2 → teal-200
border-outline-teal-3 → teal-300
border-outline-teal-4 → teal-400
border-outline-teal-5 → teal-500
border-outline-teal-6 → teal-600
border-outline-teal-7 → teal-700
border-outline-teal-8 → teal-800
border-outline-teal-9 → teal-900
border-outline-teal-10 → teal-950
border-outline-cyan-1 → cyan-100
border-outline-cyan-2 → cyan-200
border-outline-cyan-3 → cyan-300
border-outline-cyan-4 → cyan-400
border-outline-cyan-5 → cyan-500
border-outline-cyan-6 → cyan-600
border-outline-cyan-7 → cyan-700
border-outline-cyan-8 → cyan-800
border-outline-cyan-9 → cyan-900
border-outline-cyan-10 → cyan-950
border-outline-purple-1 → purple-100
border-outline-purple-2 → purple-200
border-outline-purple-3 → purple-300
border-outline-purple-4 → purple-400
border-outline-purple-5 → purple-500
border-outline-purple-6 → purple-600
border-outline-purple-7 → purple-700
border-outline-purple-8 → purple-800
border-outline-purple-9 → purple-900
border-outline-purple-10 → purple-950
border-outline-pink-1 → pink-100
border-outline-pink-2 → pink-200
border-outline-pink-3 → pink-300
border-outline-pink-4 → pink-400
border-outline-pink-5 → pink-500
border-outline-pink-6 → pink-600
border-outline-pink-7 → pink-700
border-outline-pink-8 → pink-800
border-outline-pink-9 → pink-900
border-outline-pink-10 → pink-950
border-outline-elevation-1 → gray-200
border-outline-elevation-2 → gray-200
outline-alpha
Use for borders and dividers that should preserve translucency across layered surfaces.
border-outline-alpha-base → neutral-white
border-outline-alpha-gray-1 → gray-alpha-200
border-outline-alpha-gray-2 → gray-alpha-300
border-outline-alpha-gray-3 → gray-alpha-400
border-outline-alpha-gray-4 → gray-alpha-500
border-outline-alpha-gray-5 → gray-alpha-600
border-outline-alpha-gray-6 → gray-alpha-700
border-outline-alpha-gray-7 → gray-alpha-800
border-outline-alpha-gray-8 → gray-alpha-900
border-outline-alpha-gray-9 → gray-alpha-950
border-outline-alpha-elevation-1 → gray-alpha-200
border-outline-alpha-elevation-2 → gray-alpha-200