The Best Theme Isn’t the Prettiest—It’s the One You Forget Exists

Dec 24, 2025    #neovim   #color-science   #vision-research   #oklab  

Over the past few years, I’ve created numerous Neovim color schemes. My workflow was always the same: pick an existing theme, adjust its colors in HSL space until they felt comfortable, and use it for a while. But invariably, after several weeks or months, the same pattern emerged—visual fatigue. My eyes would tire faster during long coding sessions, colors that once felt “right” started to irritate, and I’d find myself tweaking values again and again.

The cycle was frustrating: find theme → adjust → use → fatigue → repeat. Each iteration felt arbitrary. I was working blind, relying purely on subjective perception without understanding why certain colors caused fatigue and others didn’t.

This is the story of how I broke that cycle by building a color scheme from scientific first principles.

The Insight: Color Science Exists for a Reason

The breakthrough came when I realized: vision scientists have spent decades studying exactly these problems. Research exists on:

Instead of adjusting colors arbitrarily in HSL space, I could derive them from scientific principles.

Foundation 1: Perceptual Color Spaces

The Problem with RGB and HSL

RGB and HSL are convenient for computers but terrible for human perception. In RGB, the distance between #FF0000 (red) and #FF0011 (slightly different red) has no relationship to how different they appear to our eyes. HSL is better but still suffers from perceptual non-uniformity.

Enter Oklab

Oklab [1] is a perceptually uniform color space designed by Björn Ottosson. In Oklab:

The transformation from Oklab to RGB involves four steps:

Step 1: Oklab → LMS (cone response)

[lms]=[10.39630.21581−0.1056−0.06391−0.0895−1.2915][Lab] \begin{bmatrix} l \\ m \\ s \end{bmatrix} = \begin{bmatrix} 1 & 0.3963 & 0.2158 \\ 1 & -0.1056 & -0.0639 \\ 1 & -0.0895 & -1.2915 \end{bmatrix} \begin{bmatrix} L \\ a \\ b \end{bmatrix}

Step 2: Inverse cube root

LMSlinear=[l3,m3,s3]T \text{LMS}_{\text{linear}} = [l^3, m^3, s^3]^T

Step 3: LMS → Linear RGB

[RGB]=[4.0767−3.30770.2310−1.26842.6098−0.3413−0.0042−0.70341.7076][l3m3s3] \begin{bmatrix} R \\ G \\ B \end{bmatrix} = \begin{bmatrix} 4.0767 & -3.3077 & 0.2310 \\ -1.2684 & 2.6098 & -0.3413 \\ -0.0042 & -0.7034 & 1.7076 \end{bmatrix} \begin{bmatrix} l^3 \\ m^3 \\ s^3 \end{bmatrix}

Step 4: Gamma correction (sRGB)

