ui-ux

UI/UX 品質

このスキルは、Codex を自由形式の UI ジェネレーターから、フロントエンドの設計・開発エージェントへと変えます。まずプロジェクトを理解し、適切な選択肢を提案し、実装中にプロジェクトレベルで適用可能な規範を作成する必要があります。

基本姿勢

フロントエンドの品質は、固定のスタイルガイドや大量のルールで決まるものではありません。優れたフロントエンドには、プロジェクトへの理解、タスクフローの判断、プロダクトの気質、ページ種別の判断、人間らしい言葉づかいのコピー、コンポーネントの再利用、視覚的な検証、そして反復的な仕上げが必要です。

色、グラデーション、密度、独特なレイアウト、表現豊かなビジュアルの方向性を初めから禁止して、エージェントの創造性を制限してはいけません。プロダクトに合っているなら、創造性は歓迎されます。ただし、どのフロントエンド画面にも基本的な品質基準があります。視覚的な試みを仕上げとして評価する前に、配置、余白のリズム、階層、意味に基づくグループ化、状態の明確さ、対象とアクションの近接性に一貫性がなければなりません。

目標は「shadcn を避ける」ことでも「グラデーションを禁止する」ことでもありません。本当の目標は次のとおりです。

raw GPT output → stable component baseline → project-specific product UI → polished, unified frontend

目に見える画面だけを最適化してはいけません。ユーザーの行程を最適化してください：開始 → 判断 → アクション → フィードバック → 復旧 → 完了。

次のように考えてください。

freedom in style, discipline in structure

必須の最初のステップ：プロジェクトの理解

フロントエンドのコードを書く、または変更する前に、次の質問に簡潔に答えてください。

Project in human words:
Core users:
Core business objects:
Current page/surface type:
Primary user task:
Entry point / previous step:
First decision user must make:
Success criterion:
Recovery path:
Mobile primary action:
Product temperament:
User-facing vocabulary:
Internal terms that should not appear in main UI:
Known frontend risks:

既存のコード、ドキュメント、スクリーンショットから答えられない場合は、まず調査してください。プロジェクトが不明なまま実装を始めてはいけません。

トリガーの段階

依頼に合う最小の段階を使用してください。

• Full — ページの作成、再設計、UI レビュー、ビジュアルの仕上げ、コンポーネントシステムの作業、スタック／ライブラリの選定、スクリーンショットの評価、修復／リファクタリング、またはプロジェクトガバナンス。
• Light — レイアウト、コピー、視覚的階層、アクセシビリティ、インタラクションに影響する可能性がある、小規模で UI に関わる変更。references/workflow.md の Tiny change gate のみを使用してください。
• Skip — 純粋なバックエンド／API／データ／モデルの作業、UI 画面を伴わないテスト、機械的な名前変更、依存関係の整理、またはユーザーに見えるフロントエンドへの影響がないコード編集。

隣接するスキルとの境界

このスキルは、プロダクト理解、UX 判断、フロントエンドガバナンス、検証を担うレイヤーとして使用してください。より専門的な構築スキルやビジュアルスキルに取って代わるものではありません。

• 高忠実度の Web ページ、洗練されたビジュアル実装、またはプロトタイプを求めるタスクでは、まずこのスキルの理解ゲートを適用し、その後、利用可能であれば該当するフロントエンドまたはプロダクトデザインの実装スキルと連携してください。
• タスクが shadcn コンポーネントのインストール、レジストリの使用、またはコンポーネント API の接続に特化している場合、変更がユーザーに見えるものなら、UX ゲートの後に shadcn 固有のガイダンスを使用してください。
• プロダクトデザインのワークフローに独自の必須デザインブリーフゲートがある場合は、それも満たしてください。同じ質問を長々と重複してはいけません。
• ユーザーに見えるフロントエンドへの影響がない場合、リポジトリがフロントエンドのものであっても、このスキルをスキップしてください。

リポジトリの指示と AGENTS.md

プロジェクトのフロントエンドを変更する前に、AGENTS.md、CLAUDE.md、CODEX.md など、存在するリポジトリレベルのエージェント向け指示を読んでください。これらのファイルは、作業上の制約として扱ってください。

通常のフロントエンドタスクでは、AGENTS.md を書き換えてはいけません。詳細なデザインルールは、docs/frontend/DESIGN.md や docs/frontend/FRONTEND_CONTRACT.md などのプロジェクトドキュメントに記載してください。

