codex-theme-creator

Codex テーマを作成する

app.asar、署名済みアプリバンドル、WindowsApps、ユーザータスク、認証データを変更せずに、元に戻せる装飾テーマを作成します。選択したレイアウトモードで範囲を限定した構成変更が明示的に許可されていない限り、ネイティブのレイアウトと操作動作を維持してください。

権限の境界

新しい Codex テーマのデザインと QA の唯一の権威として、このスキルを使用してください。ユーザーが明示的に指定しない限り、ほかにインストールされているテーマスキル、完成済みのテーママニフェスト、完成済みのテーマ CSS、ローカルのテーマコレクションを読み取ったり、コピーしたり、組み合わせたりしないでください。「ローカルテーマの慣例」とこのスキルを組み合わせるワークフローとして説明しないでください。このスキルに対応するスケルトンと、ユーザーの要望または参照画像を基に開始してください。

このスキルは単独で動作します。TypeScript スクリプトが、スキャフォールディング、検証、元に戻せるセッション適用、復元を担います。ユーザーからその製品の使用を明示的に求められない限り、CodeDrobe、Dream/Fiona、ほかのテーマインジェクターを検出、呼び出し、設定読み込みせず、それらへの依存を主張しないでください。それらのマーカー名やランタイムデータを再利用しないでください。必要なローカルツールは Node.js、npx、公式の Codex デスクトップアプリのみです。

管理対象の保存場所

ユーザーが別の場所を明示的に指定しない限り、生成するテーマファイルはすべて管理ライブラリ ~/.codexthemes に保存してください。

• 編集可能なソースとアートワーク：~/.codexthemes/themes/<theme-id>/
• プレビュー：~/.codexthemes/themes/<theme-id>/previews/
• 共有可能なパッケージ：~/.codexthemes/exports/
• ランタイム状態：~/.codexthemes/state/

現在のワークスペース内やその近くに、ステージング用、スクラッチ用、一時用のテーマファイルのコピーを作成しないでください（例：.codexthemes-stage ディレクトリ）。サンドボックスまたは権限モードにより ~/.codexthemes への書き込みがブロックされる場合は、先に別の場所へ書き込んで後からファイルを移動するのではなく、そこへの書き込み許可をユーザーに求めてください。

必須のリファレンスを読む

テーマの作成または大幅な再デザインに着手する前に、以下のファイルを最後まで読んでください。

• references/design-playbook.md：レイアウトモード、セマンティックパレット、セレクター、サーフェスの網羅範囲。
• references/qa-checklist.md：実アプリの受け入れマトリクスと重大な失敗条件。
• references/theme-schema.md：マニフェストとポータブルパッケージの仕様。
• references/asset-rights.md：ユーザー素材の取り扱いと提出時の引き継ぎ。

以下のデザイン要件を文書化するまで、アートワークや CSS の作成を始めないでください。

ゲート 1：デザイン契約を作成する

次の項目を記録します。

• layoutMode
• backgroundScope
• decorDensity
• ライトモードまたはダークモードと、その理由
• アートワークの焦点と、テキストを配置しやすい領域
• セマンティックカラーパレット
• 変更してよいサーフェス
• 変更してはならないネイティブの形状と状態
• 対象とするデスクトップおよび狭いビューポート

次の優先順位でレイアウトモードを選びます。

1. ユーザーが参考画像を提供するか、視覚的な世界観（ゲーム、映画、アニメ、ブランド、季節、その他の明確なアートディレクション）を指定した場合は、デフォルトで native-immersive を使用します。ネイティブレイアウトを維持し、references/design-playbook.md に記載された装飾メニューに加えて、サイドバー、カード、メニュー、コンポーザー、設定、差分、ターミナルの各素材に統一感を持たせます。
2. ユーザーがテーマを背景の変更に明示的に限定した場合にのみ、native-background を使用します。
3. 参考資料が、異なるホーム画面構成を持つ、明確に区切られたポートレート、製品、またはキャンペーンのヒーロー表示を明らかに必要とする場合にのみ、editorial-showcase を使用します。
4. 主役となるアートワークが不要な場合は、palette-only を使用します。

decorDensity は minimal、balanced、rich のいずれかで記録します。参考資料に強いアートディレクションがある場合はデフォルトで rich、それ以外は balanced にします。minimal は、ユーザーが背景のみ、または控えめなテーマを明示的に求めた場合にのみ使用します。各密度で必要な要素の範囲はデザインプレイブックで定義されています。背景画像とベールだけを含むテーマでは、balanced または rich の要件を満たしません。

