lksnmnn/product-ui

Product UI

アプリケーションは作業サーフェスです。人々は仕事を完了するために繰り返し使います。すべての要素はその仕事に貢献することで存在価値を得ます。目標は習得した親しみやすさです。このカテゴリのツールに精通した人は、各コントロールを一目で信頼し、インターフェースはタスクの中に溶け込みます。

これらのルールはあらゆるアプリに適用されます。プロジェクト固有の内容（デバイスターゲット、デザインシステム、コンポーネント、方向性、既知の乖離）はプロジェクトファイルに記載し、それに基づいて構築します。画面を完成と呼ぶ前に、review.md を実行してください。

プロジェクトファイル

次の順序で探します：CLAUDE.md または AGENTS.md で指定されたパス、次に .claude/product-ui.md。存在しない場合は、最初のビルドの前に templates/project.md から .claude/product-ui.md を作成します：

1. デザインシステムを見つける：トークンファイル（CSS カスタムプロパティ、Tailwind テーマ、トークン JSON）、コンポーネントライブラリ（リポジトリ内の components/ui、shadcn、MUI、Radix など）、ストーリーファイル。
2. 画面が必要とする構成要素（ページスキャフォールド、テーブル、フォームフィールド、空の状態、ダイアログ、トーストなど）をパスとともにリストする。欠落しているものは「欠落」としてマークし、パスを勝手に作成しない。
3. コードが以下のルールを破っている場所（乖離）を確認する。
4. アプリごとのデバイスターゲットとビジュアル言語の所有者（デザインチームまたは開発者）をユーザーに尋ねる。アプリの意図からターゲットを提案する。

確認したことだけを記述します。CLAUDE.md をそのファイルにポイントし、後続のセッションが見つけられるようにします。

プロジェクトにビジュアルの方向性がなく、サーフェスが汎用的に見えてはいけない場合は、最初に design-direction スキルを実行します。その結果は同じファイルに記録されます。

目的ファースト

レイアウトの前に、それぞれを 1 行で書き留めます：

• 画面が提供するジョブとそれを実行する人物。
• 最初の読み取り：画面が開いたときに最初に見るもの。
• プライマリアクションとその繰り返し頻度。
• ターゲットデバイス：電話、タブレット、ラップトップ、大画面。プロジェクトファイルから。

画面上のすべての領域は、これらの行のいずれかにマッピングされます。どの行にもマッピングされない領域は削除されます。

実際のコンテンツ

プロダクションのようなコンテンツで構築および評価します：現実的な長さの実際の名前、最も長い可能性のあるタイトル、0、1、7、500 のアイテム、欠落したオプションの値、英語より 30% 長い翻訳。「John Doe」「Acme Inc」「Lorem ipsum」「Item 1」や丸い数字はすべてのレイアウト問題を隠し、画面が生成的に見える最初の原因です。ドメインのデータが不明な場合は、サンプルを依頼するか、スキーマから派生させます。

あらゆるサイズ

画面はプライマリデバイスに最適化され、同じ機能で他のすべてのブレークポイントでも動作します。各サイズには、デスクトップの縮小コピーではなく、適切なパターンが適用されます：サイドバーはドロワーまたはアイコンレールに、テーブルは積み重ねリストに、分割ペインは戻るステップのあるページに、ホバーは可視コントロールに、高密度ツールバーはオーバーフローメニューになります。ブレークポイント以下で消える機能はフィンディングです。

ターゲット幅では横方向にスクロールするものはありません：ページも、独自のコンテナ内のリストも同様です。自由テキスト列（名前、タイトル、メール、ファイル名）は縮小および切り詰められ、ホバー時に全文が表示されます。本当に幅の広いグリッド（マトリックス、タイムライン）のみがスクロールを許可され、その旨が明示されます。

大型モニターでは、コンテンツは読みやすいメジャーを維持します：テキストブロックは 1 行あたり約 75 文字以下、フォームは列幅を維持し、テーブルは成長する可能性がありますが、自由テキスト列はスペースを取ります。

ナビゲーション

• グローバルナビゲーションはアプリのセクションをリストし、すべての画面で同じままです。
• 独自のサブエリアを持つセクションには、1 つのローカルレイヤー（2 番目の列またはタブ）を追加できます。各レイヤーは自身のレベルのみを表示します。どのレイヤーも別のレイヤーのエントリを繰り返さず、2 つのエントリがラベルを共有することはありません。
• スコープ（画面が作用する組織、ワークスペース、アカウント）は、スイッチャーで 1 回設定されます。
• すべてのページはグローバルナビゲーションから最大 2 つの選択肢で到達でき、ローカルナビゲーションはプライマリデバイスで表示されたままです。
• 最初のコントロールより上のクロームは小さく保ちます：パンくずリストはその下のページタイトルを繰り返しません。
• 多数のセクションまたは多くのレコードを持つアプリは、名前または貼り付けられた ID でページとレコードを見つけるジャンプ検索（⌘K / Ctrl+K）を提供します。

