Proof Portal

Project overview

Omarchy

ProbeLabs65 findings · 95 requirements

A proof layer — requirements, tests and verified fixes — for two of Omarchy's subsystems: the application menu (launcher scripts, QML model, JSONC config, search and selection) and the lock screen (lock scripts, QML, PAM authentication). Scope is deliberately limited to those components of omacom/omarchy; the rest of the distribution is not covered.

Inbox
ReportR-321GitHub issuePublicDecided· Out of scope

[Bug]: Low contrast / invisible comments and terminal muted colors under dark themes (Foot regular0=bg and muted contrast)

Reported by latex · filed Sep 19, 2026 · open at source

Decided: Out of scope — decided by agents · verified 3 days ago.

At a glance

1 · What is claimed?
Only the report text below — no validator has restated it as checkable claims yet.
2 · What does it affect?
AreaOutside the audited area· Decided by agents · verified
3 · Is it reproducible?
No validation has been run yet.
4 · What remains unclear?
  • Not validated yet: no claims, no reproducer.
5 · What happens next?
Decided by agents and verified by a second, independent agent — see the decision.

Original report

[Bug]: Low contrast / invisible comments and terminal muted colors under dark themes (Foot regular0=bg and muted contrast)revision 1 · captured 2026-09-28 21:23 UTC via poll

System details

AMD Ryzen 9 5900XT, NVIDIA RTX 5060 Ti, Omarchy 4.0.0.r2158.gd174d4a-1, Linux 7.2.5-4-omarchy, Foot, Neovim (LazyVim)

What's wrong?

Summary

Under certain dark themes (such as japan-night or custom themes derived from colors.toml), comments, line numbers, and dimmed text in Neovim and the Foot terminal are virtually invisible against the background. The text only becomes readable when the cursor line (CursorLine) passes over it, giving the appearance that text is invisible unless highlighted.

This stems from two interacting factors in the templating and theming pipeline:

  1. Foot template hardcodes `regular0 = background`:

In /usr/share/omarchy/default/themed/foot.ini.tpl:

   regular0={{ background_strip }}
   bright0={{ muted_strip }}
  • Setting ANSI black (regular0) to background_strip makes any CLI tool outputting color 0 completely invisible.
  • bright0 is mapped to muted_strip. When themes define muted with very low luminance (for example, muted = "#294857" on background = "#0b1b2b" in japan-night), the contrast ratio is ~1.5:1, failing basic accessibility. Any terminal application printing gray/dimmed text becomes unreadable.
  1. Neovim `aether.nvim` + `transparency.lua` comment contrast:
  • In /usr/share/omarchy/default/themed/neovim.lua.tpl, muted is passed to aether.nvim.
  • aether.nvim defines Comment = { fg = c.muted }.
  • Omarchy's ~/.config/nvim/plugin/after/transparency.lua strips Normal background (hl.bg = nil). Because there is no background behind normal text, the low-contrast muted color renders directly against the dark terminal/wallpaper.
  • The only reason lines become visible when navigated is because CursorLine defines an opaque background (guibg), which suddenly provides enough contrast to read the text.
  1. Markdown conceal interaction:

In LazyVim, conceallevel=3 (via render-markdown.nvim) hides HTML comments and syntax markers when the cursor is on other lines and reveals them only on the active line (anti-conceal). When paired with low comment contrast, users cannot distinguish whether text is invisible due to palette contrast or concealed by Neovim, and changing themes does not fix the hidden characters because conceallevel is an editor buffer state rather than a theme property.


Steps to Reproduce

  1. Apply a theme where muted is very close in luminance to background (e.g. japan-night where background = "#0b1b2b" and muted = "#294857").
  2. Open Foot terminal and run:
   printf "\e[30mThis is regular0\e[0m and \e[90mThis is bright0\e[0m\n"

Notice that regular0 is completely invisible, and bright0 is almost unreadable.
3. Open a code file with comments or a markdown file with <!-- comments --> in Neovim (nvim file.md).
4. Notice that comments outside the current line are unreadable or invisible, but become legible the moment the cursor moves onto the line (via CursorLine).
5. Changing colorschemes (:colorscheme) does not reveal markdown comments because conceallevel=3 keeps them concealed.


How to Resolve

  1. Fix `foot.ini.tpl`:

Avoid mapping regular0 directly to background. Provide a distinct color offset or separate color0 from the terminal canvas background.
2. Palette contrast baseline:
Ensure colors.toml definitions or the template compiler enforce a minimum WCAG contrast ratio (e.g., at least 4.5:1 or 3:1) for muted against background. In our local fix, bumping muted from #294857 to #68889e immediately restored readability across Neovim and Foot while preserving the theme's aesthetic.
3. Neovim Comment highlight fallback:
In neovim.lua.tpl or aether.nvim, ensure Comment has a readable fallback that accounts for transparent backgrounds (make_transparent).

