プラグインテーマでClaude Codeの配色をチームに配布する

配色をチーム全員に配りたいときの選択肢

プラグインはthemes/ディレクトリにJSONファイルを置くだけで、独自のカラーテーマを配布できます。インストールしたユーザーの/theme一覧に、組み込みプリセットと並んで表示されます。各自がファイルをコピーする手間はかかりません。

この仕組みはv2.1.118(2026年4月23日)で入りました。同じリリースで、/themeから名前付きカスタムテーマを作って切り替える機能も加わっています。個人が配色を作る機能と、それをプラグインで配る機能が同時に揃ったことになります。

配色を配る手段は、状況によって変わります。

ブランドカラーを揃えたい、社内標準の配色を全員に使わせたい、という場面ではプラグイン側が向きます。個人の好みを試すだけなら、~/.claude/themes/で足ります。

テーマファイルの書き方

themes/配下に、1テーマ1ファイルで<slug>.jsonを置きます。フィールドはname・base・overridesの3つです。

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

3つのフィールドはいずれも省略できます。

overridesは疎(スパース)なマップです。変えたい色だけを書けば、残りはbaseの色がそのまま使われます。ブランドカラー1色だけを差し替えた軽量なテーマも、数行のoverridesで作れます。

色の値は#rrggbbと#rgb、rgb(r,g,b)、ansi256(n)、ansi:<name>が使えます。ansi:<name>の<name>は、redやcyanBrightのような16色のANSI色名です。ターミナル標準の16色に寄せたい配色でも書きやすい形式です。

ブランドカラーだけでなく、プランモードの枠線や差分表示の背景、メッセージの背景色まで同じoverridesで変えられます。次の例は、土台のダークテーマに複数のグループのトークンを重ねたものです。

{
  "name": "Midnight",
  "base": "dark",
  "overrides": {
    "claude": "#a78bfa",
    "planMode": "#38bdf8",
    "diffAdded": "#14532d",
    "diffRemoved": "#7f1d1d",
    "userMessageBackground": "#1e1b4b"
  }
}

使えるトークンの一覧は、themeコマンドの解説にまとまっています。プラグイン側で新しく覚える書式はありません。個人用のカスタムテーマと同じファイル形式だからです。

宣言方法とパスの変更

既定ではthemes/ディレクトリがそのままスキャンされます。plugin.jsonのexperimental.themesにパスを書くと、別の場所に置いたディレクトリやファイルを読み込ませられます。

{
  "name": "team-colors",
  "experimental": {
    "themes": "./themes/"
  }
}

experimentalの下にあるのは、マニフェストの形がまだ変わりうる実験的な項目だからです。公式のリファレンスでは、themesとmonitorsとevalsがここに入ります。パスは1つでも配列でも書けます。

注意したいのは、このキーを書くと既定のthemes/のスキャンが置き換わる点です。./extra-themes/だけを指定すれば、themes/のファイルは読み込まれません。両方を使いたいなら、["./themes/", "./extra-themes/"]のように既定のパスも明示します。

v2.1.289でclaude plugin validateの挙動を確かめる

最小のプラグインでclaude plugin validate(v2.1.289)を実行すると、宣言の書き方で結果が次のように変わります。

experimental.themesに書いたときは、警告はversion・description・authorの未記載だけでした。トップレベルのthemesに書き直すと、次の警告が1件増えます。

❯ themes: 'themes' is an experimental component; declare it under
  'experimental.themes' instead of at the top level. Top-level still
  loads for now but will be removed in a future release.

トップレベルの書き方は今も読み込まれますが、メッセージは将来のリリースで削除されると告げています。新しく書くプラグインは、最初からexperimental.themesにするほうが移行の手間がありません。

存在しないパスを指定した場合は、警告でなくエラーになります。

✘ Found 1 error:
 
  ❯ experimental.themes: Path not found: ./nope/. The runtime loader will
    report this as a load failure.
 
✘ Validation failed

一方で、テーマ側のJSONに存在しないトークン名(bogus)を書いても、検証は通りました。トークン名の誤りはvalidateでは見つからないため、色の反映は実際に/themeで見て確かめる必要があります。公式の仕様でも、未知のトークンや不正な色の値は無視されます。タイプミスで表示が崩れることはありませんが、色が変わらないだけで気づきにくい点でもあります。