密度

• ワーキングセットを一度に表示します。ユーザーがスキャンまたは比較するリストは、1 行に 1 アイテムのテーブルです。カードグリッドは、画像やプレビューがコンテンツである少数のアイテムに使用します。

• 行の高さはコンテンツに従います：1 行の行は 36～44px、2 行目またはサムネイルがある行は最大 64px。パディングはコンテンツよりも高くなってはいけません。

• 関連アイテム間のギャップはグループ間のギャップよりも小さく、グループ化はスペースだけで読み取れます。

• 行内のすべての要素は存在価値を証明します。それぞれをテストします：

  • タスク：この画面のジョブにおいて、アイテムの検索、比較、開く、または操作に役立つこと。
  • 消去：削除するとユーザーが必要とするものが失われること。そうでなければ削除するか、詳細ビューに移動します。
  • 冗長性：列、アクティブフィルター、ページ見出しを繰り返さないこと。
  • 自己説明的：ホバー、ツールチップ、凡例なしで読め、ステータスは単語で表現され、色だけではないこと。
  • 順序：最初にアイテムを識別するもの、次にユーザーが比較する事実、最後にアクション。

  欠落している事実もフィンディングです：ユーザーが 1 つの値を比較するためにアイテムを次々と開く場合、その値は行に属します。

• デフォルトで 1 行あたり 1 行。二次的な事実は独自の列またはミュートされた 2 行目に配置し、比較のためにホバーする必要があるツールチップには決して配置しません。

• 見出し、説明、ヘルパーテキストは、ジョブが許す限り短くします。タイトルを繰り返すページ説明は削除します。

• 空白はグループを分離します。スパースな画面を埋めるためにパディングを使用することはありません。

• ボックス（境界線、背景、影）は、ユーザーが単位として操作するものをマークします。グループ化のみはスペースまたは罫線で行います。カード内のカードはフィンディングです。

階層

• ビューごとに 1 つのプライマリアクションがあり、視覚的にプライマリで、そのスコープ（ページヘッダーまたはパネルヘッダー）の右上に配置します。セカンダリアクションはアウトラインまたはゴーストにします。破壊的なアクションは最後に配置します。
• すべてのサイズ、スペース、色、半径はサーフェスのデザインシステムから取得し、その範囲内に留めます。任意の値（text-[10px]、p-[13px]、生の16進数）はフィンディングです。修正は最も近いステップ、またはどのステップも適合しない場合は新しいトークンです。
• ウェイトと色はサイズよりも前に階層を伝えます。
• 色は意味を持ちます：アクセントはプライマリアクション、選択、状態を示します。ステータスカラーはステータスが存在する場合にのみ表示されます。
• アイコンは認識を高速化する場合（ナビゲーション、頻繁なアクション）にラベルと一緒に表示され、アクセシブルな名前を持つユニバーサルアクション（閉じる、検索、その他）の場合にのみ単独で表示されます。すべてのボタン、見出し、カードにアイコンがある場合は装飾です。
• 読み取り専用の値はテキストとしてレンダリングされ、入力としてレンダリングされません。
• 視聴者のロールが使用できないコントロールは非表示にし、サーバーがチェックするのと同じ機能によって決定されます。アクションが存在することを知ることが重要な場合は、理由とともに無効で表示します（「管理者のみ招待できます」）。
• コピーは、背後にあるインフラストラクチャではなく、人々が認識する名前を付けます。ベンダー名やパイプライン名は、対象ユーザーが直接扱う場合を除き、使用しません。ナビゲーションには、未構築またはオフになっている機能はリストしません。

コピー

インターフェーステキストはデザインの一部であり、生成された画面の最も明確な兆候です。

• ボタンはその機能を動詞と目的語として示します：「メンバーを招待」「CSV をエクスポート」。アプリ内で「送信」「OK」「ここをクリック」「はじめよう」は決して使用しません。
• 確認ボタンは質問の動詞を繰り返します：「3 つのファイルを削除しますか？」→「ファイルを削除」。
• すべてのラベル、見出し、ボタンは文ケースを使用します。感嘆符、「おっと」、「正常に」、「お願いします」は使用しません。
• フィードバックはユーザーの言葉で結果を示します：「finance@… に請求書を送信しました」。 「操作が正常に完了しました」は使用しません。
• 空の状態は、ここに何が属し、どのようにここに来るかを 1 行または 2 行の平易な文で示します。機知、イラストの埋め草、「ここには何もありません」は使用しません。
• ツール内ではマーケティングの声を使用しません：「シームレス」「簡単」「パワフル」「アンロック」「スーパーチャージ」「マジック」「AI 搭載」および製品を賞賛する文はすべて削除します。
• アプリ全体で概念ごとに 1 つの用語を使用します。用語集はプロジェクトファイルにあります。
• 数字、日付、単位はアプリごとに 1 つの形式に従います。カウントは適切な複数形を使用します（「1 ファイル」「2 ファイル」）。

