Desktop UI Color System

Color Theory (Desktop)

Build semantic roles, not a swatch list

Don't start from "here are our 8 brand colors." Start from the roles the UI actually needs, then assign colors to roles:

Every other color decision in the app should trace back to one of these roles. If you can't name which role a color is serving, it probably shouldn't be there.

The 60-30-10 balance

Roughly 60% of visible surface should be surface-base/neutral, 30% secondary surfaces and text, and only about 10% should be the accent color and status colors combined. Apps that break this — heavy accent color everywhere, saturated backgrounds — read as loud rather than confident. The accent color has more impact precisely because it's used sparingly.

Avoid the AI-purple trap

Purple/violet-to-pink gradients as a primary or accent color are the strongest single "this is an AI-generated app" visual signal that currently exists. This doesn't mean purple is banned — it means:

• If the brand color happens to be purple, use it as a flat, specific hue (not a gradient sweep) with a name and a hex value, not "purple-ish gradient."
• Don't reach for purple-to-pink by default when no brand color has been specified — that's the generator's laziest option, not a neutral choice.
• Prefer a color story that's actually tied to the product (an existing brand motif, logo color, or the mood of what the app does) over a generic "trustworthy tech" gradient.

Stacked / layered components — elevation via more than just shadow

When components sit on top of other components (a card inside a panel inside the window, a dropdown above a card, a modal above everything), each layer needs to read as clearly above or below the one beneath it. Use two or three of these together, not shadow alone:

1. A one-step surface color shift (surface-base → surface-raised → surface-overlay), even a very subtle one (a few percent lightness difference is enough in most themes).
2. A cheap box-shadow, sized to the elevation level from foundations (raised gets a small tight shadow, floating/modal get a larger, softer one) — never rely on backdrop-blur alone for this, it's expensive and doesn't read as elevation on its own.
3. A hairline border at low opacity, especially useful in dark mode where shadows read less clearly against dark backgrounds.

Never stack more than 3 visually distinct elevation levels on screen at once — beyond that, users lose track of what's "above" what, and it usually means the layout needs restructuring rather than a fourth shadow tier.

Active / selected / hover state color logic

Use a consistent, predictable transformation from rest → hover → active/selected across every component, rather than inventing a new treatment per component:

Dark mode is not "invert the colors"

Build dark mode as its own set of role assignments, not a CSS filter. In particular:

• Shadows read poorly on dark backgrounds — lean more on the surface-color-shift and border techniques above.
• Pure black (#000) backgrounds create harsh contrast against white text and cause halation/glow on OLED and some LCD panels — prefer a very dark neutral gray (e.g. #0a0a0c–#121214 range) as surface-base.
• Saturated accent colors often need to be slightly desaturated or lightened in dark mode to avoid vibrating against the dark background.

Accessibility baseline

Body text against its background should meet at least a 4.5:1 contrast ratio; large text (18px+/bold 14px+) can go as low as 3:1. Never use color as the only signal for an important state (error, success, selected) — always pair it with an icon, text, or shape change.

Review format