Hue Inheritance System - Monolex Docs

Overview

Hue Inheritance controls how much the theme’s Anchor Hue is “inherited” by different UI elements. This system is a combination of CORE and FLOW operations.

┌─────────────────────────────────────────────────────────────────┐
│  HUE INHERITANCE: CORE + FLOW COMBINATION                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: FLOW (Base Mixing)                                     │
│  ─────────────────────────                                      │
│  mix_in_oklab(bg, text, ratio)                                  │
│  → OkLab Cartesian space linear interpolation                   │
│  → Smooth intermediate colors without muddiness                 │
│                                                                 │
│  Step 2: CORE (Hue Inheritance)                                 │
│  ─────────────────────────────                                  │
│  blend_hue(original_hue, anchor_hue, inherit_ratio)             │
│  → OkLCH Polar space hue angle blending                         │
│  → Inject anchor's color identity                               │
│                                                                 │
│  Result: FLOW determines brightness/saturation                  │
│          CORE determines color identity                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Inheritance Parameters

Parameter	Range	Default	Purpose	Type
bgHueInherit	0-1	0.80	BG inherits anchor hue	CORE
bgChromaBoost	0-0.02	0.008	BG chroma addition	CORE
textHueInherit	0-1	1.00	Text inherits anchor hue	CORE
textChromaBoost	0-0.02	0.00	Text chroma addition	CORE
borderHueInherit	0-1	0.18	Border inherits anchor hue	CORE
ansiHueInherit	0-0.5	0.08	Normal ANSI inheritance	CORE
brightHueInherit	0-0.5	0.05	Bright ANSI inheritance	CORE

Why All CORE Parameters?

┌─────────────────────────────────────────────────────────────────┐
│  HUE INHERITANCE = CORE OPERATION                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  blend_hue(h1, h2, ratio) function essence:                     │
│                                                                 │
│  Input:                                                         │
│    h1 = Original hue (0-360 degrees)                            │
│    h2 = Anchor Hue (theme reference)                            │
│    ratio = Inheritance rate (0.0 - 1.0)                         │
│                                                                 │
│  Output:                                                        │
│    new_h = h1 * (1-ratio) + h2 * ratio                          │
│                                                                 │
│  This is OkLCH Polar space angle interpolation                  │
│  → Direct manipulation of color identity (Hue)                  │
│  → Typical CORE operation                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Background Hue Inheritance

Implementation Flow

BG Hue Inheritance Pipeline:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

     INPUT: bg=#1a1a2e, text=#f0f0f0
               │
               ▼
     ┌─────────────────────────────────────────────────────────┐
     │  FLOW PHASE: mix_in_oklab(bg, text, 0.04)               │
     │  ─────────────────────────────────────────              │
     │  • OkLab Cartesian space mixing                         │
     │  • bg 96% + text 4%                                     │
     │  • Result: slightly lighter base color                  │
     └─────────────────────┬───────────────────────────────────┘
                           │
                           ▼
     ┌─────────────────────────────────────────────────────────┐
     │  CONVERSION: hex_to_oklab → to_lch()                    │
     │  ─────────────────────────────────────                  │
     │  • Cartesian (L, a, b) → Polar (L, C, H)                │
     │  • Transition from FLOW to CORE space                   │
     └─────────────────────┬───────────────────────────────────┘
                           │
                           ▼
     ┌─────────────────────────────────────────────────────────┐
     │  CORE PHASE: blend_hue(h, anchor_hue, 0.80)             │
     │  ─────────────────────────────────────────              │
     │  • OkLCH Polar space hue interpolation                  │
     │  • Original Hue 20% + Anchor Hue 80%                    │
     │  • Result: new Hue dominated by anchor                  │
     └─────────────────────┬───────────────────────────────────┘
                           │
                           ▼
     ┌─────────────────────────────────────────────────────────┐
     │  CORE OUTPUT: oklch_to_hex(l, new_c, new_h)             │
     │  ─────────────────────────────────────────              │
     │  • Generate final color with new Hue                    │
     │  • Theme identity injection complete                    │
     └─────────────────────────────────────────────────────────┘
               │
               ▼
     OUTPUT: bg-secondary (background with anchor hue)

Pure Black Problem

A special case arises with pure black backgrounds.