CsRGB={12.92×Clinearif Clinear≤0.00313081.055×Clinear1/2.4−0.055otherwise C_{\text{sRGB}} = \begin{cases} 12.92 \times C_{\text{linear}} & \text{if } C_{\text{linear}} \leq 0.0031308 \\ 1.055 \times C_{\text{linear}}^{1/2.4} - 0.055 & \text{otherwise} \end{cases}

Implementation in Lua

local function oklab_to_linear_rgb(L, a, b)
  -- Step 1: Oklab to LMS
  local l = L + 0.3963377774 * a + 0.2158037573 * b
  local m = L - 0.1055613458 * a - 0.0638541728 * b
  local s = L - 0.0894841775 * a - 1.2914855480 * b
  
  -- Step 2: Inverse cube root
  local l3, m3, s3 = l * l * l, m * m * m, s * s * s
  
  -- Step 3: LMS to linear RGB
  local r = 4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3
  local g = -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3
  local b_out = -0.0041960863 * l3 - 0.7034186147 * m3 + 1.7076147010 * s3
  
  return r, g, b_out
end

local function linear_to_srgb_component(c)
  -- Step 4: Gamma correction
  if c <= 0.0031308 then
    return c * 12.92
  else
    return 1.055 * (c ^ (1 / 2.4)) - 0.055
  end
end

local function oklab_to_srgb(L, a, b)
  local r, g, b_comp = oklab_to_linear_rgb(L, a, b)
  
  r = linear_to_srgb_component(r)
  g = linear_to_srgb_component(g)
  b_comp = linear_to_srgb_component(b_comp)
  
  -- Clamp and convert to 8-bit
  r = math.floor(math.max(0, math.min(1, r)) * 255 + 0.5)
  g = math.floor(math.max(0, math.min(1, g)) * 255 + 0.5)
  b_comp = math.floor(math.max(0, math.min(1, b_comp)) * 255 + 0.5)
  
  return string.format('#%02x%02x%02x', r, g, b_comp)
end

Now I can specify colors as perceptual properties rather than hex codes:

-- Instead of: local orange = "#c5895b"
-- I write:
local orange = oklab_to_srgb(0.68, 0.055, 0.065)

The formula is the color. No more arbitrary hex values.

Foundation 2: What to Highlight - Empirical Research

Before deciding how to color code elements, I needed to understand which elements should be highlighted at all.

Hannebauer et al. (2018): The Surprising Truth About Syntax Highlighting

A study with 390 programming novices [7] found something surprising:

“Syntax highlighting has no significant effect on code comprehension or correctness”

But the study revealed a crucial insight: highlighting does help when it emphasizes structural elements rather than coloring everything equally. The key principle:

Highlight structure, minimize noise.

Tonsky (2025): The Neutral Variables Principle

Ivan Tonsky’s analysis revealed why most themes feel noisy:

“Your code is mostly references to variables and method invocation. If we highlight those, we’ll have to highlight more than 75% of your code.”

His recommendation: Keep variables and operators neutral (same color as regular text). Only highlight structural elements.

From Research to Design Decisions

These findings led to my core highlighting strategy:

  1. Highlight (bright colors):

    • Control flow keywords (if, for, while, return)
    • Function definitions
    • Type declarations

  2. Keep neutral (regular text color):

    • Variable names
    • Operators
    • Function parameters

  3. Dim (lower luminance):

    • Comments
    • Delimiters

This creates a visual hierarchy where code structure “pops” while the majority of text remains calm.

Foundation 3: Contrast Sensitivity Function (CSF)

The human visual system doesn’t respond uniformly to all contrasts. Barten’s CSF model [2] reveals that we are 5-10× more sensitive to luminance contrast than chromatic contrast.

Key Insight: Luminance Hierarchy Matters More Than Hue

This was the game-changer. Instead of asking “should keywords be orange or yellow?”, I should ask “should keywords be brighter than data?”

Deriving the Three-Layer Luminance Hierarchy

I needed to design a luminance hierarchy that satisfies:

  1. CSF comfort threshold: ΔL≥0.02\Delta L \geq 0.02 for comfortable discrimination
  2. WCAG accessibility: Adequate contrast ratios with background
  3. Perceptual distinctness: Each layer feels clearly different

Starting constraints:

Background: Lbg=0.24L_{\text{bg}} = 0.24 (dark theme, reduces eye strain) Foreground: Lfg=0.74L_{\text{fg}} = 0.74 (7.0:1 contrast, WCAG AAA)

Layer assignment based on Hannebauer (2018):

Calculating optimal luminance values:

The total usable luminance range is: Lfg−Lbg=0.74−0.24=0.50L_{\text{fg}} - L_{\text{bg}} = 0.74 - 0.24 = 0.50

For syntax colors, I reserved the upper portion of this range to maintain sufficient contrast with background. Working backwards from foreground:

Lreserve=0.06 (headroom from foreground)Lmax_syntax=0.74−0.06=0.68 \begin{aligned} L_{\text{reserve}} &= 0.06 \text{ (headroom from foreground)} \\ L_{\text{max\_syntax}} &= 0.74 - 0.06 = 0.68 \end{aligned}

Now applying the CSF minimum threshold ΔL=0.02\Delta L = 0.02:

Layer 1 (Structure):L1=0.68Layer 2 (Diagnostics):L2=L1−0.02=0.66Layer 3 (Data):L3=L2−0.02=0.64 \begin{aligned} \text{Layer 1 (Structure):} &\quad L_1 = 0.68 \\ \text{Layer 2 (Diagnostics):} &\quad L_2 = L_1 - 0.02 = 0.66 \\ \text{Layer 3 (Data):} &\quad L_3 = L_2 - 0.02 = 0.64 \end{aligned}

Verification against WCAG:

Using the contrast ratio formula CR=L1+0.05L2+0.05\text{CR} = \frac{L_1 + 0.05}{L_2 + 0.05}:

CR(L1,Lbg)=0.68+0.050.24+0.05=5.52:1(AA)CR(L2,Lbg)=0.66+0.050.24+0.05=5.03:1(AA)CR(L3,Lbg)=0.64+0.050.24+0.05=4.76:1(AA) \begin{aligned} \text{CR}(L_1, L_{\text{bg}}) &= \frac{0.68 + 0.05}{0.24 + 0.05} = 5.52:1 \quad \text{(AA)} \\ \text{CR}(L_2, L_{\text{bg}}) &= \frac{0.66 + 0.05}{0.24 + 0.05} = 5.03:1 \quad \text{(AA)} \\ \text{CR}(L_3, L_{\text{bg}}) &= \frac{0.64 + 0.05}{0.24 + 0.05} = 4.76:1 \quad \text{(AA)} \end{aligned}

All three layers meet WCAG AA standards while maintaining ΔL=0.02\Delta L = 0.02 separation.

Why this matters: In my old themes, I had errors (L=0.64L=0.64) at the same brightness as strings. Errors weren’t visually salient! Now errors are a distinct layer (L=0.66L=0.66), immediately noticeable but not overwhelming.

Perceptual validation:

The 3-layer system creates three distinct “brightness tiers”:

This matches the importance hierarchy from Hannebauer’s research: structure > errors > data.

Summary: The CSF-Optimized Luminance Hierarchy

LayerLuminanceElementsRationale
1L=0.68L=0.68Keywords, Functions, TypesHighest importance for comprehension
2L=0.66L=0.66Errors, DiagnosticsNeed prominence, not dominance
3L=0.64L=0.64Strings, Numbers, ConstantsSecondary to structure
-L=0.24L=0.24BackgroundLow strain for long sessions
-L=0.74L=0.74Foreground text7.0:1 contrast (AAA)

Key properties:

Foundation 4: CIECAM02 Color Appearance Model

CIECAM02 [3] helps us understand how colors appear under different viewing conditions. The simplified chroma calculation is:

C≈100×s×J C \approx 100 \times s \times \sqrt{J}

where ss is saturation and JJ is lightness (0-100 scale).

For comfortable long-term viewing, chroma should be in the range [30, 100]. This constrains our saturation:

s=C100×J s = \frac{C}{100 \times \sqrt{J}}

For L≈0.65L \approx 0.65 (corresponding to J≈65J \approx 65):

srecommended=65100×65≈0.081 s_{\text{recommended}} = \frac{65}{100 \times \sqrt{65}} \approx 0.081

This gives us the target saturation range: s∈[0.06,0.12]s \in [0.06, 0.12].

Hue Discrimination

CIECAM02 also tells us that for low-saturation colors, we need a minimum hue separation:

Δh≥20° to 25° \Delta h \geq 20° \text{ to } 25°

I verified all adjacent hues meet this:

Red (27°) → Orange (50°): Δh = 23° ✓
Orange (50°) → Yellow (76°): Δh = 26° ✓
Yellow (76°) → Green (130°): Δh = 54° ✓
Green (130°) → Cyan (190°): Δh = 60° ✓
Cyan (190°) → Blue (252°): Δh = 62° ✓
Blue (252°) → Violet (321°): Δh = 69° ✓

Foundation 5: Color Fatigue Research

A chromatic pupillometry study [4] found that different wavelengths cause different levels of visual fatigue:

The study recommends:

syellow/green<0.10sred<0.09saverage≈0.08 (for 8+ hour sessions) \begin{aligned} s_{\text{yellow/green}} &< 0.10 \\ s_{\text{red}} &< 0.09 \\ s_{\text{average}} &\approx 0.08 \text{ (for 8+ hour sessions)} \end{aligned}

Saturation Calculation

In Oklab, saturation is:

s=a2+b2 s = \sqrt{a^2 + b^2}

For our colors:

-- Orange: s = √(0.055² + 0.065²) ≈ 0.085 ✓
colors.orange = oklab_to_srgb(0.68, 0.055, 0.065)

-- Red: s = √(0.08² + 0.04²) ≈ 0.089 ✓ (just under 0.09 limit)
colors.red = oklab_to_srgb(0.66, 0.08, 0.04)

-- Yellow: s = √(0.02² + 0.08²) ≈ 0.082 ✓
colors.yellow = oklab_to_srgb(0.68, 0.02, 0.08)

All saturations are in the low-fatigue zone.

Foundation 6: Color Semantics

Karen Schloss’s research [5] on color semantics reveals universal color-concept associations:

Deriving the AST Token → Color Mapping

Here’s how I mapped semantic concepts to code elements using color theory:

Step 1: Identify code semantic categories

From TreeSitter and LSP semantic tokens, code elements fall into these categories:

  1. Control/Flow - Elements that change execution path
  2. Behavior - Functions and actions
  3. Structure - Type definitions and declarations
  4. Data - Literal values (strings, numbers)
  5. Meta - Compile-time constructs (macros, imports)
  6. Errors - Diagnostic information

Step 2: Map to universal color semantics (Schloss 2023)

Code CategorySemantic PropertyColor AssociationChosen Color
Control/FlowAction, DynamicWarm colors (orange/red)Orange
BehaviorLogic, StabilityCool colors (blue)Blue
StructureImportant, DefineHigh visibility (yellow)Yellow
Data (strings)Content, NaturalGrowth (green)Green
Data (numbers)AbstractNeutral (violet)Violet
MetaFrozen, TechnicalCold (cyan)Cyan
ErrorsDangerUniversal danger (red)Red

Step 3: Apply luminance hierarchy

Not all categories are equally important. Based on CSF theory and Hannebauer’s research:

Priority 1 (L=0.68L=0.68): Structure elements guide understanding

Priority 2 (L=0.66L=0.66): Errors need attention but shouldn’t dominate

Priority 3 (L=0.64L=0.64): Data is secondary to structure

Step 4: Calculate precise Oklab coordinates

For each color, I needed to satisfy:

  1. Correct hue (from color semantics)
  2. Correct luminance (from CSF hierarchy)
  3. Safe saturation (from fatigue research)
  4. Sufficient hue separation (from CIECAM02)

Example for Orange (keywords):

Converting hue to Oklab a,ba, b coordinates:

a=s×cos⁡(h×π/180)b=s×sin⁡(h×π/180) \begin{aligned} a &= s \times \cos(h \times \pi / 180) \\ b &= s \times \sin(h \times \pi / 180) \end{aligned}

For h=50°,s=0.085h = 50°, s = 0.085:

a=0.085×cos⁡(50°)≈0.055b=0.085×sin⁡(50°)≈0.065 \begin{aligned} a &= 0.085 \times \cos(50°) \approx 0.055 \\ b &= 0.085 \times \sin(50°) \approx 0.065 \end{aligned}

Therefore: colors.orange = oklab_to_srgb(0.68, 0.055, 0.065)

I repeated this process for all seven colors, ensuring:

Complete Implementation

Here’s the final color palette definition:

local colors = {}

-- Background (neutral, minimal chroma)
colors.bg = oklab_to_srgb(0.24, 0.001, 0.006)
colors.fg = oklab_to_srgb(0.74, 0.0, 0.008)

-- Layer 1: Core Structure (L=0.68)
colors.orange = oklab_to_srgb(0.68, 0.055, 0.065)  -- Keywords
colors.blue   = oklab_to_srgb(0.68, -0.02, -0.06)  -- Functions
colors.yellow = oklab_to_srgb(0.68, 0.02,  0.08)   -- Types

-- Layer 2: Diagnostics (L=0.66)
colors.red    = oklab_to_srgb(0.66, 0.08,  0.04)   -- Errors

-- Layer 3: Data (L=0.64)
colors.green  = oklab_to_srgb(0.64, -0.05, 0.06)   -- Strings
colors.cyan   = oklab_to_srgb(0.64, -0.055, -0.01) -- Constants
colors.violet = oklab_to_srgb(0.64, 0.05, -0.04)   -- Numbers

return colors

And the highlight group mappings that follow the research:

-- HIGH PRIORITY: Structure (bright, L=0.68)
vim.api.nvim_set_hl(0, 'Keyword', { fg = colors.orange })      -- Control flow
vim.api.nvim_set_hl(0, 'Function', { fg = colors.blue })       -- Behavior
vim.api.nvim_set_hl(0, 'Type', { fg = colors.yellow })         -- Definitions

-- LOW PRIORITY: Data (dimmer, L=0.64)
vim.api.nvim_set_hl(0, 'String', { fg = colors.green })
vim.api.nvim_set_hl(0, 'Constant', { fg = colors.cyan })
vim.api.nvim_set_hl(0, 'Number', { fg = colors.violet })

-- NEUTRAL: Variables and operators (same as foreground)
vim.api.nvim_set_hl(0, 'Identifier', { fg = colors.fg })
vim.api.nvim_set_hl(0, 'Operator', { fg = colors.fg })

Every value is derived from formulas, not arbitrary hex codes. Every mapping decision is backed by research.

Results

I named it Retina a scientifically optimized colorscheme for human vision.

Screenshot of the theme in action - Neovim editing C code

C code showing the luminance hierarchy in action. Keywords (orange, L=0.68L=0.68) pop more than strings (green, L=0.64L=0.64). Errors (red, L=0.66L=0.66) are immediately visible.

After using this theme for 2 months, the difference is remarkable:

Individual Differences: A Note of Caution

It’s crucial to understand that vision is deeply personal. This theme was optimized for:

Your mileage may vary. Factors that affect color perception:

  1. Age: Older adults need higher contrast [6]
  2. Display technology: OLED vs LCD affects color appearance
  3. Ambient light: Outdoor vs indoor viewing
  4. Individual differences: Color deficiency affects ~8% of males

How to Adapt This for Yourself

The beauty of the formula-based approach is that you can adjust the parameters rather than tweaking hex codes:

-- Want more contrast? Increase background-structure ΔL:
colors.orange = oklab_to_srgb(0.70, 0.055, 0.065)  -- was 0.68

-- Want lower saturation? Scale the a,b values:
colors.orange = oklab_to_srgb(0.68, 0.044, 0.052)  -- was (0.055, 0.065)

-- Want warmer tones? Shift hue by adjusting a,b ratio:
colors.orange = oklab_to_srgb(0.68, 0.050, 0.070)  -- more yellow

The formulas remain the foundation; you adjust coefficients rather than guessing hex values.

Summary and Takeaways

What started as frustration with arbitrary theme tweaking led to a systematic, science-based approach:

  1. Use perceptually uniform color spaces (Oklab) for predictable color manipulation
  2. Prioritize luminance hierarchy (CSF Theory) over hue differences
  3. Control saturation carefully (Color Fatigue research) for long-term comfort
  4. Respect perceptual thresholds (CIECAM02) for hue discrimination
  5. Align with semantic expectations (Color Semantics) for intuitive understanding
  6. Highlight structure, not noise (Hannebauer, Tonsky) for clarity

I hope this approach helps others escape the arbitrary theme-tweaking trap. The science exists—we might as well use it.

References

[1] Ottosson, B. (2020). A perceptual color space for image processing. https://bottosson.github.io/posts/oklab/

[2] Barten, P. G. J. (1999). Contrast sensitivity of the human eye and its effects on image quality. SPIE Press.

[3] Fairchild, M. D. (2013). Color appearance models (3rd ed.). John Wiley & Sons.

[4] Cao, T., Zhang, M., Jiang, Y., Lu, C., & Xu, Y. (2024). Effects of exposure to different light wavelengths on human eye fatigue. PMC, 11175232. https://www.ncbi.nlm.nih.gov/pmc/articles/PMC11175232/

[5] Schloss, K. B., & Palmer, S. E. (2024). Color semantics for visual communication. Annual Review of Vision Science, 10, 1-25.

[6] Owsley, C. (2016). Vision and aging. Annual Review of Vision Science, 2, 255-271.

[7] Hannebauer, C., Hesenius, M., & Gruhn, V. (2018). Does syntax highlighting help programming novices? Empirical Software Engineering, 23(5), 2795-2828.

Additional references:

The complete theme is available at here. Contributions and adaptations welcome.