リストとテーブル

• 数字は tabular-nums で右揃え。テキストは左揃え。
• タイムスタンプはアプリごとに 1 つの固定形式を使用し、ブラウザのロケールデフォルトは使用しません。決して切り詰めません。監視画面では、相対時間（「3 分前」）とホバー時の絶対時間をペアにするか、その逆を行います。
• ヘッダーは列の名前を 1 語または 2 語で示します。ソート可能なヘッダーはクリックでソートします。
• 検索、フィルター、ソート、ページ、開かれたアイテムは URL に保持されるため、ビューはリロード、戻る、共有リンク後も保持されます。
• 行はそのアイテムへの実際のリンクです。行全体で開き、Cmd+クリックで新しいタブが開きます。
• 行内のすべての参照（人物、組織、ジョブ、ID）は、独自のページにリンクします。
• 行ごとのアクションは行の末尾の安定した列に配置し、静止時に表示します。少なくともタッチスクリーンでは表示します。非表示のままクリックを受け付けるコントロールはバグです。
• バルク作業には、選択チェックボックス、すべて選択、バルクアクションバーが必要です（ユーザーがアイテムをバッチで処理する場合）。
• 約 50 行を超える場合はページネーションまたはウィンドウイングを使用します。カウントは常に表示します。セットを制限するフィルター（月範囲）がある場合は、ページングを置き換え、制限が表示されます。
• フィルターチップはカウントを表示できます。その場合、ページのサマリーとしても機能します。

フォーム

• ラベルはフィールドの上、1 列、ユーザーがデータについて考える順序で配置します。
• フォーカス喪失時と送信時に検証します。エラーはフィールドの下に表示され、修正方法を示します。
• デフォルトは最も一般的な回答にします。オプションフィールドはオプションとマークし、必須フィールドはマークしません。
• 作成フォームまたはアクションフォームの送信は有効のままにします。無効な入力を送信すると、最初の無効なフィールドにフォーカスし、そのフィールドの下に修正方法を表示します。
• 編集フォームの保存は、何かが変更されるまで無効のままにすることができます。保存待ちのものがないためです。何かが変更されると有効になり、上記のルールが適用され、その横に「未保存の変更」ヒントが状態を示します。
• ビューごとに 1 つの保存。未保存の変更を残して離れる場合は、最初に確認します。
• コントロールは、自身のアクションが実行中の間は無効になり、二重送信を防ぎます。
• 短いフォームまたは単一フィールドはインラインで編集します。ダイアログは、コンテキストを失ってはいけない集中タスクに使用します。
• 入力は適切なタイプと autocomplete（email、tel、one-time-code など）を使用して、電話が正しいキーボードを表示し、ブラウザが自動入力できるようにします。
• ファイルアップロードトリガーは、ピッカーを開くフォーカス可能なボタンであり、ドロップも受け入れます。
• 別のサーフェス（オンボーディング、ブランド、テンプレート）を設定するページは、そのサーフェスのプレビューを設定の横に表示します。

アクションとフィードバック

• 元に戻す方法があるアクション（復元、アーカイブ解除、再アクティブ化）は即座に実行され、元に戻すを提供します。確認は不要です。トグルはそれ自体が元に戻す機能であり、即時のフィードバックのみが必要です。
• 元に戻す方法がないアクションには、失われるものを示す確認が必要です（「3 つのドキュメントを削除」）。元に戻せるように見えるが元に戻せないアクションは、元に戻す機能が存在するまで不可逆として扱います。
• すべてのアクションは 100ms 以内に応答します：楽観的更新、コントロールの保留状態、またはコンテンツが配置される場所のスケルトン。
• 数秒以上かかる作業は、バックグラウンドで可視的な進行状況とともに実行され、ナビゲーション後も保持されます。
• エラーは、何が発生し、次に何をすべきかを、発生場所の近くに表示します。

状態マトリックス

すべてのビューは、すべての状態をデフォルトではなくデザインして提供します：

