The Fundamental Question
Before choosing a color, ask yourself one question.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ THE FUNDAMENTAL QUESTION │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ ┌──────────────────────────────────────────┐ ║│
│ ║ │ │ ║│
│ ║ │ What role does this color play? │ ║│
│ ║ │ │ ║│
│ ║ └─────────────────────┬────────────────────┘ ║│
│ ║ │ ║│
│ ║ ┌─────────────────────┴────────────────────┐ ║│
│ ║ │ │ ║│
│ ║ v v ║│
│ ║ ┌───────────────────┐ ┌───────────────────┐ ║│
│ ║ │ │ │ │ ║│
│ ║ │ IDENTITY │ │ BEHAVIOR │ ║│
│ ║ │ │ │ │ ║│
│ ║ │ WHAT it IS │ │ HOW it ACTS │ ║│
│ ║ │ │ │ │ ║│
│ ║ └────────┬──────────┘ └────────┬──────────┘ ║│
│ ║ │ │ ║│
│ ║ v v ║│
│ ║ ┌─────────────┐ ┌─────────────┐ ║│
│ ║ │ CORE │ │ FLOW │ ║│
│ ║ │ (OKLCH) │ │ (color-mix) │ ║│
│ ║ └─────────────┘ └─────────────┘ ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
The Master Decision Flowchart
Follow this chart to determine Core vs Flow.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ MASTER DECISION FLOWCHART │
│ │
│ "I need a color" │
│ │ │
│ v │
│ ┌───────────────────────────────────┐ │
│ │ Does this color represent │ │
│ │ a unique IDENTITY? │ │
│ └───────────────┬───────────────────┘ │
│ │ │
│ ┌─────────────┴─────────────┐ │
│ │ │ │
│ v v │
│ YES NO │
│ │ │ │
│ v v │
│ ┌────────────────┐ ┌──────────────────────┐ │
│ │ │ │ Is it derived from │ │
│ │ USE CORE │ │ an existing color? │ │
│ │ (OKLCH) │ └──────────┬───────────┘ │
│ │ │ │ │
│ │ Define the │ ┌─────────┴─────────┐ │
│ │ identity color │ │ │ │
│ │ │ v v │
│ └────────────────┘ YES NO │
│ │ │ │
│ v v │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ USE FLOW │ │ Create new │ │
│ │ (color-mix) │ │ CORE COLOR │ │
│ │ │ │ │ │
│ │ Derive from │ │ This is a new │ │
│ │ existing Core │ │ identity │ │
│ └────────────────┘ └────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Identity Detection
How to know if something needs a Core color.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ IDENTITY CHECKLIST - Answer YES = Use CORE │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ [ ] Does it have a unique category? ║│
│ ║ (file type, user role, entity type) ║│
│ ║ ║│
│ ║ [ ] Is it always this color when visible? ║│
│ ║ (regardless of hover, focus, or other states) ║│
│ ║ ║│
│ ║ [ ] Does changing its color change its meaning? ║│
│ ║ (blue = info, red = error, green = success) ║│
│ ║ ║│
│ ║ [ ] Is it a brand color? ║│
│ ║ (company primary, accent colors) ║│
│ ║ ║│
│ ║ [ ] Is this the "resting state" color? ║│
│ ║ (default appearance before any interaction) ║│
│ ║ ║│
│ ║ [ ] Would users recognize this element BY this color? ║│
│ ║ ("That blue badge means TypeScript") ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Identity Examples
Common categories that use Core colors.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ FILE TYPES - Each file type IS its color │
│ │
│ ┌───────────────────┬───────────────────┬───────────────────┐ │
│ │ │ │ │ │
│ │ TypeScript │ Python │ Rust │ │
│ │ [TS] │ [PY] │ [RS] │ │
│ │ Blue │ Green │ Orange │ │
│ │ │ │ │ │
│ └───────────────────┴───────────────────┴───────────────────┘ │
│ │
│ "That blue badge means TypeScript" = recognition by identity │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ STATUS INDICATORS - Status IS the color │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ SUCCESS │ │ WARNING │ │ DANGER │ │ INFO │ │
│ │ Green │ │ Yellow │ │ Red │ │ Blue │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ "Red means error, green means success" = semantic identity │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ AGENTS / TERMINALS - Each agent IS its color │
│ │
│ Agent 1 Agent 2 Agent 3 Agent 4 │
│ [1] [2] [3] [4] │
│ Orange Yellow Lime-Green Green │
│ │
│ Colors distributed using Golden Angle (27.5 degrees apart) │
│ Maximum visual separation between identities │
│ │
│ "That's the yellow agent" = Agent #2 identified by color │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Derivation Detection
How to know if something needs a Flow color.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ DERIVATION CHECKLIST - Answer YES = Use FLOW │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ [ ] Is this a state variation? ║│
│ ║ (hover, active, focus, disabled) ║│
│ ║ ║│
│ ║ [ ] Is this a transparency level? ║│
│ ║ (overlay, background tint, ghost button) ║│
│ ║ ║│
│ ║ [ ] Is this a lightness/darkness shift? ║│
│ ║ (pressed state, shadow, highlight) ║│
│ ║ ║│
│ ║ [ ] Is this between two identities? ║│
│ ║ (gradient, transition, interpolation) ║│
│ ║ ║│
│ ║ [ ] Does this color only appear temporarily? ║│
│ ║ (feedback animation, loading indicator) ║│
│ ║ ║│
│ ║ [ ] Is this creating atmosphere? ║│
│ ║ (ambient glow, focus dimming, backdrop) ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Derivation Examples
Common patterns that use Flow colors.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ STATE VARIATIONS - All states derive from the same Core │
│ │
│ CORE PRIMARY │
│ ┌─────────────┐ │
│ │ Blue │ │
│ └──────┬──────┘ │
│ │ │
│ ┌───────────┬─────────┴─────────┬───────────┐ │
│ │ │ │ │ │
│ v v v v │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ HOVER │ │ ACTIVE │ │ FOCUS │ │ DISABLED │ │
│ │ Lighter │ │ Darker │ │ Ring │ │ Muted │ │
│ │ (+15%) │ │ (-20%) │ │ (40%) │ │ (gray) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ TRANSPARENCY LEVELS - Background tints from Core │
│ │
│ CORE SUCCESS │
│ ┌─────────────┐ │
│ │ Green │ │
│ └──────┬──────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ │ │
│ v v │
│ ┌──────────┐ ┌──────────┐ │
│ │BACKGROUND│ │ GLOW │ │
│ │ 80% see │ │ 95% see │ │
│ │ through │ │ through │ │
│ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ GRADIENTS - Interpolation between two Cores │
│ │
│ ╔═══════════╗ ╔═══════════╗ │
│ ║ CORE ║ ║ CORE ║ │
│ ║ Blue ║═══════════════════════════════════=>║ Orange ║ │
│ ║ (Branch A)║ FLOW ║(Branch B) ║ │
│ ╚═══════════╝ (Merge Line) ╚═══════════╝ │
│ │
│ "Flow between Cores uses OKLAB - no muddy transitions." │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Component Decision Guide
How Core and Flow apply to UI components.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ BUTTON COMPONENT │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Element │ Type │ Reason │ │
│ ├──────────────────────┼────────┼───────────────────────────────────┤ │
│ │ Default background │ CORE │ This IS a primary button │ │
│ │ Hover background │ FLOW │ State variation of primary │ │
│ │ Active background │ FLOW │ State variation of primary │ │
│ │ Focus ring │ FLOW │ Temporary state indicator │ │
│ │ Disabled background │ FLOW │ State variation of primary │ │
│ │ Text color │ CORE │ Contrast anchor (white/black) │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────┐ │
│ │ Primary Button │ <── CORE: Default state │
│ └──────────────────┘ │
│ │ │
│ │ hover │
│ v │
│ ┌──────────────────┐ │
│ │ Primary Button │ <── FLOW: Lighter │
│ └──────────────────┘ │
│ │ │
│ │ click │
│ v │
│ ┌──────────────────┐ │
│ │ Primary Button │ <── FLOW: Darker │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ STATUS BADGE COMPONENT │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Element │ Type │ Reason │ │
│ ├──────────────────────┼────────┼───────────────────────────────────┤ │
│ │ Icon dot │ CORE │ IS the success indicator │ │
│ │ Text │ CORE │ IS the success identity │ │
│ │ Background │ FLOW │ Contextual atmosphere │ │
│ │ Border │ FLOW │ Edge of context │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────┐ │
│ │ [*] Success │ │ │
│ └───────────────────────────────────┘ │
│ ^ ^ ^ │
│ │ │ │ │
│ CORE CORE FLOW │
│ (dot) (text) (background) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Anti-Patterns
What NOT to do.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ ANTI-PATTERNS TO AVOID │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ 1. Deriving a Core from Another Core ║│
│ ║ ========================================= ║│
│ ║ ║│
│ ║ WRONG: ║│
│ ║ Core Secondary = Lighten(Core Primary) ║│
│ ║ ║│
│ ║ RIGHT: ║│
│ ║ Core Primary = Blue (55%, 0.15, 230) ║│
│ ║ Core Secondary = Purple (55%, 0.10, 200) <── Independently defined ║│
│ ║ ║│
│ ╠═════════════════════════════════════════════════════════════════════════╣│
│ ║ 2. Using Flow for Identity ║│
│ ║ =========================== ║│
│ ║ ║│
│ ║ WRONG: ║│
│ ║ TypeScript badge uses (blue + transparent 80%) ║│
│ ║ ║│
│ ║ RIGHT: ║│
│ ║ TypeScript badge uses Core TypeScript Blue ║│
│ ║ ║│
│ ╠═════════════════════════════════════════════════════════════════════════╣│
│ ║ 3. Hardcoding Flow Values ║│
│ ║ ========================= ║│
│ ║ ║│
│ ║ WRONG: ║│
│ ║ Button hover = #3399DD (manual calculation) ║│
│ ║ ║│
│ ║ RIGHT: ║│
│ ║ Button hover = Flow Primary Hover (derived from Core) ║│
│ ║ ║│
│ ╠═════════════════════════════════════════════════════════════════════════╣│
│ ║ 4. Using sRGB for Interpolation ║│
│ ║ ================================ ║│
│ ║ ║│
│ ║ WRONG: ║│
│ ║ Gradient from Blue to Orange ║│
│ ║ Blue ─────── MUDDY BROWN ─────── Orange ║│
│ ║ ║│
│ ║ RIGHT: ║│
│ ║ OKLAB Gradient from Blue to Orange ║│
│ ║ Blue ─────── VIBRANT PURPLE ─────── Orange ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Quick Reference Matrix
A quick lookup for common use cases.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ QUICK REFERENCE MATRIX │
│ │
│ ┌───────────────────────────────────┬────────┬────────┬──────────────────┐ │
│ │ Use Case │ CORE │ FLOW │ Reason │ │
│ ├───────────────────────────────────┼────────┼────────┼──────────────────┤ │
│ │ File type badge │ X │ │ Identity │ │
│ │ Agent/terminal label │ X │ │ Identity │ │
│ │ Branch color │ X │ │ Identity │ │
│ │ Status indicator │ X │ │ Identity │ │
│ │ Brand/accent color │ X │ │ Identity │ │
│ │ ANSI terminal color │ X │ │ Identity │ │
│ ├───────────────────────────────────┼────────┼────────┼──────────────────┤ │
│ │ Hover state │ │ X │ State variation │ │
│ │ Active/pressed state │ │ X │ State variation │ │
│ │ Focus ring │ │ X │ Temporary state │ │
│ │ Disabled state │ │ X │ State variation │ │
│ │ Selected state │ │ X │ State variation │ │
│ ├───────────────────────────────────┼────────┼────────┼──────────────────┤ │
│ │ Badge background │ │ X │ Atmosphere │ │
│ │ Overlay/backdrop │ │ X │ Transparency │ │
│ │ Subtle tint │ │ X │ Transparency │ │
│ │ Glow effect │ │ X │ Transparency │ │
│ ├───────────────────────────────────┼────────┼────────┼──────────────────┤ │
│ │ Gradient endpoints │ X │ │ Two identities │ │
│ │ Gradient middle │ │ X │ Interpolation │ │
│ └───────────────────────────────────┴────────┴────────┴──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
The Five Rules
Core principles for color decisions.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ THE FIVE RULES │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ RULE 1: Identity = Core ║│
│ ║ ======================= ║│
│ ║ If the color DEFINES what something IS, use Core. ║│
│ ║ ║│
│ ╠═════════════════════════════════════════════════════════════════════════╣│
│ ║ ║│
│ ║ RULE 2: State = Flow ║│
│ ║ ==================== ║│
│ ║ If the color MODIFIES how something appears, use Flow. ║│
│ ║ ║│
│ ╠═════════════════════════════════════════════════════════════════════════╣│
│ ║ ║│
│ ║ RULE 3: Flow Derives from Core ║│
│ ║ ============================== ║│
│ ║ Every Flow Color must trace back to a Core Color. ║│
│ ║ ║│
│ ╠═════════════════════════════════════════════════════════════════════════╣│
│ ║ ║│
│ ║ RULE 4: Use OKLAB for Mixing ║│
│ ║ ============================ ║│
│ ║ "Flow between Cores uses OKLAB - no muddy transitions." ║│
│ ║ ║│
│ ╠═════════════════════════════════════════════════════════════════════════╣│
│ ║ ║│
│ ║ RULE 5: Core Uses OKLCH, Flow Uses color-mix() ║│
│ ║ ============================================== ║│
│ ║ Core: Define identity with OKLCH ║│
│ ║ Flow: Derive states with color-mix() ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
“Core Colors define identity. Flow Colors handle everything in between.”
Marketing Docs
Learn how to communicate Core and Flow to stakeholders