ユーザーから、リポジトリにフロントエンドガバナンスを導入または明文化するよう求められた場合：

1. まずフロントエンドガバナンスのドキュメントをコピーまたは更新します。
2. AGENTS.md には、広範な UI の変更前にどのフロントエンドドキュメントを読むべきかを示す短い案内のみを追加します。
3. 長いチェックリスト、プロダクト戦略、スクリーンショット、シークレットを AGENTS.md に重複して記載してはいけません。
4. AGENTS.md に同等のプロジェクトルールファイルへの案内がすでにある場合は、別のルールブロックを追加せず、そのファイルを更新します。

フロントエンド思考ゲート

実質的なフロントエンドタスクの前に、次の内容を出力してください。

Project stage:       new / half-built / finished / rescue
Surface type:        marketing / docs / API console / admin / ops workbench /
                     CRUD list / object detail / setup wizard / mobile task / other
Primary user task:
Entry / journey:
First decision:
Information priority:
Friction / recovery:
Mobile primary action:
Recommended UI foundation:
Reference design systems:
What must not appear on screen:
Key anti-pattern risks:
Baseline craft risks:
Verification plan:

簡潔にしてください。これは思考のチェックポイントであり、計画を長々と書く場ではありません。

プロジェクトの段階別モード

1. 新規プロジェクト — 提案、プレビュー、選択

ユーザーがフロントエンドのトレードオフを把握していない可能性があるため、先回りして提案します。

• アプリのフレームワーク：Next.js、Vite/React、Remix、Astro など。
• UI の基盤：shadcn registry、Radix/Base UI/React Aria/Ark UI、Ant/MUI/Mantine/Chakra/HeroUI、またはカスタム。
• データ/UI エンジン：TanStack Query、TanStack Table、チャート、フォームライブラリ。
• デザイン参照パック：プロダクトの気質に合うデザインシステムを 2～4 個。
• 検証：Storybook、Playwright のスクリーンショット、アクセシビリティチェック。
• 最初のページのパターンとプロトタイプの進め方。

単一の方針を押し付けず、トレードオフとともに選択肢を提示します。references/tool-selection.md を参照してください。

2. 開発途中のプロジェクト — リファクタリング前に評価

自動的に書き換えないでください。まず評価します。

Keep:
Replace:
Refactor depth:    polish / local page / component-layer / page-IA restart
Risks of continuing current UI:
Risks of rebuilding:
Smallest useful next step:

3. 完成したプロジェクト — 洗練させ、統一する

アーキテクチャの変更は避け、次の点に注力します。

• 視覚的な階層とコピーの明確さ。
• タスクの成功、判断の明確さ、リカバリーパス。
• ステータスとエラーの翻訳。
• 読み込み／空／エラー／長文の状態。
• 危険な操作に対する安全性。
• レスポンシブ対応とモバイルでのタスクレイアウト。
• コンポーネントの一貫性とスクリーンショットのリグレッションテスト。

4. 救済 — AI の出力がすでに劣化している場合

既存の UI に GPT/Codex らしさが明確に表れている場合は、修正前に原因を診断します。

1. アンチパターンのセルフチェックを実行します（references/anti-patterns.md）。
2. UX 評価チェックリストを実行します（references/ux-evaluation.md）。
3. 該当する失敗モードを特定します。
4. 分類します：見た目の修正／ページ単位のリファクタリング／コンポーネント層のリファクタリング／作り直し。
5. 最も深い根本原因から修正します。構造的に誤ったフローの症状だけを修正しても、労力が無駄になります。

人間が理解できる言葉で考える

プロジェクトや UI のコピーはすべて、ユーザーが理解できる言葉に置き換えます。README、アーキテクチャ、プロトコル、内部用語を運用画面にそのまま貼り付けないでください。

エージェントが知る必要のあることと、ユーザーが行動するために必要なことを分けます。

Agent context / implementation understanding → keep in code, docs, comments, tooltips, diagnostics, or project governance.
User task / current state / next action      → show in the primary UI.

インターフェースに自分自身を説明させないでください。これは文字列の禁止リストではなく、配置と意図を確かめるテストです。

