OverviewCopy Anchor Link

Welcome to the Vayu UI color system! This guide will teach you how to think about colors in a semantic, meaningful way. By the end, you'll understand why we never say "use blue" — we say "use brand".

The Golden Rule: The Pairing PatternCopy Anchor Link

Before we dive into individual colors, memorize this pattern:

bg-[name] + text-[name]-content

Every background color has a paired text color that guarantees proper contrast. Always use them together.

// ✅ Do: Use paired colors
<div className="bg-surface text-surface-content">
  This text will always be readable
</div>

// ❌ Don't: Mix arbitrary colors
<div className="bg-surface text-blue-500">
  Contrast is not guaranteed
</div>

This pattern ensures:

• WCAG AA compliance in both light and dark modes
• Consistent contrast across your entire app
• Automatic dark mode support without extra work

The Layer Cake ModelCopy Anchor Link

Think of your UI as a stack of layers, like a cake. Each layer has a purpose, and they stack from bottom to top:

┌─────────────────────────────────────┐  ← Elevated (Modals, Tooltips)
│  ┌───────────────────────────────┐  │
│  │         Surface (Cards)       │  │  ← Surface (Containers)
│  │  ┌─────────────────────────┐  │  │
│  │  │                         │  │  │
│  │  │      Content Here       │  │  │
│  │  │                         │  │  │
│  │  └─────────────────────────┘  │  │
│  └───────────────────────────────┘  │
│                                     │  ← Canvas (App Background)
└─────────────────────────────────────┘

Why This MattersCopy Anchor Link

Each layer is slightly different from the one below it, creating visual separation. In light mode, layers get lighter as they go up. In dark mode, they get darker. This creates natural depth without you having to think about it.

Base LayersCopy Anchor Link

These four layers form the foundation of every screen in your app.

CanvasCopy Anchor Link

The canvas is your app's foundation. It's the bottom-most layer.

SurfaceCopy Anchor Link

Surfaces are containers that sit on top of the canvas. Cards, panels, and form elements use this layer.

SidebarCopy Anchor Link

Sidebars are for navigation. They're visually distinct from the main content area.

ElevatedCopy Anchor Link

Elevated surfaces appear above everything else. Think modals, tooltips, and dropdowns.

Semantic ColorsCopy Anchor Link

Semantic colors convey meaning. Use these when you need to communicate state or intent.

Brand (Primary)Copy Anchor Link

Your brand color is for primary actions and key interactive elements.

SuccessCopy Anchor Link

For positive outcomes, confirmations, and completed states.

WarningCopy Anchor Link

For cautionary messages and pending states.

DestructiveCopy Anchor Link

For errors, dangerous actions, and critical warnings.

InfoCopy Anchor Link

For informational messages and help content.

MutedCopy Anchor Link

For de-emphasized content, disabled states, and placeholders.

Structural ElementsCopy Anchor Link

These colors define borders and focus states.

// Card with border
<div className="bg-surface text-surface-content border border-border rounded-surface p-4">
  Card content
</div>

// Input with field border
<input className="border border-field rounded-control px-3 py-2 focus:ring-2 focus:ring-focus" />

// Focus ring on button
<button className="focus:ring-2 focus:ring-focus rounded-control px-4 py-2">
  Click Me
</button>

Dark ModeCopy Anchor Link

Dark mode is automatically handled when you use the pairing pattern. Simply add the .dark class to a parent element (typically <html> or <body>), and all colors will adapt.

How It WorksCopy Anchor Link

// In your root layout
<html className="dark">
  <body className="bg-canvas text-canvas-content">{/* All children use dark mode colors */}</body>
</html>

Toggle PatternCopy Anchor Link

'use client';
import { useState, useEffect } from 'react';

export function ThemeToggle() {
  const [isDark, setIsDark] = useState(false);

  useEffect(() => {
    document.documentElement.classList.toggle('dark', isDark);
  }, [isDark]);

  return <button onClick={() => setIsDark(!isDark)}>{isDark ? '☀️ Light' : '🌙 Dark'}</button>;
}

CSS Custom VariantCopy Anchor Link

The dark mode is configured using Tailwind's custom variant:

@custom-variant dark (&:where(.dark, .dark *));

This means dark: classes apply when the element (or any parent) has the .dark class.

Quick ReferenceCopy Anchor Link

Complete Color Pairing TableCopy Anchor Link

Do's and Don'tsCopy Anchor Link