Overview
A visual roadmap for implementing the Core and Flow color system.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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.Copy
+-----------------------------------------------------------------------------+
| |
| 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