coastdigitalgroup/coastai-skills

画像ギャラリーとライトボックスシステム

目的

画像ギャラリーとライトボックスシステムは、Web 上でメディアコレクションを展示するための厳格な設計方法論を提供します。画像や動画のグループを静的グリッド（ギャラリー）で提示し、それらのアセットをインパクトが高く、邪魔にならないフルスクリーンオーバーレイ（ライトボックス）に移行する方法を構造化します。このシステムにより、視覚的なポートフォリオ、e コマース製品のズーム、ケーススタディが、高い応答性を維持し、深いアクセシビリティ準拠（WCAG AA）を実現し、タッチスワイプジェスチャー、キーボードコントロール、フォーカストラップを通じて物理デバイスをサポートします。

使用例

• 写真、アートワーク、建築デザイン、ケーススタディを展示するポートフォリオサイト。
• 大規模な詳細画像の探索が必要な e コマース商品詳細ページ（PDP）。
• インタラクティブなフォトギャラリーを特集する記事のあるコンテンツリッチなメディアサイト。
• イベント写真や体験談を表示するイベントページやマーケティングランディングページ。
• 高解像度の内装および外観ツアーを備えた物件を提示する不動産ウェブサイト。

使用すべきでない場合

• 単一の背景またはインライン メディア: ズームやカルーセル形式のインタラクションを必要としない、スタンドアローンでグループ化されていない背景画像や、単純なインラインの記事図の場合。
• データ量の多いダッシュボードビュー: プライマリタスクが構造化データポイント（表やグラフなど）の並べ替えや分析であり、フルスクリーンオーバーレイがワークスペースを中断する場合。代わりに data-table-ui-system を使用します。
• 複雑なドキュメントまたは PDF: ユーザーが複数ページのテキスト文書を読む必要がある場合。ライトボックスは視覚メディア向けに最適化されており、読書主体のアセットには適していません。
• 独立したコンテキストモーダル: ダイアログに、構造化されたメディアではなく、フォーム入力、設定、またはリッチなインタラクティブアプリケーションが含まれている場合。代わりに overlay-and-dialog-system または settings-interface-system を使用します。

入力

1. メディアインベントリ: 高解像度のソースアセットと、それに対応する低解像度または圧縮されたサムネイルバリアント。
2. コンテキストメタデータ: タイトル、説明、著作権情報、キャプション、および必要なアクセシビリティ代替（alt）テキスト。
3. レスポンシブスペーシングルール: サイトの確立された responsive-grid-system と fluid-spacing-system に基づく、ターゲットグリッドのガター、マージン、およびレイアウト列ルール。
4. インタラクティブコントラストパレット: コントロールオーバーレイ、クローズボタン、ページネーションドットのための、アクセシブルなテキストおよびアイコンの色指定（WCAG 4.5:1 の最小コントラストを満たす）。

出力

1. ギャラリーグリッド仕様: 定義された列レイアウト、画像アスペクト比、ホバー状態、およびフォーカルポイント保存ルール。
2. ライトボックス構造設計図: フルスクリーンオーバーレイの構造。コントロール（前へ、次へ、閉じる）、キャプションの位置、サムネイルストリップのレイアウトを詳細に示します。
3. ジェスチャーおよびキーボード仕様: キーボードイベント、タップ/タッチゾーン、ドラッグ/スワイプ動作をマッピングした、完全なインタラクションマトリックス。
4. アクセシビリティランドマークマップ: 論理的なロール（dialog、group）、ラベル（aria-label）、フォーカストラッピングルール、およびリアルタイムの状態通知。

ワークフロー

1. ギャラリーグリッドの基礎を構築する

まず、プライマリページギャラリーを構造化して、スキャンと画面領域のバランスを取ります。

• アスペクト比の標準化: ギャラリーサムネイルを均一なアスペクト比（例：1:1 の正方形または 4:3 の標準）でグループ化し、整然としたリズムを確立します。CSS の aspect-ratio プロパティを使用して、レイアウトのずれを防ぎます。
• ギャップとガター: グリッドギャップには fluid-spacing-system トークン（通常 --space-s または --space-m）を使用します。
• ホバー/フォーカスのアフォーダンス: interactive-state-system の規則を適用します。ユーザーがサムネイルにホバーまたはフォーカスしたときに、微妙な視覚的変化（ズームスケーリング、ソフトオーバーレイコントラスト、カスタム検索/ズームカーソルなど）をトリガーして、アイテムがクリック可能であることを示します。
• セマンティック HTML: ギャラリーをリストラッパー（<ul> / <li>）を使用して構造化し、サムネイルを button 要素（またはインデックス作成/ディープリンクが必要な場合はリンク）としてマークして、キーボードでの到達可能性を確保します。

