Skip to content

fix: raven onboard text invisible on light-background terminals #169

Description

@0xKT

Summary

raven onboard is unreadable on a light-background (white) terminal. Colored text
elements -- unselected list options, the highlighted/current row, free-text input, the
accent-yellow titles/pointer, and one panel subtitle -- render at near-zero contrast and
effectively vanish. Only text with no explicit color (bold, inheriting the terminal's
default foreground) stays visible.

Root cause: the CLI onboarding palette is hardcoded for a dark background and there is
no light/dark theme detection anywhere in raven/. Most people run dark terminals, so
the hardcoded light foregrounds work for them; a colleague on a light iTerm2 profile is the
only one who hits it. This is the CLI (Python: rich + questionary) counterpart of the
TUI-side light-theme work in #79 -- a separate codebase that never got the same treatment.

Steps to reproduce

  1. macOS iTerm2 with a light/white background profile (or any light-background terminal).
  2. Run raven onboard.
  3. Observe the language step and the "Step 1/5 - choose LLM provider" step.

Expected behavior

All onboard text -- list options, the current/highlighted row, input text, titles, and
subtitles -- is legible on a white/near-white terminal background, the same way it is on a
dark background.

Actual behavior

The following elements are near-invisible on white. WCAG contrast ratios (AA body text
needs >= 4.5:1) make the mechanism exact -- every hardcoded color is tuned for a dark
background and fails on white, while the only survivor is the color-less bold text:

Element Color Location On white On dark #1e1e1e
Unselected list options fg:#FFF5EA (text) raven/cli/_styles.py:40 1.08 (fail) 15.48 (ok)
Highlighted/current row fg:#FFF5EA (highlighted) raven/cli/_styles.py:27 1.08 (fail) 15.48 (ok)
Free-text input fg:#FFF5EA (text) raven/cli/_styles.py:40 1.08 (fail) 15.48 (ok)
Accent titles / pointer / progress dots #fbe23f _styles.py:17,22 + markup in onboard_commands.py 1.31 (fail) 12.74 (ok)
Multi-select chosen value fg:#c8a900 (selected) raven/cli/_styles.py:30 2.30 (fail) 7.25 (ok)
Bold, no color (visible) terminal default fg _styles.py:18 21.00 (ok) 1.26 (fail)

A clean natural experiment sits in a single panel: onboard_commands.py:188-189 renders the
English subtitle as [bold white] and the Chinese subtitle as [dim]. On white, white
foreground is invisible (~1.0:1) while [dim] dims the default black foreground to a
still-readable gray -- which is exactly the reported symptom (English line gone, Chinese
line visible).

Note: highlighted (_styles.py:27) uses noreverse, which deliberately turns off
prompt_toolkit's reverse-video highlight in favor of a light foreground. On a light
background that removes the only background-based selection cue, so the current row has no
visible marker at all.

Environment

  • OS: macOS
  • Terminal: iTerm2 with a light/white background profile
  • Python: 3.12
  • Raven: main @ 6079951
  • Note: not version-specific -- reproduces on any light-background terminal,
    since the palette is hardcoded regardless of terminal type or version.

Logs or screenshots

Reporter screenshots show the language step and the "Step 1/5" provider step with titles,
options, and subtitles washed out to near-white/near-yellow on a white background. (Attach
on filing.)

Suggested scope (for discussion, not a decision)

  • Short-term: stop hardcoding light foregrounds -- restore a background-based highlight for
    the current row (drop noreverse or use a selection background), and avoid white /
    #FFF5EA for text that must read on any background.
  • Proper fix: give the CLI a light/dark aware palette, mirroring the TUI approach in
    ui-tui/src/theme.ts (OSC 11 background probe + luminance threshold + env overrides,
    fallback dark), since TS/Python cannot share code but the color table and decision logic
    can be ported. Sibling of Rework light theme readability and contrast #79 (TUI side).

Keep dark-terminal behavior unchanged.


Confirming this on the released v0.1.6 (the report tested main @ 6079951), so the broken palette ships in a tagged release, not just main. Same class of terminal as the reporter — iTerm2 with a light/white-background profile, macOS 15.6 (arm64). Adding the actual screenshots, which line up with the contrast table exactly.

  1. Language step (raven onboard, before a language is picked)
Image
  • Title Raven setup (accent yellow) and the ❯ English pointer/option render washed-out; 中文 [简体] is near-invisible.
  • The natural experiment from onboard_commands.py:188-189 is visible directly: the English subtitle ("Let's set up Raven — First, choose your language.") has vanished while the Chinese subtitle ("开始配置 Raven — 请先选择语言。") stays readable — [bold white] gone, [dim] survives, exactly as described.
  1. Step 1/5 — choose LLM provider (Chinese mode)
Image
  • The accent-yellow title, the 步骤 1/5 header, and the panel subtitle (选择 LLM 服务商) are washed out / effectively gone.
  • The entire provider list is invisible — OpenRouter / OpenAI / Anthropic / Gemini / DeepSeek / GitHub Copilot / Codex / 其他 / 返回, including the highlighted current row (❯ OpenRouter…). With noreverse there is no background cue, so there is no visible selection marker at all.
  • The only things that remain legible are the color-less bold labels — again matching "bold, no color (visible)" in the table.

So this reproduces on a second machine and on a shipped release; the two screens above are the language step and the Step 1/5 provider step the report references.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions