coastdigitalgroup/coastai-skills

メディアプレーヤーUIシステム

目的

メディアプレーヤーUIシステムは、カスタムビデオおよびオーディオプレーヤーインターフェースを埋め込むための、標準化され、アクセシブルでレスポンシブなビジュアルデザインフレームワークを提供します。ブラウザ標準のHTML <video>および<audio>コントロールには深刻な制限があります。クロスブラウザでのビジュアルスタイルの不統一、ブランド非対応の外観、タップターゲットの狭さ、モバイルビューポートでのコントロール密度の非最適化、そして予測不能なキーボードフォーカスアクセシビリティです。

効果的なカスタムメディアプレーヤーを設計するには、ビデオキャンバスのフレーミング、グラデーションオーバーレイによる保護、コントロールバーの空間階層（再生/一時停止トリガー、シークタイムライン、音量スライダー、再生速度、画質、キャプション、ピクチャー・イン・ピクチャー、全画面表示）、レスポンシブなドック遷移、そして完全なWCAG AAアクセシビリティ準拠のバランスが必要です。このスキルはデザインと技術実装を橋渡しし、Webビデオおよびオーディオ体験のためのレイアウトルール、インタラクション状態、タッチエルゴノミクス、スクリーンリーダーキーボードコントロールを定義します。

ユースケース

• オンライン動画学習・コースプラットフォーム: 再生速度セレクター、チャプターマーカー、クローズドキャプション切り替え、キーボードショートカット、トランスクリプト同期を備えたカスタムビデオプレーヤーの構造化。
• SaaSマーケティング製品デモ・ヒーロービデオ: フローティングオーバーレイトリガー、ループ/ミュートコントロール、スクロール時のスティッキーピクチャー・イン・ピクチャードッキングを備えた、軽量でブランド化されたインラインビデオプレーヤーの設計。
• ポッドキャスト・オーディオストリーミングプラットフォーム: 永続的な下部オーディオプレーヤードック、インラインオーディオカードプレーヤー、ウェーブフォームビジュアライザー、スキップフォワード/バックワードジャンプコントロールの構築。
• メディアポータル・編集系ニュースサイト: 画質ピッカー、ピクチャー・イン・ピクチャーオプション、関連ビデオオーバーレイ、アクセシブルなキャプションを備えたレスポンシブヒーロービデオプレーヤーの提示。
• デザインシステムコンポーネントライブラリ: エンタープライズデザインシステム向けの、標準化されテーマ変更可能なメディアプレーヤーのビジュアル設計図とアクセシビリティパターンの確立。

使用すべきでない場合

• 未加工のスタイル未適用ブラウザコントロール: 標準のネイティブブラウザコントロール（controls属性）で十分な、迅速な内部ツールや単純なプロトタイプの場合は、標準的なHTMLマークアップで十分です。
• 本格的なビデオ編集またはキャンバスベースのタイムラインワークステーション: タイムラインシークトラック、キーフレーム操作、WebGLキャンバスレンダリングを必要とするマルチトラック非線形Webビデオエディターの場合は、専用のビデオ編集アプリケーションを使用してください。
• 純粋な背景装飾アニメーション: オーディオ、シークコントロール、ユーザー再生コントロールを必要としない、アンビエントCSSまたはキャンバスアニメーションの場合は、interface-motion-systemまたは標準のミュート背景ループを使用してください。
• 静止画像ライトボックス・ギャラリー: 時間ベースのメディア再生を伴わない静止写真やスライドデッキを表示する場合は、image-gallery-and-lightbox-systemを使用してください。

入力

1. メディアタイプとアスペクト比: オーディオ vs ビデオ形式、ネイティブアスペクト比（16:9ワイドスクリーン、9:16縦型ビデオ、1:1スクエア、または柔軟なオーディオ高さ）。
2. コントロール密度要件: 必要なメディアコントロール（例：再生/一時停止、タイムラインシークバー、現在時刻/再生時間、音量、再生速度、CC/キャプション、画質セレクター、PiP、全画面、10秒ジャンプ）。
3. テーマとブランディングトークン: コントロールバーの背景オーバーレイ、プライマリブランドの再生ハイライト、シークバーのプログレスバー、フォーカスリング、タイポグラフィのためのカラートークン（accessible-color-system、focus-indicator-design-system、fluid-typography-systemから取得）。
4. レイアウトシェルコンテキスト: 配置環境（埋め込みインラインカード、全幅セクションヒーロー、下部永続スティッキードック、モーダルオーバーレイダイアログ）。

