---
name: courseware-visuals-qa
description: Creates, implements, and audits semantic visuals for courseware, training decks, PPT/PPTX, HTML slides, PDF handouts, and teaching materials. Use when the user says “给课件配图”“补信息图”“把文字变成图”“统一课件视觉”“重做流程图”“检查课件配图”“逐页检查课件”“大框小图”“图文不一致”“投屏字小”“全屏检查”“移动端检查”“打印版检查”或“课件视觉验收”，或正在创建、重写、完善一套课程课件。该 Skill 负责页面分级、业务问题定义、图形原型选择、SVG/可编辑图形实现、真实渲染和跨端验收。Do not use for standalone artistic illustration, pure copyediting, or data analysis without a courseware deliverable.
compatibility: HTML/SVG 可直接使用；PPTX/PDF 需要相应渲染工具。批量审计需要 Python 3.10+、Playwright、Pillow 和 Chromium；Manifest 校验仅依赖 Python 标准库。
metadata:
  version: 2.0.0
  updated: 2026-07-14
  origin: 高维学堂公开课 85 页课件视觉实践
---

# 课件配图和检查

把配图当成“论点的第二种表达”，而不是填空装饰。先判断学员需要看懂什么关系，再选择图形；完成后通过真实渲染证明桌面、投屏、移动和打印效果。

## 输入与输出契约

输入至少包含课件源文件或页面内容；品牌色、字体、受众、投屏/移动/打印场景和期望格式可从现有文件推断。无法推断且会实质改变结果时再询问。

标准输出包含：

1. 页面视觉清单：每页标记 `hero`、`support`、`keep` 或 `evidence`；
2. 每张图的业务问题、图形类型、节点、图注和实现状态；
3. 可编辑源文件或可缩放 SVG，不用低清截图替代逻辑图；
4. 逐页截图、联系表、自动审计报告和异常页复核证据；
5. 未验证项、P0/P1/P2 问题和修正结果。

完整字段、目录和验收契约见 [references/specification.md](references/specification.md)。

## 使用场景

适用于：

- 从零规划整套课程配图；
- 给现有课件补主图或辅图；
- 把文字清单转成流程、层级、输入输出、治理或闭环图；
- 重做不清楚、不可编辑或与内容不匹配的业务图；
- 统一一套课件的视觉语法和课程节奏；
- 交付前逐页检查桌面、真实全屏、移动端和打印版；
- 用户授权时继续修正并回归验证。

## 不要用于

- 单张艺术插画、写实场景图或纯图像风格转换；这类任务使用图像生成能力。
- 只审事实、语法、讲师稿或教学内容完整度，不涉及视觉交付。
- 只做数据计算或商业分析，没有课件、讲义或演示成品。
- 页面已有清晰的案例截图、数据表或完整图形，新增图只会重复正文。

生成式图片不要承担精确流程、规则、中文标签和权限关系；这些内容优先使用可编辑矢量图。

## 资源路由

根据任务只读取所需的一层资源：

| 任务 | 必读资源 |
|---|---|
| 设计、补图、统一视觉 | [references/visual-playbook.md](references/visual-playbook.md) |
| 确认字段、命名、目录和交付契约 | [references/specification.md](references/specification.md) |
| 查看完整输入—决策—输出样例 | [references/examples.md](references/examples.md) |
| 逐页检查与严重度判定 | [references/qa-playbook.md](references/qa-playbook.md) |
| 工具缺失、格式不支持或渲染失败 | [references/troubleshooting.md](references/troubleshooting.md) |
| HTML/SVG 快速实现 | [assets/semantic-visual-starter.js](assets/semantic-visual-starter.js) |
| 新建视觉清单 | [assets/visual-manifest.example.json](assets/visual-manifest.example.json) |
| 生成审计报告 | [assets/audit-report-template.md](assets/audit-report-template.md) |

不要继续从参考文件深挖其他文档；所有资源都由本文件直接路由。

## 工作流

### 1. 盘点交付场景

读取源文件、页数、目录、模板、品牌色、字体和交付模式。确认 HTML、PPTX、PDF 或图片链路，以及是否需要桌面、投屏、移动或打印。

先保留用户已有设计语言。除非用户要求重做，不用新风格覆盖已有品牌体系。

### 2. 建立视觉清单

为 100% 页面建立 Manifest：

- `hero`：需要占正文约 25%–45% 的主逻辑图；
- `support`：需要小型结构图、关系线或局部图解；
- `keep`：现有视觉足够，保持克制；
- `evidence`：使用真实截图、照片、数据图或案例证据。

从 [assets/visual-manifest.example.json](assets/visual-manifest.example.json) 复制结构，按 [assets/visual-manifest.schema.json](assets/visual-manifest.schema.json) 填写。运行：

```bash
python scripts/validate_visual_manifest.py path/to/visual-manifest.json
```

### 3. 定义业务问题

每张图先写一句业务问题，例如“输入经过什么处理形成什么输出？”或“什么条件通过后才允许继续？”。如果不能用一句话说清，先收敛页面论点。

HTML 图形把问题写入 `data-business-question`。图注写读图后的结论，不复述标题。

### 4. 选择关系匹配的原型

按关系选图，不按“哪种图好看”选图：

