Color Theory for Engineers: The Only 5 Rules You Need

export default function DashboardLayout({ children }) {
  return (
    // 60%: The dominant background (bg-zinc-50)
    <div className="min-h-screen bg-zinc-50 font-sans text-zinc-900">
      
      {/* 30%: Structural elements, borders, and secondary surfaces */}
      <aside className="w-64 border-r border-zinc-200 bg-white p-4">
        <nav className="flex flex-col gap-2">
          {/* Secondary text and subtle hover states */}
          <a href="#" className="text-zinc-600 hover:bg-zinc-100 p-2 rounded-md">
            Settings
          </a>
        </nav>
      </aside>
 
      <main className="flex-1 p-8">
        <header className="mb-8 flex justify-between items-center">
          <h1 className="text-2xl font-bold">Overview</h1>
          
          {/* 10%: The accent color, strictly used for primary action */}
          <button className="bg-indigo-600 hover:bg-indigo-700 text-white px-4 py-2 rounded-md shadow-sm focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">
            Create Project
          </button>
        </header>
        
        {/* 30%: Cards and structural borders */}
        <div className="border border-zinc-200 bg-white rounded-xl shadow-sm p-6">
          {children}
        </div>
      </main>
    </div>
  )
}
If you catch yourself applying `bg-indigo-600` to a container that occupies more than 10% of the screen real estate, you are breaking the rule. Revert it to a neutral surface and use the accent color only for the specific action within that container.
 
## 2. Enforce Contrast Ratios Mathematically
 
Stop squinting at your monitor to check if gray text is readable. Accessibility is a strict mathematical threshold. The Web Content Accessibility Guidelines (WCAG) dictate a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (18pt or 14pt bold).
 
If you put `#FFFFFF` text on a `#FBBF24` (Tailwind Amber 400) button, your contrast ratio is 1.28:1. That is functionally invisible to a user with astigmatism. If you use `#6B7280` (Gray 500) for placeholder text on a `#FFFFFF` background, the ratio is 4.54:1. You barely pass.
 
You do not need to guess these values. You need to memorize the safe pairings within a standard 11-step scale (50-950).
 
| Foreground Class | Background Class | Contrast Ratio | WCAG Status | Use Case |
| :--- | :--- | :--- | :--- | :--- |
| `text-zinc-900` | `bg-zinc-50` | 15.8:1 | Pass (AAA) | Primary body text |
| `text-zinc-500` | `bg-white` | 4.54:1 | Pass (AA) | Secondary text, placeholders |
| `text-zinc-400` | `bg-white` | 2.95:1 | **Fail** | Do not use for text |
| `text-white` | `bg-blue-600` | 5.1:1 | Pass (AA) | Primary buttons |
| `text-white` | `bg-blue-500` | 3.6:1 | **Fail** (Normal text) | Large text only (18pt+) |
 
To enforce this programmatically, use a tool like `eslint-plugin-jsx-a11y` or add a contrast-checking utility to your CI pipeline. If your primary brand color sits at the 400 or 500 level (like a bright cyan or lime), you cannot use white text on your primary buttons. You must use `text-slate-900` to hit the 4.5:1 threshold.
 
## 3. Limit HSL Ranges for Primary Colors
 
Engineers often pick primary colors by dragging the color picker to the extreme top-right corner. This yields pure, fully saturated hex codes like `#FF0000` or `#00FF00`. These colors cause eye strain because LCD monitors render them at maximum light intensity. They look like terminal output, not a modern SaaS product.
 
Professional UI colors live in a specific HSL (Hue, Saturation, Lightness) bounding box. To pick a primary color that looks premium, constrain your values:
 
- **Saturation:** 60% to 85%. Never 100%. You want color, not a laser beam.
- **Lightness:** 45% to 55%. This is the sweet spot where the color is dark enough to support white text (Rule 2), but bright enough to register as a color rather than a muddy gray.
 
If you generate a brand identity with OneMinuteBranding, the AI strictly enforces these bounding boxes. The engine outputs a `$49 one-time` package that includes a `tailwind.config.ts` where the primary color is mathematically guaranteed to hit the 45-55% lightness target, ensuring your `bg-primary` and `text-white` combination always passes WCAG requirements.
 
## 4. Dark Mode Requires Desaturation, Not Just Inversion
 
Flipping `bg-white` to `bg-black` takes 10 seconds. Fixing the neon bleed of your primary colors takes hours.
 
When you put `indigo-600` (`#4F46E5`) on a white background, it looks grounded. When you put that exact same hex code on `zinc-950` (`#09090B`), the optical contrast spikes. The color appears to vibrate. This is called halation.
 
Dark mode requires desaturating your primary colors by 10-20% and increasing lightness by 5-10%. You cannot use the exact same hex code for your primary button in both modes.
 
Here is the correct way to handle dark mode using CSS variables. You define the base values in the `:root` and modify the specific channels in the `.dark` class.
 
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
 
@layer base {
  :root {
    /* Light mode: 50% lightness, 80% saturation */
    --color-primary: 240 80% 50%;
    
    --bg-surface: 0 0% 100%;
    --text-main: 240 10% 10%;
  }
 
  .dark {
    /* Dark mode: 60% lightness (brighter), 60% saturation (less intense) */
    --color-primary: 240 60% 60%;
    
    --bg-surface: 240 10% 4%;
    --text-main: 0 0% 98%;
  }
}

// tailwind.config.ts
import type { Config } from 'tailwindcss'
 
export default {
  content: ['./app/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: 'hsl(var(--color-primary) / <alpha-value>)',
        surface: 'hsl(var(--bg-surface) / <alpha-value>)',
        main: 'hsl(var(--text-main) / <alpha-value>)',
      },
    },
  },
} satisfies Config

import Color from "colorjs.io";
 
// Base primary color in OKLCH
const baseColor = new Color("oklch(0.65 0.2 250)");
 
// Generate the 900 shade by dropping lightness to 0.25
const shade900 = baseColor.clone();
shade900.oklch.l = 0.25;
 
// Convert back to sRGB hex for Tailwind, clipping out-of-gamut colors
const hex900 = shade900.to("srgb").toString({ format: "hex" });
console.log(hex900); // Maps to your tailwind config