出力

1. 空間レイアウトとアスペクト比コンテナ: レスポンシブフレーミング、アスペクト比維持、オーバーレイスタッキングコンテキストを確立するCSSアーキテクチャ。
2. コントロールバー階層設計図: メディアコントロールツールバー（左側再生コントロール、中央タイムラインシークバー、右側セカンダリコントロール/全画面表示）のビジュアル空間レイアウト。
3. シークバータイムラインと音量スライダー仕様: ホバー時の時間プレビューツールチップ、読み込み済みバッファインジケーター、ビジュアルプログレスフィルを備えたアクセシブルなレンジコントロール。
4. スティッキーピクチャー・イン・ピクチャードック遷移: ユーザーがプライマリビューポートコンテナをスクロールで通過したときに、ビデオプレーヤーをフローティング下部コーナーミニプレーヤーに折りたたむためのレスポンシブルール。
5. アクセシブルなARIAとキーボードナビゲーションマッピング: 完全なキーボードショートカット仕様（Space、K、J、L、M、F、C、矢印キー）、ARIAライブリージョンステータスアナウンサー、WCAG AAコントラスト準拠。

---

ワークフロー

1. 空間コンテナとアスペクト比フレームの確立

メディア読み込み中にレイアウトシフト（CLS）を防ぐベースコンテナを構築します。

• アスペクト比ボックス: CSSのaspect-ratio（aspect-ratio: 16 / 9; width: 100%; position: relative; background: #000; border-radius: 8px; overflow: hidden;）を使用してビデオ要素をラップします。
• メディアレイヤーのスタッキング:
  • z-index: 1: コンテナを埋めるネイティブ<video>または<canvas>メディア要素（width: 100%; height: 100%; object-fit: contain;）。
  • z-index: 2: コントロールバーの視認性を保護する暗いグラデーションオーバーレイ（background: linear-gradient(to top, rgba(0,0,0,0.85) 0%, rgba(0,0,0,0.3) 40%, transparent 100%); pointer-events: none;）。
  • z-index: 3: 中央の大きな再生/一時停止ボタンオーバーレイまたはローディングスケルトン状態。
  • z-index: 4: 下部（およびオプションで上部）のコントロールバーツールバーコンテナ。

2. 中央の大きな再生トリガーとローディング状態の設計

最初の再生エンゲージメントのための顕著なビジュアルアフォーダンスを提供します。

• 大きな再生ボタンオーバーレイ: 正確なビジュアルセンターに、目立つ64x64px（デスクトップ）または56x56px（モバイル）の円形ボタンを配置します（top: 50%; left: 50%; transform: translate(-50%, -50%);）。
  • スタイル: background: rgba(0, 0, 0, 0.65); backdrop-filter: blur(8px); border: 2px solid rgba(255, 255, 255, 0.3); border-radius: 50%; color: #FFFFFF;
  • ホバー/フォーカス: scale(1.1); background: var(--brand-primary); border-color: transparent;
  • 動作: 再生が開始されるとフェードアウトし（opacity: 0; pointer-events: none; transition: opacity 0.25s ease;）、一時停止時に再表示されます。
• バッファリング/ローディングスピナー: メディアバッファが再生しきい値を下回ったときに、ビデオキャンバスの中央に重なる高コントラストの円形不確定スピナーオーバーレイを表示します。

3. 下部コントロールバー階層の構築

メディアフレームの下部に固定された、クリーンな3パートのフレックスレイアウトにコントロールを整理します。

• コンテナの配置: position: absolute; bottom: 0; left: 0; right: 0; padding: 12px 16px; display: flex; flex-direction: column; gap: 8px; z-index: 4;
• プライマリシークバー行（行1）: インタラクティブなタイムラインシークバーをコントロールバーの上部に全幅で配置するか、水平レイアウトではインラインで配置します。
• コントロールバーアクション行（行2）:
  • 左グループ（再生と音量）:
    1. 再生/一時停止ボタン: 40x40pxのアイコンボタン（aria-label="再生" / aria-label="一時停止"）。
    2. スキップバック/フォワード（オプション）: 「10秒戻る」/「10秒進む」ための36x36pxボタン。
    3. 音量グループ: ミュート切り替えアイコンボタン + ホバー/フォーカスで展開可能なレンジスライダー（width: 0 -> 80pxのスムーズなトランジション）または永続的なスライダー。
    4. 時間表示: 等幅数字を使用したテキストカウンター02:14 / 10:45（font-variant-numeric: tabular-nums; font-size: 0.8125rem; color: #FFFFFF;）。
  • 右グループ（設定と画面モード）:
    1. クローズドキャプション（CC）切り替え: アクティブ時に視覚的なアクティブバッジハイライトを表示するアイコンボタン（border-bottom: 2px solid var(--brand-primary)）。
    2. 再生速度メニュートリガー: アクティブな速度（例：1.0x、1.5x、2.0x）を表示するドロップダウンまたはポップオーバーボタン。
    3. ピクチャー・イン・ピクチャー（PiP）トリガー: ブラウザのPiPモードを起動するアイコンボタン。
    4. 全画面切り替え: 全ウィンドウ/全画面表示を切り替えるアイコンボタン（aria-label="全画面に入る" / aria-label="全画面を終了"）。

