[DOCS] Theme customization docs missing named custom themes and plugin `themes/` directories

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/commands

Section/Topic

/theme custom theme management, theme file locations, and plugin theme packaging

Current Documentation

No documentation currently exists for named custom themes, JSON theme files in ~/.claude/themes/, or plugin-shipped themes in a themes/ directory.

The nearest current docs only say:

/theme | Change the color theme. Includes light and dark variants, colorblind-accessible (daltonized) themes, and ANSI themes that use your terminal's color palette

* Other configuration is stored in ~/.claude.json. This file contains your preferences (theme, notification settings, editor mode), OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches.

Plugins can include much more: custom agents, hooks, MCP servers, and LSP servers. | Directory | Location | Purpose | | :---------------- | :---------- | :----------------------------------------------------------------------------- | | .claude-plugin/ | Plugin root | Contains plugin.json manifest (optional if components use default locations) | | skills/ | Plugin root | Skills as <name>/SKILL.md directories | | commands/ | Plugin root | Skills as flat Markdown files. Use skills/ for new plugins | | agents/ | Plugin root | Custom agent definitions | | hooks/ | Plugin root | Event handlers in hooks.json | | .mcp.json | Plugin root | MCP server configurations | | .lsp.json | Plugin root | LSP server configurations for code intelligence | | bin/ | Plugin root | Executables added to the Bash tool's PATH while the plugin is enabled | | settings.json | Plugin root | Default settings applied when the plugin is enabled |

What's Wrong or Missing?

Changelog v2.1.118 added a new user-facing theme workflow: "Create and switch between named custom themes from /theme, or hand-edit JSON files in ~/.claude/themes/; plugins can also ship themes via a themes/ directory".

The current docs only cover selecting built-in themes and mention that general theme preferences live in ~/.claude.json. They do not document:

A. Named custom themes in /theme

There is no explanation of how users create, save, rename, or switch between named custom themes from the /theme picker.

B. Theme file storage and manual editing

There is no documentation for the ~/.claude/themes/ directory, what files belong there, or how manual JSON edits relate to the /theme UI.

C. Plugin-shipped themes

The plugin docs and plugin reference do not mention a themes/ directory at all, so plugin authors have no documentation for shipping themes and users have no documentation for how those themes appear in Claude Code.

Suggested Improvement

Add a dedicated "Custom themes" subsection in the theme-related docs that covers:

1. How to create and switch named custom themes from /theme
2. The purpose and location of ~/.claude/themes/
3. A minimal valid JSON theme example and any schema/field reference
4. How manual JSON edits are picked up by Claude Code
5. How plugins can ship themes via a themes/ directory, including where that directory lives in the plugin root and how shipped themes become available to users

Also update the plugin structure tables in both plugin docs pages to include themes/ alongside the other supported plugin components.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/commands | 91 | /theme is documented only as a built-in theme selector |
| https://code.claude.com/docs/en/interactive-mode | 56-60 | Mentions only Ctrl+T inside the /theme picker |
| https://code.claude.com/docs/en/settings | 117, 224 | Mentions theme preferences in ~/.claude.json, but not ~/.claude/themes/ or custom theme files |
| https://code.claude.com/docs/en/plugins | 176-193 | Plugin structure table omits themes/ |
| https://code.claude.com/docs/en/plugins-reference | 15-16, 17-25 | Plugin component reference omits themes as a supported component |

Total scope: 5 pages affected

Source: Changelog v2.1.118

Exact changelog entry: Create and switch between named custom themes from /theme, or hand-edit JSON files in ~/.claude/themes/; plugins can also ship themes via a themes/ directory