Overview
A visual roadmap for implementing the Core and Flow color system.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ IMPLEMENTATION JOURNEY │
│ │
│ Estimated Time: 2-4 hours (new projects), 4-8 hours (migrations) │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ STEP 1 STEP 2 STEP 3 STEP 4 ║│
│ ║ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ║│
│ ║ │ Define │ │ Define │ │Structure│ │ Apply │ ║│
│ ║ │ Core │─────>│ Flow │─────>│ CSS │ ────>│ to │ ║│
│ ║ │ Colors │ │ Rules │ │Hierarchy│ │ Comps │ ║│
│ ║ └────────┘ └────────┘ └────────┘ └────────┘ ║│
│ ║ │ │ │ │ ║│
│ ║ v v v v ║│
│ ║ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ║│
│ ║ │ STEP 5 │ │ STEP 6 │ │ STEP 7 │ │ STEP 8 │ ║│
│ ║ │ Theme │ │Fallback│ │ Access │ │ Perf │ ║│
│ ║ │ Modes │ │ (older)│ │ Check │ │ Verify │ ║│
│ ║ └────────┘ └────────┘ └────────┘ └────────┘ ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Browser Support
Modern browsers support everything natively.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ BROWSER SUPPORT (2025) │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ Feature Support Browser Minimum ║│
│ ║ ====================╤═══════╤══════════════════ ║│
│ ║ │ │ ║│
│ ║ CSS Variables │ 96%+ │ Chrome 49+, Firefox 31+, Safari 9.1+ ║│
│ ║ │ │ ║│
│ ║ OKLCH Color Space │ 92%+ │ Chrome 111+, Firefox 113+, Safari 16.4+ ║│
│ ║ │ │ ║│
│ ║ OKLAB Color Space │ 92%+ │ Chrome 111+, Firefox 113+, Safari 16.4+ ║│
│ ║ │ │ ║│
│ ║ color-mix() │ 91%+ │ Chrome 111+, Firefox 113+, Safari 16.4+ ║│
│ ║ │ │ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
│ The vast majority of users are covered. │
│ Fallbacks available for the remaining 8%. │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 1: Define Core Colors
Your identity colors using OKLCH.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ CORE COLOR DEFINITIONS │
│ │
│ OKLCH SYNTAX: │
│ ============= │
│ │
│ oklch( L% C H ) │
│ │ │ │ │
│ │ │ └── Hue: 0-360 degrees (position on color wheel) │
│ │ └──────── Chroma: 0-0.4 (saturation/vibrancy) │
│ └────────────── Lightness: 0-100% (perceived brightness) │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ SEMANTIC CORE COLORS ║│
│ ║ ║│
│ ║ ┌───────────┬───────┬───────┬───────┬───────────────────────────────┐ ║│
│ ║ │ Color │ L │ C │ H │ Purpose │ ║│
│ ║ ├───────────┼───────┼───────┼───────┼───────────────────────────────┤ ║│
│ ║ │ Primary │ 55% │ 0.15 │ 230 │ Actions, links, selections │ ║│
│ ║ │ Success │ 55% │ 0.15 │ 145 │ Positive states, confirm │ ║│
│ ║ │ Danger │ 55% │ 0.18 │ 25 │ Errors, destructive (higher C)│ ║│
│ ║ │ Warning │ 65% │ 0.15 │ 85 │ Caution (higher L for yellow) │ ║│
│ ║ │ Info │ 55% │ 0.12 │ 230 │ Informational (softer C) │ ║│
│ ║ └───────────┴───────┴───────┴───────┴───────────────────────────────┘ ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
│ WHY THESE VALUES? │
│ ================= │
│ │
│ L = 55% is standard reference (perceptually uniform) │
│ L = 65% for yellow (needs more brightness to be visible) │
│ C = 0.15 balances vibrancy and accessibility │
│ C = 0.18 for danger (higher attention) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 2: Define Flow Derivation Rules
State variations derived from Core colors.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ FLOW DERIVATION PATTERNS │
│ │
│ CORE COLOR │
│ ┌────────────┐ │
│ │ Primary │ │
│ │ Blue │ │
│ └─────┬──────┘ │
│ │ │
│ ┌────────────┬────────────┼────────────┬────────────┐ │
│ │ │ │ │ │ │
│ v v v v v │
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ HOVER │ │ACTIVE │ │ MUTED │ │ BG │ │DISABLED│ │
│ ├───────┤ ├───────┤ ├───────┤ ├───────┤ ├───────┤ │
│ │Lighter│ │Darker │ │Trans │ │Very │ │Gray │ │
│ │ +15% │ │ -20% │ │ 80% │ │Trans │ │ 60% │ │
│ │ │ │ │ │ │ │ 90% │ │ │ │
│ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ DERIVATION TABLE ║│
│ ║ ║│
│ ║ ┌────────────────┬─────────────────┬────────────────────────────┐ ║│
│ ║ │ Pattern │ How to Derive │ Use Case │ ║│
│ ║ ├────────────────┼─────────────────┼────────────────────────────┤ ║│
│ ║ │ Lighter │ Core + white │ Hover states │ ║│
│ ║ │ Darker │ Core + black │ Pressed/active states │ ║│
│ ║ │ Muted │ Core + trans │ Backgrounds, tints │ ║│
│ ║ │ Background │ Core + 90% trans│ Subtle fills │ ║│
│ ║ │ Focus ring │ Core + 40% trans│ Focus indicators │ ║│
│ ║ │ Disabled │ Core + gray │ Inactive elements │ ║│
│ ║ └────────────────┴─────────────────┴────────────────────────────┘ ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
│ MIXING COLOR SPACE: │
│ =================== │
│ │
│ OKLCH for lightening (preserves chroma) │
│ OKLAB for darkening and transparency (more natural) │
│ │
│ "Flow between Cores uses OKLAB - no muddy transitions." │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 3: Structure CSS Hierarchy
Organize variables into 4 levels.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ 4-LEVEL CSS HIERARCHY │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ LEVEL 1: PRIMITIVES ║│
│ ║ ======================= ║│
│ ║ ║│
│ ║ Raw values for backgrounds, text, borders ║│
│ ║ ║│
│ ║ Background: Primary, Secondary, Tertiary ║│
│ ║ Text: Primary, Secondary, Tertiary ║│
│ ║ Border: Primary, Secondary ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │ │
│ v │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ LEVEL 2: SEMANTIC (Core & Flow) ║│
│ ║ ================================ ║│
│ ║ ║│
│ ║ Core: Primary, Success, Danger, Warning, Info ║│
│ ║ Flow: Hover, Active, Muted, Background, Disabled ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │ │
│ v │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ LEVEL 3: COMPONENT ║│
│ ║ ================== ║│
│ ║ ║│
│ ║ Component-specific references to L1 and L2 ║│
│ ║ ║│
│ ║ Button: bg, text, hover-bg ║│
│ ║ Badge: bg, text ║│
│ ║ Input: border, focus-ring ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │ │
│ v │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ LEVEL 4: CONTEXTUAL ║│
│ ║ =================== ║│
│ ║ ║│
│ ║ Background-foreground pairings ║│
│ ║ ║│
│ ║ On Primary Background: Text color ║│
│ ║ On Accent Background: Contrast text ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 4: Apply to Components
How Core and Flow work in real components.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ BUTTON COMPONENT │
│ │
│ DEFAULT STATE HOVER STATE │
│ ============== =========== │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ │ │ │ │
│ │ Primary Blue │ hover │ Lighter Blue │ │
│ │ (CORE) │ ─────────> │ (FLOW) │ │
│ │ │ │ │ │
│ └────────────────┘ └────────────────┘ │
│ │
│ ACTIVE STATE DISABLED STATE │
│ ============ ============== │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ │ │ │ │
│ │ Darker Blue │ │ Gray-Blue │ │
│ │ (FLOW) │ │ (FLOW) │ │
│ │ │ │ │ │
│ └────────────────┘ └────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ STATUS BADGE COMPONENT │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ [*] Success Message │ │
│ └──────────────────────────────────────┘ │
│ ^ ^ ^ │
│ │ │ │ │
│ CORE CORE FLOW │
│ (icon) (text) (background) │
│ │
│ The dot IS the success indicator (Core) │
│ The text IS the success message (Core) │
│ The background provides context (Flow) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ GRADIENT COMPONENT │
│ │
│ ╔═══════════════════════════════════════════════════╗ │
│ ║ ║ │
│ ║ CORE Blue ══════ FLOW ══════ CORE Green ║ │
│ ║ ║ │
│ ╚═══════════════════════════════════════════════════╝ │
│ │
│ Endpoints are Core (identity colors) │
│ Middle is Flow (interpolation in OKLAB) │
│ │
│ "Flow between Cores uses OKLAB - no muddy transitions." │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 5: Configure Themes
Light and dark mode switching.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ THEME CONFIGURATION │
│ │
│ KEY INSIGHT: Only override PRIMITIVES. Core & Flow stay the same! │
│ │
│ ╔══════════════════════════════════╗ ╔══════════════════════════════════╗ │
│ ║ DARK THEME ║ ║ LIGHT THEME ║ │
│ ║ (default) ║ ║ (override) ║ │
│ ╠══════════════════════════════════╣ ╠══════════════════════════════════╣ │
│ ║ ║ ║ ║ │
│ ║ PRIMITIVES (change): ║ ║ PRIMITIVES (change): ║ │
│ ║ ──────────────────── ║ ║ ──────────────────── ║ │
│ ║ Background: Black ║ ║ Background: White ║ │
│ ║ Text: Light Gray ║ ║ Text: Dark Gray ║ │
│ ║ Borders: Dark Gray ║ ║ Borders: Light Gray ║ │
│ ║ ║ ║ ║ │
│ ├──────────────────────────────────┤ ├──────────────────────────────────┤ │
│ ║ ║ ║ ║ │
│ ║ CORE COLORS (same): ║ ║ CORE COLORS (same): ║ │
│ ║ ─────────────────── ║ ║ ─────────────────── ║ │
│ ║ Primary = Blue ║ ║ Primary = Blue ║ │
│ ║ Success = Green ║ ║ Success = Green ║ │
│ ║ Danger = Red ║ ║ Danger = Red ║ │
│ ║ Warning = Yellow ║ ║ Warning = Yellow ║ │
│ ║ ║ ║ ║ │
│ ├──────────────────────────────────┤ ├──────────────────────────────────┤ │
│ ║ ║ ║ ║ │
│ ║ FLOW COLORS (auto-update): ║ ║ FLOW COLORS (auto-update): ║ │
│ ║ ────────────────────────── ║ ║ ────────────────────────── ║ │
│ ║ All flows recalculate via ║ ║ All flows recalculate via ║ │
│ ║ CSS cascade ║ ║ CSS cascade ║ │
│ ║ ║ ║ ║ │
│ ╚══════════════════════════════════╝ ╚══════════════════════════════════╝ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 6: Add Browser Fallbacks
Support for older browsers.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ FALLBACK PATTERN │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ HEX FALLBACK FIRST, THEN OKLCH ║│
│ ║ ================================== ║│
│ ║ ║│
│ ║ Browser that doesn't support OKLCH: ║│
│ ║ Uses the HEX value (first declaration) ║│
│ ║ ║│
│ ║ Browser that supports OKLCH: ║│
│ ║ Uses the OKLCH value (second declaration overwrites) ║│
│ ║ ║│
│ ║ ┌───────────────────────────────────────────────────────────────────┐ ║│
│ ║ │ │ ║│
│ ║ │ Core Primary = #2380C7 <── Fallback for old browsers │ ║│
│ ║ │ Core Primary = oklch(55%...) <── Modern browsers use this │ ║│
│ ║ │ │ ║│
│ ║ └───────────────────────────────────────────────────────────────────┘ ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
│ FEATURE DETECTION (optional): │
│ ============================= │
│ │
│ @supports (color: color-mix(...)) │
│ --> Use advanced features │
│ │
│ @supports not (color: color-mix(...)) │
│ --> Use static fallback values │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 7: Verify Accessibility
Contrast checking with OKLCH.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ ACCESSIBILITY VERIFICATION │
│ │
│ OKLCH CONTRAST RULE: │
│ ==================== │
│ │
│ Lightness (L) difference of 55%+ approximates WCAG AA (4.5:1) │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ CONTRAST EXAMPLES ║│
│ ║ ║│
│ ║ ┌────────────────────┬────────┬────────┬─────────┬──────────────────┐ ║│
│ ║ │ Pairing │ Text L │ Bg L │ Delta │ Result │ ║│
│ ║ ├────────────────────┼────────┼────────┼─────────┼──────────────────┤ ║│
│ ║ │ Dark text on white │ 15% │ 95% │ 80% │ Exceeds AA │ ║│
│ ║ │ Light text on dark │ 90% │ 20% │ 70% │ Exceeds AA │ ║│
│ ║ │ Primary on dark │ 55% │ 10% │ 45% │ Close to minimum │ ║│
│ ║ └────────────────────┴────────┴────────┴─────────┴──────────────────┘ ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
│ VERIFICATION CHECKLIST: │
│ ======================= │
│ │
│ [ ] Primary button text readable │
│ [ ] Success badge text visible │
│ [ ] Warning text on light backgrounds │
│ [ ] Error messages stand out │
│ [ ] Focus rings visible everywhere │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step 8: Measure Performance
Confirm the speed advantage.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ PERFORMANCE METRICS │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ TARGET METRICS ║│
│ ║ ║│
│ ║ ┌────────────────────────┬──────────────┬─────────────────────────┐ ║│
│ ║ │ Metric │ Target │ Core & Flow Typical │ ║│
│ ║ ├────────────────────────┼──────────────┼─────────────────────────┤ ║│
│ ║ │ Theme switch time │ < 100ms │ < 0.1ms (CSS only) │ ║│
│ ║ │ Initial paint │ < 500ms │ No additional delay │ ║│
│ ║ │ JavaScript bundle │ 0 KB impact │ 0 KB (CSS native) │ ║│
│ ║ │ CSS file size (colors) │ < 10 KB │ ~3-5 KB │ ║│
│ ║ └────────────────────────┴──────────────┴─────────────────────────┘ ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
│ COMPARISON: │
│ =========== │
│ │
│ Theme Switch Time: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Core & Flow │=│ < 0.1ms │ │
│ │ Material HCT │═══════════════════════════════════════│ 10ms │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ Bundle Size: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Core & Flow │ 0 KB │ │
│ │ Material HCT │═════════════════════════│ 45 KB │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Migration Strategy
Moving from existing color systems.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ MIGRATION FROM HEX/HSL │
│ │
│ BEFORE: Many manual color values │
│ ===================================== │
│ │
│ primary = #2380C7 │
│ primary-light = #4A9DD9 <── Manual calculation │
│ primary-lighter = #7AB8E6 <── Manual calculation │
│ primary-dark = #1A6091 <── Manual calculation │
│ primary-alpha = rgba(...) <── Manual calculation │
│ │
│ AFTER: One Core, automatic Flow │
│ ===================================== │
│ │
│ Core Primary = oklch(55% 0.15 230) │
│ │ │
│ └───> Flow Hover = Core + lighter (auto) │
│ └───> Flow Active = Core + darker (auto) │
│ └───> Flow Background = Core + transparent (auto) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ MIGRATION STEPS │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ 1. Convert HEX to OKLCH ║│
│ ║ Use oklch.com to find equivalent values ║│
│ ║ ║│
│ ║ 2. Identify which colors are identities (Core) ║│
│ ║ These are the base colors that define meaning ║│
│ ║ ║│
│ ║ 3. Identify which colors are states (Flow) ║│
│ ║ These are variations of the base colors ║│
│ ║ ║│
│ ║ 4. Replace hardcoded values with var() references ║│
│ ║ Point to Core or Flow variables ║│
│ ║ ║│
│ ║ 5. Test theme switching ║│
│ ║ Verify all flows update correctly ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Complete Checklist
Summary of all implementation steps.┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ IMPLEMENTATION CHECKLIST │
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗│
│ ║ ║│
│ ║ STEP 1: Core Colors defined in OKLCH ║│
│ ║ [ ] Semantic colors (primary, success, danger, warning, info) ║│
│ ║ [ ] Brand colors ║│
│ ║ [ ] Entity colors (file types, agents) ║│
│ ║ ║│
│ ║ STEP 2: Flow derivation rules using color-mix() ║│
│ ║ [ ] Hover states ║│
│ ║ [ ] Active states ║│
│ ║ [ ] Muted/background ║│
│ ║ [ ] Disabled states ║│
│ ║ [ ] Overlays ║│
│ ║ ║│
│ ║ STEP 3: 4-level CSS hierarchy structured ║│
│ ║ [ ] Level 1: Primitives ║│
│ ║ [ ] Level 2: Semantic (Core & Flow) ║│
│ ║ [ ] Level 3: Component ║│
│ ║ [ ] Level 4: Contextual ║│
│ ║ ║│
│ ║ STEP 4: Components using Core & Flow ║│
│ ║ [ ] Buttons ║│
│ ║ [ ] Badges ║│
│ ║ [ ] Inputs ║│
│ ║ [ ] Gradients ║│
│ ║ ║│
│ ║ STEP 5: Light/dark themes configured ║│
│ ║ [ ] Dark mode (default) ║│
│ ║ [ ] Light mode (override primitives only) ║│
│ ║ ║│
│ ║ STEP 6: Browser fallbacks added ║│
│ ║ [ ] HEX fallbacks before OKLCH ║│
│ ║ [ ] @supports detection (optional) ║│
│ ║ ║│
│ ║ STEP 7: Accessibility verified ║│
│ ║ [ ] Contrast ratios checked ║│
│ ║ [ ] Focus states visible ║│
│ ║ ║│
│ ║ STEP 8: Performance measured ║│
│ ║ [ ] Theme switch < 1ms ║│
│ ║ [ ] No JavaScript overhead ║│
│ ║ ║│
│ ╚═════════════════════════════════════════════════════════════════════════╝│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
“Core Colors define identity. Flow Colors handle everything in between.”
CSS Architecture
Learn more about the 4-level CSS variable hierarchy