ux-ui-maxpro

ux-ui-maxpro

このリポジトリのデザインシステム上で、近似や架空のコンテンツに逸れず、参照 UI を正確に再現するためのプレイブックです。snapcn スタック（Next.js App Router + Tailwind v4 + トークン駆動の app/globals.css、DESIGN.md のルール）に最適化されていますが、手法は特定のスタックに依存しません。

唯一のルール

入力する前に測定してください。 参照を目測でそのままコードに落とし込んではいけません。まず仕様を書き出し、その仕様に基づいてコードを記述します。推測すると「まあまあ近い」仕上がりになりますが、ユーザーが「変更は一つも加えないで」と言う場合に、まさに拒否されるのがこの「まあまあ近い」状態です。

1. 参照から仕様を抽出する

デザインシステムを読み解くようにスクリーンショットを確認し、ファイルに手を加える前に具体的な数値を書き出します。

• 構造：領域（トップバー、サイドバー、コンテンツなど）の数と、それぞれの幅／高さを確認します。トップバーに境界線、シャドウ、ぼかしがあるのか、ページの背景と一体化しているのかも記録します。
• グリッド：最も幅の広いブレークポイントでの列数、ガターのサイズ、列数の変化（4 → 3 → 2 → 1）を確認します。メイソンリーの場合は、カードの高さが変わるか、どの程度変わるかを記録します。この変化のリズムこそが、通常はデザインの要です。
• カード／タイル：角の丸み、サーフェスの色、境界線の有無、シャドウの有無、オーバーレイ要素（アバター、ボタン）のサイズと角からのインセットを確認します。
• 文字：テキストの役割（タイトル、タグライン、メタ情報、ナビゲーションリンク）ごとに、サイズ、ウェイト、色を確認します。2 つの役割が同じベースライン上に並ぶ場合（太字のタイトル＋グレーのタグラインなど）も記録します。
• ピル／コントロール：カプセルの高さ、左右のパディング、間隔、有効状態と無効状態の見せ方（白黒の反転が一般的）を確認します。
• 色：サーフェスのグレーやアクセントカラーを正確に採取します。完全な #fff／#000 であることはほとんどありません。

この仕様を手元に置き、記述するクラスがすべて測定値に基づいていることを確認してください。

2. 各要素を正確なデータに対応させる

参照内の各要素について、このプロジェクトで実際に使えるデータを判断します。実際のデータに見える数値を捏造してはいけません（このリポジトリの継続的なルールです）。「オンライン 63 人」という表示は、実際に算出した数（コンポーネントの合計数など）に置き換えます。「11 時間前に最終更新」という表示は、ハードコードした文字列ではなく、API から取得した実際のタイムスタンプを、適切なフォールバック付きで表示します。正確に対応するデータがない場合は、偽の情報を表示するのではなく、その要素を省きます。参照にないアクセシビリティ機能（アイコンのみのリンクに aria-label／title を指定する、フィルターピルに aria-pressed を指定するなど）も維持します。

3. 色は必ずトークンで指定し、16 進数を直接使わない

DESIGN.md に従い、コンポーネントに色、角の丸み、シャドウをハードコードしてはいけません。参照で必要な新しいサーフェス（ギャラリーカードのグレーなど）は、app/globals.css に新しいセマンティックトークンとして追加します。

• 生の値を :root（ライトモード）と .dark（ダークモード）の両方に追加します。参照がライトモードのみでも、ダークモード側の値は必須です。ダークモードの値は目視で調整します。
• @theme inline に登録します（--color-<name>: var(--<name>)）。これにより、bg-<name>／text-<name> ユーティリティが使えるようになります。
• 正確な見た目の実現に DESIGN.md からの逸脱（カプセルボタン、ぼかしチップ、境界線のないカードなど）の記録が必要な場合は、DESIGN.md に短い追記を加え、次のコントリビューターが「修正」して元に戻さないようにします。

4. Masonry のレシピ

• CSS columns（columns-N、子要素に break-inside-avoid mb-*）をデフォルトにします。列ごとに上から下へ詰め、レイアウトシフトなしで SSR でき、そして何より、すべてのカードを1つの DOM 親要素内に保つため、安定した React の key によって、フィルタリングや並べ替えの際もカードのマウント状態が維持されます。左から右への行順が本当に必要な場合を除き、これを使ってください。
• JS によるバランス調整列（高さを測定し、最も短い列に配置する方法）は行優先の順序になりますが、初回描画時の測定処理が必要で、子要素が列ごとの親要素間で再マウントされます。行順が必須の場合に限り使ってください。
• 変化のあるリズムを作る方法：元のメディアが均一な場合（例：すべて16:9）、インデックスやスラッグに基づく安定した関数で各カードのタイル形状を決め、リストをフィルタリングしたり並べ替えたりしても形状が変わらないようにします。実際のメディアはタイルの表面内に中央揃えで収めます（ユーザーがトリミングを選択しない限り、決して切り抜かないでください）。静的なタイル比率とメディア比率を比較して、どちらの寸法を基準にするかを計算します。

5. メディア負荷の高いグリッド

100個以上のライブプレーヤーや動画があるグリッドを、すべて即座にマウントすることはできません。このリポジトリの重要なパターンを再利用します。IntersectionObserver（rootMargin: "200px 0px"）で各プレビューを遅延マウントし、マウント前はプレースホルダーを表示して、カードが画面外にスクロールされたら再生を一時停止し、一度にレンダリングされる数を少数に抑えます。フィルタリングによってカードがアンマウントされると、プレーヤーは自動的に解放されます。残ったカードが不要に再マウントされないよう、キーは安定させてください。

6. 両方のテーマでオーバーレイを使って確認する

「完了」とは、一致していることです。実際に確認してください。

• アプリを実行し、リファレンスとまったく同じブレークポイントで、構築したページのスクリーンショットを撮ります。
• 2つを約50％の不透明度で重ねる（または横に並べる）ことで、バーの高さ、ベースラインの位置合わせ、ピルの高さと間隔、ガター、カードの角丸、オーバーレイのサイズとインセットなど、測定可能な数値をすべて確認します。
• 各ブレークポイントの境界をまたいでリサイズし、指定どおりに列数が切り替わることを確認します。
• ライト／ダークを切り替え、新しいトークンが両方で正しく表示されることを確認します。
• キーボード操作（ピル → コントロール → カード）で順に移動し、フォーカスリングと ARIA を確認します。
• 変更するつもりのなかった兄弟ページを開き、バイト単位で変更されていないことを確認します。共有部分の編集は簡単に影響が漏れます。

オーバーレイが一致し、兄弟ページに変更がないことを確認するまで、完了とはしないでください。