chore: document colors

AGENTS.md

@@ -12,6 +12,10 @@ Before finalizing a change to `codex-rs`, run `just fmt` (in `codex-rs` director
 1. Run the test for the specific project that was changed. For example, if changes were made in `codex-rs/tui`, run `cargo test -p codex-tui`.
 2. Once those pass, if any changes were made in common, core, or protocol, run the complete test suite with `cargo test --all-features`.
 
+## TUI style conventions
+
+See `codex-rs/tui/styles.md`.
+
 ## TUI code conventions
 
 - Use concise styling helpers from ratatui’s Stylize trait.

codex-rs/clippy.toml

@@ -5,4 +5,5 @@ disallowed-methods = [
     { path = "ratatui::style::Color::Indexed", reason = "Use ANSI colors, which work better in various terminal themes." },
     { path = "ratatui::style::Stylize::white", reason = "Avoid hardcoding white; prefer default fg or dim/bold. Exception: Disable this rule if rendering over a hardcoded ANSI background." },
     { path = "ratatui::style::Stylize::black", reason = "Avoid hardcoding black; prefer default fg or dim/bold. Exception: Disable this rule if rendering over a hardcoded ANSI background." },
+    { path = "ratatui::style::Stylize::yellow", reason = "Avoid yellow; prefer other colors in `tui/styles.md`." },
 ]

codex-rs/tui/styles.md

@@ -0,0 +1,21 @@
+# Headers, primary, and secondary text
+
+- **Headers:** Use `bold`. For markdown with various header levels, leave in the `#` signs.
+- **Primary text:** Default.
+- **Secondary text:** Use `dim`.
+
+# Foreground colors
+
+- **Default:** Most of the time, just use the default foreground color. `reset` can help get it back.
+- **Selection:** Use ANSI `blue`.
+- **User input tips and status indicators:** Use ANSI `cyan`.
+- **Success and additions:** Use ANSI `green`.
+- **Errors, failures and deletions:** Use ANSI `red`.
+- **Codex:** Use ANSI `magenta`.
+
+# Avoid
+
+- Avoid custom colors because there's no guarantee that they'll contrast well or look good on various terminal color themes.
+- Avoid ANSI `black`, `white`, `yellow` as foreground colors because the terminal theme will do a better job. (Use `reset` if you need to in order to get those.) The exception is if you need contrast rendering over a manually colored background.
+
+(There are some rules to try to catch this in `clippy.toml`.)