add-ui

必須の準備

ユーザーは /add-ui でこのワークフローを開始します。add-ui は、このリポジトリにおける正式なスキル名です。一部のホストでは使いやすい /add エイリアスが公開されている場合がありますが、ドキュメント、ラッパー、ソースファイルでは引き続きスキルを add-ui として参照してください。

このスキルが有効になったら、$frontend-design を読み込みます。ここにはデザイン原則、アンチパターン、コンテキスト収集プロトコルが含まれています。先に進む前に、そのプロトコルに従ってください。デザインコンテキストがまだ存在しない場合は、まず $setup を必ず読み込んでください。

新規のランディングページ、マーケティングページ、または複数の明確に異なる方向性が求められていて、まだ美的方向性が定まっていない場合は、frontend-design のデザインの方向性にある承認済みのスタイル選択ルールを使用します。漠然とした雰囲気のラベルを考案するのではなく、プロダクトのアイデアやブランドコンテキストに合う方向性を選んでください。

確立されたビジュアルシステムを持つ既存プロジェクトで作業する場合は、まずそのシステムを維持し、プロダクトのブランドをひそかに変更することなく、それぞれの選択肢に明確な違いを持たせてください。

また、実用的なコードを生成するために必要な最小限の実装情報も収集します。

• フレームワーク／ランタイム（React、Next.js、Vue、プレーンな HTML など）
• スタイリングシステム（Tailwind、CSS modules、styled-components、vanilla CSS など）
• 挿入先（新しいルート、既存ページ、共有コンポーネントのフォルダー、デザインシステム領域）
• 新規に作成するものか、既存のものを再設計するものか
• セクション、ページ、フロー、シェル、スタンドアロンコンポーネントのどれをユーザーが求めているか
• 品質基準（簡易ドラフト、本番環境向け、フラッグシップ）

既存のものを再設計する場合は、次の点も特定します。

• 見分けがつく状態で維持する必要がある部分（コンテンツブロック、セクションの順序、インタラクションモデル、馴染みのあるアフォーダンス、ブランド要素）
• 柔軟に変更できる部分（スタイル、色、コピー、タイポグラフィ、メディアの扱い、密度、細部の表現）
• ユーザーが主に安全な改善を望んでいるのか、幅広く案を探して比較したいのか、あるいは踏み込んだ方向性を1つまたは2つ試したいのか

実装のデフォルトを決める際は、次の優先順位に従います。

1. まず既存プロジェクトのスタイリングライブラリとコンポーネントライブラリを検出し、それらに合わせる
2. 新規プロジェクトで、ユーザーがスタイリングライブラリまたはコンポーネントライブラリを明示した場合は、それを使用する
3. 新規プロジェクトで、ユーザーが指定していない場合は、frontend-design に定められたフレームワークのデフォルトを使用する

React ベースのフォールバック設定が関係する場合は、コンポーネントライブラリの統合も参照し、求められた成果物にプリミティブ、再利用可能なパターン、ブロックアクセラレーターのどれを使うべきか判断してください。

不足している点だけを質問します。コードベースから技術スタックを推測できる場合は、そうしてください。

必要に応じて、次のリファレンスを参照してください。

• 成果物の分類
• コンポーネントライブラリの統合
• バリエーションの品質基準
• プレビューと適用のパターン
• リクエストのマッピングに関するヒューリスティクス
• 例とコマンドの命名

ホストやエージェント間で一貫性を高めるのに役立つ場合は、次の決定的なヘルパーアセットを使用してください。

• 比較表テンプレート
• コンポーネントライブラリ統合チェックリスト
• バリエーションの命名規則
• プレビューページのチェックリスト
• 適用／クリーンアップのチェックリスト

---

求められた成果物について、意味のある違いがある複数の UI 方向性を生成し、ユーザーによる比較を支援してから、選択と統合を案内します。

これには、新しい UI の追加と既存 UI の再設計の両方が含まれます。 既存のページ、セクション、フロー、シェル、コンポーネントの再設計を依頼された場合、ユーザーが構造の刷新を明示的に求めない限り、成果物の見慣れた骨格を維持することを基本とします。通常は、次のように進めます。

• すでに目的の達成に役立っている場合は、情報アーキテクチャ、コンテンツブロック、順序を維持します
• 明らかな問題がある場合や、ユーザーが大幅な UX の変更を求めている場合を除き、使い慣れた操作やアフォーダンスを維持します
• タイポグラフィ、色、コピーの見せ方、メディアの扱い、細部の表現、余白のリズム、強調の方法を通じて、ビジュアルシステムを進化させます
• 各案で、何を維持し、何を変更したのかが明確に伝わるようにします

構造を意図的に大きく変える案がある場合は、既存ページをひそかに一掃するのではなく、思い切った案として明確に示します。

このスキルは、次のような依頼を対象とします。

