setup

このプロジェクトのデザインに関する背景情報を集め、以降のすべてのセッションで使えるように保存してください。

setup は .better-web-ui.md を正式な保存先として使用します。.better-ui.md や .impeccable.md などの古いファイルは、移行時にのみ入力として使用するレガシーファイルであり、新たな作業で引き続き使用するファイルではありません。

プロダクトの価値観、トーン、繰り返し生じるトレードオフを、同じ議論を繰り返さずに後続の作業でも再利用できる、長期的なデザイン原則にまとめる際は、デザイン原則を参照してください。 プロジェクトで、目標とする成果、ユーザーへの注力、優先事項、実現可能性、主要なリスクを明確にするための戦略的な枠組みが必要な場合は、UX 戦略を参照してください。

ステップ 1：コードベースを調査する

質問する前に、プロジェクトを徹底的に調べ、把握できる情報を集めます。

• README とドキュメント：プロジェクトの目的、対象ユーザー、明示されている目標
• Package.json / 設定ファイル：技術スタック、依存関係、既存のデザインライブラリ
• shadcn プロジェクト設定：components.json、shadcn スキーマの使用状況、CLI で生成された設定、プリセットの手がかり、Radix と Base UI の選択
• スタイリングシステム：Tailwind、CSS modules、CSS-in-JS、vanilla CSS、ユーティリティシステム、トークン
• コンポーネントライブラリ：shadcn/ui、Nuxt UI、Angular Material、カスタム UI パッケージ、社内システム
• フォームの構成：TanStack Form、React Hook Form、Formik、vee-validate、Angular forms、カスタムのバリデーション／状態管理の接続
• テーブル／データグリッドの構成：TanStack Table、AG Grid、フレームワーク標準のテーブル、カスタムのテーブル状態管理
• 長いリスト／仮想化の構成：TanStack Virtual、react-window、react-virtualized、フレームワーク標準の仮想化、カスタムのウィンドウ化ロジック
• 既存のコンポーネント：現在使われているデザインパターン、余白、タイポグラフィ
• ブランドアセット：ロゴ、ファビコン、すでに定義されている色の値
• デザイントークン／CSS 変数：既存のカラーパレット、フォントスタック、余白の尺度
• スタイルガイドやブランド資料

把握できたことと、まだ不明なことを記録します。

ステップ 2：UX に関する質問をする

コードベースから推測できない点を明らかにするため、ユーザーに直接質問します。コードベースの調査から推測できなかったことだけに絞ってください。

ユーザーと目的

• 誰が使いますか？どのような状況で使いますか？
• UX に反映すべき習慣やニーズを持つ、特定の年齢層、ライフステージ、ユーザー層を対象としていますか？
• 保護者、教師、管理者、介護者など、考慮すべき副次的なユーザーや意思決定者はいますか？
• ユーザーは何を達成しようとしていますか？
• インターフェースはどのような感情を呼び起こすべきですか？（自信、喜び、落ち着き、切迫感など）

ブランドと個性

• ブランドの個性を 3 つの言葉で表すと、どのようになりますか？
• 目指す雰囲気に合う参考サイトやアプリはありますか？具体的にどの点が参考になりますか？
• 明確に避けたい見た目はありますか？避けるべき参考例はありますか？
• インターフェースは、よりシリアス、遊び心のある、エレガント、実用的、エディトリアル、あるいは別の雰囲気にすべきですか？
• 言葉遣いは、フォーマル、中立的、会話的のどれがよいですか？

美的な好み

• ビジュアルの方向性に強い好みはありますか？（ミニマル、大胆、エレガント、遊び心のある、テクニカル、オーガニックなど）
• ライトモード、ダークモード、または両方が必要ですか？
• 必ず使う色や、避けるべき色はありますか？
• 角の形状は、ほぼ直角、控えめな角丸、柔らかく遊び心のあるもののどれがよいですか？
• パレットは暖色系、寒色系、中間色系のどれを中心にしますか？

アクセシビリティとインクルージョン

• アクセシビリティに関する具体的な要件はありますか？（WCAG の適合レベル、把握しているユーザーニーズなど）
• 動きの低減、色覚特性、その他の配慮事項はありますか？

コードベースの調査ですでに答えが明らかな質問は省略してください。

実装のデフォルト

