phoenix-ui

Phoenix UI は、フロントエンド作業向けのローカルデザインツールを提供します。プロジェクトのプロダクトに関する事実、採用済みの方針、デザインルールに従い、コマンドリファレンスを使って、明確なビジュアル方針を備えた、完成度が高くアクセシブルなインターフェースを作成してください。

このランタイムは npm の @xgent-ai/skills を通じてインストールしてください。skills.sh からコピーしたソースには、エンジンのインストールは含まれません。コンテキストの取得、検出、フックの実行中に、エンジンが更新またはダウンロードされることはありません。明示的に engine install を実行すると、インストール済みパッケージに固定されたバージョンに戻せます。

基本原則：

• 全力を尽くしてください。妥協や近道はありません。成果物は完成している必要があります（ユーザーが提供する必要のあるアセットを除きます）。
• 大きく大胆な発想で取り組んでください。独創的で美しく、際立ち、強く心を動かす作品を目指してください。
• Phoenix のデザインに関する自己 QA は、まとめて行う 1 回の検査と、指摘事項を修正した後の確認 1 回以内にしてください。この上限はデザイン工程に適用されます。独立した review-ui/apply-ui-review サイクル、およびユーザーが許可した作業には、それぞれ独自の完了条件が適用されます。Finish-reviewer とコンポーネントレビューの証跡では、独立した UI 受け入れサイクルは完了しません。

セットアップ

1. セッションごとに 1 回、<skill-base-dir>/scripts/phoenix-ui context を実行してください。ここで、<skill-base-dir> はこの SKILL.md が格納されている場所を指します。作業ディレクトリはユーザーのプロジェクトにしてください。このコマンドは、このスキルおよびそのリファレンス内にあるすべての <skill-base-dir>/scripts/phoenix-ui <verb> コマンドの解決に使われます。このリリースは macOS と Linux に対応しています。軽量ランチャーには Node >=18 が必要で、実行前に固定マニフェスト、バイナリのダイジェスト、Phoenix エンジンのバージョンを検証します。ユーザーが Rust を用意する必要はありません。名前付きのソースファイルまたはルートを --target <path> で指定してください。このコマンドは PRODUCT.md、DESIGN.md、対応するサーフェスブリーフ、ネイティブプラットフォーム向けガイダンスを読み込みます。その指示に従ってください。 デザインに関する事実を確認する場合は、<skill-base-dir>/scripts/phoenix-ui context --target <primary-target> --json も読み込んでください。product、design、surfaceBrief、provenance、parseCoverage、conflicts は、それぞれ元の情報源を保持しています。カバレッジが部分的な場合は、元の情報を読んでください。明示的に有効化されたプロファイルは参考情報を提供しますが、プロダクトに関する事実、採用済みの方針、固定された対象が優先されます。コンテキストが不足している場合やプロファイルが無効な場合、テンプレートのデフォルト値は提供されません。JSON モードを利用できない場合は、元のファイルを直接読み、プロファイルとブリーフのマッピングが読み込まれていないことを明記してください。付随してインストールやアップグレードを行ってはいけません。
2. リクエストに対応するプレイブックを読み込んでください。明示または暗示されたサブコマンドがある場合は、Commands テーブルのリファレンスを参照してください。新しいサーフェスまたはビジュアル世界全体の置き換えの場合は、reference/new-work.md を参照してください。編集前に、対象と既存のビジュアルに関する事実を確認してください。アプリを実行できない場合は、コミット済みのビジュアルリグレッション用ゴールデン画像またはスクリーンショットフィクスチャから始めてください。現在のトークン、CSS、コンポーネント、アセットに照らして対象と鮮度を検証し、競合を解決して、テーマ／バリアントのキャプチャを比較してください。
3. 分析と方針を確定したら、UI の編集に入る直前に reference/craft-floor.md を読んでください。小さな調整の場合も同様です。ここには品質の最低基準、絶対に行ってはならないこと、検出ツールでは捉えられない基本動作が記載されています。計画だけを行う場合は読み込まないでください。

ランチャーが利用できない場合： 拒否または失敗した場合は、次のツール呼び出しの前に別のメッセージを送り、「コンテキストの読み込みを実行できませんでした。既存のプロジェクトコンテキストを直接読みます。」と伝えてください。その後、コンテキストを捏造せずに既存の PRODUCT.md と DESIGN.md を読み、該当する手順 2～3 に従い、利用可能なツールを使って作業を続けてください。この手順は計画と編集の両方に適用されます。ランチャーの失敗だけを理由に、いずれかを中断する必要はありません。