• マーケティングおよび収益化の画面：ヒーロー、機能、料金、推薦文、FAQ、CTA、ロゴ一覧、ギャラリー、ブログ、概要、お問い合わせ、プラン選択、アップグレードモーダル、ペイウォール
• ナビゲーションおよびシェル：ナビバー、フッター、ダッシュボードシェル、オンボーディングフィード、設定、カードナビゲーション
• 認証およびアカウント：ログイン、登録、パスワード忘れ、パスワードリセット、メール認証、二要素認証
• コマース：商品概要、商品カテゴリ、商品一覧、フィルター、カート、チェックアウト、レビュー、注文概要、ギフトカード
• データ UI：チャート、ウィジェット、データテーブル、フォーム、比較ビュー、ベントーグリッド、タイムライン、ダッシュボード

この一覧は一例であり、すべてを網羅するものではありません。

基本的な運用ルール

1. 色を変えるだけではなく、本物の別案を作る

   • 各案では、レイアウト、階層、情報密度、トーン、操作モデル、コンテンツの見せ方を変えます。
   • パレット、角丸、アイコンセットだけを変えても、新しい方向性とは見なしません。

2. 依頼された目的から始める

   • 料金セクションは、単なるカードではありません。
   • ログイン画面は、単なる入力欄ではありません。
   • ダッシュボードシェルは、単なる装飾ではありません。
   • 各案の軸を、ユーザーの主なタスクと製品のトーンに定めます。
   • 新規プロジェクトの幅広いマーケティング依頼では、承認済みのデザインの方向性から企業や製品のアイデアに合うものを選び、その適合性を説明します。

3. 一時的な DOM の仕掛けより、ソースに基づくプレビューを優先する

   • ホストがプレビューに対応している場合は、ユーザーが確認して選べる実際のコンポーネント、ページ、ルートを生成します。
   • 主なワークフローとして、ブラウザー拡張機能のような DOM インジェクションに頼らないでください。これは壊れやすく、保守可能なソースコードも作成できません。

4. 確固とした判断を示す

   • better-web-ui は、個性が際立つ、審美性の高い出力を目指します。
   • 最も無難な、ありきたりの SaaS レイアウトに落とし込まないでください。
   • フロントエンドデザインのアンチパターンに関するガイダンスを積極的に活用します。

5. 統合を考慮する

   • プロジェクトの既存のコード規約とフォルダー構造に合わせます。
   • 共有 UI システムがすでにある場合は、場当たり的なプリミティブを作るのではなく、そのシステムに組み込みます。
   • 各案で構造の繰り返しが見られる場合は、適切な共有要素を抽出します。

6. 本質を維持するという依頼に応える

   • ユーザーが本質を保つよう求めた場合、より大幅な刷新を明示的に認めていない限り、見慣れた構造、主要な要素、ストーリーの流れを維持します。
   • タイポグラフィ、色、コピー、情報密度、根拠の見せ方、表面のスタイリング、メディアの方向性、アクションの強調方法によって、異なる方向性を十分に表現できます。
   • 「選択肢を出して」という依頼を、既存のアーキテクチャを捨ててよいという許可だと取り違えないでください。

ワークフロー

1. リクエストを分類する

アーティファクトの分類を使って、ユーザーがセクション、ページ、フロー、シェル、データ／コンテンツコンポーネントのどれを求めているかを判断します。

また、次のどれに当てはまるかを判断します。

• 新規アーティファクト
• 構造をほぼ維持した既存アーティファクトの再設計
• 中程度の再構成が可能な再設計
• 全面的な見直しを伴う再設計

次に、以下を特定します。

• 主なユーザーの目標
• 中核となるコンテンツブロック
• 重要な状態（読み込み中、空、エラー、成功、バリデーション、レスポンシブレイアウト）
• 配置コンテキスト（新しいページ、既存ページ内、ダッシュボード内、マーケティングサイト内）
• 固定する構造要素と柔軟に変更できる構造要素
• 現状のまま認識できるように保つ品質と、変更する品質

2. 5つの異なる方向性を定義する

候補となる方向性を5つ作成します。3つ未満では探索の幅が狭まり、5つを超えると選択肢が多すぎて判断しにくくなります。

バリエーションの品質基準を使い、5つの方向性が表面的な色替えではなく、意味のある違いを持つようにします。

既存の構造や本質を維持するようリクエストされた場合は、現行のアーティファクトを基本の骨格として扱います。許可なくページを削除したり並べ替えたりするのではなく、主にビジュアルシステムとメッセージングの選択によって各方向性に違いを持たせます。

このような再設計では、次の組み合わせによって選択肢に違いを持たせられます。

• タイポグラフィとフォントの組み合わせ
• パレットとコントラストの方針
• コピーのトーンと見出しの表現
• 信頼性を示す要素の配置と強調
• 情報密度と余白のリズム
• 画像やイラストの扱い
• 表面のスタイル、枠線、奥行き、細部の表現
• アクションの優先順位と CTA の見せ方

各方向性には以下を含めます。

• 名前：短く、覚えやすく、コンセプトが伝わる名前
• 承認済みの方向性：主な構造上の方向性と、必要に応じて補足する表現
• デザインの主旨：アイデアを説明する1文
• 効果：ユーザーの目標をどのように支援するか
• 主な特徴：階層、レイアウト、情報密度、個性、メディアの扱い、アクションの方針
• 最適な用途：他の方向性ではなく、この方向性を選ぶべき状況
• スタイル上のコスト：注意すべき主な実装、パフォーマンス、または状態管理上のコスト

