repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs: design yazi nugu dotfiles config

616f345ec6b8f0ccc14b8d91658ec9c44949f9d9

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/superpowers/specs/2026-05-30-yazi-nugu-dotfiles-design.md

Added
new file mode 100644
1 +# Yazi Nugu dotfiles design
3 +Date: 2026-05-30
5 +## Goal
7 +Make Yazi a first-class, dotfiles-managed terminal file manager configuration that uses the personal Nugu theme and integrates tastefully with existing tools. The result should feel native to the rest of the dotfiles without turning Yazi into a large plugin project.
9 +## Non-goals
11 +- Do not vendor third-party plugin repositories into dotfiles.
12 +- Do not add bookmarks or session/autosession plugins.
13 +- Do not replace Yazi defaults wholesale.
14 +- Do not add a Space leader layer; keep Space for selection.
15 +- Do not implement Jujutsu (`jj`) Yazi plugin support in v1.
16 +- Do not add heavyweight statusline alternatives beyond the chosen minimal statusline plugin.
18 +## Current context
20 +- Live Yazi config currently lives in `~/.config/yazi` and contains only:
21 + - `theme.toml`, selecting the `noctalia` flavor.
22 + - `flavors/noctalia.yazi/flavor.toml`.
23 +- Dotfiles do not currently manage `~/.config/yazi`.
24 +- Nugu already provides generated themes for Ghostty, Helix, and WezTerm.
25 +- Existing dotfiles favor declarative config, Nushell automation, generated theme artifacts, and symlink manifests.
26 +- Relevant available tools include `nvim`, `git`, `jj`, `glow`, `bat`, `mpv`, `wl-copy`, `fzf`, `zoxide`, `fd`, `rg`, `jq`, `7z`, `ffmpeg`, `magick`, `resvg`, `pdftoppm`, `ouch`, and `hexyl`.
28 +## Architecture
30 +### Dotfiles ownership
32 +Create a new `yazi/` directory in the dotfiles repository. It will be symlinked to `~/.config/yazi` through the host symlink manifests, consistent with other applications.
34 +Planned files:
36 +```text
37 +yazi/
38 +├── theme.toml
39 +├── yazi.toml
40 +├── keymap.toml
41 +├── init.lua
42 +├── package.toml
43 +└── flavors/
44 + ├── nugu-dark.yazi/
45 + │ └── flavor.toml
46 + └── nugu-light.yazi/
47 + └── flavor.toml
48 +```
50 +The symlink manifest should map:
52 +```text
53 +yazi
54 +~/.config/yazi
55 +```
57 +Linux desktop host manifests should receive this mapping: `desktop.symlinks`, `fedora.symlinks`, and `x230.symlinks`. `termux.symlinks` and Windows manifests can be added later if Yazi is used there.
59 +### Plugin package hygiene
61 +Yazi plugins will be managed with `ya pkg`. The committed source of truth is `yazi/package.toml`, not the installed plugin directories.
63 +- Commit `package.toml`.
64 +- Ignore `yazi/plugins/`.
65 +- Do not vendor plugin repositories.
66 +- Restore plugins on a new machine with `ya pkg install`.
68 +The generated Nugu flavors are not third-party plugin clutter. They are first-party generated artifacts and should be committed.
70 +### Nugu integration
72 +Add a `nugu/yazi.nu` generator that maps Nugu palette roles to Yazi's flavor schema.
74 +Extend `nugu/justfile` with a `yazi` recipe that:
76 +1. Builds or reads the Nugu palette.
77 +2. Generates dark and light flavor files under `output/yazi/` or directly writes `../yazi/flavors/nugu-{dark,light}.yazi/flavor.toml`.
78 +3. Keeps generated Yazi flavor output reproducible.
80 +Extend `nugu/justfile install` to include the Yazi generation step.
82 +`yazi/theme.toml` will select Nugu:
84 +```toml
85 +[flavor]
86 +dark = "nugu-dark"
87 +light = "nugu-light"
88 +```
90 +Yazi will use separate generated Nugu dark and light flavors so terminal light/dark switching has matching colors.
92 +## Theme mapping
94 +The Yazi flavor should use Nugu semantic palette roles rather than raw arbitrary colors.
96 +Suggested role mapping:
98 +- App/status backgrounds: `ui.backdrop`.
99 +- Main text: `content.normal`.
100 +- File manager borders: `ui.unfocus` or `ui.minor`.
101 +- Active UI elements: `ui.accent` and `ui.important_local`.
102 +- Selected counts/markers: `content.focus` and `ui.important_local`.
103 +- Warnings/errors: `warning` and `error`.
104 +- Git signs:
105 + - modified: `warning`
106 + - added: `content.focus`
107 + - untracked: `content.accent`
108 + - deleted: `error`
109 + - ignored: `content.minor`
111 +The initial flavor should style enough of Yazi to feel intentionally Nugu without duplicating the full Noctalia icon table. Existing Yazi default icons can remain unless they clash visually.
113 +## Yazi behavior config
115 +`yazi/yazi.toml` should be minimal and override defaults only where the dotfiles imply a preference.
117 +Planned manager settings:
119 +```toml
120 +[mgr]
121 +show_hidden = true
122 +sort_by = "natural"
123 +sort_dir_first = true
124 +linemode = "none"
125 +```
127 +Use default pane ratio `[1, 4, 3]` unless testing shows preview feels cramped.
129 +Preview/opening behavior:
131 +- Keep built-in JSON, PDF, image, video, and archive previews where they work well.
132 +- Use `piper` selectively for tools already present:
133 + - Markdown preview via `glow`.
134 + - Fallback binary preview via `hexyl`.
135 +- Use `ouch` for archive preview/extract behavior where it improves over defaults.
136 +- Use `nvim` as blocking editor.
137 +- Use `mpv` for media.
138 +- Use `xdg-open` for general open behavior.
140 +Git integration:
142 +- Configure `git.yazi` fetchers for files and directories.
143 +- Do not configure `vcs-files` in v1.
144 +- Do not attempt inline `jj` status in v1.
146 +## Lua initialization
148 +`yazi/init.lua` should only initialize selected plugins and avoid custom UI rewrites.
150 +Planned setup:
152 +```lua
153 +require("full-border"):setup { type = ui.Border.PLAIN }
154 +require("git"):setup { order = 1500 }
155 +require("yaziline"):setup { separator_style = "liney" }
156 +```
158 +Additional plugin setup can be added only if required by the chosen plugin's documented API. Avoid overriding core Yazi UI build functions.
160 +## Keymap design
162 +Use `[[mgr.prepend_keymap]]` only. Preserve Yazi defaults and add targeted improvements.
164 +Principles:
166 +- Space remains selection.
167 +- `g`, `t`, `c`, and existing Yazi prefix groups remain native Yazi-style groups.
168 +- No full keymap replacement.
169 +- Avoid terminal-fragile Alt bindings when a normal sequence is available.
171 +Planned bindings:
173 +| Key | Action |
174 +| --- | --- |
175 +| `l` | `plugin smart-enter` |
176 +| `<Enter>` | `plugin smart-enter` |
177 +| `p` | `plugin smart-paste` |
178 +| `f` | `plugin smart-filter` |
179 +| `T` | `plugin toggle-pane min-preview` |
180 +| `F` | `plugin toggle-pane max-preview` |
181 +| `c m` | `plugin chmod` |
182 +| `c D` | `plugin diff` |
183 +| `!` | blocking `$SHELL` in current directory |
184 +| `g w` | `cd ~/Workspace` |
185 +| `g k` | `cd ~/Workspace/dotfiles` |
186 +| `g n` | `cd ~/Notes` |
187 +| `g y` | `cd ~/.config/yazi` |
188 +| `g r` | change to repo root using `git rev-parse --show-toplevel` or `jj root` |
190 +Input behavior:
192 +- Override input `<Esc>` to close the input immediately, avoiding Yazi input's vi-normal mode when the intent is simple cancellation.
194 +## Plugin set
196 +Install and lock these plugins in `yazi/package.toml`:
198 +- `yazi-rs/plugins:full-border`
199 +- `yazi-rs/plugins:toggle-pane`
200 +- `yazi-rs/plugins:smart-enter`
201 +- `yazi-rs/plugins:smart-filter`
202 +- `yazi-rs/plugins:smart-paste`
203 +- `yazi-rs/plugins:git`
204 +- `yazi-rs/plugins:chmod`
205 +- `yazi-rs/plugins:diff`
206 +- `yazi-rs/plugins:piper`
207 +- `ndtoan96/ouch`
208 +- `llanosrocas/yaziline`
210 +Deferred plugins and integrations:
212 +- Custom `jj` plugin.
213 +- `vcs-files` and `git-files`.
214 +- Bookmark plugins.
215 +- Session/autosession plugins.
216 +- `lazygit` plugin until the `lazygit` binary is installed.
217 +- `starship`, `yatline`, `simple-status`, and other statusline alternatives.
218 +- `mount`, `sudo`, and clipboard plugins.
220 +## Validation strategy
222 +Functional validation:
224 +1. Generate Nugu Yazi flavor.
225 +2. Run `ya pkg install` from the Yazi config directory.
226 +3. Run `yazi --debug` to inspect merged config and schema issues.
227 +4. Launch Yazi with `YAZI_LOG=debug` if plugin errors occur.
228 +5. Check keybindings in Yazi help.
229 +6. Smoke-test:
230 + - hidden files visible by default
231 + - `l`/Enter smart-enter behavior
232 + - `p` smart-paste behavior
233 + - `f` smart-filter behavior
234 + - `T` and `F` pane behavior
235 + - `c m` chmod prompt
236 + - `c D` diff behavior
237 + - Markdown preview via glow
238 + - archive handling via ouch
239 + - git signs in a Git repo
241 +Repo validation:
243 +1. Ensure `yazi/plugins/` is ignored.
244 +2. Ensure `yazi/flavors/nugu-dark.yazi/flavor.toml` and `yazi/flavors/nugu-light.yazi/flavor.toml` are tracked.
245 +3. Ensure symlink manifest tests still pass.
246 +4. Ensure regenerating Nugu Yazi flavor produces no unexpected diff.
248 +## Implementation phases
250 +1. Add Yazi dotfiles skeleton and symlink manifest entries.
251 +2. Add Nugu Yazi generator and generated flavor.
252 +3. Add Yazi config files (`theme.toml`, `yazi.toml`, `keymap.toml`, `init.lua`).
253 +4. Install and lock selected plugins via `ya pkg`.
254 +5. Add ignore rules for installed plugin artifacts.
255 +6. Validate with Yazi, Nugu generation, and dotfiles checks.
257 +## Open follow-ups after v1
259 +- Add a local custom Yazi plugin for `jj` changed files or inline status signs.
260 +- Consider adding a `just yazi` or root-level dotfiles recipe for Yazi validation.
261 +- Consider adding `lazygit` integration if the binary is installed later.