Make dim terminal text and editor comments readable on low-contrast themes
The cause holds. foot.ini.tpl maps regular0 to background_strip and bright0 to muted_strip, ghostty.conf.tpl has palette = 0={{ background }} and palette = 8={{ muted }}, kitty.conf.tpl has color0 background and color8 muted, and alacritty.toml.tpl has black = background in normal and black = muted in bright. neovim.lua.tpl passes muted to aether.nvim v3, whose base.lua sets Comment and LineNr to c.muted. ~/.config/nvim/plugin/after/transparency.lua clears Normal. Recomputing WCAG contrast of muted against background for all 22 stock themes reproduced every quoted figure (matte-black and rose-pine 1.48, everforest 1.55, hackerman 1.59, lumon 1.68, nord 1.69, tokyo-night 1.91, and only white 3.95, vantablack 4.89 and ethereal 4.90 at 3:1 or above). Issue #12520 is open and describes the same mechanism. The fix has a side effect it does not mention. omarchy-theme-dir prefers ~/.config/omarchy/themes/<name> whenever that directory exists, and omarchy-plymouth-list keeps a theme only if that directory has preview-unlock.png. An overlay holding only colors.toml therefore removes the stock theme from Style > Unlock, and omarchy-plymouth-set-by-theme then fails with Logo file not found. The corrected fix copies unlock.png and preview-unlock.png into the overlay. It also replaces the hand-picked placeholder #7a83a8 with a computed value that reaches 3:1 by mixing muted toward foreground, and it notes that the overlay pins that theme's colors.toml. The overlay steps and the picker were dry-run in a temporary directory, and the picker gives 3:1 values for five stock themes. Not exercised: an actual theme set.
Symptom
In the terminal, shell autosuggestions, ls and git output in dark grey, and anything printed in ANSI black are invisible or barely visible. In Neovim, comments and line numbers vanish until the cursor line passes over them. printf '\e[30mregular0\e[0m \e[90mbright0\e[0m\n' prints one word I cannot see at all and one I can barely read. It happens on stock themes such as Matte Black, Everforest and Hackerman, and badly on some community themes.
Cause
All four terminal templates map ANSI colour 0 (black) to the theme background and colour 8 (bright black) to the theme's muted colour: regular0={{ background_strip }} and bright0={{ muted_strip }} in foot.ini.tpl, palette = 0={{ background }} and palette = 8={{ muted }} in ghostty.conf.tpl, color0/color8 in kitty.conf.tpl, and black in both sections of alacritty.toml.tpl. So text in colour 0 is exactly the background colour, and dim text depends entirely on how far muted is from background. The Neovim template passes muted to aether.nvim as the Comment colour, and Omarchy's transparency plugin clears the Normal background, so comments sit directly on the terminal background. Only CursorLine, which keeps a background, lifts them.
Measured on the 4.0.4 stock themes (WCAG contrast of muted against background): Matte Black and Rose Pine 1.48:1, Everforest 1.55:1, Hackerman 1.59:1, Lumon 1.68:1, Nord 1.69:1, Tokyo Night 1.91:1. Only Ethereal, Vantablack and White reach 3:1. The community theme in #12520 measured about 1.5:1.
Fix
Measure the current theme first:
python3 - "$(omarchy-theme-color background)" "$(omarchy-theme-color muted)" <<'EOF'
import sys
def L(h):
c=[int(h.lstrip('#')[i:i+2],16)/255 for i in (0,2,4)]
c=[x/12.92 if x<=0.03928 else ((x+0.055)/1.055)**2.4 for x in c]
return 0.2126*c[0]+0.7152*c[1]+0.0722*c[2]
a,b=sorted([L(sys.argv[1]),L(sys.argv[2])])
print(f"muted contrast {(b+0.05)/(a+0.05):.2f}:1")
EOF
Raise muted with a theme overlay. A directory under ~/.config/omarchy/themes/ with the same name as a stock theme is copied on top of the stock theme at theme-set time. Omarchy's Unlock (boot splash) commands also look in that directory first and need unlock.png and preview-unlock.png there, so copy those two images along with colors.toml, or the theme drops out of Style > Unlock. This picks the first value between the current muted and foreground that reaches 3:1:
t=$(cat ~/.local/state/omarchy/current/theme.name)
src=/usr/share/omarchy/themes/$t
dst=~/.config/omarchy/themes/$t
mkdir -p "$dst"
cp "$src/colors.toml" "$src/unlock.png" "$src/preview-unlock.png" "$dst/"
new=$(python3 - "$(omarchy-theme-color background)" "$(omarchy-theme-color muted)" "$(omarchy-theme-color foreground)" <<'EOF'
import sys
bg, muted, fg = (h.lstrip('#') for h in sys.argv[1:4])
def rgb(h): return [int(h[i:i+2], 16) for i in (0, 2, 4)]
def L(h):
c = [x / 255 for x in rgb(h)]
c = [x / 12.92 if x <= 0.03928 else ((x + 0.055) / 1.055) ** 2.4 for x in c]
return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]
def ratio(a, b):
a, b = sorted([L(a), L(b)])
return (b + 0.05) / (a + 0.05)
def mix(a, b, t):
return ''.join(f'{round(x * (1 - t) + y * t):02x}' for x, y in zip(rgb(a), rgb(b)))
for step in range(101):
cand = mix(muted, fg, step / 100)
if ratio(bg, cand) >= 3.0:
print(f'#{cand}')
break
else:
sys.exit('foreground itself is below 3:1, pick muted by hand')
EOF
)
echo "new muted: $new"
sed -i "s/^muted = .*/muted = \"$new\"/" "$dst/colors.toml"
grep '^muted' "$dst/colors.toml"
omarchy theme set "$t"
That fixes bright black in all four terminals and Neovim comments in one place. muted is also used by the shell surfaces, so expect slightly brighter secondary text in the bar and menus. The overlay pins this theme's colors.toml, so later upstream changes to the stock palette do not reach it. To undo, remove the overlay and set the theme again:
rm -r ~/.config/omarchy/themes/"$t"
omarchy theme set "$t"
To stop colour 0 matching the background exactly, override the terminal templates. For Foot:
mkdir -p ~/.config/omarchy/themed
sed 's/^regular0=.*/regular0={{ muted_strip }}/' /usr/share/omarchy/default/themed/foot.ini.tpl > ~/.config/omarchy/themed/foot.ini.tpl
omarchy theme set "$(cat ~/.local/state/omarchy/current/theme.name)"
Do the same for whichever of ghostty.conf.tpl (palette = 0=), kitty.conf.tpl (color0) and alacritty.toml.tpl (the first black =) you use. If you already keep a user foot.ini.tpl, edit that one rather than overwriting it.
Verify
The contrast script prints 3:1 or higher, the printf test shows both words, comments in nvim are readable on lines the cursor is not on, and omarchy-plymouth-list still lists the theme.
Sources
- https://github.com/omacom/omarchy/issues/12520
- https://github.com/omacom/omarchy/blob/quattro/default/themed/foot.ini.tpl
- https://github.com/omacom/omarchy/blob/quattro/default/themed/kitty.conf.tpl
- https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-set-templates
- https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-plymouth-list