videojs-skin

Video.js スキンをデザインする

スキンはプレーヤーの UI、つまりメディアを取り囲むコントロール、レイアウト、スタイル、インタラクションです。videojs skin create は、1 つのスキンのソースを src/ に、さまざまなサイズ、言語、再生設定でプレビューできるワークベンチを apps/preview/ に含むプロジェクトを作成します。このスキルではその環境を用意し、メディアプレーヤーに必要なルールに沿ってデザイン作業を進めます。

既存のアプリ内のスキンを別のスタイルにする場合は、Shadcn のインストール方法でソースを追加してください。その場合は videojs スキルを参照してください。

1. プロジェクトをセットアップする

作業ディレクトリにすでに skin.json がある場合は、この手順をスキップしてください。

ユーザーがターミナルを使ったことがない可能性も考慮してください。すべてのコマンドを自分で実行し、各コマンドの内容をわかりやすく説明します。ユーザーに操作をお願いするのは、パスワードが必要なソフトウェアのインストールやサインインなど、自分ではできない場合に限ります。

1. node --version を実行します。Node.js がインストールされていない場合、または現在の LTS リリースより古い場合は、作業を中断して説明してください。プロジェクトには Node.js が必要であり、ユーザーは https://nodejs.org の LTS インストーラーを使って一度インストールすればよいことを伝えます。代わりにインストールしてはいけません。インストーラーでパスワードが求められるためです。node --version が動作したら続行します。
2. npx @videojs/cli skin create <directory> --name <name> を実行します。ターミナルがない場合、このコマンドは何も変更せず、デフォルト値とともに、まだ選択する必要がある項目を一覧表示します。項目の説明は --help で確認できます。skin create が認識されない場合は、CLI が古いバージョンです。そこで作業を引き継ぎ、videojs スキルの Shadcn の方法でアプリにスキンのソースを追加するよう案内してください。また、スタンドアロンのワークベンチはないことも伝えます。この方法では skin.json、apps/preview/、deploy スクリプトは作成されないため、このスキルのワークベンチと公開の手順はスキップしてください。手順 3 と 4 のデザインに関するガイダンスと videojs-ui スキルは引き続き適用されますが、アプリ内で確認します。
3. すべての選択肢を 1 回のメッセージで提示し、まとめて確認します。フレームワークは React または HTML です。React のスタイリングには Tailwind CSS または通常の CSS を選べます。HTML のスキンでは CSS を使います。ユーザーのアプリですでに使われているものを推奨してください。最初のスキンについては、基盤から独自のデザインを作るか（Scaffold。最小限のスタイルで、すべてのコントロールが接続されています）、完成済みのデザインにブランドを適用するか（Neutral はブランドに合わせやすく、Default は Video.js 独自のデザインで、Compat は機能と引き換えにブラウザー対応範囲を広げます）を尋ねます。プリセットはプレーヤーの種類で、動画、音声、ライブ動画、ライブ音声から選びます。既存のプレーヤーやデザインに合わせる必要がある場合は、まず references/match-reference.md を読んでください。どのスキンを最初に使うかは、参考資料に基づいて決めます。
4. すべての選択肢をフラグとして付けて、コマンドを再実行します。依存関係がインストールされ、ワークベンチの起動コマンドが表示されます。開発サーバーをバックグラウンドで起動し、表示されたワークベンチの URL を共有してください。スキンのファイルの場所と、ファイルを開く方法も一文で説明します。

2. 構成を把握する

編集する前に、プロジェクトの AGENTS.md、README.md、skin.json を読んでください。これらには、このバージョンのレイアウト、スクリプト、ワークベンチについて説明されています。このスキルより、プロジェクト内の記述を優先してください。Video.js のドキュメントは、インストール済みパッケージの node_modules/@videojs/<react|html>/docs/llms.txt にあります。見つからない場合は https://videojs.org/docs/framework/<react|html>/llms.txt を参照し、ページ URL の末尾に .md を付けてください。まず、タイトルを手がかりに次のページを読みます。

必要な情報	読むページ
変更を担当するファイル	Customize skins、「Style skin source」
コントロールが公開する状態、props、レンダリングのカスタマイズ方法	UI components、その後、各コンポーネントのリファレンスページ
ショートカットとジェスチャー	Keyboard shortcuts
ラベル、言語、右から左への表示	Internationalization
コンポーネントがアクセシビリティのために備えている機能	Accessibility

3. デザインに合意する

スタイルを設定する前にスキンの見た目を合意しておきます。詳細を即興で決め、後から修正するのが最も時間のかかる進め方です。

• 参考資料に合わせる場合（製品名、既存のプレーヤー、スクリーンショット、デザインファイルなど）：references/match-reference.md に従います。参考資料の切り抜きを保存し、寸法を記載した design/spec.md を作成して、参考資料では確認できない点だけをユーザーに尋ねます。プレーヤーに合わせる場合は、コントロールのアイコンも対象に含まれます。ユーザー自身のデザインファイルから書き出すか、他者のプレーヤーからコピーせずに描き直します。
• オリジナルデザインの場合：ユーザーの要望に基づいて、レイアウトとコントロールの順序、メニュー、アイコンのスタイル、書体、色とサーフェス、スライダー、動きをまとめた短い design/spec.md を作成し、一度確認します。