設計方法

• ブリーフを最優先します。 飽和したパターンに関する警告と矛盾する場合でも、指定された美的方向性、時代、素材、フォント、配色を尊重してください。明確なブリーフを自分の好みに誘導するのは失敗です。
• 改良は維持し、再設計は置き換えます。 改良では、既存のアイデンティティ、挙動、コピー、スコープ外のすべてを維持します。事実に関するコピーを置き換えたり、主張を追加したりする前に確認してください。再設計では、プロダクトの事実、コンテンツ、機能、ネイティブな操作性、制約を維持し、許可されたスコープ内で置き換える世界観を選びます。既存の DESIGN.md の変更には、design-md の記述権限とユーザーが承認した決定が適用されます。凍結された対象を置き換える前に、変更の承認を記録してください。
• ビジュアルの判断基準は証拠であり、ファイル名ではありません。 DESIGN.md がないだけで、プロジェクトがグリーンフィールドだと判断してはいけません。既存の世界観を維持、拡張、置換するかは、new-work が決定します。

モード

モードは、この画面で訪問者がどのような状態になれば成功かを表します。

• 説得： 訪問者が決断し、行動します。デザインがプロダクトです。ランディングページ、マーケティング、キャンペーン、価格設定が該当します。関心と行動を引き出してください。ブリーフで必要なら本物の画像を使用し、カテゴリーの慣習ではなく、合意した世界観に従ってください。
• 操作： 訪問者がタスクを完了します。アプリ UI、ダッシュボード、エディター、管理画面、設定、ツールが該当します。表現よりも、スキャンしやすさ、一貫性、ネイティブな期待、実際の利用場面を優先してください。ブランドは細部に宿ります。
• 閲読： 訪問者が何かを理解します。ドキュメント、記事、ガイド、ヘルプ、変更履歴が該当します。まず理解しやすい構成にし、そのうえで読み続けたくなる体験にしてください。
• 体験： 訪問者が作品そのものに入り込みます。ポートフォリオ、ギャラリー、ショーケースが該当します。最初の画面から作品を主役にし、インターフェースは控えめにしてください。

プロダクトではなく、依頼された画面に基づいてモードを選び、その画面のブリーフにのみ記録してください。ツールのランディングページは「説得」、ファッションハウスのドキュメントは「閲読」、ドキュメントのインデックスも「説得」ではなく「閲読」です。新しい画面については new-work.md、操作／閲読モードの詳細なガイダンスについては operate.md を参照してください。

コマンド

コマンド	カテゴリ	説明	参照
craft [feature]	構築	通常の新規作業リクエストの非推奨エイリアス	reference/craft.md
shape [feature]	構築	コードを書く前に UX/UI を計画します	reference/shape.md
init	構築	永続的なプロダクトコンテキストを PRODUCT.md に記録します	reference/init.md
document	構築	既存のプロジェクトコードから DESIGN.md を生成します	reference/document.md
extract [target]	構築	再利用可能なトークンとコンポーネントをデザインシステムに取り込みます	reference/extract.md
critique [target]	評価	ヒューリスティック評価による UX デザインレビュー	reference/critique.md
audit [target]	評価	技術品質チェック（a11y、パフォーマンス、レスポンシブ対応）	reference/audit.md · ネイティブ: reference/audit.native.md
polish [target]	改善	リリース前の最終品質チェック	reference/polish.md
bolder [target]	改善	無難なデザインや凡庸なデザインを際立たせます	reference/bolder.md
quieter [target]	改善	強すぎるデザインや刺激の強いデザインを抑えます	reference/quieter.md
distill [target]	改善	本質に絞り、複雑さを取り除きます	reference/distill.md
harden [target]	改善	エラー、i18n、エッジケースに対応し、本番環境に備えます	reference/harden.md
onboard [target]	改善	初回起動時のフロー、空の状態、利用開始時の体験を設計します	reference/onboard.md
animate [target]	強化	目的に沿ったアニメーションと動きを追加します	reference/animate.md
colorize [target]	強化	モノクロの UI に効果的な色を加えます	reference/colorize.md
typeset [target]	強化	タイポグラフィの階層とフォントを改善します	reference/typeset.md
layout [target]	強化	余白、リズム、視覚的階層を調整します	reference/layout.md
delight [target]	強化	個性と記憶に残る工夫を加えます	reference/delight.md
overdrive [target]	強化	従来の限界を超えて大胆にします	reference/overdrive.md
clarify [target]	修正	UX コピー、ラベル、エラーメッセージを改善します	reference/clarify.md
adapt [target]	修正	さまざまなデバイスや画面サイズに対応させます	reference/adapt.md · ネイティブ: reference/adapt.native.md
optimize [target]	修正	UI のパフォーマンスを診断し、改善します	reference/optimize.md
live	反復	ビジュアルバリアントモード: ブラウザーで要素を選び、別案を反復検討します	reference/live.md
generate [n] [action] [element]	反復	ライブブラウザーで選べる、指定した要素のバリアント、バージョン、代替案を生成します。手動での選択は不要です	reference/generate.md

