| name | color-system-design |
| description | Use when establishing a color system for a SaaS product, marketing site, or brand. Covers tokens,
semantic naming, accent strategy, accessibility (WCAG contrast), dark vs light considerations, and
when to use gradients.
|
Color System Design
A color system is not a palette. A palette is a list of colors; a system is the rules about which color goes where.
Token architecture
Two-layer token system:
Primitive tokens (raw hex values, never used directly in UI):
--blue-500: #3B82F6
--teal-500: #2DD4BF
--gray-50: #F8FAFC
--gray-900: #0F172A
Semantic tokens (refer to primitives, used in UI):
--color-text-primary: var(--gray-50)
--color-text-secondary: var(--gray-300)
--color-bg: var(--gray-900)
--color-accent: var(--teal-500)
--color-link: var(--teal-500)
The semantic layer is what changes between light/dark themes. The primitive layer is constant.
Accent strategy
For SaaS, 1 primary accent, sometimes 2, never more than 3.
- 1 primary accent carries buttons, links, focus states, active nav, ~80% of color usage
- 1 secondary accent for differentiation (premium tier, partner program)
- 1 warning (amber) reserved for state
- 1 danger (red) reserved for error / destructive
If you add a 5th accent, you've started a new brand.
Semantic neutral ladder
Most of a SaaS UI is neutrals. Define them as a ladder:
text-primary #F8FAFC
text-secondary #E2E8F0
text-tertiary #94A3B8
text-disabled #64748B
text-inverse #0F172A
Plus matching surface ladder for backgrounds.
Accessibility minimums
WCAG AA (baseline):
- 4.5:1 contrast for body text
- 3:1 for large text (18pt+ or 14pt+ bold) and UI components
Pure white on pure black is usually wrong — #F8FAFC on #0A1929 reads better and hits AAA.
When to use gradients
- ✓ Once in the hero (gradient text on the h1)
- ✓ On primary CTAs
- ✓ As subtle background washes (10-15% opacity)
- ✗ Multiple gradient surfaces on the same page
- ✗ Gradients on body text (unreadable at small sizes)
- ✗ Gradient EVERYTHING — this trend will date
Common mistakes
- 7 accent colors → looks like a startup deck
- Light gray on white at 3:1 contrast → fails WCAG
- Hard-coded hex throughout → impossible to theme
- "Brand red" used for buttons AND errors → ambiguous
- Different shades of teal in different places → drift
Where this fits in X3 Compass
X3 Compass uses cyan-teal #2DD4BF primary, violet #8B5CF6 secondary, amber #FBBF24 warning, red #EF4444 danger. Token model in brand/palette.css.