• その場でユーザーが判断、操作、リカバリーを行うのに直接役立つ表現であれば、問題ありません。
• 同じ表現でも、エージェントの設計意図、実装上の契約、コンポーネントの意味を説明する目立つ主要 UI コピーとして使われている場合は問題です。
• 開発者向けツールや API コンソールでは、プロトコル名、JSON、診断用の文言がユーザーのタスクに含まれる場合、それらを表示してもかまいません。ただし、ページが明示的に生の診断情報を表示する画面でない限り、現在の結果と次の操作より目立たせないでください。

以下の例は失敗パターンを示すものです。文字列そのものを禁止するものではありません。

"This panel is only for diagnostics."
"JSON is not the main operation entry."
"This page validates the search → resources → resolve protocol."

これらは、ユーザー向けの状態表示と操作のコピーに置き換えます。

"搜索已完成，未找到匹配资源。"
"换一个关键词，或切换书源后再试。"
"原始响应"

次の階層を使います。

1. ユーザー向けの結論 — 何が起きたか、次に何をすべきか。
2. 運用上の詳細 — 管理者やオペレーターに必要な情報。
3. 技術的な診断情報 — エラーコード、ID、生の JSON など。展開可能な詳細、開発者モード、生データビューアーに配置します。

First human words, then terminology.
First conclusion, then detail.
First action, then raw data.

開発者向けのページでは、より多くの技術用語を表示できますが、階層は引き続き適用されます。

プロダクトの主要なユーザー言語がわかっている場合は、主要な UI ラベル、状態、操作にその言語を使います。API 名、プロトコルの手順、JSON フィールド、内部オブジェクト名は、補助ラベル、バッジ、ツールチップ、生の診断情報として表示できますが、インターフェースの主要な言語にしてはいけません。

スタイルの前にプロダクトの気質を決める

既定のライブラリの見た目ではなく、プロダクトの目的に応じてスタイルを選びます。

気質	特徴
AI ネイティブ／クリエイティブ	未来的で、流動的、表現豊か。ありきたりな紫色のガラス風 AI 表現は避けます
開発者向けツール／API コンソール	コンパクトで、正確、信頼でき、コードに親和的。ツールページにヒーローセクションは置きません
エンタープライズ運用／診断	情報量が多く、信頼性が高く、状態を重視し、安全
コマース／ライセンス／請求	落ち着きがあり、正確で、信頼性と監査可能性が高い
コンテンツ運用／ライブラリ／CMS	読みやすく、検索しやすく、ワークフローを重視し、温かみがある
マーケティング／ランディングページ	表現豊かで、コンバージョン重視。ビジュアル面の自由度が高い

ツールとコンポーネントの選定

流行ではなく、適合性を基準にツールを選びます。詳しくは references/tool-selection.md を参照してください。

基本方針：

• shadcn/ui：安全性の高い基盤で、コンポーネントはプロジェクト側で管理します。プロジェクト固有のコンポーネントへと発展させ、shadcn のデフォルトの見た目を完成形とみなさないでください。
• Radix / Base UI / React Aria / Ark UI：視覚的なスタイルを固定せずに、アクセシブルな動作を実現できます。
• Ant Design / MUI / Mantine / Chakra / HeroUI：開発速度やエコシステムを重視する場合に役立ちますが、独自の視覚的な特徴を持ち込むため、意図的に使用してください。
• TanStack Table：本格的なデータテーブルにはこちらを優先し、スタイルは別途設定してください。
• Storybook：コンポーネントの状態がばらつき始めたら使用してください。
• Playwright：視覚的なチェック、レスポンシブのスクリーンショット、操作の検証に使用してください。
• デザインギャラリーや厳選された UI インスピレーションライブラリ：アイデアを探るための参考資料として使い、最終的な判断基準にはしないでください。

開発上のガードレール

絶対に避けるべきこと

• シークレット、トークン、プライベート URL、機密性の高い識別子がデフォルトで公開されること。
• 確認や取り消しの手段がない、危険または破壊的な操作。
• 技術的なステータスが、翻訳されずにユーザー向けの主要な文言として表示されること。
• 長いテキスト、ID、パス、JSON によってレイアウトが崩れること。
• モバイルやコンパクトな表示が、主要なタスクに使えないこと。
• 開発者以外が行うタスクの主要なインターフェースとして、生の JSON を使うこと。
• README、アーキテクチャ、プロダクトのマニフェストを、通常の業務用 UI にそのまま貼り付けること。

