[Docs] terminal-config: color token reference covers ~35 of 69 tunable tokens

Problem

The official terminal-config docs at <https://code.claude.com/docs/en/terminal-config#color-token-reference> list ~35 color tokens for ~/.claude/themes/*.json, and the page itself acknowledges the list is partial:

The interactive editor in /theme shows the same tokens with a live preview, including a small number of internal tokens not covered here.

In practice, the canonical preset object inside the v2.1.126 binary contains 69 distinct token keys, all reachable via overrides. About half the tunable surface is not discoverable from the docs.

This causes downstream confusion. For example, #50818 ("Per-component UI color customization") proposes a new uiColors settings field for behavior that's already supported — overriding userMessageBackground, text, messageActionsBackground, etc. via a custom theme — because the relevant tokens aren't in the public reference.

There is also no published JSON Schema for theme files (only claude-code-settings.json on schemastore), so editors can't autocomplete or validate ~/.claude/themes/*.json.

What's missing from the docs

Of the 69 tokens in the dark preset object, ~34 are not in the published reference. Notable groups:

• Shimmer variants for tokens whose docs only mention claudeShimmer and warningShimmer: permissionShimmer, promptBorderShimmer, inactiveShimmer, fastModeShimmer
• System spinner: claudeBlue_FOR_SYSTEM_SPINNER, claudeBlueShimmer_FOR_SYSTEM_SPINNER
• Suggestion / background: suggestion, background
• Fullscreen-mode message backgrounds: userMessageBackgroundHover, messageActionsBackground, bashMessageBackgroundColor, memoryBackgroundColor
• Rate-limit indicator: rate_limit_fill, rate_limit_empty
• Brief mode labels: briefLabelYou, briefLabelClaude
• Marketing accents: professionalBlue, chromeYellow
• Mascot easter egg: clawd_body, clawd_background
• Rainbow palette (7 colors × shimmer pair = 14 tokens): rainbow_red, rainbow_red_shimmer, etc.

Proposed contribution

I've assembled a community reference that covers all 69 tokens — a JSON Schema (Draft 2020-12) and a Markdown catalog with Documented / Internal badges and an inferred description for each token:

• Gist: https://gist.github.com/cameronsjo/34a6fb8ade2b44c8380e1a2adebbac2b
• theme.schema.json — strict-mode schema, validates name / base / overrides, enumerates all 69 tokens, validates color formats (#rrggbb, #rgb, rgb(r,g,b), ansi256(n), ansi:<name>)
• THEME-REFERENCE.md — token catalog grouped by purpose, with methodology section showing how the canonical list was extracted from the binary so it can be refreshed for future versions

The methodology is a one-liner: strings -n 4 over the installed binary, then an awk extraction around the preset-object identifier. Token names are factual extractions; descriptions for the 35 documented tokens paraphrase the existing docs, and descriptions for the 34 internal tokens are inferred from naming + surrounding code (clearly badged).

What would help

A few directions, any of which would address the gap:

1. Extend the existing doc page with the missing tokens (or at minimum a note of which groups exist), even if descriptions stay terse for internals.
2. Publish an official JSON Schema to schemastore so users can "$schema": "https://json.schemastore.org/claude-code-theme.json" in their theme files. Happy to PR this if a community-maintained schema is acceptable.
3. Confirm/correct the inferred descriptions in the linked reference so it can be a reliable secondary source while official docs evolve.

Happy to open a docs PR with whatever shape works best for the team. Filed as documentation rather than a feature request since the functionality already ships in v2.1.118+ — it's purely a discoverability gap.

Environment

• Claude Code v2.1.126
• macOS (Darwin 25.2.0)
• Reference derived from ~/.local/share/claude/versions/2.1.126