> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme System (Colors)

> ChatCLI's unified color palette: 12 themes (dark, light, grafite + 9 community palettes), themed markdown, and graceful degradation by terminal capability.

Since **v1.125**, every color in ChatCLI comes from a single source of truth: the `ui/theme` package. It defines a **semantic palette** (colors named by role, not by hue), detects the **terminal's color capability**, and ships **12 ready-made themes** (`dark`, `light`, `grafite` + 9 community palettes) that re-skin the entire UI — chat, `/coder` and `/agent` cards, borders, markdown, code blocks, and spinners — with no restart.

<Info>
  The theme is **process-global state**. Switching applies on the **next render**, no restart needed. Unlike `CHATCLI_CODER_UI` (the timeline style), which the renderer re-reads from the environment on every call.
</Info>

***

## Switch themes at runtime

```bash theme={"system"}
/config ui                     # show the active theme + detected color profile
/config ui theme               # same thing (explicit form)
/config ui theme dark          # switch to the dark theme
/config ui theme dracula       # switch to any theme by name
/config ui theme tokyo-night   # hyphenated names work fine

/config theme dracula          # shorthand equivalent to /config ui theme dracula
```

<Tip>
  Full autocomplete: type `/config ui theme <TAB>` (or `/config theme <TAB>`) and every theme appears: `dark · light · grafite · dracula · nord · tokyo-night · solarized-dark · solarized-light · gruvbox · catppuccin-mocha · monokai · one-dark`.
</Tip>

The status panel (`/config ui`) shows the active theme, the **source** of the value (environment variable vs. default), the detected **color profile**, and the list of themes with the active one marked by `→`.

***

## Available themes

There are **12 themes** in total. Each strip shows the name and the palette's **real colors**, in the order **model · accent (reasoning) · ok · warn · error**:

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/dark.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=815f91edaaed571de10d41049e7ae6da" alt="dark theme" width="420" height="40" data-path="images/themes/dark.svg" /> — default, dark-background terminals

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/light.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=a00feadc08705d24c4211d92a52b2165" alt="light theme" width="420" height="40" data-path="images/themes/light.svg" /> — light-background terminals

<img src="https://mintcdn.com/encom/10veCW9LR_AsF92O/images/themes/grafite.svg?fit=max&auto=format&n=10veCW9LR_AsF92O&q=85&s=f886d544235a737709c1673aaa8a8950" alt="grafite theme" width="420" height="40" data-path="images/themes/grafite.svg" /> — sober graphite dark: calm blue accents, low-key chrome

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/dracula.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=415cbc3ebad4e8672681f7a3acee5cda" alt="dracula theme" width="420" height="40" data-path="images/themes/dracula.svg" /> — high-contrast purple/pink/cyan

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/nord.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=5bb6bc1c2f16890f8d9b90a1bc69d958" alt="nord theme" width="420" height="40" data-path="images/themes/nord.svg" /> — cool arctic, low saturation

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/tokyo-night.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=78effb64f88e8f59da6a4494e23ce853" alt="tokyo-night theme" width="420" height="40" data-path="images/themes/tokyo-night.svg" /> — modern night-blue

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/solarized-dark.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=0d63cd2c30533298636cf692a44dee49" alt="solarized-dark theme" width="420" height="40" data-path="images/themes/solarized-dark.svg" /> — Solarized on its dark base

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/solarized-light.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=c80ffc90a7bb5f8336b9a7e2e8e44c71" alt="solarized-light theme" width="420" height="40" data-path="images/themes/solarized-light.svg" /> — same hues on a light background

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/gruvbox.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=6b83325929fc354c6dc8762a1e360398" alt="gruvbox theme" width="420" height="40" data-path="images/themes/gruvbox.svg" /> — retro, warm, high-contrast

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/catppuccin-mocha.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=f6f36a9c166e04ad7ec1f21a288f3f6f" alt="catppuccin-mocha theme" width="420" height="40" data-path="images/themes/catppuccin-mocha.svg" /> — soft pastel (Mocha)

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/monokai.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=e9c649b29429c286ebcb456301a96fd4" alt="monokai theme" width="420" height="40" data-path="images/themes/monokai.svg" /> — classic editor palette on charcoal

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/one-dark.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=87f6d59d1d880c76d475f1dd3fdc2058" alt="one-dark theme" width="420" height="40" data-path="images/themes/one-dark.svg" /> — Atom's balanced blue/gray

<Note>
  `dark`, `light` and `grafite` are ChatCLI's calibrated variants; the other nine are adaptations of the classic community palettes mapped onto ChatCLI's semantic roles (same structure, different colors). All of them degrade to 256 and 16 colors while keeping the roles distinguishable.
</Note>