2. フルスクリーンライトボックスの背景をデザインする

ライトボックスの背景は、ビューアーをページの残りの部分から分離する必要があります。

• スクリムレイヤー: ソリッドまたは半透明の背景（例：95% の不透明度の #0a0a0a、またはダークな backdrop-blur）をオーバーレイして、周辺の注意散漫を排除します。
• アスペクト比の保持: アクティブな画像をビューポートの絶対中央に配置します。コンテナが max-width: 90vw および max-height: 80vh で動的にスケーリングされ、ソースのアスペクト比をクリッピングやトリミングせずに、任意のビューポートに収まるようにします。
• ローディング状態: 中央に配置された視覚的なインジケーター（スピナー、ローディングスケルトン、プログレスリング）を aria 対応（aria-busy="true"）で構築し、ユーザーが高解像度アセットをダウンロードしていることを確実に認識できるようにします。

3. ナビゲーションコントロールとキャプションオーバーレイを確立する

オーバーレイ要素を配置およびスタイリングして、デスクトップとモバイルでの人間工学を最適化します。

• 閉じるターゲット: 閉じるボタンを右上隅に配置します。明確な視覚的境界を持ち、最小タッチターゲットサイズ48x48px（または WCAG に従って 44x44px）を満たし、明確なキーボードフォーカスリングを維持する必要があります。
• 前へ & 次へ矢印: ナビゲーション矢印を左右のマージンに垂直に中央配置します。モバイルデバイスでは、これらの矢印を非表示にするか、少し内側に配置して、タッチスワイプ操作に完全に集中できるようにします。
• キャプションとインデックスインジケーター: セマンティックなキャプションとインデックス（例：「12 枚中 3 枚目の画像」）をコンテナの下部に配置します。インデックスが更新されたときに、スクリーンリーダーに変更イベントを通知するために aria-live コンテナを使用します。
• サムネイルストリップ: メイン画像の下に、スクロール可能な小さなサムネイルの行を表示します。アクティブなアイテムを、太くてコントラストの高い境界線と明確な :focus アウトラインで強調表示します。

4. キーボードとジェスチャーのメカニズムを配線する

ライトボックスは、デスクトップ周辺機器とモバイルジェスチャーのインタラクションを同等にエレガントに処理する必要があります。

• キーボードマッピング: キーコントロールの即時サポートを確保します。Escape でライトボックスを閉じ、ArrowRight/ArrowDown で「次へ」をトリガーし、ArrowLeft/ArrowUp で「前へ」をトリガーします。
• フォーカストラッピング: ライトボックスが開いたら、キーボードフォーカスをその中にトラップします。ユーザーは背景ページにタブで戻ることができません。最初にフォーカスされる要素は、メインダイアログコンテナまたは閉じるボタンである必要があります。
• フォーカスの復元: ライトボックスが閉じたら、すぐにトリガーとなった特定のサムネイルボタンにフォーカスを戻します。
• スワイプでナビゲート: スムーズなスワイプ左およびスワイプ右のタッチスクリーンジェスチャーをサポートします。
• スワイプで閉じる: 垂直方向（上または下）にドラッグまたはスワイプしてライトボックスをすばやく閉じることができるようにし、ネイティブのモバイルオペレーティングシステムのパターンを再現します。

5. アクセシビリティとドキュメントアウトラインを最終決定する

高度な ARIA 宣言を適用して、WCAG AA 準拠のスクリーンリーダーエクスペリエンスを保証します。

• ロールとラベル: ライトボックスラッパーに role="dialog"、aria-modal="true" をマークし、aria-label または aria-labelledby を使用してタイトル/キャプションを参照してラベルを付けます。
• 背景の遮蔽: ライトボックスがアクティブな場合、メインページラッパー（<main> または #app-root）に aria-hidden="true" を適用して、スクリーンリーダーのスイープをオーバーレイ内に分離します。
• ライブアップデート: 画像のタイトル/キャプションの変更が通知されるように、それらを aria-live="polite" ゾーン内に配置するか、そのゾーンを介して参照します。

決定ルール