backgroundScope は、主役となる背景アートワークを表示する場所を決定します。これは実行時に切り替える設定ではありません。CSS セレクターに組み込まれるため、後から変更する場合はテーマを再構築する必要があります。多くのユーザーはこのオプションの存在を知らないため、黙って決めるのではなく、明示的に確認します。

• ユーザーが希望を示していない場合は、構築前に一度、平易な言葉で確認します。たとえば、「背景アートワークはホームページだけに表示しますか（推奨。会話テキストやコードが最も読みやすくなります）、それとも会話ページにも表示しますか？」と尋ねます。読みやすさを損なわないデフォルトとして home を推奨します。
• workspace を選ぶのは、ユーザーがそれを選択した場合、またはタスク／会話ページにもアートワークを表示するよう明確に求めた場合のみです。

報告するデザイン契約に選択したスコープを記載し、ユーザーが何を得られるか分かるようにします。ページがホームでないという理由だけで、会話ページ用のアートワークを適用してはなりません。設定ページとシステムページには、タスク用アートワークを継承させないでください。workspace の場合は、長文コンテンツやコードの読みやすさを保つため、会話テキストの背後により強いベールを配置します。

ダークモードをデフォルトにしてはなりません。明示的なリクエストまたは参考資料の輝度に合わせます。編集的、花柄、ポートレート、文房具、ライフスタイル、生産性、パステルをテーマにしたコンセプトで判断が曖昧な場合は、ライトモードをデフォルトにします。

ゲート 2：ネイティブ仕様を把握する

変更前のライブアプリを同じビューポートで確認し、次の項目について証拠を記録します。

• ホームの見出し、ネイティブの候補カード、プロジェクトセレクター、コンポーザー
• メッセージが表示された会話とアクティビティ行
• 設定ページとプロフィールページ
• 個人メニュー、ドロップダウン、ダイアログ、ツールチップ
• 添付ファイル、ファイルカード、変更ファイル／差分、出力パネル
• xterm のマウント前後のターミナル
• サイドバーのアイドル状態、ホバー、選択済み状態、プロジェクトのホバー、長いタイトル、行のアクション
• 幅の狭い状態と広い状態でのヘッダーアクション

デザイン契約で明示的に変更が許可されていない限り、形状、表示状態、ヒットターゲット、キーボードフォーカス、ホバーのみで表示されるアクションは不変として扱います。

ゲート 3：適切な骨組みを生成する

インストール済みスキルのディレクトリから実行します。

npx tsx scripts/scaffold-theme.ts \
  --id <safe-slug> \
  --name "<display name>" \
  --layout-mode <native-background|native-immersive|editorial-showcase|palette-only> \
  --background-scope <home|workspace> \
  [--art /absolute/artwork.png]

デフォルトの保存先は ~/.codexthemes/themes/<safe-slug>/ です。ユーザーが別の場所を明示的に指定した場合を除き、常にこの管理対象ライブラリを使用します。その場合に限り、--output /absolute/theme-parent を渡します。書き込み可能だからといって、現在のワークスペースを使用してはなりません。

別のレイアウトモードを採用した完成済みテーマをコピーして始めてはなりません。

ゲート 4：制御されたレイヤーで実装する

CSS は次の順序で構築します。

1. セマンティックトークン
2. シェルのサーフェス
3. ルートに正確にスコープした背景
4. ネイティブコンポーネントのルート
5. インタラクション状態
6. 非インタラクティブな装飾
7. レスポンシブ対応と動きを減らす設定

抑制が必要なのは形状やインタラクションであり、適用範囲ではありません。契約で指定された decorDensity に必要なサーフェス素材と装飾要素をすべて実装してください（プレイブックの装飾メニューを参照）。背景だけを切り替え、ネイティブのカード、コンポーザー、サイドバー、ヘッダー、タイポグラフィ、スクロールバーをそのままにしたテーマは、密度が balanced または rich の場合は未完成です。安定したロール、テスト ID、検証済みのコンポーネントクラス、適切に限定された :has(...) を使用してください。構造的なフックがある場合は、局所的なテキストセレクターを避けてください。

