Skip to main content

​
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