• 今後の UI 作業では、デフォルトでどのフレームワーク／ランタイムを想定すべきですか？
• 新規プロジェクトの場合、ユーザーは特定のスタイリングシステムを希望していますか？
• 新規プロジェクトの場合、ユーザーは特定のコンポーネントライブラリまたはブロックシステムを希望していますか？
• プロジェクトですでにフォームライブラリまたはバリデーションスタックを使用していて、今後の UI 作業でも維持すべきですか？
• プロジェクトですでにテーブルまたはデータグリッドのライブラリを使用していて、今後の UI 作業でも維持すべきですか？
• プロジェクトですでに長いリスト向けの仮想化またはウィンドウ化ライブラリを使用していて、今後の UI 作業でも維持すべきですか？
• プロジェクトですでに shadcn/ui を使用している場合、主にアップストリームのプリミティブを直接使用していますか。それとも、その上に構築されたローカルラッパー／コンポジションを使用していますか？
• 該当する場合、プロジェクトでは一般的なセクションやフローを効率化するために、すでに shadcn/ui Blocks または re-ui を使用していますか？
• 該当する場合、プロジェクトはヘッドレスプリミティブやコンポジットコンポーネントに、主に Radix 系または Base UI 系のエコシステムを採用していますか？
• プロジェクトで shadcn を使用している場合、現在のベースラインとして扱うべき components.json ファイルや、shadcn create ／ shadcn apply によるカスタマイズの痕跡はありますか？

プロジェクトですでにスタイリングシステム、コンポーネントライブラリ、フォームスタック、またはテーブル／グリッドスタックを使用している場合、ユーザーが明示的に変更を希望しない限り、それをデフォルトとして扱います。

プロジェクトが新規で、ユーザーが実装の好みを指定していない場合は、framework defaults のフレームワーク別デフォルト表を使用し、その結果を記録します。新しい React、Vue、Angular、Solid、または Svelte プロジェクトでフォームのアーキテクチャが未決定の場合は、TanStack Form をデフォルトとし、そのことも記録します。同じエコシステムでテーブルまたはデータグリッドのアーキテクチャが未決定の場合は、TanStack Table をデフォルトとし、そのことも記録します。長いリストまたは仮想化のアーキテクチャが未決定の場合も、TanStack Virtual をデフォルトとし、そのことも記録します。

ステップ 3：デザインコンテキストを記述する

調査結果とユーザーの回答をまとめて、## Design Context セクションを作成します。

## Design Context

### Users
[Who they are, their context, the job to be done]

### Brand Personality
[Voice, tone, 3-word personality, emotional goals]

### Aesthetic Direction
[Visual tone, references, anti-references, theme]

### Implementation Defaults
[Detected or chosen framework, styling system, component library defaults, form library / validation defaults, table/data-grid defaults, virtualization defaults, any block accelerators in use, any relevant Radix-vs-Base-UI ecosystem preference, any important `components.json` / `shadcn create` / `shadcn apply` customizations, and whether they came from the existing codebase, explicit user preference, or framework fallback defaults]

### Design Principles
[3-5 principles derived from the conversation that should guide all design decisions]

曖昧な願望ではなく、具体的な手段から原則を導き出します。次のような内容を優先します。

• 「色を加える前に、余白とウェイトで階層を明確にする」
• 「温かみのあるニュートラルカラーと控えめなアクセントカラーを使う」
• 「エディトリアルなタイポグラフィと、ほぼスクエアな角を優先する」
• 「各画面で、ひと目でわかる主要アクションを 1 つに絞る」

最も効果的な原則は、何をすべきかだけでなく、何を避けるべきかも説明します。装飾的なスローガンではなく、判断を伴うデフォルトの方針として扱います。

このセクションをプロジェクトルートの .better-web-ui.md に記述します。ファイルがすでに存在する場合は、Design Context セクションをその場で更新します。従来の .better-ui.md または .impeccable.md ファイルが存在する場合は、Design Context セクションを .better-web-ui.md に移行または複製し、今後は better-web-ui のプロジェクトコンテキストファイルを 1 つに統一します。

従来のファイルは移行時のフォールバック入力としてのみ使用します。新しい作業では、.better-web-ui.md を正式な保存先とします。

保存するコンテキストでは、次の優先順位を明確に記録してください。

1. 検出された既存のプロジェクトスタック
2. 新規プロジェクトに対するユーザーの明示的な希望
3. フレームワークに基づくフォールバックのデフォルト

React 系のコンポーネントエコシステムで区別が重要な場合は、後続のデザイン作業で推測が生じないよう、プロジェクトが実質的に Radix 系、Base UI 系、または混在型のいずれであるかも記録します。

shadcn 固有のプロジェクト設定が存在する場合は、後続のセッションで汎用的なフォールバックのデフォルトが想定されないよう、ベースラインの一部として記録します。

続けて、Design Context を AGENTS.md にも追加するかどうかをユーザーに尋ねます。希望する場合は、そこにもセクションを追加または更新します。

完了を伝え、今後のすべての作業の指針となる主要なデザイン原則を要約します。