4. アクセシブルなタイムラインシークバーと音量スライダーの構築

タイムラインシークバーは、完全にタッチフレンドリーで、正確で、キーボードアクセス可能でなければなりません。

• レンジ入力アーキテクチャ: <input type="range" min="0" max="100" step="0.1">またはカスタムARIAスライダー（role="slider"、aria-valuemin="0"、aria-valuemax="100"、aria-valuenow="23"、aria-valuetext="10分45秒のうち2分14秒"）を使用します。
• トラックのレイヤリング:
  1. 背景トラック: ベースのグレートラック（height: 4px; background: rgba(255,255,255,0.3); border-radius: 2px;）。ホバー/フォーカス時にトラックの高さを8pxに拡大します。
  2. バッファバー: プリロードされたバッファビデオを示すセカンダリバー（background: rgba(255,255,255,0.5);）。
  3. 再生済みフィルバー: 再生された進行状況を示す鮮やかなプライマリカラーバー（background: var(--brand-primary, #3B82F6);）。
  4. シークバーつまみ: 14x14pxの円形つまみハンドル（background: #FFFFFF; box-shadow: 0 2px 4px rgba(0,0,0,0.4);）。ホバー/ドラッグ時に18x18pxに拡大します。
• ホバー時間プレビューツールチップ: シークバートラックに沿ったカーソルホバー位置の上に、フローティングタイムスタンプボックス（background: #000; padding: 4px 8px; border-radius: 4px; font-size: 0.75rem;）を表示します。

5. ピクチャー・イン・ピクチャー（PiP）とスクロール駆動スティッキードッキングの実装

ユーザーが長い記事や製品ページをスクロールダウンする際に、ビデオコンテキストが失われるのを防ぎます。

• スクロールオブザーバー（IntersectionObserver）: プライマリメディアコンテナがアクティブビューポートのしきい値（20%未満表示）を超えてスクロールアウトしたときを追跡します。
• フローティングミニプレーヤー状態:
  • プレーヤーをフローティング固定コーナードックに遷移させます（position: fixed; bottom: 24px; right: 24px; width: 320px; aspect-ratio: 16/9; z-index: 1000; box-shadow: var(--shadow-xl); border-radius: 12px; border: 1px solid var(--border-subtle); animation: slideInUp 0.3s ease;）。
  • ミニプレーヤーに右上の閉じる/展開ボタンを追加します（aria-label="スティッキープレーヤーを閉じる" / aria-label="ビデオ位置に戻る"）。
  • スティッキーモードでは、コントロールバーをプライマリの再生/一時停止、閉じる、ミュートトリガーに簡略化します。

6. キーボードショートカットとARIAアクセシビリティの実装

マウスやポインター操作を必要とせず、完全なキーボードコントロールを保証します。

• グローバル/フォーカスされたキーボードショートカット:
  • SpaceまたはK: 再生/一時停止の切り替え。
  • J: 10秒巻き戻し。
  • L: 10秒早送り。
  • 左矢印 / 右矢印: 5秒巻き戻し/早送り。
  • 上矢印 / 下矢印: 音量を10%増加/減少。
  • M: ミュート/ミュート解除の切り替え。
  • F: 全画面モードの切り替え。
  • C: クローズドキャプションのオン/オフ切り替え。
  • 0から9: ビデオ合計再生時間の0%〜90%にシーク。
• スクリーンリーダーステータスアナウンス:
  • 非表示のaria-live="polite"リージョンにステータス更新を送信します（例：「2分14秒で一時停止しました」、「音量が80%に設定されました」、「キャプションが有効になりました」）。

---

決定ルール

メディアコントロールバーレイアウト設定

メディアタイプと配置	コントロールバーの空間パターン	推奨キーコントロール
ヒーロービデオ/コースビデオ（>640px）	全フローティングオーバーレイバー	フルコントロール: 大きな中央再生、フルシークバー、時間、音量、CC、速度、PiP、全画面。
コンパクトインラインビデオカード（<480px）	コンデンスフローティングバー	必須コントロール: 再生/一時停止、インラインシークバー、時間、ミュート切り替え、全画面。
永続的な下部オーディオドック（グローバル）	スティッキー3カラムバー	左: トラック情報（サムネイル+タイトル）; 中央: 再生/一時停止+10秒ジャンプ+シークバー; 右: 音量+プレイリスト。
インラインオーディオポッドキャストカード	水平埋め込みボックス	再生/一時停止円形ボタン、トラックタイトル+プログレスシークバー、現在時刻/合計時間、速度メニュー。

ビデオオーバーレイ自動非表示戦略

• 再生中: ビデオキャンバス内でポインターが2.5秒間非アクティブな場合、オーバーレイコントロールバーを自動非表示にします（opacity: 0; cursor: none; transition: opacity 0.3s ease;）。
• 一時停止中またはフォーカス中: コントロールバーを常に表示状態に保ちます（opacity: 1）。
• キーボードフォーカス時: プレーヤー内のコントロールボタンにキーボードフォーカスが入るたびに、コントロールを即座に表示状態に保ちます（:focus-within { opacity: 1; }）。

---

制約

• アクセシビリティ（WCAG 2.1 AA）:
  • SC 1.2.2 キャプション（収録済み）: 音声を含む同期ビデオメディアには、クローズドキャプションボタンを提供する必要があります。
  • SC 1.4.3 コントラスト（最小）: コントロールアイコン、テキストカウンター、シークバープログレストラックは、コントロールオーバーレイ背景に対して少なくとも4.5:1のコントラスト比を維持する必要があります。
  • SC 2.1.1 キーボード: すべてのプレーヤー機能（再生、一時停止、シーク、音量、CC、速度、全画面）は、キーボードナビゲーションで完全に操作可能でなければなりません。
  • SC 2.4.7 フォーカスの可視化: フォーカスされたプレーヤーコントロールボタンは、クリップされていない高コントラストのフォーカスインジケーターを表示する必要があります（outline: 2px solid #FFFFFF; outline-offset: 2px;）。
  • SC 2.5.8 ターゲットサイズ: インタラクティブなコントロールボタンとスライダーつまみは、最小タップターゲット24x24px（モバイル/タッチビューポートでは最小44x44px）を提供する必要があります。
• レイアウトシフト防止: ビデオ読み込み中のページレイアウト再計算を防ぐため、アスペクト比ラッパーはCSSのaspect-ratioまたはパディングトップハックで宣言する必要があります。
• タッチジェスチャーエルゴノミクス: モバイルタッチデバイスでビデオキャンバスの左/右ゾーンをダブルタップすると、10秒のスキップバック/フォワードをトリガーし、視覚的なリップルフィードバックを表示する必要があります。

---

一般的な障害パターン

• アクセシブルでないネイティブカスタムラッパー: ネイティブブラウザコントロールを非表示にしながら、カスタムHTML <div>ボタンにキーボードショートカットやARIA属性を提供しないため、キーボードおよびスクリーンリーダーユーザーを完全にブロックします。
• ちらつくオーバーレイコントロール: マウスがシークバースライダーの近くでアクティブに動いている間、遅延やトランジションなしでコントロールバーを即座に非表示にします。
• 制約のない全画面スケーリング: 全画面モードで適切なアスペクト比を維持できず、ビデオの比率が引き伸ばされたり歪んだりします。
• 明るいビデオフレーム上の低コントラストコントロール: 基礎となる暗いグラデーションオーバーレイ（rgba(0,0,0,0.7)）なしで、プレーンな白色のコントロールアイコンをレンダリングし、明るいビデオフレーム上でコントロールが見えなくなります。
• ページ内の複数プレーヤーによるキーボードショートカットの競合: 単一ページに複数のプレーヤーインスタンスがある場合に、どのプレーヤーインスタンスがキーボードショートカットに応答するかを適切にスコープ指定しません。
• ピクチャー・イン・ピクチャードックの難点: スクロールドリブンのスティッキードッキングの実装に失敗し、ユーザーが記事を読む際にビデオを追跡できなくなります。