> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # TrueColor Tint System Architecture > How terminal colors transform in real-time to match your theme ## What is the Tint System? When applications output colors to your terminal, those colors need to match your theme. The Tint System transforms arbitrary colors in real-time while preserving their relationships. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ APPLICATION OUTPUT YOUR THEME │ │ ================== ========== │ │ │ │ #FF0000 (Pure Red) --> #E06C75 (Soft Rose) │ │ #00FF00 (Pure Green) --> #98C379 (Muted Sage) │ │ #0000FF (Pure Blue) --> #61AFEF (Sky Blue) │ │ │ │ The colors change, but their relationships remain: │ │ - Red is still "warm" │ │ - Green is still "natural" │ │ - Blue is still "cool" │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` *** ## The Transform Pipeline Every color passes through seven transformation steps. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 7-STEP TRANSFORM PIPELINE │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ INPUT: Any RGB Color (e.g., #FF5733 bright orange) │ │ │ │ │ v │ │ ┌──────────────────┐ │ │ │ 1. COLOR SPACE │ Convert to perceptually uniform space │ │ │ CONVERSION │ RGB --> OKLAB (how humans see color) │ │ └────────┬─────────┘ │ │ │ │ │ v │ │ ┌──────────────────┐ │ │ │ 2. POLAR FORM │ Switch to angle-based representation │ │ │ │ OKLAB --> OKLCH (Lightness, Chroma, Hue) │ │ └────────┬─────────┘ │ │ │ │ │ v │ │ ┌──────────────────┐ │ │ │ 3. LIGHTNESS │ Adjust brightness for theme contrast │ │ │ MAPPING │ (Weber-Fechner perceptual scaling) │ │ └────────┬─────────┘ │ │ │ │ │ v │ │ ┌──────────────────┐ │ │ │ 4. CHROMA │ Scale saturation for theme harmony │ │ │ SCALING │ (Reduce intensity slightly) │ │ └────────┬─────────┘ │ │ │ │ │ v │ │ ┌──────────────────┐ │ │ │ 5. FRAME DRAG │ Pull hue toward theme's tint color │ │ │ │ (Like gravity pulling nearby objects) │ │ └────────┬─────────┘ │ │ │ │ │ v │ │ ┌──────────────────┐ │ │ │ 6. EINSTEIN ARC │ Redistribute complementary colors │ │ │ │ (Bend colors around theme anchor) │ │ └────────┬─────────┘ │ │ │ │ │ v │ │ ┌──────────────────┐ │ │ │ 7. OUTPUT │ Convert back to displayable RGB │ │ │ CONVERSION │ OKLAB --> RGB --> #E07055 │ │ └──────────────────┘ │ │ │ │ OUTPUT: Theme-harmonized color (#E07055 coral-red) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` *** ## Physics Metaphors in Color The Tint System borrows concepts from physics to make color transformation intuitive. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ PHYSICS OF COLOR TRANSFORMATION │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ FRAME DRAG (from rotating black holes) │ │ ====================================== │ │ │ │ In space, a rotating massive object drags nearby space with it. │ │ In color, the theme's tint color "drags" nearby colors toward it. │ │ │ │ ~~~~~~~~~~~~~~~~~~~~ │ │ ~~~ ~~~ │ │ ~~ Colors get pulled ~~ │ │ ~ toward theme center ~ │ │ ~ @@@@@@@ ~ │ │ ~ @@ TINT @@ ~ │ │ ~ @@@@@@@ ~ │ │ ~ ~ │ │ ~~ ~~ │ │ ~~~ ~~~ │ │ ~~~~~~~~~~~~~~~~~~~~ │ │ │ │ EINSTEIN ARC (from gravitational lensing) │ │ ========================================= │ │ │ │ Light bends around massive objects in space. │ │ Colors bend around the theme's anchor hue. │ │ │ │ Light rays │ │ \ │ / │ │ \ │ / │ │ ┌──────===──────┐ │ │ │ ANCHOR │ <-- Theme's core color │ │ │ HUE │ bends other colors │ │ └──────===──────┘ │ │ / │ \ │ │ / │ \ │ │ Bent around │ │ │ │ CAUSTIC (from light convergence) │ │ ================================ │ │ │ │ When light bends around an object, it converges at a bright spot. │ │ In color, the "Caustic zone" is where complementary colors gather. │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` *** ## Two Coordinate Systems Colors live in two different mathematical spaces, each suited for different operations. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ TWO WAYS TO DESCRIBE COLOR │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ POLAR SPACE (OKLCH) CARTESIAN SPACE (OKLAB) │ │ =================== ====================== │ │ │ │ Like describing a point on Like describing a point on │ │ a color wheel using: a flat grid using: │ │ - Distance from center (Chroma) - Left-Right position (a axis) │ │ - Angle around wheel (Hue) - Up-Down position (b axis) │ │ - Height (Lightness) - Height (Lightness) │ │ │ │ Hue angle +b (yellow) │ │ / │ │ │ ______/______ │ │ │ / @ \ │ │ │ │ Chroma │ -a ────┬───────┼───────┬──── +a │ │ \ radius / (green)│ │ │(red) │ │ \__________/ │ │ │ │ │ │ │ -b (blue) │ │ │ │ BEST FOR: BEST FOR: │ │ - Defining colors (hue angle) - Smooth transitions │ │ - User parameters (degrees) - Gradient calculations │ │ - Identity operations - Preventing muddy colors │ │ │ │ Used in: Frame Drag, Einstein Arc Used in: Caustic gradient fill │ │ (outside zone) (inside zone) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` *** ## The Four Parameter Groups The Tint System is controlled by four groups of parameters. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ FOUR PARAMETER GROUPS │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────┐ ┌───────────────────────────┐ │ │ │ GROUP 1: TINT │ │ GROUP 2: ANCHOR │ │ │ │ (Global Color Overlay) │ │ (Theme Identity) │ │ │ ├───────────────────────────┤ ├───────────────────────────┤ │ │ │ │ │ │ │ │ │ tintHue: 250 deg │ │ darkAnchorHue: 250 deg │ │ │ │ (What color to blend) │ │ (Theme's "home" color) │ │ │ │ │ │ │ │ │ │ tintStrength: 10% │ │ darkAnchorChroma: 0.02 │ │ │ │ (How much to blend) │ │ (Background saturation) │ │ │ │ │ │ │ │ │ │ tintChroma: 0.02 │ └───────────────────────────┘ │ │ │ (Tint saturation) │ │ │ └───────────────────────────┘ │ │ │ │ ┌───────────────────────────┐ ┌───────────────────────────┐ │ │ │ GROUP 3: ARC │ │ GROUP 4: INHERIT │ │ │ │ (Einstein Arc Settings) │ │ (Hue Inheritance) │ │ │ ├───────────────────────────┤ ├───────────────────────────┤ │ │ │ │ │ │ │ │ │ causticComplementary: │ │ bgHueInherit: 80% │ │ │ │ 60 deg (offset from │ │ (Background gets theme) │ │ │ │ complementary color) │ │ │ │ │ │ │ │ textHueInherit: 100% │ │ │ │ causticWidth: 90 deg │ │ (Text fully themed) │ │ │ │ (Size of Caustic zone) │ │ │ │ │ │ │ │ ansiHueInherit: 8% │ │ │ │ causticStrength: 10% │ │ (ANSI colors preserved) │ │ │ │ (Compression intensity) │ │ │ │ │ │ │ └───────────────────────────┘ │ │ │ causticMode: 2 │ │ │ │ (Algorithm selection) │ │ │ └───────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` *** ## Performance Architecture Color transforms happen thousands of times per second. Caching makes this fast. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ PERFORMANCE ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ THEME LOAD (happens once when you switch themes) │ │ ================================================ │ │ │ │ User Parameters Precomputed Cache │ │ (degrees, %) --> (radians, ratios) │ │ │ │ tintHue: 250 deg --> tint_hue: 4.36 rad │ │ tintStrength: 10% --> tint_strength: 0.10 │ │ causticWidth: 90 deg --> caustic_width: 1.57 rad │ │ │ │ Time: ~10ms (one-time cost) │ │ │ │ COLOR TRANSFORM (happens for every color) │ │ ========================================= │ │ │ │ Input Color │ │ │ │ │ v │ │ ┌────────────────┐ │ │ │ Check Cache │────-> HIT: Return cached result (<0.1 us) │ │ └───────┬────────┘ │ │ │ │ │ v MISS │ │ ┌────────────────┐ │ │ │ Compute │────-> Store in cache │ │ │ Transform │ │ │ └────────────────┘ │ │ │ │ │ v │ │ Output Color (~1 us) │ │ │ │ Cache: 1024 recent colors (LRU eviction) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` *** ## Data Flow Example Watch a color transform step by step. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ TRANSFORMING #FF5733 (BRIGHT ORANGE) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ INPUT: #FF5733 │ │ │ │ Step 1: RGB to OKLAB │ │ #FF5733 --> L=0.68, a=0.18, b=0.14 │ │ (Bright, red-ish, yellow-ish) │ │ │ │ Step 2: OKLAB to OKLCH │ │ L=0.68, a=0.18, b=0.14 --> L=0.68, C=0.23, H=38 deg │ │ (Brightness, Saturation, Orange-red hue) │ │ │ │ Step 3: Lightness Mapping │ │ L=0.68 --> L=0.65 │ │ (Slightly darker for theme contrast) │ │ │ │ Step 4: Chroma Scaling │ │ C=0.23 --> C=0.19 │ │ (Reduced saturation for harmony) │ │ │ │ Step 5: Frame Drag (tint toward blue 250 deg at 10%) │ │ H=38 deg --> H=36 deg │ │ (Slight shift toward theme's blue tint) │ │ │ │ Step 6: Einstein Arc │ │ H=36 deg is OUTSIDE Caustic zone --> H=32 deg │ │ (Expanded slightly as zone compressed) │ │ │ │ Step 7: Output │ │ L=0.65, C=0.19, H=32 deg --> #E07055 │ │ │ │ OUTPUT: #E07055 (Theme-harmonized coral) │ │ │ │ Visual comparison: │ │ Before: [#FF5733] Bright, sharp orange │ │ After: [#E07055] Softer, theme-matched coral │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` *** ## Key Takeaways 1. **Colors transform in real-time** - Every terminal color passes through the 7-step pipeline 2. **Physics metaphors explain behavior** - Frame Drag pulls colors toward tint, Einstein Arc bends colors around anchor 3. **Two coordinate systems work together** - Polar (OKLCH) for identity, Cartesian (OKLAB) for smooth transitions 4. **Parameters are human-friendly** - Degrees and percentages, not radians and decimals 5. **Caching ensures performance** - Less than 1 microsecond per cached transform *** Learn about the four parameter groups