• 解像度分割: ギャラリーグリッド内のサムネイルは、大幅に圧縮され、適切なサイズ（例：最大幅 600px）である必要があります。ライトボックスはマスターの高解像度バリアントをロードする必要がありますが、モバイル帯域幅を節約するために、オンデマンドでのみ（次のスライドと前のスライドを遅延ロード）ロードします。
• キーボード vs タッチの優先順位: モバイルビューポート（幅 < 768px）では、画像の画面スペースを優先します。デスクトップの UI コントロール（前へ/次へ矢印）を非表示にしてタッチスワイプジェスチャーを優先しますが、常に非常に視認性の高い「閉じる」ボタンを維持します。
• 無限ループ vs ハードストップ:
  • *無限ループ（最後のアイテムの後、カルーセルが 1 にループバック）*を使用するのは、クリエイティブなポートフォリオ、体験談、または流動的なスキャンが好まれる製品の場合です。
  • *ハードストップ（最後のアイテムで次へ矢印を無効にする）*を使用するのは、方向性が重要なステップバイステップのチュートリアル、指示セット、または時系列の場合です。
• キャプション vs オーバーレイスペース: 画像に長い説明がある場合は、画像自体の上にオーバーレイしないでください。画像の境界の下にある専用の下部バーに配置し、テキストが垂直画面スペースをオーバーフローする場合に独立してスクロールできるようにします。
• デスクトップカーソルのアフォーダンス: デスクトップカーソルを動的に変更します。
  • ギャラリーサムネイルにホバー中: cursor: zoom-in
  • アクティブなライトボックス画像（ズーム可能）: cursor: zoom-in（クリックするとフル解像度に拡大され、カーソルが cursor: zoom-out に変わりパン可能になります）。
  • ライトボックスの背景にホバー中: cursor: pointer（クリックでオーバーレイを閉じます）。

制約

• レスポンシブ性: 画像はライトボックス内で歪んだり、アスペクト比を失ったりしてはなりません。コンテナはフレキシブルなビューポート単位（vw/vh）と CSS の object-fit: contain を使用して、すべてのデバイスの向きで画面境界内に厳密に収まる必要があります。
• コントラスト比: 閉じる、ナビゲーション、サムネイルのインタラクティブコントロールは、背景および画像オーバーレイに対して少なくとも 4.5:1 のコントラスト比を満たす必要があります。
• フォーカス状態: すべてのアクティブなナビゲーション要素は、表示可能な :focus-visible リングを持っている必要があります。フォーカスインジケーターは、バウンディングボックスや隣接する要素によってクリップされてはなりません。
• タッチターゲット: モバイルデバイスのタップターゲットは、WCAG 2.2 SC 2.5.8（少なくとも 24x24px、ただしプライマリアクションである閉じるやナビゲーションには 44x44px を強く推奨）を満たす必要があります。

一般的な失敗パターン

• 「無限タブトラップ」: 開いているライトボックスから背景ページにタブアウトしてしまい、スクリーンリーダーが非表示のコンテンツを読み上げ、キーボードナビゲーションが壊れます。
• 「画像オーバーラン」: 縦長のポートレート画像がモバイルビューポートの上端または下端を超えて拡大し、ナビゲーション矢印や閉じるボタンに完全に到達できなくなります。
• フォーカルポイントの喪失: 静的なギャラリーでのサムネイルが、絶対中央のトリミングにより、コアな被写体（人物の頭など）を切り取ってしまいます。object-position またはカスタムのレスポンシブクロッピングを使用して解決します。
• 「デッドエスケープ」: Escape キーを配線し忘れ、キーボードのみのユーザーがモーダルオーバーレイ内に閉じ込められ、閉じる直感的な方法がなくなります。
• 開くときのレイアウトシフト: ライトボックスを開くときにブラウザのスクロールバーが消え、背景ページのレイアウト全体がガタついたり横にずれたりします。一致するガターまたはスクロールロックパディングを追加して解決します。
• フォーカスの復元なし: ライトボックスを閉じると、フォーカスがサイトマップまたは body の先頭にリセットされ、キーボードユーザーは元の場所に戻るためにヘッダーナビゲーション全体を再度タブ移動する必要があります。

検証基準

• ギャラリーサムネイルが標準化されたアスペクト比を使用し、明確なホバー/フォーカスインジケーターがある。
• アクティブなライトボックス画像がアスペクト比を維持し、ビューポート制限（max-width: 90vw および max-height: 80vh）内に完全に収まる。
• 閉じるボタンと矢印が、背景レイヤーに対して最小 4.5:1 のコントラスト比を満たしている。
• キーボードナビゲーションがアクティブである: Escape で閉じる、ArrowRight で進む、ArrowLeft で戻る。
• ライトボックスが開いているときはフォーカスが内部にトラップされ、閉じると元のギャラリー要素に完全に復元される。
• タッチジェスチャーが有効である: モバイルビューポートでスワイプ左/右でナビゲート、スワイプ上/下で閉じる。
• ライトボックスモーダルがアクティブなとき、メインページラッパーに aria-hidden="true" がマークされている。
• ローディング状態のスピナーが表示され、高解像度アセットのロード中に aria-busy="true" がマークされている。