Color System

The UI Lab design system uses OKLCH, a perceptually-uniform color space, to ensure consistent, accessible colors across all themes and components. This guide documents the complete palette and provides task-focused guidance for using colors in your projects.

Quick Reference

Understanding OKLCH

OKLCH is a perceptually-uniform color space designed for human perception. Unlike RGB or HSL, equal steps in lightness produce equal perceived brightness changes, making it possible to build themes programmatically while maintaining visual consistency.

Why OKLCH?

• Perceptual Uniformity: Lightness correlates directly with perceived brightness
• Hue Stability: Colors maintain their character across the entire lightness scale
• Accessible Defaults: All combinations designed for WCAG AA compliance
• Predictable Theming: Dynamic theme generation maintains visual balance automatically

Color Components

Each color consists of three values:

• L (Lightness): 0% (black) to 100% (white) — controls brightness
• C (Chroma): 0 (grayscale) to ~0.4 (saturated) — controls color intensity
• H (Hue): 0° to 360° — the color position on the color wheel

Example: oklch(50% 0.150 25) represents a medium-brightness red with moderate saturation

Complete Color Palette

Below is the comprehensive color palette for all color families. Click any value to copy it to your clipboard.

Color Palette Families

Core Colors

Background — Grayscale palette for surfaces and containers

• Shade Scale: 500–950 (only these shades exist; no 50–400 variants)
• Usage: Page backgrounds, card surfaces, elevated containers
• Tip: Lower numbers (500–600) are used for primary surfaces; higher numbers (700–950) for deeper/elevated layers. Direction reverses between light and dark mode.

Foreground — Grayscale palette optimized for text and icons

• Shade Scale: 50–400 (only these shades exist; no 500–950 variants)
• Usage: Body text, labels, icons, borders, dividers
• Tip: Lower numbers (50–100) are lighter; higher numbers (300–400) are darker. Direction reverses between light and dark mode.

Accent — Primary interactive color (dynamically themable)

• Shade Scale: 50–600 (only these shades exist)
• Usage: Primary buttons, links, focus indicators, highlights
• Theming: Can be customized per theme while maintaining accessibility

Semantic Colors

All semantic families share the same shade range: 50–600 only. Shades 700–950 do not exist for semantic colors.

Success — Positive actions and confirmations

• Chroma Range: 0.01 – 0.28
• Use: Success messages, confirmations, approved states, positive feedback

Danger — Errors and destructive actions

• Chroma Range: 0.01 – 0.28
• Use: Error messages, destructive action confirmations, failed states

Warning — Cautions and attention-needed states

• Chroma Range: 0.01 – 0.26
• Use: Warning messages, pending states, important notices

Info — Information and neutral states

• Chroma Range: 0.01 – 0.24
• Use: Info messages, documentation links, neutral metadata

How to Use Colors

Selecting Colors

1. Choose the Right Family: Select based on semantic meaning (success, danger, etc.), not appearance
2. Pick a Shade by family:
   • Background (500–950): 500–600 for primary surfaces, 700–950 for deeper/elevated layers
   • Foreground (50–400): 50–100 for subtle text/icons, 200–300 for secondary, 400 for primary text
   • Semantic / Accent (50–600): 50–200 for light tints (backgrounds/badges), 300–400 for medium tones, 500–600 for bold/interactive use
3. Verify Contrast: Always check that text/background pairs meet WCAG AA (4.5:1 minimum)
4. Consider Both Themes: All colors work in light and dark modes

Practical Examples

Success Message

<!-- Background: success-50 or success-100 -->
<!-- Text: success-500 or success-600 -->
<!-- Border: success-200 or success-300 -->

Error/Danger Button

<!-- Background: danger-500 or danger-600 -->
<!-- Text: foreground-50 -->
<!-- Hover: danger-600 -->

Info Badge

<!-- Background: info-100 or info-200 -->
<!-- Text: info-500 or info-600 -->

CSS Variables

All colors are available as CSS variables:

--{family}-{shade}

Examples: --background-900, --foreground-300, --accent-500, --success-700, --danger-600, --warning-400, --info-500

In CSS:

.button {
  background-color: var(--accent-600);
  color: var(--foreground-50);
  border-color: var(--accent-700);
}

.button:hover {
  background-color: var(--accent-700);
}

.success-alert {
  background-color: var(--success-50);
  color: var(--success-900);
  border: 1px solid var(--success-300);
}

In React/TSX:

<div style={{ backgroundColor: 'var(--success-50)', color: 'var(--success-900)' }}>
  Success!
</div>

With Tailwind CSS v4:

<div class="bg-success-50 text-success-900">Success!</div>
<button class="bg-accent-600 text-foreground-50 hover:bg-accent-700">Click me</button>

Accessibility

Contrast Ratios

All color combinations in this palette are designed to meet or exceed WCAG AA standards:

• Normal Text: Minimum 4.5:1 contrast ratio
• Large Text: Minimum 3:1 contrast ratio
• Graphics & UI: Minimum 3:1 contrast ratio

Best Practices

1. Never rely on color alone: Always use text labels and icons in addition to color
2. Test your combinations: Verify contrast before using in production
3. Consider colorblind users: Use semantic colors with supporting icons
4. Use sufficient spacing: Help distinguish similarly-colored elements through spacing

Testing Tools

• WebAIM Contrast Checker
• APCA Contrast Calculator
• Accessible Colors

Dynamic Theming

The accent color family can be dynamically customized while maintaining accessibility:

import { generateThemePalettes } from '@/lib/color-utils'

const customTheme = generateThemePalettes(
  { l: 0.16, c: 0.0, h: 0 },      // Background
  { l: 0.9, c: 0.0, h: 0 },       // Foreground
  { l: 0.5, c: 0.15, h: 260 },    // Accent (custom purple)
  'dark'
)

The system automatically:

• Scales chroma appropriately across shades
• Maintains perceptual uniformity
• Respects WCAG AA compliance
• Applies global adjustments consistently

Browser Support

The OKLCH color space is supported in all modern browsers:

• Chrome/Edge 111+
• Firefox 113+
• Safari 15.4+
• All modern mobile browsers

For older browsers, CSS variables fall back to oklch() syntax with fallback values automatically provided.

Further Reading

• OKLCH Color Space Specification
• Perception vs Reality in Color
• WCAG 2.1 Color Contrast Guidelines
• Color Blindness Simulation Tools