yazi-gruvbox/README.md

yazi-gruvbox

A Gruvbox Dark theme.toml for Yazi — including the icon table, so the devicons in front of your files stop looking like a paint spill on an otherwise muted colour scheme.

Written against Yazi 26.9. It uses the current schema ([mgr], [tabs], [pick], [cmp], [indicator], …), not the pre-25.x one — older Gruvbox themes floating around still use [manager] and [select] and will throw errors on a current Yazi.

What it covers

Panel chrome, status bar, tabs, mode indicator, which-key, confirm/spot/notify popups, picker, input, completion, task manager, help — plus:

File and directory names ([filetype]):

directories	#83a598 blue
regular files	#ebdbb2 fg1
executables	#b8bb26 green
archives	#fe8019 orange
images	#fabd2f yellow
audio / video	#d3869b purple
PDF / doc	#8ec07c aqua
orphan symlinks	red background

Icons ([icon]): all 725 entries of Yazi's preset table, every glyph colour remapped to its nearest Gruvbox tone.

Syntax highlighting (gruvbox-dark.tmTheme): 39 scope rules for the file preview, written from scratch against morhetz/gruvbox's own vim highlight links — comments gray italic, strings green, constants purple, keywords red, identifiers blue, functions green bold, types yellow, preprocessor aqua, operators plain foreground.

How the icon colours were derived

Yazi's preset ships 725 icon entries using 221 distinct colours from the nvim-tree/devicons palette — saturated web colours that clash badly with Gruvbox's muted ground.

regen-icons.py maps each of them onto the Gruvbox palette:

• Nearest neighbour in Oklab, so the match is perceptual rather than a naive RGB distance.
• Lightness weighted down (0.7) in the distance metric, so hue drives the result. Docker blue stays blue, Ruby red stays red, instead of everything collapsing toward whatever tone happens to be equally bright.
• Chromatic and greyish sources are matched from separate pools (split at Oklab chroma 0.04). Without that split a vivid magenta can land on grey, and white can land on orange.
• Low-contrast targets are excluded. #cc241d (2.69:1) and #7c6f64 (3.03:1) on #282828 were dropped from the target palette — icons are non-text, so 3:1 is the bar. The dimmest icon now sits at 3.48:1.

221 colours end up on 19 Gruvbox tones. Icons stay colourful and stay distinguishable; they just stop shouting.

Install

git clone https://git.opennerds.org/templis/yazi-gruvbox
cp yazi-gruvbox/theme.toml yazi-gruvbox/gruvbox-dark.tmTheme ~/.config/yazi/

theme.toml overrides Yazi's built-in theme-dark.toml; anything it does not set keeps the default.

Both files are needed — theme.toml points at the .tmTheme for syntax highlighting in file previews.

Keeping the icon table current

The [icon] block replaces Yazi's preset table wholesale. Icons added by later Yazi releases will not show up until it is regenerated:

git clone --depth 1 https://github.com/sxyazi/yazi
awk '/^\[icon\]/{f=1} f' yazi/yazi-config/preset/theme-dark.toml > icons-src.toml
./regen-icons.py icons-src.toml      # writes icon-gruvbox.toml

Then replace the [icon] block in theme.toml with the generated file. The script prints which Gruvbox tone each source colour landed on.

regen-tmtheme.py does the same for gruvbox-dark.tmTheme — edit the palette or the scope rules at the top of the script and re-run it.

Self-contained

Everything needed is in this repository — nothing has to be fetched from a third-party theme repo, and no file here carries a copyleft licence.

Licence

MIT — see LICENSE. The .tmTheme is original work; the derived icon data is MIT as well. Notices in THIRD-PARTY.md.