framevideo-visual-qa

FrameVideo 视觉 QA

何时使用

在以下场景使用此技能：

• 交付前最终 QA — 在确认可以交付前检查构图
• 布局变更后 — 确认没有引入重叠或裁切
• 添加字幕/说明文字后 — 确保文字没有与其他元素重叠
• 素材放置 — 确认 Logo、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. 无重叠 — 确认动画过程中没有文字/Logo 碰撞

---

检查关卡

1. 优先检查主视觉帧 — 找出每个场景中最拥挤但仍清晰可读的时刻：所有关键文字、前景素材、字幕、CTA 和 Logo 均清晰可见。在信任动画效果之前，先检查该帧。
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。

安全区域

默认情况下，将关键信息保持在安全区域内：

• 重要文字、Logo、CTA、字幕、出镜者面部、产品 UI 以及法律/价格说明应远离边缘。
• 对于 16:9 构图，画布四周至少预留约 5% 的宽度/高度作为关键内容的安全边距。在 1920x1080 画面中，水平约为 96px，垂直约为 54px。
• 字幕和 CTA 的底部安全区域应留得更宽裕，尤其是在可能存在进度条、平台 UI 或下三分之一字幕时。
• 全屏背景、光晕、颗粒、粒子、擦除效果和转场素材可以超出画面边界。如果 inspect 会报告此类情况，请使用 data-layout-allow-overflow 标记有意溢出的元素。
• 使用 data-layout-ignore 标记不应纳入审核的装饰元素。

除非用户明确要求贴边设计，且已对画面进行视觉检查，否则不要将可读文字、Logo 或重要产品 UI 放在最外侧 5% 的范围内。

对比度

使用 npx framevideo validate 作为对比度检查关卡。默认情况下，该命令会运行 WCAG AA 审核。

• 普通文字必须达到 4.5:1。
• 大号文字必须达到 3:1。字号为 24px 或以上，或加粗时为 19px 或以上，即视为大号文字。
• 在深色背景上，提亮现有前景色。
• 在浅色背景上，加深现有前景色。
• 保持在项目的配色体系内。不要仅为通过对比度检查而新增品牌色。
• 如果警告采样的是转场帧或尚未入场的不可见元素，请先核实该精确时间点，再决定是否忽略。

对于每条对比度警告，请判断属于以下哪种情况：

• 真实问题 — 文字可见但对比度过低；请调整颜色、底板、阴影、遮罩或位置。
• 采样伪影 — 文字尚不可读、正处于淡入淡出过程中，或在该时间点被有意隐藏；请说明原因。

布局与文本

添加或评估动画之前，先构建并审查可读的最终状态。

• 内容布局优先使用 flex、grid、内边距、间距、max-width 和明确划分的区域。
• 绝对定位仅用于装饰、叠加层和有意固定的元素。避免使用绝对定位的 top/left 布局来排列主要内容。
• 文本容器必须有实际的宽度限制。使用 max-width、自然换行，或使用 window.__framevideo.fitTextFontSize(...) 来适应动态文案。
• 对可变文本不要依赖强制换行。将较长文案拆分到多个场景中。
• 如果单个场景中的文本达到 35 个或更多单词，请拆分。
• 如果标签或徽章的文本是动态的，请让容器能够伸缩，或调整字体大小。固定尺寸的徽章常常会导致文字被裁切。
• 字幕不得遮挡 CTA、徽标、演示者的面部或身体、产品 UI，或具有法律重要性的文案。

每当文本、字幕、用户提供的文案、变量或翻译后的字符串可能发生变化时，都要运行 inspect。

重叠与图层

只有在有意为之且可读时，视觉重叠才可接受：例如文本背后的阴影、辉光，按 Z 轴堆叠的卡片、纹理、纵深或转场效果。

以下情况应标记并修复为缺陷：

• 两块可读文本同时占据同一区域。
• 字幕文本与下三分之一处的信息条、CTA、徽标、演示者或产品 UI 冲突。
• 前景素材遮挡图像或视频中的主体。
• B-roll 遮挡了它本应辅助传达的信息。
• 装饰图层降低文本对比度，导致文本难以辨认或显得模糊。
• 元素在可读停留期间部分超出画布。

如果两个元素占用了相同的视觉区域，除非分镜明确要求有意重叠，否则元素 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 和 long dead-zone 标记。逐一修复或明确说明理由。不要将绿色的 lint 结果当作动效视觉安全的证明。

网站与数字人视频

对于从网站衍生的视频，采集的品牌素材应辅助传达信息，而不是遮挡信息：

• 不要用主视觉截图、SVG 或 B-roll 遮挡核心标题文本。
• 除非使用遮罩层或底板确保对比度，否则不要让产品 UI 位于同色文本的背后。
• 字幕和 CTA 不得遮挡数字人的面部、手部、身体或字幕轨道。
• 静音 B-roll 是视觉图层，不代表可以遮挡主要信息。

完成标准

只有满足以下条件，构图才能通过视觉 QA：

• npx framevideo lint 没有错误。
• npx framevideo validate 没有未解决的运行时错误或实际的 WCAG AA 不合规问题。
• npx framevideo inspect 没有未解决的溢出问题；若存在有意设计的溢出，必须标记 data-layout-allow-overflow / data-layout-ignore。
• 主视觉画面和抽样时间轴画面中的文本清晰可读、位置安全，且没有非预期的重叠。
• 复杂动画改动经过动画映射审查，且每个标记的问题都已修复或说明理由。