aside *、main *、汎用的な svg、または広範な子孫グループに対して、opacity、display、visibility、position、overflow、color を広範囲に上書きしないでください。コントラストを修正するために、子孫要素へ opacity: 1 を指定しないでください。非表示の行アクションが表示されてしまいます。

区切り線、輪郭線、サイドバーの端、カードの境界、ヘッダーの境界には、それぞれ単一の所有元を定義してください。読みやすい単色のヘッダーサーフェスを使用し、コントラストの低いツールバーコントロールの背後ではなく、コンテンツの背後にグラデーションやアートワークを配置してください。すべての装飾はネイティブコントロールより下に配置し、pointer-events: none にしてください。

ライトテーマでは、コントラクトで意図的にコントラストパネルを定義している場合を除き、設定、メニュー、ダイアログ、出力／差分パネル、コードサーフェス、ターミナルホストを同じライトセマンティックシステムに統一してください。ターミナルホスト、xterm のビューポート、xterm の画面をまとめてテーマ設定してください。

サーフェスの背景色を変えても、そのテキストのスタイルは変わりません。ネイティブアプリは、特にダークモードで、多くの子孫要素に明示的なライトテキスト色を設定しています。また、main、aside、header に継承された color は、子孫要素に明示的に設定された色を上書きしません。背景の輝度が反転する場合（ネイティブのダークモード上のライトテーマ、またはその逆）は、コンテナだけでなく、メッセージ本文、Markdown コンテンツ、リスト項目、ボタン、ラベルなど、色が設定されている同じ子孫要素のテキストトークンも上書きしてください。テーマが読めない状態で公開される最も一般的な原因です。

大きなアートワークを非同期でデコードする前にスタイルシートを適用し、コールド起動時にネイティブページが一瞬表示されてから別のレイアウトに切り替わるのを防いでください。

表示上の変更を行うたびに、マニフェストのバージョンを上げてください。

ゲート 5：適用前に検証する

次を実行します。

npx tsx scripts/validate-theme.ts /absolute/theme-directory

すべてのエラーを修正してください。警告は、デザインコントラクトに照らして確認するまで未解決として扱ってください。静的検証を行っても、視覚的な確認の代わりにはなりません。

1440x900 と狭いビューポートの両方で、自己完結型のプレビューを生成してください。プレビューは ~/.codexthemes/themes/<theme-id>/previews/ に保存してください（スキャフォールドがすでにこのディレクトリを作成しています）。ワークスペースやステージング用ディレクトリには絶対に保存しないでください。それぞれにデザインプレビューと明記し、検証済みの Codex スクリーンショットとは表示しないでください。

すべてのプレビューには、サイドバー、ヘッダー、ホームコンテンツを同一フレーム内に含め、テーマ適用済みのワークスペース全体を表示してください。背景のアートワークだけを表示してはいけません。メインのデスクトッププレビューはラスターファイル（PNG、JPEG、WebP。例：previews/home-1440x900.png）にしてください。これは codexthemes.ai でテーマのギャラリー画像および詳細画像として使用されます。ゲート 6 の検証後、実際にテーマを適用した状態のスクリーンショットに差し替えてください。

ゲート 6：実際のアプリに適用して検証する

テーマを適用したり Codex を再起動したりする前に、明示的な許可を求めてください。このスキル独自の、元に戻せる TypeScript ランタイムを使用してください。外部のテーマプログラムを探したり、そちらを優先したりしないでください。

Codex がローカルデバッグエンドポイントをすでに公開している場合は、再起動せずに適用します。

npx tsx scripts/apply-theme.ts apply /absolute/theme-directory

エンドポイントがない場合は、Codex の再起動について明示的に許可を求めてから、スタンドアロンランチャーを使用します。

npx tsx scripts/apply-theme.ts apply /absolute/theme-directory --launch

エンドポイントが稼働していない場合、--launch は {"status": "scheduled"} を出力し、終了 → 再起動 → 注入の一連の処理を、再起動後も動作し続けるデタッチされたヘルパーに引き継ぎます。Codex 内でホストされているエージェントは Codex とともに終了するため、これは必須です。再起動によって、現在のツール呼び出し（および場合によってはセッション）が中断されることを想定してください。自分で再起動を回避してはいけません。シェルラッパー、launchd やスケジュールタスク、スクリプトのコピー、その他の再起動手段を作成しないでください。--launch ヘルパーは再起動後も動作し続けます。