CIで警告も失敗扱いにしたいときは、--strictを付けます。claude plugin validate --helpには、警告をエラーとして扱い、終了コード1で止める指定だと書かれています。トップレベルのthemesの取り残しを、配布前に機械的に止められます。--jsonを付ければ、検証結果をJSONで受け取れます。

配布前にローカルで確認する

公開する前に、--plugin-dirフラグで自分のプラグインを読み込めば、インストールなしで動作を確かめられます。

claude --plugin-dir ./my-plugin

起動後に/themeを開き、次の3点を見ます。

ライトとダークの両方の環境で、見え方が崩れていないかも切り替えて見ておくと安心です。

作り方の近道は対話エディタで下書きすること

themes/のJSONは、ユーザーが~/.claude/themes/に作るカスタムテーマと同じ形式です。ゼロから手書きするより、対話エディタで形にしてから移すほうが早く済みます。

まず自分の環境で、/themeの一覧の末尾にあるNew custom theme…から配色を作ります。リアルタイムのプレビューを見ながら、変えたいトークンを選んで色を決められます。できあがったファイルを~/.claude/themes/からプラグインのthemes/へコピーし、必要ならnameを調整します。

~/.claude/themes/は、ファイルの追加や変更を監視して再読み込みされます。エディタで直接書き換えた内容も、動作中のセッションに反映されます。ただし、このフォルダ自体が起動時に存在しなかった場合は、最初のテーマファイルを作ったあとに1回だけ再起動が必要です。

個人のカスタムテーマは、/themeの一覧で選択中のテーマにカーソルを合わせてCtrl+Eを押すと編集できます。対話エディタには、リファレンスの表に載っていない単一用途のアクセント(オンボーディング画面の色など)も並びます。表にない色まで触りたいときは、エディタで一度開いてみると手がかりになります。

複数のテーマを配るなら、最初の1つだけ対話エディタで仕上げます。残りは、コピーしたファイルのoverridesの差分だけをJSONで直接直すほうが速く済みます。

ユーザーの画面にどう見えるか

プラグインのテーマは、/themeの一覧にnameの名前で並びます。どのプラグインのテーマかも示されます。個人のカスタムテーマも同じ一覧に並びます。

プラグインが配るテーマは読み取り専用です。ユーザーが/themeでそのテーマを編集すると、編集内容は元のファイルでなく、ユーザー自身のテーマディレクトリにコピーとして保存されます。配布側のファイルは、ユーザーが手元で微調整しても元の配色のままです。

テーマの<slug>は、保存するファイル名(themes/<slug>.json)です。複数のテーマを配るプラグインでは、分かりやすいファイル名を付けておくと管理しやすくなります。

Claude Codeの標準機能だけでテーマを配るので、フックやMCPサーバーのようにコマンドを実行する設定は含まれません。テーマのファイルに入るのは、名前と土台の指定と色の値だけです。

有効化と配色の選択は別の話

プラグインのテーマは/themeの選択肢に並び、使うにはユーザーが選びます。配色をチームで揃えたいときは、/themeでの選び方を手順として伝えておく方法があります。/themeの使い方を、あわせて共有しておくと迷いません。

よくあるつまずき

• baseにautoを指定してしまう: baseに書けるのは組み込み6種類(dark light dark-daltonized light-daltonized dark-ansi light-ansi)です。autoはその一覧にありません
• 存在しないトークン名をoverridesに書く: エラーにならず無視される。claude plugin validateも通るため、反映されないときはタイプミスをまず疑う
• トップレベルのthemesのまま放置する: 今は動くが、validateが警告を出し、将来のリリースで削除されると案内される。新しく書くならexperimental.themesから始める
• experimental.themesでパスを変えたのに旧ディレクトリを残す: 指定したパスだけが読まれ、旧themes/のファイルは読み込まれない。移行はパスの変更とファイルの移動をセットで行う
• 存在しないパスを指定する: claude plugin validateがエラーを返し、読み込みも失敗する。パスの検査はv2.1.283以降で動く
• プラグインのテーマを直接書き換えられると思い込む: 読み取り専用です。配布元のテーマを直したいときは、プラグイン自体を更新します

配色の要件別の選び方

まとめ

claude plugin validateは、overridesのトークン名が間違っていても通します。配布前に--plugin-dirで/themeを開き、色が狙った場所に出ているかを目で見る作業が、誤りを見つける唯一の手段です。