┌═══════════════════════════════════════════════════════════════════════════════┐
│ │
│ THE CENTER │
│ │
│ "CodexMono is The Brick - the fundamental unit that enables │
│ Monokinetics: unified Human + AI experience through predictable, │
│ trustable visual alignment." │
│ │
│ CSS System as Brick Implementation: │
│ - Two Anchors create mathematical predictability │
│ - Container Queries enable context-aware alignment │
│ - OKLCH ensures perceptual uniformity across all surfaces │
│ │
└═══════════════════════════════════════════════════════════════════════════════┘
CSS System Architecture
“VariableMD extends the Brick from Terminal to Documents”How the CSS System Works
┌──────────────────────────────────────────────────────────────────────────┐
│ CSS SYSTEM OVERVIEW │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ THE PROBLEM: Terminal and Documents look inconsistent │
│ ============ │
│ │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ Terminal │ │ Document │ │
│ │ (Dark Blue) │ =/= │ (Light Gray) │ │
│ └───────────────┘ └───────────────┘ │
│ │
│ Different colors, different fonts, jarring experience │
│ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ THE SOLUTION: Three-Tier Variable System │
│ ============ │
│ │
│ Level 1: Primitives │
│ │ (Raw values, font definitions) │
│ v │
│ Level 2: Semantic │
│ │ (Two Anchors + derived colors) │
│ v │
│ Level 3: Component │
│ (Context-specific theming) │
│ │
│ Result: Unified appearance across Terminal and Documents │
│ │
└──────────────────────────────────────────────────────────────────────────┘
The Two-Anchor System
The heart of Monolex theming: all colors derive from just two anchor points.┌──────────────────────────────────────────────────────────────────────────┐
│ TWO-ANCHOR SYSTEM │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ Instead of defining hundreds of colors: │
│ │
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ Color1│ │ Color2│ │ Color3│ │ Color4│ │ Color5│ ... │
│ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ │
│ │
│ We define TWO anchors: │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ │ │ │ │
│ │ BG ANCHOR │ │ TEXT ANCHOR │ │
│ │ (Background) │ │ (Foreground) │ │
│ │ │ │ │ │
│ └───────────────────┘ └───────────────────┘ │
│ │ │ │
│ │ Mathematical │ │
│ │ Derivation │ │
│ v v │
│ ┌────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ALL OTHER COLORS │ │
│ │ (Secondary, Tertiary, Borders, etc.) │ │
│ │ │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ Benefit: Change 2 values, entire theme updates │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Theme Switching
How dark and light themes work with the anchor system:┌──────────────────────────────────────────────────────────────────────────┐
│ THEME SWITCHING │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ DARK THEME LIGHT THEME │
│ ========== =========== │
│ │
│ BG Anchor: Dark (#0b1117) BG Anchor: Light (white) │
│ Text Anchor: Light (#93a1a1) Text Anchor: Dark (black) │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ │ │///////////////////│ │
│ │ Dark Background │ │ Light Background│ │
│ │ Light Text │ SWAP │ Dark Text │ │
│ │ │ --> │///////////////////│ │
│ └───────────────────┘ └───────────────────┘ │
│ │
│ Same CSS code, different anchors │
│ All derived colors automatically adjust │
│ │
│ Result: Single stylesheet works for both themes │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Container Queries
Traditional responsive design responds to window size. VariableMD responds to container size.┌──────────────────────────────────────────────────────────────────────────┐
│ VIEWPORT vs CONTAINER │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ VIEWPORT-BASED (Traditional) │
│ ============================= │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Window: 1440px │ │
│ │ ┌──────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ │ Sidebar │ │ Terminal │ │ MD Editor │ │ │
│ │ │ 240px │ │ 600px │ │ 600px │ │ │
│ │ └──────────┘ └──────────────────┘ └──────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Problem: Window is 1440px, but MD Editor is only 600px │
│ Styles based on 1440px are wrong for 600px content! │
│ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ CONTAINER-BASED (VariableMD) │
│ ============================ │
│ │
│ ┌──────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Sidebar │ │ Terminal │ │ MD Editor │ │
│ │ 240px │ │ 600px │ │ 600px │ │
│ │ Responds│ │ Responds │ │ Responds │ │
│ │ to 240 │ │ to 600 │ │ to 600 │ │
│ └──────────┘ └──────────────────┘ └──────────────────┘ │
│ │
│ Each panel responds to its OWN width │
│ │
│ Result: Consistent behavior regardless of layout │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Adaptive Typography
Text automatically adjusts to container width:┌──────────────────────────────────────────────────────────────────────────┐
│ ADAPTIVE TYPOGRAPHY │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ WIDE CONTAINER (>= 500px) │
│ ========================= │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ # Large Heading │ │
│ │ ## Medium Heading │ │
│ │ Body text at comfortable reading size │ │
│ │ │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ Fixed proportional sizes (em units) │
│ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ NARROW CONTAINER (< 500px) │
│ ========================== │
│ │
│ ┌────────────────────────┐ │
│ │ │ │
│ │ # Heading │ <- Text scales to fit │
│ │ ## Heading │ container width │
│ │ Body text adjusts │ │
│ │ │ │
│ └────────────────────────┘ │
│ │
│ Dynamic sizing based on container (cqw units) │
│ │
│ Result: Readable text at any container size │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Heading Scale System
One setting controls all heading sizes through linear interpolation:┌──────────────────────────────────────────────────────────────────────────┐
│ HEADING SCALE SYSTEM │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ Control ONE value: H1 Scale = 2.0 │
│ │
│ Size │
│ │ │
│ 2.0 ─│──────────────────────────────── * H1 (2.0x) │
│ │ * │
│ 1.8 ─│────────────────────────── * H2 (1.8x) │
│ │ * │
│ 1.6 ─│──────────────────── * H3 (1.6x) │
│ │ * │
│ 1.4 ─│────────────── * H4 (1.4x) │
│ │ * │
│ 1.2 ─│──────── * H5 (1.2x) │
│ │ * │
│ 1.0 ─│── * H6 (1.0x = base) │
│ │ │
│ └────┬────┬────┬────┬────┬────┐ │
│ H6 H5 H4 H3 H2 H1 │
│ │
│ Linear progression: H6 to H1 │
│ │
│ Change H1 Scale: │
│ - 1.5 = subtle hierarchy │
│ - 2.0 = balanced (default) │
│ - 3.0 = dramatic hierarchy │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Variable Bridging
How theme variables flow from global to component level:┌──────────────────────────────────────────────────────────────────────────┐
│ VARIABLE BRIDGING │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ GLOBAL THEME │
│ ============ │
│ │
│ ┌───────────────────┐ │
│ │ │ │
│ │ Theme Colors │ │
│ │ (body level) │ │
│ │ │ │
│ └────────┬──────────┘ │
│ │ │
│ │ Bridge (automatic flow) │
│ │ │
│ v │
│ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │
│ │ │ │ │ │ │ │
│ │ Terminal │ │ MD Editor │ │ Sidebar │ │
│ │ (inherits) │ │ (inherits) │ │ (inherits) │ │
│ │ │ │ │ │ │ │
│ └───────────────────┘ └───────────────────┘ └───────────────────┘ │
│ │
│ Benefits: │
│ - Theme changes propagate everywhere │
│ - Components can override when needed │
│ - Clear separation of concerns │
│ │
└──────────────────────────────────────────────────────────────────────────┘
OKLCH Color Space
Monolex uses OKLCH for perceptually uniform colors:┌──────────────────────────────────────────────────────────────────────────┐
│ OKLCH COLOR SYSTEM │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ Traditional RGB: │
│ ================ │
│ │
│ Same "50% brightness" looks different: │
│ │
│ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ Red │ │ Green │ │ Blue │ <- Different perceived │
│ │ (50%) │ │ (50%) │ │ (50%) │ brightness! │
│ └───────┘ └───────┘ └───────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ OKLCH (Perceptually Uniform): │
│ ============================= │
│ │
│ Same lightness = same perceived brightness: │
│ │
│ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ Red │ │ Green │ │ Blue │ <- All look equally │
│ │ (50%) │ │ (50%) │ │ (50%) │ bright! │
│ └───────┘ └───────┘ └───────┘ │
│ │
│ Result: Consistent contrast ratios across all colors │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Key Principles
┌──────────────────────────────────────────────────────────────────────────┐
│ CSS SYSTEM PRINCIPLES │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. TWO ANCHORS, INFINITE THEMES │
│ ┌─────┐ ┌──────┐ │
│ │ BG │ │ TEXT │ --> All other colors │
│ └─────┘ └──────┘ │
│ │
│ 2. CONTAINER-AWARE │
│ Components respond to their container, not the window │
│ │
│ 3. MATHEMATICAL PRECISION │
│ OKLCH ensures perceptually uniform color mixing │
│ │
│ 4. SINGLE SCALE CONTROL │
│ One H1 scale value generates all heading sizes │
│ │
│ 5. ADAPTIVE TYPOGRAPHY │
│ cqw units for narrow, em units for wide containers │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Summary
┌═══════════════════════════════════════════════════════════════════════════════┐
│ │
│ CSS SYSTEM: The Brick Extended to Documents │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ │ │ │ │ │ │
│ │ Two Anchors │ --> │ Container │ --> │ Consistent │ │
│ │ (BG + Text) │ │ Queries │ │ Experience │ │
│ │ │ │ │ │ │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
│ Technology Stack: │
│ - OKLCH color space (perceptual uniformity) │
│ - Container Queries (context-aware styling) │
│ - CSS Custom Properties (variable inheritance) │
│ - CodexMono typography (terminal consistency) │
│ │
│ Result: Terminal and Documents share unified visual language │
│ │
└═══════════════════════════════════════════════════════════════════════════════┘
Related:
- Theming System - Tree gutter and CodexMono font stack
- The Brick Extended to Documents - Core design philosophy