What Are Semantic Colors?
Semantic colors convey MEANING, not decoration. They tell users what is happening in the system at a glance.┌──────────────────────────────────────────────────────────────────────────────┐
│ THE FIVE SEMANTIC COLORS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ PRIMARY (Blue) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Meaning: Main action, brand identity │ │
│ │ Usage: [Save] [Submit] [Continue] buttons, links │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ SUCCESS (Green) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Meaning: Positive outcome, active state │ │
│ │ Usage: "Saved successfully", "Running", "Connected" │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ DANGER (Red) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Meaning: Error, destructive action, critical issue │ │
│ │ Usage: [Delete], "Error occurred", "Disconnected" │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ WARNING (Yellow) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Meaning: Caution, pending action │ │
│ │ Usage: "Unsaved changes", "Pending", "Action required" │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ INFO (Soft Blue) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Meaning: Neutral information, tips │ │
│ │ Usage: Tooltips, helper text, informational badges │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Color Intensity Hierarchy
Different semantic colors have different visual “weight” based on their urgency:┌──────────────────────────────────────────────────────────────────────────────┐
│ VISUAL WEIGHT HIERARCHY │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ STRONGEST WEAKEST │
│ │ │ │
│ v v │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ DANGER │ │ PRIMARY │ │ SUCCESS │ │ INFO │ │
│ │ │ │ WARNING │ │ │ │ │ │
│ │ OOOO │ │ OOO │ │ OOO │ │ OO │ │
│ │ OOOOOO │ │ OOOOO │ │ OOOOO │ │ OO │ │
│ │ OOOOOOOO │ │ OOOOOO │ │ OOOOOO │ │ OOO │ │
│ │OOOOOOOOOO │ │OOOOOOO │ │OOOOOOO │ │ OOO │ │
│ │ │ │ │ │ │ │ │ │
│ │ Highest │ │ Standard │ │ Standard │ │ Softest │ │
│ │ Intensity │ │ Intensity │ │ Intensity │ │ Intensity │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
│ │
│ DANGER grabs attention FIRST - that is intentional. │
│ INFO recedes - it is helpful but not urgent. │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
The OKLCH Values
┌──────────────────────────────────────────────────────────────────────────────┐
│ SEMANTIC COLOR SPECIFICATIONS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Color Lightness Chroma Hue Why These Values? │
│ ─────────────────────────────────────────────────────────────────────── │
│ │
│ PRIMARY 55% 0.15 230 Standard weight, │
│ (Blue) trustworthy color │
│ │
│ SUCCESS 55% 0.15 130 Standard weight, │
│ (Green) positive association │
│ │
│ DANGER 55% 0.18 25 HIGHER chroma (0.18) │
│ (Red) demands attention │
│ │
│ WARNING 65% 0.15 85 HIGHER lightness (65%) │
│ (Yellow) compensates for yellow │
│ │
│ INFO 55% 0.12 230 LOWER chroma (0.12) │
│ (Blue) gentler, less urgent │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ NOTE: Danger uses higher chroma because errors need to stand out. │
│ Warning uses higher lightness because yellow appears dark otherwise. │
│ Info uses lower chroma because it should not compete for attention. │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Derived States: Hover and Muted
Every semantic color has derived states for interactions:┌──────────────────────────────────────────────────────────────────────────────┐
│ HOVER STATES │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ When user hovers, the color BRIGHTENS (adds white): │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Normal: [=========] │ │
│ │ Hover: [============] (+15% white) │ │
│ │ │ │
│ │ Exception: Warning only uses +10% white │ │
│ │ (Yellow is already bright, more white would wash it out) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ MUTED STATES │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ For backgrounds, colors become semi-transparent: │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Full: [XXXXXXXXXXXX] 100% opacity │ │
│ │ Muted: [............] 20% opacity (80% transparent) │ │
│ │ │ │
│ │ The color stays recognizable, just softer. │ │
│ │ Used for: Badge backgrounds, notification backgrounds │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Status Badge Pattern
Status badges use a three-layer composition:┌──────────────────────────────────────────────────────────────────────────────┐
│ STATUS BADGE ANATOMY │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────────────────────────────────┐ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ SUCCESS TEXT │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ └──────────────────────────────────────────┘ │ │ │
│ │ │ (Text: Full color) │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ │ (Background: 20% opacity of same color) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ (Border: Full color, 1px) │
│ │
│ │
│ THREE LAYERS: │
│ 1. Border: Full semantic color (defines the edge) │
│ 2. Background: 20% opacity (subtle fill) │
│ 3. Text: Full semantic color (readable on the background) │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Terminal Color Synchronization
Semantic colors match ANSI terminal colors for consistency:┌──────────────────────────────────────────────────────────────────────────────┐
│ UI AND TERMINAL ALIGNMENT │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ When terminal output shows an error in red, and a UI badge shows │
│ "Error" in the danger color, they should look THE SAME. │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Terminal Output: │ │
│ │ > npm ERR! [RED] Module not found │ │
│ │ │ │
│ │ UI Badge: │ │
│ │ [RED ERROR BADGE] │ │
│ │ │ │
│ │ SAME RED = User instantly understands the connection │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ MAPPINGS: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Semantic ANSI Terminal │ │
│ │ ───────────────────────────────────────────────────────── │ │
│ │ Primary (Blue) ANSI Blue │ │
│ │ Success (Green) ANSI Green │ │
│ │ Danger (Red) ANSI Red │ │
│ │ Warning (Yellow) ANSI Yellow │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Accessibility: Dark vs Light Themes
┌──────────────────────────────────────────────────────────────────────────────┐
│ VISIBILITY ON DARK BACKGROUND │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Background: Black (L = 0%) │
│ │
│ Color Lightness Contrast Visible? │
│ ───────────────────────────────────────────────────── │
│ Primary 55% 55% Yes │
│ Success 55% 55% Yes │
│ Danger 55% 55% Yes │
│ Warning 65% 65% Excellent │
│ Info 55% 55% Yes │
│ │
│ All colors stand out clearly on dark backgrounds. │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ VISIBILITY ON LIGHT BACKGROUND │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Background: White (L = 100%) │
│ │
│ Color Lightness Contrast Visible? │
│ ───────────────────────────────────────────────────── │
│ Primary 55% 45% Acceptable │
│ Success 55% 45% Acceptable │
│ Danger 55% 45% Acceptable │
│ Warning 65% 35% Marginal (needs dark text) │
│ Info 55% 45% Acceptable │
│ │
│ Warning on light backgrounds needs DARK TEXT to be readable. │
│ This is the ONLY semantic color override between themes. │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Key Takeaways
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ 1. Five semantic colors: Primary, Success, Danger, Warning, Info │
│ │
│ 2. Danger has the highest intensity (0.18 chroma) │
│ - Errors demand attention │
│ │
│ 3. Warning has higher lightness (65%) │
│ - Compensates for yellow appearing dark naturally │
│ │
│ 4. Info has the lowest intensity (0.12 chroma) │
│ - Helpful but not urgent │
│ │
│ 5. Status badges use 3 layers: border, background (20%), text │
│ │
│ 6. UI colors match terminal ANSI colors for consistency │
│ │
│ 7. Only Warning needs a theme override (dark text on light theme) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
CSS Variables
Learn how these colors are organized in CSS