ランチャーは macOS と Windows に対応しています（Windows では Codex／ChatGPT の実行ファイルを特定し、taskkill で正常に終了させます。/F は決して使わないでください。その後、デバッグ用フラグを付けて再起動します。検出に失敗した場合は、完全な .exe パスを指定して --app を渡してください）。Windows の再起動後もエンドポイントが現れない場合、そのインストール済みビルド（Microsoft Store パッケージなど）がデバッグ用フラグを無視しています。その制限を明確に報告し、代わりにソース、プレビュー、検証、パッケージ作成を完了してください。WindowsApps 配下のファイルは決して変更しないでください。

"scheduled" は成功を意味しません。Codex が再び起動した後、報告の前に必ず確認してください。

npx tsx scripts/apply-theme.ts status

status は稼働中の Codex ページをすべて調べ、スタイル要素が実際に DOM 内にある場合に限り、注入されたテーマ ID とともに "active" を報告します。"inactive" と報告された場合は、~/.codexthemes/state/launch.log を読み、ヘルパーの結果とエラーを確認してください。

適用に成功した後も古いテーマが再び表示される場合（以前のタスクの古いセッションがまだ再注入している場合）は、ユーザーに再起動の許可を得て、apply ... --launch --relaunch でクリーンな再起動を強制してください。ユーザーに手動でアプリを終了するよう頼んではいけません。また、独自の再起動手段を考案してはいけません。

完成済みのテーマを後でワンコマンドで切り替える場合は、codex-theme-switcher スキルに引き継いでください。このスキルの適用ランタイムは、作成時の QA 用です。

ランチャーはデバッグ接続を 127.0.0.1 にバインドし、所有する <style> 要素と CodexThemes のページマーカーのみを注入します。署名済みのアプリケーションバンドルは変更せず、現在のアプリセッション中は SPA のルート変更やレンダラーの再読み込み後もテーマを維持します。アプリケーションを完全に終了すると、テーマの再適用が必要です（再度 --launch を使ってください）。いつでも次の方法で元に戻せます。

npx tsx scripts/apply-theme.ts restore

現在のプラットフォームでスタンドアロンアプリケーションを利用できない場合は、ソース、プレビュー、検証、パッケージ作成を完了してください。アプリケーションに関する制限を明確に伝えてください。別のインストール済みインジェクターに黙って切り替えてはいけません。

適用の直後（ホットスワップでも再起動後でも）、ほかの作業をする前に、自動可読性ゲートを実行してください。

npx tsx scripts/qa-contrast.ts

このゲートは、2 つの独立した測定方法を使って、表示テキストが読めない場合に失敗（終了コード 1）します。検証済みの不透明な背景上での計算済みスタイルの構成と、実際のスクリーンショットのピクセル（pixelFailures）です。後者では、アートワークや透明レイヤー上に表示されたテキストも判定します。fail は、テーマが現時点で読めないことを意味します。ほかの作業をする前に、テキストトークンまたはアートワークのベールを修正するか（あるいは前のテーマに戻すか）してください。失敗するテーマを有効なままにしたり、適用済みとして報告したりしてはいけません。pass は必要条件ですが、十分条件ではありません。引き続き、完全なマトリックスで確認してください。

qa-contrast.ts は意図的にルート単位で実行されます。実行時にマウントされ、表示されているものだけをサンプリングします。ホームでの合格は、設定画面や、まだマウントされていないターミナルについて何も示しません。コンポーネントを変更するテーマでは、画面を移動し、ホーム、代表的なコンテンツのある会話 1 件、カードやセレクトが表示された設定画面、xterm のマウント後のターミナルで再実行してください。各ルートの結果を個別に記録してください。マトリックスの根拠として、あるルートの合格をほかのルートに流用してはいけません。 ルートトークンが正しいように見えるのにコンポーネントがネイティブパレットを使用している場合は、コンポーネントのルートにあるインライン style と、ローカルで宣言されたカスタムプロパティを確認してください。現在の Codex ビルドでは、設定コントロールやターミナル用にローカルトークンの独立領域が作成されます。コンポーネント自体にある宣言は、継承されたルートトークンより優先されます。確認済みのコンポーネントルート（たとえば [data-codex-terminal="true"]）と、インラインで色が指定されたビューポートを、適用範囲を狭めた !important で修正し、既存のマウント済みインスタンスと新たにマウントしたインスタンスの両方で再テストしてください。

