The Four-Level Hierarchy
Monolex colors follow a structured hierarchy from raw values to contextual relationships:┌──────────────────────────────────────────────────────────────────────────────┐
│ CSS VARIABLE HIERARCHY │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ LEVEL 4: Contextual Relationships │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ "What text color works on this background?" │ │
│ │ │ │
│ │ --bg-accent-primary-text (white on blue button) │ │
│ │ --status-success-text (green on green badge bg) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ v │
│ LEVEL 3: Component Colors │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ "What color is this UI element?" │ │
│ │ │ │
│ │ --color-context-menu-bg (specific component) │ │
│ │ --status-success-bg (badge background) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ v │
│ LEVEL 2: Semantic Colors (OKLCH) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ "What does this color MEAN?" │ │
│ │ │ │
│ │ --oklch-primary (main action) │ │
│ │ --oklch-success (positive outcome) │ │
│ │ --oklch-danger (error, critical) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ v │
│ LEVEL 1: Primitive Colors │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ "What is the raw color value?" │ │
│ │ │ │
│ │ --color-bg-primary (background base) │ │
│ │ --color-text-primary (text base) │ │
│ │ --color-ansi-red (terminal red) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Level 1: Primitive Colors
The foundation layer - raw color values without semantic meaning:┌──────────────────────────────────────────────────────────────────────────────┐
│ PRIMITIVE COLORS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ BACKGROUNDS (Light to Dark): │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ --color-bg-primary [=====] Pure black (#000000) │ │
│ │ --color-bg-secondary [======] Near black (#090e13) │ │
│ │ --color-bg-tertiary [=======] Dark gray (#0b1117) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ TEXT (Dark to Light): │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ --color-text-tertiary [====] Dim (#586e75) │ │
│ │ --color-text-secondary [======] Medium (#657b83) │ │
│ │ --color-text-primary [========] Bright (#93a1a1) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ANSI TERMINAL COLORS: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ [Black] [Red] [Green] [Yellow] [Blue] [Magenta] [Cyan] [White] │ │
│ │ 0 1 2 3 4 5 6 7 │ │
│ │ │ │
│ │ Same colors used in terminal output and UI elements │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Level 2: Semantic Colors
Colors with meaning - the core identity layer:┌──────────────────────────────────────────────────────────────────────────────┐
│ SEMANTIC COLORS AS ANCHOR POINTS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Each semantic color defines a "zone" on the color wheel: │
│ │
│ 0 (Red) │
│ │ │
│ DANGER ──┐ │ │
│ (H=25) │ │ ┌── WARNING │
│ v │ v (H=85) │
│ [===]│[===] │
│ │ │
│ 270 ───────────────────.─────────────────── 90 │
│ │ │
│ [===]│[===] │
│ ^ │ ^ │
│ PRIMARY ──┘ │ └── SUCCESS │
│ (H=230) │ (H=130) │
│ │ │
│ 180 (Cyan) │
│ │
│ Colors near each anchor point visually "belong" to that semantic zone. │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Level 3: Component Colors
Specific UI elements reference the lower levels:┌──────────────────────────────────────────────────────────────────────────────┐
│ COMPONENT COLORS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ CONTEXT MENU: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ ┌────────────────────────────────────────────┐ │ │
│ │ │ --color-context-menu-bg │ │ │
│ │ │ --color-context-menu-border │ │ │
│ │ │ ┌────────────────────────────────────┐ │ │ │
│ │ │ │ --color-context-menu-text │ │ │ │
│ │ │ │ --color-context-menu-hover │ │ │ │
│ │ │ └────────────────────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ STATUS BADGES (Reference Level 2): │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ --status-success = var(--oklch-success) <- Level 2 │ │
│ │ --status-success-bg = oklch-success @ 20% <- Derived │ │
│ │ │ │
│ │ --status-warning = var(--oklch-warning) <- Level 2 │ │
│ │ --status-warning-bg = oklch-warning @ 20% <- Derived │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Level 4: Contextual Relationships
The highest level - defines how elements relate to each other:┌──────────────────────────────────────────────────────────────────────────────┐
│ BACKGROUND-FOREGROUND RELATIONSHIPS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ "If I have THIS background, what text color should I use?" │
│ │
│ PRIMARY BUTTON: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Background: --oklch-primary (Blue) │ │
│ │ │ │ │
│ │ v │ │
│ │ Text: --bg-accent-primary-text (White) │ │
│ │ │ │
│ │ Result: [ Save ] <- White text on blue button │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ SUCCESS BADGE: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Background: --status-success-bg (20% green) │ │
│ │ │ │ │
│ │ v │ │
│ │ Text: --status-success-text (Full green) │ │
│ │ │ │
│ │ Result: [ Connected ] <- Green text on pale green bg │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Overlay System
Transparent overlays for hover states and shadows:┌──────────────────────────────────────────────────────────────────────────────┐
│ OVERLAY SYSTEM │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ LIGHT OVERLAYS (for hover states on dark theme): │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ overlay-light-1 [ ] 8% white <- Subtle hover │ │
│ │ overlay-light-2 [ .] 12% white <- Active hover │ │
│ │ overlay-light-3 [..] 16% white <- Strong focus │ │
│ │ overlay-light-4 [...] 20% white <- Pressed state │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ DARK OVERLAYS (for shadows): │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ overlay-dark-1 [ ] 5% black <- Light shadow │ │
│ │ overlay-dark-2 [ .] 10% black <- Medium shadow │ │
│ │ overlay-dark-3 [..] 20% black <- Strong shadow │ │
│ │ overlay-dark-4 [...] 30% black <- Deep shadow │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Theme Switching
When themes change, only Level 1 primitives need updating:┌──────────────────────────────────────────────────────────────────────────────┐
│ THEME SWITCHING ARCHITECTURE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ DARK THEME (Default): │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Level 1 (Primitives): │ │
│ │ --color-bg-primary: #000000 <- Black background │ │
│ │ --color-text-primary: #93a1a1 <- Light text │ │
│ │ │ │
│ │ Levels 2-4: UNCHANGED │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ LIGHT THEME: │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Level 1 (Primitives): │ │
│ │ --color-bg-primary: #ffffff <- White background │ │
│ │ --color-text-primary: #1a1a1a <- Dark text │ │
│ │ │ │
│ │ Levels 2-4: UNCHANGED │ │
│ │ │ │
│ │ Exception: --bg-accent-warning-text: #1a1a1a │ │
│ │ (Warning needs dark text on light theme for readability) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ BENEFIT: Semantic colors stay consistent across themes. │
│ "Success green" is the same green on both themes. │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Visual Summary
┌──────────────────────────────────────────────────────────────────────────────┐
│ COMPLETE HIERARCHY FLOW │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Raw Value Meaning Component Context │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ #000000 │ --> │ bg-primary │ --> │ menu-bg │ │ text-on-bg │ │
│ │ #93a1a1 │ │ text-primary│ │ header-text │ │ contrast │ │
│ │ H=230 │ │ primary │ │ button-bg │ │ relationship│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ LEVEL 1 LEVEL 2 LEVEL 3 LEVEL 4 │
│ (What) (Why) (Where) (How Together) │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Key Takeaways
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ 1. Four levels: Primitive -> Semantic -> Component -> Contextual │
│ │
│ 2. Level 1 holds raw values, Level 2 adds meaning │
│ │
│ 3. Higher levels reference lower levels (never the reverse) │
│ │
│ 4. Theme switching only changes Level 1 (mostly) │
│ │
│ 5. Semantic colors (Level 2) stay consistent across themes │
│ │
│ 6. Level 4 answers "what text goes on this background?" │
│ │
│ 7. Only one Level 4 override needed: warning text on light theme │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
File Type Colors
Learn how file extensions get their colors