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.
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.
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.
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.
Colors 7–8: High contrast backgrounds
These two colors are designed for high contrast UI component backgrounds.
Colors 9–10: Text and icons
These two colors are designed for accessible text and icons.
shadcn mapping
The shadcn semantic slots are pure var(--ds-*) aliases onto the ramp, never values.
| shadcn token | ziiz 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 |