The switch applies the palette **all at once** because `Colorize` and the `ansiColorToLip` converter route through the active theme — there's no call-site churn.

***

## Semantic palette

Colors are named by the **role** they serve, not by hue. That's what makes swapping the whole theme a matter of touching only the palette:

| Group | Field | Use |
| - | - | - |
| Brand/Hierarchy | `Primary` | model name, primary actions |
| | `Secondary` | multi-agent, batch, secondary badges |
| | `Accent` | reasoning / cognitive emphasis |
| | `Muted` | neutral borders, secondary text, defaults |
| Semantic state | `Success` | tool success, enabled |
| | `Warning` | warnings, disabled |
| | `Danger` | errors, tool failure |
| | `Info` | notes / explanations |
| Structural | `Border` | default card border |
| | `Text` / `TextStrong` | body text / bold and headings |
| | `Background` | code-block background |

***

## The input line and the completion dropdown

The REPL prompt is drawn by `go-prompt`, which owns its own render loop and never sees the ANSI strings the rest of the UI builds. Until **v1.199** its colors were literals — the text you typed was hardcoded to white — so a light theme on a light terminal printed **white on white**. Every one of those colors now comes from the active palette:

| Surface | Palette entry |
| - | - |
| prompt prefix, inline completion preview | `Info` |
| the text you type | `TextStrong` |
| suggestion list (fill / ink) | `Border` / `TextStrong` |
| selected suggestion (fill / ink) | `Secondary` / `Background` |
| description panel (fill / ink) | `Background` / `Warning` |
| scrollbar (thumb / track) | `Muted` / `Background` |

Ink is always chosen against the **fill it lands on**, never against the terminal — `Background` is the theme's own ground, so it is the readable ink on a saturated row under a dark *and* a light palette.

<Note>
  `go-prompt` copies these onto its renderer when the prompt is built and never re-reads them, so `/config ui theme` rebuilds the prompt on the spot. That is the one surface where a theme switch does more than wait for the next render.
</Note>

***

## Legibility contract

Every built-in palette is held to a machine-checked floor, so "opinionated about hue" never becomes "unreadable":

* **Body text** (`Text`, `TextStrong`) clears **4.5:1** against the theme's own ground; **`Muted`** — secondary text — clears **3:1**.
* On a **16-color** terminal a light palette never reaches into the bright range (9–15, which is painted for a dark ground), and a dark palette never uses index 0.
* Each dropdown fill/ink pair clears 3:1 and never collapses onto the same 16-color index.

`Border` is deliberately exempt from the contrast floor: Nord, Solarized, Catppuccin and One Dark all define their border tone as a near-ground fill on purpose, and raising it would replace the palette's identity with ours.

***

## Themed markdown

Markdown is rendered by glamour with a `StyleConfig` **derived from the palette** (replacing the legacy `glamour.WithStandardStyle("dark")`), so markdown and code-block colors share the UI's hues. Syntax highlighting via **chroma** and a **language chip** above each code block. The document is rendered **whole** (not block by block), so reference links, footnotes, and paragraph spacing all resolve correctly.

***

## Color profile and graceful degradation

ChatCLI detects the terminal's capability and degrades gracefully. In pipes, CI, or `dumb` terminals, output becomes **clean plain text with no color codes**.

| Profile | Meaning |
| - | - |
| `TrueColor` | 24-bit terminal |
| `ANSI256` | 8-bit (256-color) terminal |
| `ANSI` | classic 16-color terminal (SGR 30–37 / 90–97) |
| `ASCII` | no color — `NO_COLOR`, `dumb`, pipe/redirect |

Detection honors the usual signals (`NO_COLOR`, `CLICOLOR_FORCE`, `TERM`, `COLORTERM`). The `dark` theme keeps the **ANSI16 = 10** index for green, so 16-color terminals are identical to legacy behavior.

The startup banner uses the profile too. On a truecolor terminal its block letters are painted column by column with a left-to-right gradient: coral through orange to amber on the `dark` and `light` themes, and from the theme's Primary to its Secondary on every other theme. A 256-color terminal gets the nearest palette entry per column. A 16-color terminal, `NO_COLOR` and piped output keep the single-color banner.

***

## Persistence

A runtime switch applies only to the **current process**. To pin a default across sessions, add to your `.env`:

```bash theme={"system"}
CHATCLI_THEME=light
```

The mutator prints this hint right after each switch. ChatCLI **never rewrites your `.env`** on its own. See [`CHATCLI_THEME`](/reference/environment-variables) in the environment-variable reference.

<Note>
  Parallel change in v1.125: the chat reply envelope gained a **footer** with per-turn cost and context usage, and spinners were unified into a single themed braille spinner, shown only when a terminal is present.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.