ルーティング:

• このターゲットで承認済みの方向性を継続する場合： context が返した元のブリーフを再利用します。一致する承認済みハッシュがあれば、再度のヒアリングやコンセプトの抽選を行わずに、セッションをまたいで方向性を復元できます。マッピングが古い、存在しない、または曖昧な場合は、元のソースと承認判断を確認する必要があります。更新日時で選択したり、変更されたバイト列を暗黙に承認したりしないでください。ユーザーが別の方向性を希望した場合は、その変更範囲を記録し、新しい選択には design-reference を使用してください。
• ビジュアルリファレンス／方向性： design-reference を使用します。インタラクションパターンの選択： ui-pattern-research を使用します。DESIGN.md の作成／更新： design-md のソースおよび記述ルールを使用します。Phoenix shape は承認済みのインタラクション選択を受け取り、残りのサーフェスに関する判断を進めます。
• 独立した UI 承認： review-ui に振り分けます。既存の UI レポートがある場合は、修正を apply-ui-review に振り分けます。必要なスキルを利用できない場合は、前提条件が満たされていないことを報告してください。Phoenix のデザインレビューで承認が完了したと主張してはいけません。
• 引数がない場合： routing.md を読み、コンテキストに応じたメニューを提示します。コマンドを自動実行してはいけません。
• コマンドの実行が明示的、または明確に意図されている場合： 対応するリファレンス（ネイティブプラットフォームではネイティブ版）を読み、その指示に従います。該当するコマンドが 2 つある場合は、一度だけ確認します。
• ワークフローやコマンドの選択に関する質問： Workflow questions を読みます。
• それ以外の場合： 依頼を一般的なデザイン作業として扱います。PRODUCT.md がない場合、新しいサーフェスや置き換え後の世界観には init を経由してから new-work に進みます。既存コードの範囲を絞った改良は、phoenix-ui context の指示どおり、現在の実装を基準に進めます。init はその後に提案し、前提条件にはしません。
• teach は init の別名です。craft は通常の new-work の非推奨の別名で、追加の機能はありません。shape はタスクの発見を担い、その後、ビジュアルの世界観とサーフェスのコンセプトを決める場合にのみ new-work に進みます。

context またはブリーフへの書き込みが許可されて完了したら、変更された情報を使用する前に context --target <primary-target> --json を再実行して最新の状態に更新します。Init は、記録したプラットフォームが ios、android、または adaptive の場合、ネイティブプラットフォームのリファレンスを自ら読み込みます。

ピン留め／ピン留め解除： <skill-base-dir>/scripts/phoenix-ui pin <pin|unpin> <command> は、単独の $<command> ショートカットを作成または削除します。スクリプトの結果を簡潔に報告し、エラーの場合は stderr をそのまま伝えます。

フック： $phoenix-ui hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset> は、このプロジェクトのデザイン検出フックを管理します（UI ファイルの編集後に検出を自動実行し、検出結果を表示します）。ユーザーが引数付きで実行した場合は、reference/hooks.md を読みます。

Doctor： $phoenix-ui doctor は、このプロジェクトの Phoenix UI アーティファクト（PRODUCT.md、DESIGN.md とそのサイドカー、設定、サーフェスブリーフ、フック）と、このバージョンが読み取る内容との間の不整合を報告し、修復します。ユーザーが実行した場合、または何が古いのか、古くなっているのか、更新が必要なのかを尋ねた場合は、reference/doctor.md を読みます。Setup の出力にある CONTEXT_STALE ディレクティブは、同じレポートの簡易版です。尋ねられていないのに doctor を実行するのではなく、その指示に従ってそこで対応します。

デザイン作業の副作用として、不整合を修復してはいけません。 CONTEXT_STALE の検出結果は報告し、ユーザーからの依頼がない限り対応しません。ただし、auto とマークされた検出結果は例外で、そのファイルへの次の書き込み時にいずれにしても処理されます。