The Fundamental Question
Before choosing a color, ask yourself one question.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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