状態	形状
ローディング	コンテンツが配置されるレイアウトのスケルトン
空	ここに何が属し、追加するアクションを提供する
フィルター結果空	フィルターが何も一致しなかったことを示し、クリアするアクションを提供する
部分	ロードされた部分はレンダリング。失敗した部分は独自のエラーを表示し、ゼロは表示しない
アクセスなし	誰がこれを表示でき、アクセスする方法を示し、先に進む方法を提供する
エラー	何が失敗したか、再試行、画面の残りの部分は引き続き使用可能
完全	実際のボリュームの実際のコンテンツ、長い名前と多数の行を含む

すべてのインタラクティブコントロールには、デフォルト、ホバー、フォーカス可視、アクティブ、無効、保留状態があります。

ダッシュボードでは、各タイルとチャートが独自の状態を持ちます。失敗した読み取りは独自のエラーを表示し、ゼロや空のチャートは表示しません。ダッシュボードは、注意が必要なものを表示して開き、メトリックカードの行では開きません。数値は、それを意味のあるものにする比較（目標、前期）と、チームが合意した定義がある場合にのみ表示されます。チャートは、dataviz スキルがインストールされている場合、それに従います。

アクセシビリティとテーマ

• 本文テキストは 4.5:1、大きなテキストとコントロールの境界は 3:1 のコントラストを、すべてのテーマで満たします。ミュートされたグレーにグレーは最も一般的な失敗です。
• フォーカスは常に可視であり、クリップされません。フォーカスリングはデザインされ、ブラウザのデフォルトは削除されません。
• すべてのコントロールにはアクセシブルな名前があります。アイコンのみのボタンは aria-label を取得します。ランドマーク（nav、main）とページごとに 1 つの h1。
• テキストは 200% に拡大され、レイアウトは保持されます。
• アプリがダークテーマをサポートする場合、それはデザインされます：独自のサーフェスステップと再調整されたアクセント。色を反転させたものではありません。すべての画面を両方でレビューします。

人間工学

• プライマリタスクはキーボードから完了します：タブ順序は読み取り順序に従い、Enter で送信、Escape で閉じ、フォーカスは元の場所に戻ります。
• クリックターゲットは少なくとも 24×24px、頻繁なものはより大きく、タッチでは 44px。ヒットエリアは行またはラベル全体をカバーし、アイコンだけではありません。
• 頻繁なアクションは、その操作対象の近くに配置します。距離とクリック数は、単一の画面ジョブの完了に費やされる時間と動きを最小限に抑えます。
• 単一の操作（名前の変更、フィルターの選択）は、追加のページ遷移なしにその場で行われます。
• パンくずリストは最初の制御から読み取ります：設定 > チーム > メンバー。
• アプリのショートカットは、使用する場所の近くのツールチップにリストされます（「⌘K で検索」）。
• テキストの選択は強調表示可能であり、UI 要素によってブロックされません。
• ウィンドウのサイズ変更は領域を再分配します。1000px のチャットは 500px では快適に読めるはずです。

レビュープロセス

レビューは、コラボレーターの介入またはスキルが明示的に要求した場合にのみこのスキルによって利用されます。レビューの前にユーザーの同意を求め、スクリーンショットを含めます。レビュースクリプト - review.sh は各ルールを名前で呼び出します。

レビューの実行方法

画面のレビューを求められたら：

1. review.sh を見つけて実行し、product-ui レビューのスクリーンショットを取得します（下記参照）。
2. このファイルを参照して、スクリーンショットを 1 つずつ調べます。
3. その画面のルールに違反する領域に注釈を付け、各違反に対して「X がこの Y ルールに違反しています」とマークします。鋭く、簡潔に、正確に。
4. 結果をユーザーに返し、優先順位を付けます：各フィンディングをその重大度（ブロッカー、メジャー、マイナー）とその違反理由とともにリストします。
5. 修正を提案します。完全な実装は行いません。コードを変更する前にユーザーと合意を得てください。

review.sh

このレポジトリのルートにある review.sh は、「このアプリの全画面をきちんとレビューする」ために使用されます。使用方法：

./review.sh product-ui   # 現在の画面を product-ui ルールでレビュー

スクリプトは、各画面のスクリーンショットを撮り、すべての product-ui ルールを確認し、違反を強調するために画像に注釈を付けます。次のスクリーンショットがレビューの一部として利用可能です：

• screenshots/screen-01.png - メインダッシュボード
• screenshots/screen-02.png - ユーザーリスト
• screenshots/screen-03.png - フォーム編集

レビューする画面のスクリーンショットにアクセスできない場合は、スキルがアクセスできる場合は自動的にスクリーンショットを撮るか、ユーザーに手動で提供するよう依頼します。

参照

• templates/project.md プロジェクト設定用テンプレート
• review.md レビュープロセスの詳細