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

プラグインテーマでできること

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

チームでブランドカラーを統一したい、社内標準の配色を全員に配りたいといった場面に向きます。配色をdotfilesで個別に共有するより、プラグインの更新1回で全員に行き渡る点が違いです。

プラグインがテーマを配布できる仕組みは、/themeにカスタムテーマの作成・切り替え機能が加わったv2.1.118と同時期に整備されました。エンドユーザーが自分の配色を作る機能と、開発者がそれをチームに配る機能が、ほぼ同じタイミングで揃った形です。

テーマファイルの書き方

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

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

色の値の形式や個々のトークン名は、エンドユーザーがカスタムテーマを自作するときと同じ仕様です。使えるトークンの一覧や色指定の書式はthemeコマンドの解説にまとまっています。プラグイン側で新しく覚える書式はありません。色は#rrggbbのような16進表記のほか、rgb(r,g,b)やANSIカラー名を指すansi:<name>でも指定できるので、ターミナル標準の16色に寄せたい配色でも書きやすくなっています。

overridesは名前のとおり疎(スパース)なマップです。すべてのトークンを埋める必要はなく、変えたい色だけを書けば、それ以外はbaseで指定した組み込みテーマの色がそのまま使われます。ブランドカラー1色だけを変えた「ダークテーマ+アクセントカラーだけ差し替え」のような軽量なテーマも、数行のoverridesだけで作れます。

宣言方法とパスの変更

既定ではthemes/ディレクトリがそのままスキャンされます。plugin.jsonのexperimental.themesにパスを指定すれば、別の場所に置いたディレクトリやファイルを使うこともできます。

{
  "experimental": {
    "themes": "./themes/"
  }
}

experimentalキーの下にあるのは、themesの仕様がまだ固まりきっていない実験的コンポーネントだからです。トップレベルのthemesフィールドも当面は動きますが、claude plugin validateが警告を出すようになっており、将来のリリースではexperimental.themesへの移行が必須になる見込みです。

作り方の近道 — 対話エディタで下書きしてから移す

themes/のJSONファイルはユーザーがカスタムテーマを作るときと全く同じスキーマです。ゼロからJSONを手書きするより、対話エディタで下書きするほうが早く形になります。まず自分の環境で/themeのNew custom theme…から対話的に配色を作り、できあがったファイルを~/.claude/themes/からプラグインのthemes/ディレクトリへコピーしてnameを調整するだけです。リアルタイムプレビューを見ながら調整できるのは対話エディタ側だけなので、細部の作り込みはそちらで済ませてしまうのが効率的です。

配色の候補が複数あるなら、まず1つを対話エディタで仕上げてからコピーし、残りはoverridesの差分だけをJSONで直接調整するほうが速く済みます。ファイルを1つずつ対話エディタで作り直す必要はありません。

社内ブランドの配色だけを配りたいなら、社外に公開する必要はありません。プライベートリポジトリでプラグインマーケットプレイスをホストすれば、チーム内だけにテーマを届けられます。社外にも公開したい場合は、コミュニティマーケットプレイスへの申請フォームから提出する経路が別に用意されています。

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

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

claude --plugin-dir ./my-plugin

起動後に/themeを開き、一覧に想定した名前でテーマが表示されるか、baseが意図どおり反映されているか、overridesの色が思ったとおりに出ているかを確認します。ここでCtrl+Eを試しておけば、配布後にユーザーが体験する「コピーしてから編集する」流れも自分の目で確かめられます。ライト・ダーク両方の環境で見え方が崩れていないかも、公開前にひととおり切り替えて確認しておくと安心です。

ユーザー側にどう見えるか

ユーザーがプラグインのテーマを/themeから選ぶと、設定ファイルにはcustom:<plugin-name>:<slug>という値が保存されます。個人が作ったカスタムテーマのcustom:<slug>とは名前空間が分かれているため、同名のテーマがあっても衝突しません。

プラグインが配布するテーマは読み取り専用です。ユーザーが/themeの一覧でプラグインテーマをハイライトしてCtrl+Eを押すと、Claude Codeはそのテーマを~/.claude/themes/にコピーしてから編集を始めます。元のプラグインテーマ自体は書き換わりません。配布側からすると、ユーザーが手元で微調整しても配布元のファイルは常に元の配色を保つということです。

個人が作るカスタムテーマでは、ファイル名(拡張子を除いた部分)がそのままテーマのスラッグになります。プラグイン側の<slug>もファイル名に由来すると見てよく、themes/に置くファイル名がそのままcustom:<plugin-name>:<slug>としてユーザーの目に触れる可能性があります。分かりやすい名前を付けておくほうが、複数のテーマを配るプラグインでは見分けやすくなります。

