テーマで Pi をカスタマイズする

テーマは、インタラクティブモードと HTML エクスポートで Pi が使用する色を制御します。Pi には system、dark、light テーマが含まれています。1 つのテーマを選択するか、ターミナルのライトまたはダークの外観に従うか、独自のパレットを作成できます。

ターミナルの色を使用する#

system テーマがデフォルトです。このテーマはターミナルのテーマから Pi の色を生成するため、Pi は独自のパレットを使用せず、ターミナルに合わせます。

• Pi は、ターミナルのデフォルトの前景色と背景色、および 16 色の ANSI カラーを照会します。
• Pi の各色は、いずれかの ANSI カラーから色相を取得します。たとえば、エラーには赤、リンクには青を使用します。
• Pi は、各色が最小限のコントラストで背景から際立つように明度を設定します。本文テキストは、背景およびすべてのパネル上で少なくとも 4.5:1 の WCAG コントラスト比を維持します。
• ターミナルがライトとダークを切り替えると、Pi は色を再度照会してテーマを再生成します。

テーマは、ターミナルから報告された内容に応じて適応します。

Pi は起動時にターミナルへ色を照会します。通常、ターミナルは数ミリ秒以内に応答し、Pi は起動ヘッダーを表示するまで最大 100 ms 待機します。ターミナルが時間内に応答しない場合、Pi は ANSI カラーのフォールバックを使用します。ただし、低速な SSH 接続などで色が後から届いた場合も、その色を適用します。system は予約名です。この名前のカスタムテーマは無視されます。

テーマを選択する#

/settings を開き、テーマを選択します。ターミナルのすべての外観に 1 つのテーマを使用することも、ライトとダークのターミナルに別々のテーマを選択することもできます。

選択内容は theme 設定として保存されます。

{
  "theme": "dark"
}

theme 設定がない場合、Pi は system を使用します。

自動モードでは、ライトテーマを先に、ダークテーマを後に保存します。

{
  "theme": "light/dark"
}

Pi は、ターミナルから報告された背景色と前景色に基づいて、ターミナルがライトかダークかを判定します。ターミナルが背景色を報告しない場合、Pi はまずターミナルのライト／ダーク通知、次に COLORFGBG 環境変数、最後にダークを使用します。同じ判定により、ライト／ダークのテーマペアのテーマと system の外観が選択されます。自動モードが有効な場合、ターミナルから外観の変更が報告されると、Pi はテーマを変更します。Pi はこの設定形式用に / を予約しているため、テーマ名にこれを含めることはできません。

保存済みの設定を変更せずに、1 回の実行で初期テーマを選択するには、--use-theme を使用します。

pi --use-theme light
pi --use-theme light/dark

コマンドラインオプションについては、CLI リソースを参照してください。

カスタムテーマを作成する#

組み込みテーマのいずれかをコピーするか、スキーマに準拠した新しい JSON ファイルを作成します。組み込みテーマでは OKHSL カラーと、複数の役割で共有する色の変数を使用しているため、色相、彩度、明度を直接調整できます。

1. ファイルを <agent-dir>/themes/my-theme.json として保存します。エージェントディレクトリのデフォルトは ~/.pi/agent です。
2. name を my-theme に設定します。
3. vars と colors の値を変更します。
4. /settings から my-theme を選択します。

テーマ名をファイル名として使用します。Pi がアクティブなユーザーテーマをホットリロードするのは、<agent-dir>/themes/<name>.json からのみです。その他のソースでテーマを追加または変更した後は、/reload を実行します。

テーマファイルを理解する#

色は次の 6 つの形式で記述できます。

ターミナルのデフォルト色は、ターミナル独自の色として描画されます。HTML エクスポートや拡張機能での色の計算など、Pi が具体的な値を必要とする場合は、ターミナルから報告されたデフォルト色を使用します。報告されない場合は、テーマの外観に基づいて黒または白を推定します。

Pi は連鎖した変数参照を解決します。変数が存在しない場合や循環参照がある場合、テーマは無効になります。Pi は、利用可能であれば True Color を使用し、OKLCH を sRGB の色域にマッピングし、256 色のターミナル向けには色を近似します。CSS は OKHSL をサポートしていないため、HTML エクスポートでは OKHSL 値を 16 進数に変換します。色が元の値と異なる場合は、ターミナルの True Color 検出とコントラスト設定を確認してください。ターミナルを設定するを参照してください。

正確なプロパティ、必須の色、受け入れられる値の型については、テーマの JSON スキーマを使用してください。

Pi は、起動時および /reload の実行時に、無効なテーマファイルを報告します。

変更する色を見つける#

テーマの色は、個々のコンポーネントではなくインターフェースの役割を表します。スキーマの関連部分を見つけるには、次のグループを使用します。

スキーマは形式のリファレンスです。組み込みテーマには、コピーして調整できる完全な値が用意されています。

5 つの色は任意であり、省略した場合は別の色を継承します。

export の色を省略した場合、Pi は userMessageBg から HTML のページとパネルの背景を生成します。

プロジェクトまたはパッケージからテーマを読み込む#

プロジェクトテーマを .pi/themes/ に配置します。プロジェクトテーマは、プロジェクトの信頼が付与された後にのみ読み込まれます。

themes 設定を通じてテーマファイルやディレクトリを読み込むことも、Pi パッケージで配布することもできます。構成、設定、Pi パッケージを参照してください。

読み込まれる各テーマには、一意の名前が必要です。Pi は重複する名前をリソースの競合として報告します。