framevideo-visual-qa

FrameVideo ビジュアル QA

使用する場面

次のような場合にこのスキルを使用します。

• 納品前の最終 QA — 準備完了と伝える前に、構図を確認します
• レイアウト変更後 — 重なりやクリッピングが発生していないか確認します
• キャプション／字幕の追加 — テキストがほかの要素と重なっていないか確認します
• アセットの配置 — ロゴ、CTA、重要な UI がセーフエリア内にあるか確認します
• コントラストの問題 — 背景に対して読みにくいテキストを修正します
• アニメーションの衝突 — 動きの中で重なりを検出します

使用しない場面

次のような場合は、このスキルの使用を避けてください。

• ブランドアイデンティティのデザイン — ブランドルールについては、プロジェクトの frame.md または DESIGN.md を参照してください
• アニメーションの作成 — framevideo スキルを使用してください（このスキルは QA 専用です）
• 色やフォントの選択 — これは読みやすさのためのものであり、デザインを決めるためのものではありません
• パフォーマンスの問題 — レンダリングの問題には framevideo-cli スキルを使用してください

---

クイックスタート

コンポジションの作成／編集後に、ビジュアル QA を実行します。

# 1. Lint structure
npx framevideo lint

# 2. Validate runtime
npx framevideo validate

# 3. Visual inspection (samples key frames)
npx framevideo inspect

# For dense videos, sample more frames
npx framevideo inspect --samples 15

# Or check specific moments
npx framevideo inspect --at 1.5,4,7.25

手動での確認項目：

1. 最初にヒーローフレームを確認 — すべてのテキストが見える、最も混み合った場面を見つけます
2. タイムライン上のフレームを確認 — 各シーンの開始、表示中、終了のフレームを確認します
3. セーフエリア — 重要なコンテンツは端から 5% 離します（1920x1080 の場合、横方向に 96px、縦方向に 54px）
4. コントラスト — テキストが読みやすいことを確認します（WCAG AA の最低基準）
5. 重なりがないこと — アニメーション中にテキストやロゴが衝突しないことを確認します

---

確認手順

1. 最初にヒーローフレームを確認 — 各シーンで、重要なテキスト、前景のアセット、キャプション、CTA、ロゴがすべて見える、最も混み合った読みやすい場面を特定します。アニメーションを信頼する前に、そのフレームを確認してください。
2. 次にタイムライン上のフレームを確認 — 各シーンの開始、表示中、終了直前のフレームを確認します。静止した開始時点と最後の表示状態の間に、動的な問題が発生することがよくあります。
3. 最後にツールを使用 — コマンドを実行し、その出力を根拠として扱います。

npx framevideo lint
npx framevideo validate
npx framevideo inspect

情報量の多い動画では、次を使用します。

npx framevideo inspect --samples 15
npx framevideo inspect --at 1.5,4,7.25

既知のヒーローフレーム、キャプションの多い場面、CTA の表示中、またはユーザーが指定したフレームには、--at を使用してください。

セーフエリア

基本的に、重要な情報はセーフエリア内に収めてください。

• 重要なテキスト、ロゴ、CTA、キャプション、プレゼンターの顔、製品 UI、法的表記／価格表記は、端から離してください。
• 16:9 のコンポジションでは、重要なコンテンツのために、キャンバスの幅と高さのそれぞれ少なくとも約 5% を四辺に確保してください。1920x1080 のフレームでは、横方向に約 96px、縦方向に約 54px です。
• キャプションや CTA には、より広めの下部エリアを確保してください。特に、プログレスバー、プラットフォーム UI、ローワーサードが存在する可能性がある場合は注意してください。
• フルブリードの背景、グロー、グレイン、パーティクル、ワイプ、トランジション素材は、フレームの外にはみ出してもかまいません。inspect で報告されないように、意図的なはみ出しには data-layout-allow-overflow を指定してください。
• 監査対象にしない装飾要素には data-layout-ignore を指定してください。

ユーザーから端に寄せたデザインを明示的に求められ、フレームが視覚的に確認されている場合を除き、最外周の 5% には読み取れるテキスト、ロゴ、重要な製品 UI を配置しないでください。

コントラスト

コントラストの判定には npx framevideo validate を使用してください。デフォルトで WCAG AA 監査を実行します。

• 通常のテキストは 4.5:1 以上にしてください。
• 大きなテキストは 3:1 以上にしてください。大きなテキストとは、24px 以上、または太字の場合は 19px 以上を指します。
• 暗い背景では、既存の前景色を明るくしてください。
• 明るい背景では、既存の前景色を暗くしてください。
• プロジェクトのパレットの系統から外れないようにしてください。コントラスト基準を満たすためだけに、新しいブランドカラーを作らないでください。
• 警告がトランジション中のフレーム、または表示前で見えない要素をサンプリングしている場合は、その正確なタイムスタンプを確認してから、問題なしと判断してください。