動作条件

テーマ配布そのものに、monitorsのような対話セッション限定や面ごとの可用性制約はありません。/themeが使える環境であれば、プラグインのテーマもそのまま一覧に表示されます。

テーマの定義ファイルには色の値と参照名だけが入り、コマンドを実行するフィールドはありません。hooksやmonitors、MCPサーバーのようにコマンドの信頼レベルを気にする必要がなく、配布の障壁がその分だけ低いコンポーネントです。

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

プラグインを有効にしても、そのテーマが自動で選ばれるわけではありません。/themeの一覧に並ぶだけで、実際に使うかどうかはユーザーが選択して初めて決まります。チーム全体に配色まで含めて強制したい場合は、プラグインのテーマ配布とは別に、settings.jsonのthemeキーへ"custom:<plugin-name>:<slug>"を書いてリポジトリにコミットしておく方法を組み合わせます。この2つは独立した仕組みなので、テーマを配るだけなら前者、既定で適用したいなら両方を使う、という組み合わせ方になります。

よくあるつまずき

• baseにautoを指定してしまう: autoは自動判定用の特別な値で、baseには使えません。組み込み6種類(dark light dark-daltonized light-daltonized dark-ansi light-ansi)から選ぶ
• 存在しないトークン名をoverridesに書く: エラーにはならず、単に無視されます。反映されないときはタイプミスをまず疑う
• トップレベルのthemesフィールドのまま放置する: 動作はするもののclaude plugin validateが警告を出す。新規に書くならexperimental.themesから始めたほうが移行の手間がない
• プラグインテーマを直接書き換えられると思い込む: 読み取り専用なので、ユーザー側の変更は~/.claude/themes/にコピーされた別ファイルにしか反映されない。配布元のテーマを更新したい場合はプラグイン自体を更新する
• experimental.themesでパスを変えたのに旧ディレクトリを残したまま: 参照先が新しいパスに切り替わるため、旧themes/ディレクトリのファイルは読み込まれなくなる。移行時はパスの変更とファイルの移動をセットで行う

使い分け早見表

よくある質問

1つのプラグインに複数のテーマを同梱できますか

できます。themes/ディレクトリに複数のJSONファイルを置けば、ファイルごとに1つのテーマとして/themeの一覧に並びます。

プラグインのテーマを更新すると、既にインストール済みのユーザーにも反映されますか

プラグイン自体の更新に追随する形で反映されます。ユーザーがCtrl+Eでコピーして個別に編集したテーマは、そのユーザーのローカルファイルなので更新の影響を受けません。

overridesを空にすると何が起きますか

baseで指定した組み込みテーマがそのまま使われます。まずはbaseだけを指定して配布し、必要なトークンだけ後からoverridesに足していく進め方もできます。

色覚多様性対応のテーマをプラグインで配布できますか

できます。baseにdark-daltonizedまたはlight-daltonizedを指定したうえで、overridesでブランドカラーなど一部のトークンだけ調整する組み合わせが使えます。

テーマ配布のためだけに新しいプラグインを作る必要がありますか

いいえ。プラグインで必須のフィールドはnameだけで、skillsやhooksなど他のコンポーネントを持たない、テーマ専用のプラグインを作ることもできます。逆に、既に配布しているプラグインにthemes/ディレクトリを追加するだけでも成立します。

プラグインを有効にすると配色も自動で切り替わりますか

いいえ。プラグインを有効にしただけでは配色は変わりません。ユーザーが/themeから明示的に選ぶか、settings.jsonのthemeキーで指定して初めて適用されます。

まとめ

プラグインのthemes/ディレクトリは、name・base・overridesの3フィールドだけでカラーテーマをチーム全体に配布できる仕組みです。ユーザー側では/themeの一覧に自動的に並び、custom:<plugin-name>:<slug>という専用の名前空間で管理されます。読み取り専用で配布され、ユーザーが編集したい場合はCtrl+Eでコピーが作られる点を踏まえておくと、「配布元が勝手に書き換わるのでは」という誤解を避けられます。個人の好みで配色を試したいだけならローカルのカスタムテーマで十分ですが、組織で配色を統一したい場合はプラグインでの配布が向いています。

書き方自体は個人がカスタムテーマを作るときと同じスキーマなので、新しく学ぶことは多くありません。むしろ検討が要るのは公開範囲(社内限定にするか、公開マーケットプレイスに申請するか)と、experimental.themesへの移行を早めに済ませておくかどうかという運用面です。