Skip to content

fix(tui): improve colour contrast for light-background terminals#40339

Closed
ademczuk wants to merge 2 commits intoopenclaw:mainfrom
ademczuk:fix/tui-color-contrast-light-themes
Closed

fix(tui): improve colour contrast for light-background terminals#40339
ademczuk wants to merge 2 commits intoopenclaw:mainfrom
ademczuk:fix/tui-color-contrast-light-themes

Conversation

@ademczuk
Copy link
Copy Markdown
Contributor

@ademczuk ademczuk commented Mar 8, 2026

Replaces #38636 (closed due to force-push).

Summary

  • Detect light terminal backgrounds via COLORFGBG env var with proper WCAG 2.1 sRGB linearisation
  • Pick a WCAG AA-compliant light palette when detected
  • Add OPENCLAW_THEME=light|dark override for terminals without auto-detection
  • Light-theme syntax highlighting colours (VS Code light-inspired)

Changes

  • src/tui/theme/theme.ts - background detection + adaptive palettes
  • src/tui/theme/syntax-theme.ts - light-theme syntax colours
  • src/tui/theme/theme.test.ts - detection + WCAG AA contrast tests
  • docs/help/environment.md - document OPENCLAW_THEME and COLORFGBG
  • docs/web/tui.md - terminal colours section
  • CHANGELOG.md - entry under Fixes

Test plan

  • pnpm vitest run src/tui/theme/theme.test.ts
  • pnpm tsgo (type check)
  • pnpm build

Original author: @ademczuk. Rewrite by @vincentkoc. CHANGELOG conflict resolved.

…nclaw#38636)

Detect light terminal backgrounds via COLORFGBG and apply a WCAG
AA-compliant light palette. Adds OPENCLAW_THEME=light|dark env var
override for terminals without auto-detection.

Uses proper sRGB linearisation and WCAG 2.1 contrast ratios to pick
whichever text palette (dark or light) has higher contrast against
the detected background colour.

Co-authored-by: ademczuk <[email protected]>
@openclaw-barnacle openclaw-barnacle bot added docs Improvements or additions to documentation size: M labels Mar 8, 2026
@vincent067
Copy link
Copy Markdown

Yes please! 🙏 This has been driving me crazy.

I use a light terminal theme (Solarized Light) and some of the UI elements are basically invisible. The gray text on light background is particularly bad - I have to squint to read status messages.

Would love to see either:

  • Better default colors that work on both light and dark
  • A config option to switch between light/dark themes
  • Respect terminal ANSI colors instead of hardcoded hex values

This is probably an easy win that would help a lot of users who prefer light backgrounds. Happy to provide screenshots of the problematic areas if that helps!

@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps bot commented Mar 8, 2026

Greptile Summary

This PR adds adaptive light/dark TUI theming by detecting the terminal background colour via COLORFGBG and offering an OPENCLAW_THEME override, with a full WCAG AA-compliant light palette and matching syntax-highlight colours. The implementation integrates cleanly alongside the existing dark palette and theme object — the rest of the codebase sees a drop-in palette export that is already mode-resolved.

Key observations:

  • The sRGB linearisation and xterm 256-colour cube decoding in isLightBackground() are correct; the hardcoded greyscale cutoff at index 244 matches the analytic luminance crossover point exactly.
  • All lightPalette colours are verified at WCAG AA (≥ 4.5 : 1) by the new accessibility test.
  • The local variable named bg inside isLightBackground shadows the module-level bg chalk-wrapper function — this will trigger no-shadow linting rules in most configurations.
  • The "light palette accessibility" describe block mutates process.env.OPENCLAW_THEME without a corresponding afterEach cleanup, leaving the test environment in a non-pristine state for any future dynamic imports added to the file.

Confidence Score: 4/5

  • Safe to merge; logic is well-reasoned and test-covered, with only minor style and test-hygiene issues.
  • The core detection algorithm is mathematically sound (WCAG sRGB linearisation, correct 256-colour cube mapping, analytically-correct greyscale threshold), the light palette passes the WCAG AA assertion test, and the dark path is unaffected. The two flagged issues are non-blocking style concerns: variable shadowing and missing test-environment cleanup.
  • src/tui/theme/theme.ts (variable shadowing) and src/tui/theme/theme.test.ts (missing afterEach cleanup in accessibility describe block).

Last reviewed commit: f164605

@ademczuk
Copy link
Copy Markdown
Contributor Author

ademczuk commented Mar 8, 2026

Closing - this was landed via #40345, which vincentkoc squash-merged to main.

The CHANGELOG entry credits both contributors: Thanks @ademczuk and @vincentkoc.

Commit message on main references our original PR #38636.

@ademczuk ademczuk closed this Mar 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to documentation size: M

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants