テーマ SDK 概要
テーマ SDK は、NeoTavern のビジュアルシェル全体を置き換えるためのバージョン管理されたコントラクトです — 色を変えるだけではありません。
テーマ SDK とは
テーマは、アプリケーションの見た目とメイン領域の構成を制御するパッケージ（.sttheme）です。プラグインとは異なり、テーマには JavaScript がありません: マニフェスト内の CSS、セマンティックトークン、宣言型シェルレイアウトです。SDK は宣言型であるため、テーマはアプリケーションの動作を壊したり、データに到達したりできません。
@neotavern/theme-sdk パッケージはコントラクト自体を提供します: 正規のトークン名、マニフェスト検証、継承解決、CSS 変数の生成です。ホストのリファレンス実装は、--st-* カスタムプロパティをドキュメントルートに書き込み、テーマのスタイルシートを定義された順序で読み込むことでテーマを適用します。
3 つのレベル
テーマは 3 つのレベルで構成され、テーマはそのいずれも使用できます:
- デザイントークン — 色、フォント、間隔、角丸、影、z-index レイヤー、モーション、コントロールサイズのためのセマンティック変数。コンポーネントはこれらのトークンのみを参照するため、トークンをオーバーライドするとインターフェース全体が一貫して再スタイリングされます。
- コンポーネントスキン — 安定した
data-component、data-part、data-role、data-stateフックを通じてコンポーネントを再スタイリングする CSS。 - シェルレイアウト — メイン領域の宣言型構成: ナビゲーションレール、管理パネル、チャットワークスペース。
チャットロジック、データモデル、動作は手を付けられないため、テーマはオペレーティングシステム、ゲームコンソール、ビジュアルノベルインターフェース、モバイルアプリレイアウトを、機能を壊さずに模倣できます。詳細はレベル を参照してください。
ビルドステップなしの作成
テーマは theme.json、components.css、shell.css を含む ZIP です。手で 1 つ構築できます:
- テーママネージャーを開き、テーマスターターキットをダウンロードします。
- 解凍して
theme.json、components.css、shell.cssを編集します。 - ファイルをアーカイブルートで再 ZIP してパッケージをインストールします。
- ライトモードとダークモード、モバイル、キーボードフォーカス、RTL、セーフモードを確認してから、テーマを適用します。
最初のテーマに Node.js、npm、JavaScript、テーマ SDK CLI は必要ありません。
インストールと有効化
パッケージのインストールは有効化しません。有効化は、欠落した親と循環について extends チェーン全体を検証してから、有効なテーマと保存されたテーマ選択を 1 つのトランザクションで更新します。同じ id のパッケージのアップデートは、ディレクトリをアトミックに置き換え、現在の有効化状態を保持します。レジストリエラー時には前のディレクトリが復元されます。
ディストリビューションには AMOLED、GitHub Dark、Matrix、Nord、Gruvbox、Dracula、Tokyo Night、Catppuccin Mocha、Solarized Dark、One Dark などの一連の組み込みテーマが同梱されているため、テーママネージャーが空で開くことはありません。
安全性
テーマはチャット、API キー、ファイルシステムを読み取れず、実行可能コードを含みません。すべてのスタイルシートは禁止構造がないかスキャンされ、セーフモードはサードパーティのテーマを完全に無効化します。保証についてはセーフモード を、完全な API は生成されたテーマ SDK リファレンス を参照してください。
次のステップ
- レベル — トークン、スキン、シェルレイアウト。
- デザイントークン — セマンティックトークンのコントラクト。
- コンポーネントスキン — スタイリングスタックとフック。
- シェルコントラクト — 名前付き領域と安定したスロット。
- セーフモード — 壊れたテーマからの復旧。