既存のアーティファクトを再設計する場合は、さらに以下も記載します。

• 維持する骨格：現行のアーティファクトから意図的に認識できる状態で残すもの
• 主な変更点：この方向性で最も強く打ち出すもの

3. 実際の候補アーティファクトを作成する

各方向性について、実際のアーティファクト一式を作成します。

次を優先します。

• 実際のコンポーネントファイル
• 実際のルート／ページファイル
• バリエーションを切り替えられる実際のプレビューシェル
• UI を分かりやすくするために必要な、実際のデータモックやプレースホルダー

既存のアーティファクトを再設計する場合は、実用上可能であれば、全体を一から作り直すのではなく、実際の現行実装をベースに分岐させます。まずリクエストされた構造を維持し、その上にデザインの変更を重ねます。

プレビューと適用のパターンを使い、プレビュー、代替比較形式、最終的な統合の構成方法を決めます。

4. バリエーションを実際に比較できるようにする

すべてのバリエーションに、同じ実用的な確認項目を含めます。

• レスポンシブ時の挙動
• アクセシビリティに関する要件
• 主なインタラクション状態
• コンテンツのプレースホルダーまたはコピーの例
• 実装に関する注記
• 必要な補助コンポーネント

再設計の場合は、さらに以下も含めます。

• 構造上、一貫して維持された点についての短い説明
• ビジュアルまたは編集方針上の変更点についての短い説明

ある選択肢をスケッチにとどめ、別の選択肢を本番品質に仕上げることは避けてください。同じ条件で比較できるようにします。

5. 推奨案を示し、ユーザーに選んでもらう

選択肢を生成した後は、次の手順に従います。

1. トレードオフを簡潔な表にまとめます
2. ユーザーの目標に明確に合致する場合は、1つの選択肢を推奨します
3. 複数の方向性が有効な場合は、ユーザーに明示的に選んでもらいます

推奨する方向性が次の点に最もよく合う理由を説明してください。

• 対象ユーザー
• プロダクトのトーン
• 情報密度
• コンバージョンまたはユーザビリティの目標
• 現在のコードベースでの保守性

6. 選ばれた方向性をきれいに適用する

方向性が選ばれたら、次のようにします。

• 指定された対象箇所に組み込みます
• プロジェクトの規約とインポートを維持します
• 繰り返し使われ、実際に再利用可能なプリミティブを抽出します
• ユーザーが代替案を残したいと希望する場合を除き、明らかに不要になった一時的な足場コードを削除します
• 今後の反復作業に役立つ場合にのみ、プレビュー用の成果物を残します

再利用可能なパターンが見つかった場合は、extract の考え方を取り入れます。ただし、1つの依頼のために肥大化したデザインシステムを構築しないでください。

ヒーローセクション、料金表、ペイウォール、認証、ダッシュボード、コマースフロー、コンテンツ画面など、成果物ごとの優先事項には、リクエストのマッピングに関するヒューリスティクスを使用してください。

出力の契約

可能な限り、次の順序で結果を提示してください。

1. 生成した内容 — 依頼された成果物と方向性の数
2. バリエーションの概要表 — 1/2/3/4/5を、コンセプトと最適な用途とともに記載します。必要に応じて、比較表のテンプレートを使用してください
3. 推奨案 — 適切な場合
4. プレビュー／適用に関するメモ — バリエーションの確認方法や切り替え方法
5. 実装結果 — 作成または更新したファイル

ラベル、ファイル名、選択の対応関係を一貫させるため、バリエーションの命名規則を使用してください。 プレビュー画面を構築する際は、プレビューページのチェックリストを使用してください。 ユーザーが方向性を選んだ後は、適用／クリーンアップのチェックリストを使用してください。

絶対にしないこと

• 見た目だけが異なる、ほぼ同一のバリエーションを5つ生成する
• 一時的なブラウザー DOM の注入を、主な実装方法として使う
• 既存のコードベース構成やスタイルシステムを無視する
• 本質や見慣れた要素を残すよう求められているのに、既存の成果物の構成を大きく壊す
• 指示が曖昧だからといって、一般的なスタートアップ風のデザインを既定にする
• このライブラリで、レトロ、サイバー、シンセウェーブ、ターミナル、または一般的な未来的ネオンの方向性を既定にする
• どの選択肢も派手で、カードを多用し、グラデーションやアニメーションを多用する
• 成果物に大きく影響する読み込み中、エラー、空の状態、レスポンシブレイアウトの状態を省略する
• 何を変更したかを明確にせず、選ばれたバリエーションを適用する

覚えておいてください。このスキルは、互換可能な UI を出すスロットマシンではありません。実際に異なる、プロダクション品質の方向性からユーザーが選べるよう支援し、保守しやすいソースコードに仕上げるための、体系的な探索ワークフローです。