┌─────────────────────────────────────────────────────────────────┐
│  PURE BLACK PROBLEM                                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  coreDark: #000000 (pure black)                                 │
│       |                                                         │
│  OkLab: L=0, a=0, b=0                                           │
│       |                                                         │
│  OkLCH: L=0, C=0, H=??? (undefined)                             │
│                                                                 │
│  Problem:                                                       │
│  • H = atan2(b, a) = atan2(0, 0) = undefined                    │
│  • When Chroma is 0, Hue is meaningless                         │
│  • blend_hue() cannot work properly                             │
│                                                                 │
│  After FLOW mix:                                                │
│  mix(#000000, #f0f0f0, 0.04) = #0d0d0d                          │
│  → OkLCH: L~0.05, C~0, H=undefined                              │
│  → Still cannot blend Hue                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Solution: bgChromaBoost

┌─────────────────────────────────────────────────────────────────┐
│  SOLUTION: bgChromaBoost (CORE Injection)                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Strategy:                                                      │
│  1. If Chroma is near 0, inject directly                        │
│  2. Use Anchor Hue directly (blending impossible)               │
│                                                                 │
│  Code logic:                                                    │
│  if cache.bg_chroma_boost > 0.0 {                               │
│      new_h = cache.anchor_hue;        // Direct CORE injection  │
│      new_c = c + cache.bg_chroma_boost; // Add chroma           │
│  }                                                              │
│                                                                 │
│  Example (monolex-darknight):                                   │
│  coreDark: #000000                                              │
│  bgChromaBoost: 0.012                                           │
│  anchor_hue: 250 degrees (Blue)                                 │
│       |                                                         │
│  bg-secondary:                                                  │
│    L = 0.05 (from mix)                                          │
│    C = 0.012 (injected)                                         │
│    H = 250 degrees (anchor, direct)                             │
│       |                                                         │
│  Result: very dark background with blue undertone               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Text Hue Inheritance

100% Inheritance Meaning

Text Hue Inheritance (100%):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

text_hue_inherit = 1.0 (default)
  |
blend_hue(original_h, anchor_h, 1.0)
  |
new_h = original_h * 0.0 + anchor_h * 1.0
new_h = anchor_h (completely Anchor Hue)

Meaning:
• Text color completely follows Theme's hue
• L/C preserved from original for readability
• Only Hue matches Theme → strong visual unity

Example:
  coreLight: #f0f0f0 (neutral gray)
  anchor_hue: 250 degrees (blue)
  text_hue_inherit: 100%
      |
  text-primary: brightness preserved, Hue is blue-tinted
  text-secondary: medium brightness, Hue is blue-tinted
  text-tertiary: darker brightness, Hue is blue-tinted

Border Hue Inheritance

Borders use a special Chroma Scaling approach.

Border Chroma Scaling (CORE):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

border_hue_inherit = 0.18 (18%)
anchor_chroma = 0.05

base_chroma = 0.05
border_chroma = 0.05 + 0.18 * 0.06 = 0.0608

┌─────────────────────────────────────────────────────────────────┐
│  Border Level          Chroma        Visual Effect              │
├─────────────────────────────────────────────────────────────────┤
│  border-primary        0.0608        Subtle theme hint          │
│  border-secondary      0.0730        Slightly more visible      │
│  border-light          0.0851        Most visible theme color   │
└─────────────────────────────────────────────────────────────────┘

Why this design?
• Borders serve as UI dividers
• Too strong colors are distracting
• Progressive Chroma increase expresses depth
• Anchor Hue reflected subtly (18%)

ANSI Hue Inheritance

Normal vs Bright ANSI

ANSI Type	Inherit	Reasoning
Normal	8%	Slight theme color hint
Bright	5%	Already bright, so less inheritance

Why Low ANSI Inheritance?

┌─────────────────────────────────────────────────────────────────┐
│  ANSI LOW INHERITANCE REASONING                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ANSI color purpose:                                            │
│  • Information delivery in ls, git, syntax highlighting         │
│  • Semantic colors: red = error, green = success                │
│  • Distortion by theme causes information loss                  │
│                                                                 │
│  Solution:                                                      │
│  • ansiHueInherit = 8% (very subtle hint only)                  │
│  • Original ANSI color identity 92% preserved                   │
│  • Harmony with theme handled by Hue Warp algorithm             │
│                                                                 │
│  Bright ANSI (5%):                                              │
│  • Bright colors already have high saturation                   │
│  • More sensitive to Hue changes                                │
│  • Less inheritance to preserve original                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Theme Inheritance Strategies

Comparison Table

Theme	bgHue	textHue	borderHue	ansiHue	Strategy
monolex-night	80%	100%	18%	8%	Balanced defaults
monolex-darknight	100%	100%	20%	10%	Strong theme colors
monolex-forest	0%	100%	25%	15%	Natural BG
dracula	0%	100%	15%	8%	Preserve BG, unify text
solarized-dark	0%	100%	25%	12%	Solarized philosophy
standard	0%	0%	0%	0%	xterm compatible mode

Strategy Patterns

┌─────────────────────────────────────────────────────────────────┐
│  INHERITANCE STRATEGY PATTERNS                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Pattern A: Full Integration (monolex-night)                    │
│  ────────────────────────────────────────────                   │
│  • BG 80%: Strong theme color in background                     │
│  • Text 100%: Complete text unification                         │
│  • Result: Very unified visual experience                       │
│                                                                 │
│  Pattern B: Selective (monolex-forest)                          │
│  ────────────────────────────────────────────                   │
│  • BG 0%: Background keeps original (already green)             │
│  • Text 100%: Only text unified                                 │
│  • Result: Prevents excessive green, natural harmony            │
│                                                                 │
│  Pattern C: Pure (standard)                                     │
│  ────────────────────────────────────────────                   │
│  • All inheritance 0%                                           │
│  • Result: xterm compatible, pure original colors               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Mix Ratio and Inheritance Interaction

Mix Ratio Parameters

Parameter	Default	Purpose
bgSecondaryRatio	0.96	bg-secondary = 96% bg + 4% text
bgTertiaryRatio	0.92	bg-tertiary = 92% bg + 8% text
textSecondaryRatio	0.70	text-secondary = 70% text + 30% bg
textTertiaryRatio	0.62	text-tertiary = 62% text + 38% bg

FLOW to CORE Cascade

Color Generation Cascade:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

bg-primary:   [████████████████████████████████]  coreDark (100%)
              (no FLOW, no CORE)

bg-secondary: [████████████████████████████████░░]
              │                              │
              └── FLOW: 96% bg + 4% text ────┘
              │
              └── CORE: blend_hue(h, anchor_h, 80%)

bg-tertiary:  [████████████████████████████░░░░]
              │                          │
              └── FLOW: 92% bg + 8% text ┘
              │
              └── CORE: blend_hue(h, anchor_h, 80%)
              │
              └── CORE: tint(tint_hue, tint_strength)

At each step:
1. FLOW determines brightness/saturation first
2. CORE applies color identity after

THE CENTER

How Hue Inheritance Helps Information Flow

The Hue Inheritance system directly serves Core-Flow’s mission of using color to help humans parse information.

Connection to Core-Flow:
├── Visual Hierarchy: Different inheritance levels create depth
│   → Users can distinguish primary from secondary from tertiary
├── Theme Identity: High text inheritance (100%) ensures brand
│   → Immediate recognition of "my terminal"
├── Information Preservation: Low ANSI inheritance (8%)
│   → Error/success semantics preserved
└── Flexible Strategies: Per-theme customization
    → Different use cases supported (dev, design, accessibility)

The FLOW + CORE combination achieves:

Perceptual accuracy (FLOW): mix_in_oklab provides uniform mixing
Color identity (CORE): blend_hue injects theme hue
Independent control: Mix ratios and inheritance rates adjust separately

Rust and TypeScript Implementation

Compare the dual implementation across languages

​Overview

​Inheritance Parameters

​Why All CORE Parameters?

​Background Hue Inheritance

​Implementation Flow

​Pure Black Problem

​Solution: bgChromaBoost

​Text Hue Inheritance

​100% Inheritance Meaning

​Border Hue Inheritance

​ANSI Hue Inheritance

​Normal vs Bright ANSI

​Why Low ANSI Inheritance?

​Theme Inheritance Strategies

​Comparison Table

​Strategy Patterns

​Mix Ratio and Inheritance Interaction

​Mix Ratio Parameters

​FLOW to CORE Cascade

​THE CENTER

​How Hue Inheritance Helps Information Flow