Design notes / Claude Code themes
What 50 dark Claude Code themes taught me about semantic terminal colors.
A terminal theme is not just a palette. It is a mapping between color and meaning. Decorative accents can move; errors, warnings, success states and diffs still need to read instantly.
The useful constraint: do not theme away meaning.
When I started building the set, the obvious temptation was to make every interface color belong to each palette. That produces a neat screenshot, but it weakens the tool. If the same accent can mean an assistant label, a warning, a successful operation and a diff addition, color stops helping.
The better rule was narrower: change identity and hierarchy, preserve operational meaning. The theme can own foreground text, secondary text, borders, prompts, permissions and raised surfaces. Claude Code's base dark preset can keep the status roles people already recognize.
Graphite is a useful concrete example.
This focused fragment comes directly from the Graphite theme. It changes the identity, text hierarchy and surfaces, but it does not override success, error, warning or diff colors.
{
"name": "Graphite",
"base": "dark",
"overrides": {
"claude": "#C9CFD6",
"text": "#E9EAEC",
"inactive": "#A0A4AB",
"subtle": "#2E2F33",
"promptBorder": "#C9CFD6",
"permission": "#ECEEF0",
"userMessageBackground": "#27282B"
}
}
The omission is the point. A restrained theme file can be more coherent than one that overrides every available key.
Contrast needs a role, not one universal number.
“More contrast” is not a complete design direction. Primary text, muted text, decorative borders and selected surfaces do different jobs. Treating them as equivalent either makes the interface harsh or lets important information disappear.
| Role | What it must do | Common failure |
|---|---|---|
| Primary text | Remain readable through long responses and logs. | Looks elegant in a card, tires the eye in continuous output. |
| Inactive text | Stay legible without competing with the current task. | Falls so close to the background that context disappears. |
| Subtle borders | Separate structure without becoming a visual grid. | Uses a bright accent everywhere and overwhelms content. |
| Status colors | Signal success, warning, error and change immediately. | Gets recolored for mood and loses semantic recognition. |
| Raised surfaces | Separate messages and controls from the terminal plane. | Matches the background exactly or becomes an opaque patch. |
The terminal owns the background.
Claude Code can style its interface, but it cannot set the terminal application's background. That ownership boundary matters. Each gallery card therefore exposes a matching surface hex so the terminal can be tuned separately when someone wants the complete look.
Graphite example: set the terminal background to #1D1E20. The Claude Code theme then uses #27282B for the user-message surface, creating a small but deliberate lift.
Transparent terminals make the boundary obvious.
A transparent terminal can reveal the desktop or window behind it, but Claude Code's userMessageBackground is still painted as an opaque interface surface. It does not inherit terminal transparency.
Trying to hide that with an exact background match produces an awkward block whenever transparency changes. I found it more honest to treat the message as a raised panel: close to the palette, clearly intentional, and usable on both transparent and opaque terminals.
What I now check in a real theme.
- Long assistant output, not only the theme picker.
- Errors, warnings and successful commands next to each other.
- Diff additions and deletions in the same view.
- Permission and plan-mode prompts under pressure.
- Muted information in a dense log.
- User messages on opaque and transparent terminal backgrounds.
- The palette with a terminal background that is slightly wrong, because real setups are rarely perfect.
The question is not only “does this look good?” It is “does the interface still tell the truth quickly?”
Quick answers.
Errors, warnings, success states and diffs carry meaning. Keeping the base dark status colors preserves recognition while the rest of the interface changes.
No. The terminal application owns that surface. The gallery provides a matching hex you can set separately.
Yes. The complete theme set, plugin package and installer are public under the MIT license.
The themes are free.
All 50 Claude Code themes, the plugin packaging and the installer are public under the MIT license. Use them, inspect the JSON, change them, or point out where the semantic hierarchy still breaks in real work.