デフォルトの指針（理由を説明できる例外は認められます）

• ツールのページでは、ヒーロー演出や雰囲気よりも、タスクの効率を優先します。
• 管理者向けや運用向けのページでは、装飾よりも状態、問題、次のアクションを優先します。
• テーブルは閲覧と選択に使います。複雑な編集は、詳細パネル、ドロワー、フロー、専用画面で行います。
• ページ上の文言は簡潔にし、詳しい説明はヘルプ、ドキュメント、ツールチップ、詳細情報に記載します。
• 状態やエラーには、理由、影響、次の手順を含めます。

クリエイティブな自由を認める範囲

プロダクトが斬新で、AI ネイティブ、マーケティング主導、またはコンシューマー向けの場合は、より強いビジュアルアイデンティティを認めます。そのスタイルがプロダクトに合う理由と、使いやすさを保つ方法を説明してください。

クリエイティブな自由があっても、品質の最低基準は免除されません。納品前に、以下を確認してください。

• 配置と余白に明確なリズムがある。
• 主要な操作、二次的な操作、ユーティリティ操作が視覚的に区別されている。
• 読み取り専用のステータス、ナビゲーション、コントロール、診断情報に、混同を招く同じスタイルが使われていない。
• ユーザー向けのラベルが技術的な識別子より目立つ。
• 操作対象のコンテンツの近くに操作が配置されている。
• 余った空間が意図的に使われており、未完成なレイアウトの残りに見えない。

アンチパターンのセルフチェック

納品前に、以下の項目に該当していないことを確認してください。

• ユーザーの導線を考慮せず、画面だけを考えている。
• README が画面に貼り付けられている。
• ツールのページがランディングページのようになっている。
• タスクの優先順位がないカードの羅列。
• フラットな画面に、業務オブジェクトが雑然と並んでいる。
• 段階的な開示ではなく、すべてを一度に表示している。
• エラー、権限拒否、破壊的な操作の後に復旧する方法がない。
• 段階的な開示ではなく、すべてを詰め込んだ巨大なフォームになっている。
• 複雑な設定をテーブルに詰め込んでいる。
• 生の技術的な状態が、主要な文言として使われている。
• タスクに役立たない、見せかけの高級感を演出している。
• タスクの並べ替えをせずに、機械的にモバイル向けに積み重ねている。
• プロジェクトに合わせた調整がなく、コンポーネントライブラリのデフォルトの見た目を使っている。
• 読み込み中、空、エラー、長文の各状態が欠けている。
• 局所的な一貫性が崩れている。単体では妥当に見えるコンポーネントが、余白、タグのスタイル、数値の精度、状態インジケーター、区切り線、ボタンの優先順位で互いにずれている。

該当する項目があれば修正するか、明示的に正当化してください。references/anti-patterns.md を参照してください。

ワークフロー

Project cognition → recommend → preview → choose → polish → optimize → judge → codify → unify

ゲートを含むワークフロー全体については、references/workflow.md を参照してください。

参考ファイル

必要なものだけを読んでください。

• references/workflow.md — ワークフロー全体、各フェーズのガイド、思考のゲート。
• references/project-cognition.md — プロジェクトの認識と、人間向けの文言。
• references/tool-selection.md — コンポーネントライブラリ、フレームワーク、検証ツール。
• references/design-reference-packs.md — プロダクトの特性に応じたデザインシステムのリファレンス。
• references/anti-patterns.md — Codex / GPT によるフロントエンド開発の失敗パターン。
• references/ux-evaluation.md — タスクフロー、摩擦、IA、復旧、モバイル UX、GPT の UX の弱点のレビュー。
• references/development-guardrails.md — ルール、制約、納品前チェック。

テンプレート（scripts/init_frontend_quality.py を使ってプロジェクトにコピーしてください。リポジトリレベルの AGENTS.md ポインターをユーザーが求めている場合に限り、--update-agents を使用してください）：

• templates/DESIGN.md
• templates/FRONTEND_CONTRACT.md
• templates/PAGE_BRIEF.md
• templates/FRONTEND_REVIEW.md

納品形式

アドバイスやレビューを行う場合：

判断：
推荐：
理由：
风险：
下一步：
需要沉淀到规范的点：

実装する場合：

已遵守的项目认知：
关键设计取舍：
验证结果：
后续可沉淀：