Colors

Learn how to work with our color system.

Scales

There are 10 color scales in the system: backgrounds, gray, gray alpha, blue, red, amber, green, teal, purple, and pink. Values are defined in oklch, so wide-gamut color renders on supported browsers and displays. Every non-background scale has the same 10 steps with the same roles. The sections below describe each role once, and it applies to every scale. The swatches use gray as the representative ramp.

The scales are hand-tuned per step, not interpolated. Some steps deliberately reverse (Color 4 on the alpha scale is lighter than Color 3), so treat every step as a named role, never a point on a gradient.

100
200
300
400
500
600
700
800
900
1000
Background
Gray
Gray Alpha
Blue
Red
Amber
Green
Teal
Purple
Pink

Backgrounds

There are two background colors for pages and UI components. In most instances, you should use Background 1, especially when color is being placed on top of the background. Background 2 should be used sparingly when a subtle background differentiation is needed.

Background 1
var(--ds-background-100)
Default element background
Background 2
var(--ds-background-200)
Secondary background

Colors 1–3: Component backgrounds

The first three colors are component backgrounds, on every scale: Color 1 at rest, Color 2 on hover, Color 3 when pressed or selected. In practice there are two ladders.

Filled components, like secondary buttons and badges, step 1 → 2 → 3 as written.

If a component's default background is Background 1 (the page surface showing through, like ghost buttons, menu items and tab chips), the ladder shifts down a rung: Color 1 is the hover background and Color 2 the active background. Components that rest transparent take that shift on the alpha scale, so the state reads over any surface.

Two refinements hold on both ladders. A transient open state (aria-expanded, data-open) pins to the hover step: the highlight lives in the popup, so the trigger only ever looks hovered. And hovering an already-selected control deepens one step further (gray-alpha-300 on the alpha ladder, gray-950 on the inverted fills) so selection never swallows the hover response.

Color 1
var(--ds-gray-100)
Default background
Color 2
var(--ds-gray-200)
Hover background
Color 3
var(--ds-gray-300)
Active background

Colors 4–6: Borders

These three colors are designed for UI component borders.

In practice, borders default to the alpha scale; alpha hairlines hold up over any surface. Bordered controls and text fields step the hairline to Color 5 on hover. For fields, that border step is the entire hover response. Color 6's "active border" role is filled by the focus signature: solid gray-600 replaces the hairline on focus rather than stepping the alpha scale.

Color 4
var(--ds-gray-400)
Default border
Color 5
var(--ds-gray-500)
Hover border
Color 6
var(--ds-gray-600)
Active border

Colors 7–8: High contrast backgrounds

These two colors are designed for high contrast UI component backgrounds.

Color 7
var(--ds-gray-700)
High contrast background
Color 8
var(--ds-gray-800)
Hover high contrast background

Colors 9–10: Text and icons

These two colors are designed for accessible text and icons.

Color 9
var(--ds-gray-900)
Secondary text and icons
Color 10
var(--ds-gray-1000)
Primary text and icons

shadcn mapping

The shadcn semantic slots are pure var(--ds-*) aliases onto the ramp, never values.

shadcn tokenziiz token

Base

--background--ds-background-100
--foreground--ds-gray-1000

Surfaces

--card--ds-background-100
--card-foreground--ds-gray-1000
--popover--ds-background-100
--popover-foreground--ds-gray-1000

Actions

--primary--ds-gray-1000
--primary-foreground--ds-background-100
--secondary--ds-gray-100
--secondary-foreground--ds-gray-1000
--muted--ds-gray-100
--muted-foreground--ds-gray-900
--accent--ds-gray-100
--accent-foreground--ds-gray-1000
--destructive--ds-red-800

Borders and focus

--border--ds-gray-alpha-400
--input--ds-gray-alpha-400
--ring--ds-gray-600

Charts

--chart-1--ds-blue-700
--chart-2--ds-amber-700
--chart-3--ds-green-700
--chart-4--ds-purple-700
--chart-5--ds-pink-700

Sidebar

--sidebar--ds-background-200
--sidebar-foreground--ds-gray-1000
--sidebar-primary--ds-gray-1000
--sidebar-primary-foreground--ds-background-200
--sidebar-accent--ds-gray-100
--sidebar-accent-foreground--ds-gray-1000
--sidebar-border--ds-gray-alpha-400
--sidebar-ring--ds-gray-600

Go to a page

Search every page in the navigation.