コントラストに関する警告が出るたびに、次のいずれかを判断してください。

• 実際の問題 — テキストが表示されており、コントラストが不十分です。色、背景プレート、シャドウ、スクリーン、または配置を修正します。
• サンプリング上のアーティファクト — テキストがまだ読めない、フェードの途中にある、またはそのタイムスタンプでは意図的に非表示になっています。その理由を記録してください。

レイアウトとテキスト

アニメーションを追加または評価する前に、読みやすい完成状態を構築して確認してください。

• コンテンツのレイアウトには、flex、grid、パディング、gap、max-width、明示的な領域を優先してください。
• 装飾、オーバーレイ、意図的に固定する要素には絶対配置を使用してください。メインコンテンツの配置に、上端や左端を基準とした絶対配置は避けてください。
• テキストコンテナーには、実際の幅制約を設定してください。動的なテキストには、max-width、自然な折り返し、または window.__framevideo.fitTextFontSize(...) を使用してください。
• 可変のテキストに強制的な改行を使用しないでください。長いテキストは複数のシーンに分割してください。
• 1つのシーンに35語以上のテキストがある場合は、分割してください。
• ラベルやバッジのテキストが動的に変わる場合は、コンテナーを伸縮可能にするか、フォントサイズを調整してください。固定サイズのバッジは、テキストが切れる原因になりがちです。
• キャプションが CTA、ロゴ、プレゼンターの顔や体、製品 UI、または法的に重要なテキストに重ならないようにしてください。

テキスト、キャプション、ユーザー提供のテキスト、変数、翻訳文字列が変更される可能性がある場合は、必ず inspect を実行してください。

重なりとレイヤー

視覚的な重なりが許容されるのは、意図的で読みやすい場合に限られます。例：テキストの背後の影や光彩、Z 軸方向に重ねたカード、テクスチャ、奥行き、トランジション効果。

以下は不具合として扱い、修正してください。

• 2つの読み取り可能なテキストブロックが、同時に同じ領域を占めている。
• キャプションのテキストが、ローワーサード、CTA、ロゴ、プレゼンター、製品 UI と衝突している。
• 前景のアセットが、画像や動画の被写体を覆っている。
• B ロールが、伝えるべきメッセージを隠している。
• 装飾レイヤーによってテキストのコントラストが低下し、基準を満たさない、または濁って見える。
• 読み取り可能な表示中に、要素の一部がキャンバス外にはみ出している。

2つの要素が同じ視覚領域を使う場合、ストーリーボードで意図的な重なりが指定されていない限り、要素 A の読み取り可能な退出が完了してから、要素 B の読み取り可能な出現を開始してください。

モーションの衝突

重要なアニメーション変更を行った場合は、インストール済みの FrameVideo スキルディレクトリからアニメーションマップを実行してください。

node .agents/skills/framevideo/scripts/animation-map.mjs <project-dir> --out <project-dir>/.framevideo/anim-map

プロジェクトのスキルが別の場所にインストールされている場合は、そのスキルディレクトリ内の framevideo/scripts/animation-map.mjs を見つけ、同じスクリプトを実行してください。

animation-map.json を読み込み、すべての collision、offscreen、invisible、paced-fast、paced-slow、長いデッドゾーンのフラグを確認してください。それぞれを修正するか、明示的に正当化してください。lint の結果が緑色であることを、モーションが視覚的に安全である証拠として扱わないでください。

ウェブサイトとデジタルヒューマンの動画

ウェブサイトを基にした動画では、キャプチャしたブランドアセットを、メッセージを隠さずに補強するために使用してください。

• ヒーロースクリーンショット、SVG、B ロールで、主要な見出しのテキストを覆わないでください。
• スクリムまたは背面プレートでコントラストを保てない場合は、製品 UI の背後に同系色のテキストを配置しないでください。
• キャプションと CTA が、デジタルヒューマンの顔、手、体、字幕トラックに重ならないようにしてください。
• 音声のない B ロールは視覚レイヤーであり、主要なメッセージを見えにくくしてよい理由にはなりません。

完了条件

以下をすべて満たした場合にのみ、構成はビジュアル QA に合格します。

• npx framevideo lint にエラーがない。
• npx framevideo validate に未対処のランタイムエラーや、実際の WCAG AA 違反がない。
• npx framevideo inspect に未対処のオーバーフロー問題がない。または、意図的な問題に data-layout-allow-overflow / data-layout-ignore が設定されている。
• ヒーローフレームとタイムラインのサンプルフレームで、テキストが読みやすく、安全な位置に配置され、意図しない重なりがない。
• 複雑なアニメーション変更についてアニメーションマップでレビューされ、すべてのフラグが修正または正当化されている。