- 顺序推进 → 阶段流、时间轴；
- 输入—处理—输出 → 输入输出图；
- 多项构成 → 交付物组合、分层架构；
- 差异与取舍 → 对比、矩阵；
- 逐层收敛 → 漏斗；
- 权限与风险 → 治理闸门、人工断点；
- 反馈改进 → 生命周期、闭环；
- 跨角色协同 → 泳道图；
- 真实系统操作 → 带焦点标注的产品截图。

同一原型不要连续三页重复。不要默认使用桥、河流、人物、齿轮等装饰性隐喻。

### 5. 先画语义骨架

先确定节点、方向、层级、分支、异常、人工断点和结果回写，再设置颜色、圆角和留白。图中所有标签必须能回到正文概念。

一张图解释一个核心关系：标题讲结论，图形讲结构，图注讲关键判断。

### 6. 按载体实现

#### HTML / SVG

优先复用 [assets/semantic-visual-starter.js](assets/semantic-visual-starter.js)。保留真实 `<text>`、`role="img"`、`aria-label`、`data-visual-type` 和 `data-business-question`。把视觉增强放在独立脚本或组件层，便于回退和测试。

#### PPTX

使用可编辑形状、连接线和文本框；复杂图可嵌入 SVG，但保留源文件。先按投影距离设计字号，再检查笔记本与打印。

#### PDF / 图片

从源课件导出，不放大低分辨率截图。照片和产品截图保留真实焦点；逻辑图在最终尺寸下保持可读。

### 7. 保持统一但不单调

默认视觉语言是企业蓝图：深蓝负责结构，亮蓝负责推进，浅蓝负责重点结果，白色负责内容面，灰色负责次要说明，红色只表示风险与阻断。设计令牌见 [assets/design-tokens.json](assets/design-tokens.json)。

优先形成“标题结论 → 内容证据 → 语义图 → 一句收束”的阅读路径。避免渐变、3D、厚重阴影、无关人物和图标拼贴。

### 8. 真实渲染和逐页检查

完成设计后：

1. 渲染 100% 页面；
2. 每 18–24 页生成一张联系表；
3. 检查桌面、真实全屏、移动和打印；
4. 检查溢出、字号、图框比例、居中、裁切、资源失败和图文语义；
5. 放大复核所有报警页、特殊页和用户点名页；
6. 修正后重跑受影响页面；全局样式改动则全量回归。

HTML 课件运行：

```bash
python scripts/audit_courseware_visuals.py http://127.0.0.1:8000 \
  --output-dir outputs/visual-audit \
  --modes desktop,fullscreen,mobile,print
```

自动检查只是报警器。最终结论必须同时包含联系表人工扫描与异常页原图复核。

### 9. 交付前自检

运行包级检查，验证 frontmatter、引用、JSON、脚本语法和必需目录：

```bash
python scripts/check_skill_package.py .
```

使用 [assets/audit-report-template.md](assets/audit-report-template.md) 输出结论。

## 失败与降级

- 无法读取源文件：确认格式并寻找可渲染版本，不以文件列表冒充检查。
- 浏览器不可用：渲染 PDF/PPTX 图片，明确未验证交互和真实全屏。
- Playwright/Pillow 缺失：按 [references/troubleshooting.md](references/troubleshooting.md) 安装；无法安装时手工截图并记录未验证项。
- 页面没有固定分页：按视觉模块编号，覆盖每张图和其上下文。
- 字体或资源加载失败：记录失败资源，使用交付环境字体后重测。
- 内容过密：先精简表达、调整布局或拆页，最后才小幅缩小字号。
- 语义无法确定：停止画图，列出缺失的业务关系并请求最小必要信息。

不要为了让自动检查通过而隐藏元素、关闭报警或把文字栅格化。

## 完成门槛

只有同时满足以下条件才可说完成：

- Manifest 覆盖 100% 页面且通过 Schema 校验；
- 每张新增图都回答明确业务问题，删除它会损失信息；
- 图形结构与真实关系匹配，标签均可追溯到正文；
- 主图充分占用区域，无大框小图、明显偏心或无意义留白；
- 主交付模式无文字溢出、主体裁切、资源失败和不可读小字；
- 实际交付范围内的桌面、全屏、移动和打印均已验证；
- 提供逐页截图、联系表、报告、源文件和未验证项。

## 输出格式

```markdown
- 配图范围：新增/重做 <数量> 页，保留 <数量> 页
- 视觉清单：<manifest 路径>
- 图形体系：<原型与视觉语言>
- 检查范围：<已检查>/<总页数>，<模式与视口>
- 结果：P0 <数量>，P1 <数量>，P2 <数量>
- 证据：<联系表、单页截图、报告、打印文件路径>
- 未验证项：<无或具体说明>
```

## 最小示例

**输入：**“把‘四项材料进入审核，审核通过后发布，否则转人工’做成课件配图。”

**决策：**业务问题是“什么条件通过后才允许继续？”，使用 `governance-gate`，不用普通线性流程。

**输出：**四项检查位于左侧，审核闸门位于中部，右侧区分“发布”和“转人工”；HTML 包含业务问题元数据、可编辑 SVG 文本、可访问标签和结论式图注。

更多完整样例与反例见 [references/examples.md](references/examples.md)。

