| 1 | # Accessibility |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/ACCESSIBILITY.md](zh_hans/ACCESSIBILITY.md)。 |
| 4 | |
| 5 | Codewhale runs in a terminal, so the platform's own accessibility |
| 6 | stack (screen readers, magnifiers, terminal-level themes) does most |
| 7 | of the work. The TUI provides a small set of toggles that reduce |
| 8 | visual motion and density for screen-reader and low-motion users. |
| 9 | |
| 10 | ## Quick reference |
| 11 | |
| 12 | | Toggle | Default | Effect | |
| 13 | | --- | --- | --- | |
| 14 | | `NO_ANIMATIONS=1` env var | unset | At startup, forces `low_motion = true` and `fancy_animations = false`. Overrides whatever's saved in `settings.toml`. | |
| 15 | | `CODEWHALE_ASCII_SAFE=1` env var | unset | Replaces decorative Unicode and box-drawing marks with narrow ASCII at the terminal backend. Labels, focus, state, and controls remain available. | |
| 16 | | `low_motion` setting | `false` | Freezes decorative and state animation without changing model text delivery. The footer water strip is controlled separately by `fancy_animations`. | |
| 17 | | `fancy_animations` setting | `true` | Enables expressive live-state chrome. Set to `false` to keep live-turn chrome still. | |
| 18 | | `ocean_treatment` setting | `ombre` | Chooses the background appearance: `ombre` paints the state-reactive water column; `flat` uses the plain theme surface. Both keep the same state marks and idle ambient life; appearance is independent of motion settings. | |
| 19 | | `status_indicator` setting | `cw` | Static typographic header mark. Set to `dots` for the legacy animation, or `off` to hide it; `whale` is retired and normalizes to `cw`. | |
| 20 | | `calm_mode` setting | `true` | Collapses tool-output details by default and trims status messages. Useful for screen readers that announce every redraw. | |
| 21 | | `show_thinking` setting | `true` | Set to `false` to hide model `reasoning_content` blocks from the TUI presentation. Canonical session/replay receipts remain unchanged. | |
| 22 | | `thinking_default_expanded` setting | `false` | Set to `true` to expand visible thinking blocks initially. Space still collapses or expands the selected block. | |
| 23 | | `show_tool_details` setting | `false` | Set to `true` to expand tool calls inline; details remain available on demand either way. | |
| 24 | | `inline_diffs` setting | `full` | Use `summary` or `off` to reduce inline File-change density. Exact applied evidence remains available with Alt/Option+V in every mode. | |
| 25 | |
| 26 | ## Color contrast guarantees |
| 27 | |
| 28 | The palette enforces WCAG contrast floors in two places, and this is what |
| 29 | the code actually guarantees — no more: |
| 30 | |
| 31 | * **At draw time**, every text cell is lifted to a 4.5:1 contrast ratio |
| 32 | against the surface it will actually render on (`enforce_cell_contrast` in |
| 33 | the terminal backend). Frame chrome (borders, block glyphs) is not clamped, |
| 34 | and community presets that own a full custom palette (Catppuccin, Tokyo |
| 35 | Night, Dracula, Gruvbox, Claude, Matrix, Solarized Light, Terminal) are |
| 36 | exempt from this draw-time pass because their authors tuned those pairs. |
| 37 | * **Per theme**, an audit (`theme_contrast_violations`) holds every |
| 38 | selectable preset to the same floors: body, soft, and muted text at 4.5:1 |
| 39 | on every primary surface (including selection and error surfaces); hint and |
| 40 | dim text at 3:1; status, warning, success, and info roles at 3:1 because |
| 41 | they are redundant — every status also carries a glyph and a word label, |
| 42 | so color is never the only channel. Diff foreground/background pairs are |
| 43 | held to 3:1. |
| 44 | * The **Terminal** (transparent) theme is exempt by design: it paints |
| 45 | `Color::Reset` surfaces and ANSI accents so the host terminal's own scheme |
| 46 | shows through. Those colors are terminal-owned and cannot be measured, so |
| 47 | the audit skips them rather than claiming a pass |
| 48 | (`theme_uses_terminal_owned_surfaces` makes the exemption explicit). |
| 49 | * The **Grayscale** theme's "Color-minimal high contrast" tagline is |
| 50 | enforced: its body text hierarchy clears 4.5:1 on every surface. |
| 51 | * The ASCII tier (`CODEWHALE_ASCII_SAFE=1`) keeps labels, focus, and state |
| 52 | available without decorative glyphs, so the non-color redundancy above |
| 53 | survives in the plainest rendering mode. |
| 54 | |
| 55 | ## Standard env-var surface |
| 56 | |
| 57 | Set these in your shell profile so they apply to every session: |
| 58 | |
| 59 | ```bash |
| 60 | # Force low-motion + no fancy animations. |
| 61 | export NO_ANIMATIONS=1 |
| 62 | |
| 63 | # Force the terminal-safe ASCII rendering tier. |
| 64 | export CODEWHALE_ASCII_SAFE=1 |
| 65 | |
| 66 | # Optional: respect the wider terminal-color convention. |
| 67 | export NO_COLOR=1 # terminal-owned colors; bold/underline remain |
| 68 | ``` |
| 69 | |
| 70 | A nonempty `NO_COLOR` value suppresses foreground, background, and underline |
| 71 | colors in the TUI. An empty value leaves normal terminal color detection active. |
| 72 | This follows the [NO_COLOR convention](https://no-color.org/) while retaining |
| 73 | text modifiers and selection symbols. ASCII rendering and reduced motion are |
| 74 | separate choices. |
| 75 | |
| 76 | `NO_ANIMATIONS` accepts any of `1`, `true`, `yes`, or `on` |
| 77 | (case-insensitive). Any other value (including `0`, `false`, empty, |
| 78 | or unset) leaves your saved settings alone. |
| 79 | |
| 80 | The override is applied once at startup. Changing the env var |
| 81 | mid-session has no effect — settings are only re-read on the next |
| 82 | launch. |
| 83 | |
| 84 | ## Configuring via `/config` |
| 85 | |
| 86 | The same toggles are reachable from the command palette: |
| 87 | |
| 88 | * `/config low_motion on --save` |
| 89 | * `/config fancy_animations off --save` |
| 90 | * `/config calm_mode on --save` |
| 91 | * `/config status_indicator off --save` |
| 92 | |
| 93 | Settings written this way persist to `~/.codewhale/settings.toml` on new |
| 94 | installs, with legacy `~/.deepseek/settings.toml` and platform config-dir |
| 95 | settings kept as compatibility fallbacks. |
| 96 | The `NO_ANIMATIONS` env var still wins at startup if it's set, so |
| 97 | unsetting the env var is the way to honor your saved choice. |
| 98 | |
| 99 | Tilix and Terminator sessions automatically start in low-motion mode because |
| 100 | those VTE-based terminals have reported visible redraw flicker during active |
| 101 | turns. You can still override the saved settings after launch if your terminal |
| 102 | version renders cleanly. |
| 103 | |
| 104 | ## Notes for screen-reader users |
| 105 | |
| 106 | * `low_motion` slows the idle redraw loop to ~120ms per frame and freezes state |
| 107 | markers without synthesizing or throttling model text. Combined with |
| 108 | `calm_mode`, the redraw rate stays low enough that VoiceOver / |
| 109 | Orca announcements track linearly with model output instead of |
| 110 | re-reading the whole screen on each tick. |
| 111 | * The transcript is pure text — no images or canvas rendering — so |
| 112 | any terminal that integrates with the platform's accessibility |
| 113 | service (e.g. macOS Terminal.app, iTerm2, Ghostty, Windows |
| 114 | Terminal) will pass the rendered content straight through. |
| 115 | * If you find a UI surface that still produces motion when |
| 116 | `low_motion = true`, please file an issue against |
| 117 | [`PRIOR: Screen-reader / accessibility flag`](https://github.com/codewhale-hq/CodeWhale/issues/450) |
| 118 | with a screenshot or terminal recording. |
| 119 | |
| 120 | ## Related issues / history |
| 121 | |
| 122 | * [#450](https://github.com/codewhale-hq/CodeWhale/issues/450) — |
| 123 | documenting the existing flag, adding the `NO_ANIMATIONS` |
| 124 | startup overlay, and writing this page. |
| 125 | * [#449](https://github.com/codewhale-hq/CodeWhale/issues/449) — |
| 126 | footer statusline now uses the active theme's contrast pair |
| 127 | instead of a bespoke palette. |
| 128 |