どちらの場合も、仕様とユーザーが求めるものだけを作ります。求められていないコントロール、オーバーレイ、テキストを追加しないでください。

デザインの方向性を決して勝手に決めないでください。構築前と、作業中に新たな疑問が生じたときは、以下のように分類します。

• 方向性：質問する。 デザインの意図を変え、要望、参考資料、プロジェクトから判断できないものです。たとえば、ブランドカラー、雰囲気、情報密度、含めるコントロール、レイアウトのスタイルなどが該当します。具体的な選択肢を2〜3個と、それぞれのおすすめの既定値をまとめて1つのメッセージで示し、回答を待ちます。
• 実装：判断する。 合意した内容から導き出せる詳細です。たとえば、アクセントカラーから派生するホバー時の色合いや、2つのボタンの間隔などが該当します。これらは自分で判断し、質問する代わりに仕様へ 派生 と記載します。

4. 構築する

videojs-ui スキルでは、動画上でのコントラスト、アイコンの状態、動き、書体、色、ラベルなど、各コントロールの作り込みについて説明しています。また、組み合わせて使うデザインスキルと監査スキルも含まれます。スキンプロジェクトでは、次のルールも適用します。

• ワークベンチではなく、スキンを編集します。 スキンのコードはすべて src/ に置き、apps/preview/ からは何もインポートしません。これにより、そのままアプリに移せます。
• ルールより先にトークンを変更します。 色、サーフェス、角の丸み、サイズ、動きは、スキンのテーマファイルに CSS カスタムプロパティとして定義します。パッケージ化されたスキンが公開する --media-accent-color などの公開プロパティは、引き続き機能するようにします。
• 各作業工程の後に整理します。 後続のルールで上書きされるルールを削除し、メニューのサーフェス、アイコンのサイズと線幅、間隔、スライダーの形状など、複数箇所で使う値は共通のトークンとして管理します。
• コンポーネントが設定する data-* 属性（data-paused など）で状態をスタイルします。スクリプトで切り替えるクラスは使いません。
• コンテナークエリでサイズを調整します。 プレーヤーの幅がビューポートの幅と同じであることはほとんどありません。
• コンテナーの data-theme と data-preset を維持します。 スタイルはこれらの属性に基づいて適用されます。
• スキンのモーショントークンを使って動きを追加します。 環境設定用のスタイルシートが、動きを減らす設定時にこれらを無効化します。
• 見た目以外にスキンが提供する機能も維持します。 エラーダイアログ、ホットキー、ジェスチャー、ステータス通知機能は、同等のものがある場合に限って置き換えます。
• コントロールの順序は CSS ではなくソースで変更します。 フォーカス順は視覚上の順序と一致させます。スキンが処理する右から左へのレイアウトは例外です。

次に、ドキュメントに記載されているフレームワークの構成ルールに従います。React では、render 関数が受け取る props をスプレッドします。HTML では、レンダリングする要素パーツをすべてインポートし、ツールチップやポップアップをボタンに接続する id、trigger、commandfor の各ペアが一意で、互いに対応するようにします。

5. 検証

1. プロジェクトの typecheck スクリプトと build スクリプトを実行します。
2. 機能だけでなく、忠実度も確認します。リファレンスに合わせる場合は、スキンの完成を宣言したり、ユーザーにレビューを依頼したりする前に、references/match-reference.md の忠実度チェックに合格してください。それ以外の場合は、最初に動作するプレビューを design/spec.md と比較してから仕上げに進みます。見つけた差異は自分で修正し、レポートにスクリーンショットを含めてください。
3. 変更の影響を受けるすべての状態で、ワークベンチ内のスキンを確認します。オプションパネルでは幅、アスペクト比、配色、方向、言語、再生を設定でき、プロジェクトの README.md には URL から状態を開く方法が記載されています。確認すべき点については videojs-ui のレビューを参照してください。一般的な UI 監査では見落とされる、ビデオプレーヤー特有の項目も網羅しています。

6. 公開（依頼された場合）

プロジェクトの deploy スクリプトを実行すると、ワークベンチが Vercel、Netlify、または Cloudflare Pages に公開されます。公開 URL が作成され、ホスティングサービスにサインインするため、ユーザーから依頼された場合にのみ実行してください。ターミナルを使わない場合は、ホスティングサービス名を指定します。 <package manager> run deploy vercel。pnpm の場合は run を残してください。pnpm deploy は別の組み込みコマンドです。ホスティングサービスへのサインインはユーザーが完了します。

スキンが他社のプレーヤーに似ている場合は、公開または出荷する前に、アイコン、フォント、色、全体的な外観など、取り入れた要素を使用する許可があることを確認するよう、ユーザーに念を押してください。非公開でのビルドや調査と、実運用での利用は別の話であり、後者には許可が必要な場合があります。

同意を得て上流にフィードバックを送る

タスクを通じて Video.js または skin create のバグやドキュメントの不備が明らかになった場合は、区切りのよいタイミングで一度だけ、videojs スキルのフィードバックルールに従ってフィードバックの下書きを作成することを提案してください。文面への明示的な承認を得ずに送信してはいけません。