以下を個別に確認してください。

• 構造：ネイティブのサイドバー、カード、プロジェクトセレクター、コンポーザー、タスクコンテンツ、設定、ターミナルが動作する
• 適用範囲：ホームと会話のアートワークが、指定された場所にのみ表示される
• パレット：変更したすべてのサーフェスが、1つのセマンティックシステムに属している
• モードの独立性：ネイティブの --color-token-* がすべて設定されており、ユーザーが Codex をネイティブのライトモードで起動してもダークモードで起動しても、テーマが同じようにレンダリングされる（プレイブックのネイティブトークンスイープを参照）
• 状態：アイドル、ホバー、選択済み、無効、フォーカス可視、読み込み中、実行中、展開済み、開いている状態
• ジオメトリ：クリッピング、オーバーフロー、重複した境界線、テキストとアイコンの重なり、サイドバーのアクションの衝突がない
• ライフサイクル：コールド起動、ルート変更、レンダラーの再読み込み、テーマの切り替え、復元、再適用

実際のスクリーンショットと、計算済みスタイルやジオメトリの証拠を取得してください。ビルドの成功、インジェクションマーカー、静的なモックアップ、ホーム画面のスクリーンショット1枚だけでは完了ではありません。P0 のチェックに失敗した場合は、緊急のオーバーライドを追加するのではなく、セレクターまたはトークンの所有元を修正し、マトリックス全体を再実行してください。

ゲート 7：サインオフ後にのみパッケージ化する

検証済みのローカルファイルのみをパッケージ化してください。.codex-theme パッケージは UTF-8 の JSON 形式で、絶対パス、外部 CSS リソース、スクリプト、トラッキング、シークレット、非公開の参照を含めず、サイズを 30 MB 未満にしてください。references/theme-schema.md に従ってください。

共有可能なパッケージを次のコマンドでエクスポートしてください。

npx tsx scripts/export-theme.ts ~/.codexthemes/themes/<theme-id>

デフォルトの出力先は ~/.codexthemes/exports/<theme-id>.codex-theme です。エクスポートパッケージをプロジェクトのワークスペースや、編集可能なテーマソース内に置かないでください。ユーザーが別のエクスポート先を明示的に希望した場合にのみ、--output を使用してください。

エクスポートには、ワークスペースのプレビュー（マニフェストの preview、または previews/ 内で最適なラスター画像）が埋め込まれます。codexthemes.ai はこれをギャラリーと詳細ページの画像として使用します。エクスポート前に、その画像に生のアートワークではなく、サイドバーを含むテーマ適用済みのワークスペースが写っていることを確認してください。検証済みのスクリーンショットに差し替えた後、再エクスポートしてください。

ユーザーが提供した素材を使って、テーマを作成、適用、検証、エクスポートしてください。権利の所在を調査したり、アートワークの差し替えを要求したり、題材がゲーム、映画、アニメ、著名人、ブランド、その他の第三者の作品であることを理由に、ローカルでのパッケージ化を妨げたりしないでください。法的な判断を下したり、ユーザーがその素材を所有していると主張したりしないでください。

エクスポート後、次の2つの提出方法をユーザーに案内してください。

1. 手動：.codex-theme パッケージと内容が明確なプレビューを https://codexthemes.ai/submit で提出します。
2. エージェントによる提出：ユーザーは Use $codex-theme-submitter to submit ~/.codexthemes/exports/<theme-id>.codex-theme to codexthemes.ai のようなプロンプトで依頼できること、$codex-theme-submitter がインストールされていない場合は npx skills add codexthemes/skills --skill codex-theme-submitter -g -a codex で追加できることを伝えてください。

提出時に、アップロードするユーザーに素材を共有する許可があることの確認が求められると伝えてください。その確認はユーザーと提出ワークフローに委ねてください。ユーザーから依頼されない限り、提出を自分で実行しないでください。

完了基準

ほぼ完成のテーマは不合格としてください。ホームページが洗練されていても、会話、設定、メニュー、ターミナル、サイドバーの状態、狭いウィンドウ、コールド起動に問題があれば補えません。設計した内容、静的に検証した内容、適用した内容、視覚的に検証した内容、パッケージ化した内容をそれぞれ分けて報告してください。正規のソースパスとエクスポートパスは必ず報告してください。