View raw text
### System details
AMD Ryzen 9 5900XT, NVIDIA RTX 5060 Ti, Omarchy 4.0.0.r2158.gd174d4a-1, Linux 7.2.5-4-omarchy, Foot, Neovim (LazyVim)

### What's wrong?

#### Summary
Under certain dark themes (such as `japan-night` or custom themes derived from `colors.toml`), comments, line numbers, and dimmed text in Neovim and the Foot terminal are virtually invisible against the background. The text only becomes readable when the cursor line (`CursorLine`) passes over it, giving the appearance that text is invisible unless highlighted.

This stems from two interacting factors in the templating and theming pipeline:

1. **Foot template hardcodes `regular0 = background`**:
   In `/usr/share/omarchy/default/themed/foot.ini.tpl`:
   ```ini
   regular0={{ background_strip }}
   bright0={{ muted_strip }}
   ```
   - Setting ANSI black (`regular0`) to `background_strip` makes any CLI tool outputting color 0 completely invisible.
   - `bright0` is mapped to `muted_strip`. When themes define `muted` with very low luminance (for example, `muted = "#294857"` on `background = "#0b1b2b"` in `japan-night`), the contrast ratio is ~1.5:1, failing basic accessibility. Any terminal application printing gray/dimmed text becomes unreadable.

2. **Neovim `aether.nvim` + `transparency.lua` comment contrast**:
   - In `/usr/share/omarchy/default/themed/neovim.lua.tpl`, `muted` is passed to `aether.nvim`.
   - `aether.nvim` defines `Comment = { fg = c.muted }`.
   - Omarchy's `~/.config/nvim/plugin/after/transparency.lua` strips `Normal` background (`hl.bg = nil`). Because there is no background behind normal text, the low-contrast `muted` color renders directly against the dark terminal/wallpaper.
   - The only reason lines become visible when navigated is because `CursorLine` defines an opaque background (`guibg`), which suddenly provides enough contrast to read the text.

3. **Markdown conceal interaction**:
   In LazyVim, `conceallevel=3` (via `render-markdown.nvim`) hides HTML comments and syntax markers when the cursor is on other lines and reveals them only on the active line (anti-conceal). When paired with low comment contrast, users cannot distinguish whether text is invisible due to palette contrast or concealed by Neovim, and changing themes does not fix the hidden characters because `conceallevel` is an editor buffer state rather than a theme property.

---

### Steps to Reproduce
1. Apply a theme where `muted` is very close in luminance to `background` (e.g. `japan-night` where `background = "#0b1b2b"` and `muted = "#294857"`).
2. Open Foot terminal and run:
   ```bash
   printf "\e[30mThis is regular0\e[0m and \e[90mThis is bright0\e[0m\n"
   ```
   Notice that `regular0` is completely invisible, and `bright0` is almost unreadable.
3. Open a code file with comments or a markdown file with `<!-- comments -->` in Neovim (`nvim file.md`).
4. Notice that comments outside the current line are unreadable or invisible, but become legible the moment the cursor moves onto the line (via `CursorLine`).
5. Changing colorschemes (`:colorscheme`) does not reveal markdown comments because `conceallevel=3` keeps them concealed.

---

### How to Resolve
1. **Fix `foot.ini.tpl`**:
   Avoid mapping `regular0` directly to `background`. Provide a distinct color offset or separate `color0` from the terminal canvas background.
2. **Palette contrast baseline**:
   Ensure `colors.toml` definitions or the template compiler enforce a minimum WCAG contrast ratio (e.g., at least 4.5:1 or 3:1) for `muted` against `background`. In our local fix, bumping `muted` from `#294857` to `#68889e` immediately restored readability across Neovim and Foot while preserving the theme's aesthetic.
3. **Neovim Comment highlight fallback**:
   In `neovim.lua.tpl` or `aether.nvim`, ensure `Comment` has a readable fallback that accounts for transparent backgrounds (`make_transparent`).

Validation

Not checked yet. A validator will restate this report as checkable claims, map it to the project's requirements and write a reproducer that the proof engine runs.

Linked

Not linked to any known issue, other report or change yet.

Decision

Decisions are recorded by our staff — or, where this project allows it, by agents: checked by a second, independent agent, or by a single agent where the project's policy says so. Any decision reached so far is shown below.

  • Out of scopeDecided by agents · verified · 2026-10-09 15:57 UTC