# Terminal Color Architecture
## Overview
trackWork adapts to the user's actual terminal theme instead of assuming fixed
RGB values. At startup we query the real RGB behind the 16 ANSI palette indices,
then resolve named colors (`Color::Gray`, `Color::Green`, ...) through that
palette when computing animations or dimmed variants. So a dimmed label gets
darker on a dark theme + lighter on a light theme — it always blends toward the
user's real background.
## Pieces
| `query_palette()` | `src/termcolor.rs` | OSC 4 query for indices 0–15 at startup. Returns `HashMap<u8,(u8,u8,u8)>`. Empty if terminal doesn't answer. |
| `app.term_palette` | `src/app.rs` | Stored query result. Passed to color helpers. |
| `themed_rgb(c, palette)` | `src/dashboard/utils.rs` | Real RGB for a ratatui `Color`. Prefers queried palette → falls back to `color_to_rgb`. `Rgb` passes through. |
| `dim_toward_bg(c, palette, t)` | `src/dashboard/utils.rs` | Blend `c` toward background (index 0) by `t` (0=unchanged, 1=full bg). Theme-aware "dimmer". |
| `breathe_color(base, t)` | `src/dashboard/utils.rs` | HSL pulse for highlighted bars (brightness+saturation move together). |
| `color_to_rgb(c)` | `src/dashboard/utils.rs` | Static fallback RGB (VS Code dark) when palette unavailable. |
## Startup flow
`main.rs`: `query_palette()` → `app.term_palette = ...`. Query has a 150ms
timeout per index + bails after index 0 if no reply, so a non-answering terminal
costs one timeout total.
## Rules
- **Never hardcode `Color::Rgb(...)` for grays/dims.** Use `dim_toward_bg(base, &app.term_palette, t)` so it tracks the theme. Index 0 = background.
- **Animations** (breathe etc.) resolve their base via `themed_rgb` so hues match the user's palette.
- Index 0 = background, 7 = gray/fg, 8 = dark gray. Map names via `color_index`.
## Example: timeline guide lines
`src/dashboard/drawers/timeline/ui.rs` dims time labels + empty-row guide lines
with a 3-step `t` hierarchy off `Color::Gray` (full hour brightest → half → other
faintest). Higher `t` = closer to background = fainter.