Colors

Using colors

Reference a scale step via a Tailwind utility — bg-gray-2, text-accent-12, border-grayA-4 — or read the underlying CSS variable directly with hsl(var(--accent-11)).

All scales are defined at the workspace level (@unkey/ui/tailwind.css) so every app using the design system sees the same palette. Dark-mode values are already mapped on .dark; you never need to write a dark-mode variant.

Steps

Every scale follows Radix’s twelve-step structure. Each step has a canonical role — reach for the same step across scales to keep intent consistent. Full reference at the Radix scale guide.

• 01 App background.
• 02 Subtle background — striped rows, nested surfaces.
• 03 Component background, resting state.
• 04 Component background, hovered.
• 05 Component background, pressed or selected.
• 06 Subtle border — sidebars, cards, separators.
• 07 Border on interactive components.
• 08 Stronger border, hover, focus ring.
• 09 Solid background — maximum chroma, headers, overlays.
• 10 Solid background, hovered.
• 11 Low-contrast text — body copy, descriptions.
• 12 High-contrast text — headings, icons.

Scales

Gray

The neutral workhorse. Use low steps (1–4) for backgrounds and surfaces, mid steps (5–8) for borders and separators, and high steps (9–12) for text and icons.

Gray (Alpha)

Gray with transparency. Preferred for hover states, subtle overlays, and any element that sits on a colored or patterned surface where a solid gray would look flat.

Accent

The brand neutral — a tuned Slate scale. Used for primary buttons, active states, and anywhere the product needs a quiet but confident emphasis.

Success

Teal. Reserved for positive confirmation — a successful save, a healthy status, a completed step.

Warning

Amber. Signals caution without implying failure — an impending expiration, a non-fatal edge case, a degraded but functional state.

Error

Tomato. For destructive actions and failure states — a deletion confirmation, a request that could not complete.

Info

Blue. Neutral informational emphasis, links in some contexts, and primary interactive accents where accent would read as ambiguous.

Feature

Violet. Signals a distinct product area or a premium capability. Use sparingly so it stays meaningful.

Black (Alpha)

Pure-black transparent overlays. Useful for modal backdrops and shadows that should render the same in both themes.

White (Alpha)

Pure-white transparent overlays. Mirror image of BlackA; common for lifts on dark surfaces.

Text on background

Radix guarantees that steps 11 and 12 of any scale meet strong APCA contrast on top of step 2 of the same scale. That pair is the workhorse: body copy at 11, headings and icons at 12, both on a tinted surface 2.

Text steps at a glance

A quick sweep of what each high step looks like on the app background (bg-gray-1). Use 12 for headings and icons, 11 for body copy, 10 for tertiary metadata, 9 for hints and uppercase labels.

Solid backgrounds

Step 9 is the only step with maximum chroma — designed for solid button backgrounds, chips, and headers. White text sits on most hues; the amber/yellow family is light enough that warning-9 wants dark text (gray-12 works) for readability. Step 10 is the hover mate.

Tinted callouts

Step 3 backgrounds paired with step 11 text are the canonical semantic callout: readable, quiet, and obviously tinted. Reach for this pattern when you want Alert-like color without Alert-level weight.

Component states

Steps 3 → 4 → 5 are the state progression for component surfaces: resting, hovered, pressed. Borders at 6 → 7 → 8 match the same progression for separators and interactive outlines.