visual-report

可视化报告

一项用于将审计发现、系统健康状态和已保存的定期运行结果转换为可视化内容的技能——交互式 HTML 仪表板、SVG 图表和 Mermaid 图表——让设计系统的健康状况一目了然。

输出类型： 文件创建。此技能会生成 HTML 仪表板文件、SVG 图表文件或 Mermaid 图表块，可嵌入文档、演示文稿，也可直接分享。

---

开始之前：核对参考资料

确认此技能 frontmatter 中 references: 下的每个路径都相对于此 SKILL.md 存在。如果有任何路径缺失，请停止：安装不完整，通常是因为扁平化安装程序（例如 npx skills install）未包含仓库根目录下的 knowledge-notes/ 目录。请告知用户使用 1-INSTALL.md 中的方法重新安装，并从安装根目录运行 verify-install.sh。只有用户明确要求忽略参考资料时，才可在缺少这些资料的情况下继续；此时需在输出中说明内容是在未使用该工具包参考资料的情况下生成的。

存在的意义

Markdown 表格中的数字准确无误，但也难以察觉。利益相关者不会从文本报告中留意到“系统健康：🟡 两个维度偏弱，但整体运行正常”。而展示各维度状态的雷达图——标出红色区域、琥珀色区域和绿色区域——则能让人一眼看明白。

设计系统健康数据本质上适合可视化。令牌覆盖图、组件依赖关系图、严重级别分布饼图、随时间变化的趋势线，都是审计技能产出数据的自然呈现形式。此技能弥合原始发现与可视化沟通之间的差距。

适用范围

此技能将现有发现可视化——不会运行审计，也不会生成新数据。如果不存在审计输出或会话历史记录，就没有可供可视化的内容；请先运行相关审计技能。如果用户要的是面向利益相关者的书面摘要，而非可视化产物，请改用 stakeholder-brief。此技能生成 HTML 仪表板、SVG 图表和 Mermaid 图表——如果用户需要幻灯片或 PDF，此技能的可视化输出可用于制作这些格式，但不会直接生成它们。

---

配置

如果存在 .ds-ops-config.yml，请遵循配置与定期运行知识说明（../../knowledge-notes/configuration-and-recurring.md），了解如何加载配置、处理集成回退和定期运行。此技能会读取：

visuals:
  brand_primary: "#0052CC"           # Primary colour for charts
  brand_secondary: "#FF5630"         # Accent colour for warnings/critical
  brand_success: "#36B37E"           # Success colour
  brand_neutral: "#6B778C"           # Neutral/baseline colour
  output_format: "html"              # html, svg, or mermaid
  output_directory: ".ds-ops/visuals"

如果不存在配置，请使用以下默认值：

• 主要颜色：#2563EB（蓝色）
• 次要颜色：#DC2626（红色）
• 成功色：#16A34A（绿色）
• 中性色：#6B7280（灰色）
• 输出格式：html
• 输出目录：.ds-ops/visuals（与配置默认值相同，因此无论是否有配置文件，运行结果都会保存到同一位置）

---

输入格式

此技能接受以下任意一种输入：

1. 原始技能输出 — 从任意审计技能复制粘贴或引用的输出
2. 已保存的报告 — recurring.output_directory 中先前运行生成的报告，用于绘制趋势线
3. 系统健康状态 — system-health 中各维度的状态
4. 对比数据 — 定期运行添加到报告中的趋势部分
5. 手动数据 — 用户以任意格式提供的指标（将进行标准化处理）

---

步骤 0：确定可视化类型

根据输入数据和用户请求，选择一种或多种可视化类型：

可用的可视化类型

类型	最适合的场景	格式
状态条	系统健康度各维度状态	每个维度一个色块，颜色表示状态
严重程度分布	按严重程度展示审计发现	环形图
趋势线	随时间变化的指标	折线图
覆盖热力图	Token 或组件覆盖情况	网格热力图
依赖关系图	组件关系	Mermaid 流程图
对比柱状图	前后对比	分组柱状图
行动优先级矩阵	按工作量与影响展示发现	散点图
完整仪表板	在一个页面上展示多个可视化图表	HTML 仪表板

如果请求比较模糊（“制作这个可视化图表”），请选择最符合数据的可视化类型：

• 系统健康度状态 → 状态条
• 审计发现 → 严重程度分布 + 行动优先级矩阵
• 会话历史 → 趋势线
• 前后数据 → 对比柱状图
• 多种数据类型 → 完整仪表板

---

步骤 1：解析并规范化数据

从审计输出中提取

提取：

• 发现 ID、严重程度、类别
• 指标总数（违规数量、覆盖百分比）
• 组件名称（用于依赖关系图）
• Token 层级（用于覆盖热力图）

从已保存的定期运行记录中提取

提取：

• 日期和技能名称
• 每次运行的关键指标（对齐后用于趋势线）
• 各次运行之间的差异，取自每份报告的趋势部分

从系统健康度中提取

提取：

• 报告包含的维度状态（system-health 有七个维度；不要臆测，请读取实际数据）
• 整体健康状态
• 成熟度阶段

将所有数据规范化为简单结构：

metrics: [{ label, value, max, category }]
timeseries: [{ date, metric, value }]
findings: [{ id, severity, category, effort?, impact? }]   # effort and impact only when the source report carries them
relationships: [{ source, target, weight }]

---

步骤 2：生成可视化图表

状态条

按报告中的顺序，为每个维度生成一个色块，包含维度名称、状态词和状态颜色（🟢 强、🟡 良好、🟠 较弱、🔴 缺失），并附上一行概述关键发现的说明文字。状态是序数标签，因此用状态条展示更准确；雷达图会暗示这些标签具有实际上并不存在的大小和面积。如果用户无论如何都要求雷达图，请在坐标轴上标注状态词，并在说明文字中注明图形仅供示意。

实现方式：使用 HTML flex 行排列卡片，或使用 SVG 绘制一行矩形。

严重程度分布图

生成环形图，展示各严重程度发现的分布。

环形区段仅使用 output-discipline 中的四种严重程度，按颜色从深到浅排序（Critical 到 Low），确保灰度下仍能看出顺序。每种颜色与白色背景的对比度至少为 3:1，并且每个区段都带有文字标签：

• Critical：深红色（#991B1B）
• High：橙色（#C2410C）
• Medium：琥珀色（#C27C0E）
• Low：灰色（#6B7280）

只要出现严重程度，均使用相同的四种颜色（气泡图、堆叠柱状图、徽标等）。配置中的品牌颜色仅用于非严重程度系列。

中心文字：发现总数。

实现方式：使用 Chart.js 环形图，或 SVG 弧线路径。

趋势线图

生成折线图，X 轴表示时间，Y 轴表示指标。每个跟踪的指标使用一条折线。

包括：

• 用圆圈标记数据点
• 鼠标悬停时显示精确数值的工具提示
• 如果已配置，则显示目标线
• 正向／负向趋势注释

实现方式：在 HTML 中使用 Chart.js 折线图。

覆盖热力图

生成网格，其中：

• 行 = Token 类别或组件区域
• 列 = 覆盖维度（primitive、semantic、component、documented、tested）
• 单元格 = 按覆盖状态用颜色编码（绿色 = 已覆盖，琥珀色 = 部分覆盖，红色 = 缺失，灰色 = 不适用）

实现方式：使用带 CSS 背景色的 HTML 表格，或 SVG 网格。

依赖关系图

生成 Mermaid 流程图，展示组件关系：

graph TD
    Button["Button (fan-in: 12)"]
    Card["Card (fan-in: 8)"]
    Modal["Modal (fan-in: 5)"]
    Button --> Card
    Button --> Modal
    Card --> ProductCard["ProductCard"]
    Card --> UserCard["UserCard"]

如果有相关数据，按健康状态为节点着色。使用线条粗细表示依赖权重。

实现方式：Mermaid.js 语法代码块。

对比条形图

为每项指标绘制分组条形图，展示前后数值。每项指标对应一组（例如，违规数、严重问题数、覆盖率 %）。

颜色编码：

• 指标改善：绿色条形（违规数：after < before；覆盖率：after > before）
• 指标恶化：红色条形
• 指标无变化：灰色条形

在每组条形上方标注变化量：“↓ 33%”或“↑ 5%”

实现方式：在 HTML 中使用 Chart.js 分组条形图。

行动优先级矩阵（仅适用于有来源依据的工作量和影响）

仅当矩阵中要显示的每项发现都有源报告提供的工作量值和影响值时才绘制：工作量取自审计生成的估算表及其假设（例如 token-audit 的估算表），影响取自该发现的严重程度。如果源报告没有工作量数据，则跳过矩阵，并在文本摘要中说明。绝不要为了绘制图表而给发现分配工作量；仪表板上凭空写一个“8–12 hrs”，就会变成一个冲刺承诺。

绘制散点图，其中：

• X 轴 = 工作量（低 → 高）
• Y 轴 = 影响（低 → 高）
• 每个点 = 一项发现，点的大小按严重程度设置
• 象限标签：“快速见效”（低工作量、高影响）、“战略性投资”（高工作量、高影响）、“补充项”（低工作量、低影响）、“审慎考虑”（高工作量、低影响）

实现方式：在 HTML 中使用带象限叠加层的 Chart.js 散点图。

完整仪表板

将多个图表组合到一个 HTML 页面中，页面包含：

• 显示系统名称、日期和整体健康状态的页眉
• 页眉下方的一句标题说明：读者应有多担忧，以及应先查看什么；内容取自源报告的开篇
• 网格布局（桌面端为 2 列，移动端为 1 列）
• 按比例设置图表尺寸
• 顶部的摘要部分，包含 3–5 个关键指标卡片
• 交互式筛选器（存在已保存的定期运行记录时）：用于切换运行记录的下拉菜单
• 底部的范围说明：源报告检查了什么、未检查什么（“未检查”），以及哪些数值是报告提供的而非实际测量所得；内容沿用源报告

实现方式：使用单个 HTML 文件，所有数据均内嵌。Chart.js 是唯一的依赖项；CDN 上的 chart.js@4 会自动指向最新的 4.x 版本，在离线环境或严格的内容安全策略下会失效。因此，应内嵌该库（如果项目中有 node_modules/chart.js/dist/chart.umd.js，则读取该文件），或固定到确切版本（npm view chart.js version），并添加 integrity 属性；在页脚说明使用了哪种方式。

---

第 3 步：构建 HTML 仪表板（完整仪表板模式）

仪表板是一个单独的 HTML 文件。结构如下：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[System Name] — Design System Health Dashboard</title>
  <script src="https://cdn.jsdelivr.net/npm/chart.js@[exact version]/dist/chart.umd.min.js" integrity="[sri hash]" crossorigin="anonymous"></script>
  
  <style>
    /* Inline styles — no external CSS */
    /* Use CSS Grid for layout */
    /* Responsive: 2 columns above 768px, 1 column below */
    /* Cards with subtle shadows for key metrics */
    /* Colour variables from config or defaults */
  </style>
</head>
<body>
  <header>
    
  </header>
  <p class="headline">
    
  </p>
  <section class="metrics-cards">
    
  </section>
  <section class="charts-grid">
    
  </section>
  <section class="scope">
    
  </section>
  <footer>
    <p>Generated by Design System Ops — visual-report</p>
    <p>[Date]</p>
  </footer>
  <script>
    // All chart configuration inline
    // Data embedded as JS objects
    // Chart.js instantiation for each chart
  </script>
</body>
</html>

关键指标卡片

每张卡片显示：

• 指标标签（例如，“违规总数”）
• 当前值（大号字体）
• 与上一次会话相比的变化（如有，附箭头和颜色）
• 趋势迷你图（如有 3 个或更多数据点）

响应式行为

• 桌面端（>768px）：图表采用 2 列网格，指标卡片每行显示 3–5 张
• 平板端（768px）：图表采用 2 列网格，指标卡片每行显示 2 张
• 移动端（<768px）：单列布局，指标卡片垂直堆叠

颜色无障碍性

• 绝不要仅依赖颜色来传达含义
• 使用纹理（目标值使用虚线，实际值使用实线）
• 为所有图表区段添加标签
• 确保所有文本的对比度至少为 4.5:1
• 在每个图表下方添加文本摘要，供屏幕阅读器使用

---

第 4 步：输出

HTML 仪表板

将文件保存到配置的输出目录： [output_directory]/[system-name]-dashboard-[YYYY-MM-DD].html

单个图表（SVG）

将每个图表分别保存为 SVG 文件： [output_directory]/[chart-type]-[YYYY-MM-DD].svg

Mermaid 图表

在对话中以内嵌形式输出 Mermaid 语法块（以便嵌入 Markdown 文档）。

所有格式

同时输出一份文本摘要，说明可视化内容，让用户无需查看可视化结果也能了解这些发现：

Dashboard generated: agds-dashboard-2026-03-09.html

What the visuals show:
- Status strip: Strongest in Tokens (🟢 Strong), weakest in Documentation (🟠 Weak)
- Severity distribution: 12 findings — 2 Critical, 4 High, 4 Medium, 2 Low
- Trend: Violations decreased 33% since January
- Coverage: Feedback token category has zero coverage across all tiers
- Priority matrix: skipped, the source report carries no effort figures

---

与其他技能的集成

作为任何审计技能的后续步骤

任何审计完成后，建议：“运行 visual-report，根据这些发现生成图表。”

作为 full-system-diagnostic Agent 的一部分

诊断 Agent 可以在 Phase 4 后接续运行 visual-report，根据完整诊断输出自动生成仪表板。

作为 stakeholder-brief 的配套工具

生成利益相关者简报时，建议：“先运行 visual-report，并将仪表板附在简报中。”

配合定期运行

加载 recurring.output_directory 中保存的报告，以生成各次运行的趋势线；configuration-and-recurring 说明介绍了这些报告的匹配方式。

---

质量检查

• 每个值都能追溯到输入中的发现或数据；缺失数据应标记为缺失，绝不插值或估算来补全图表
• 仪表板以一句标题句开头，并以一个包含“未检查”内容的范围区块结尾
• 严重性仅使用输出规范中规定的四个等级，并采用上述颜色
• 仅使用广泛支持的 HTML、CSS 和 JavaScript
• 除 Chart.js 外，不使用外部依赖；如使用 Chart.js，须内联，或固定到带完整性哈希的确切版本
• 仅当源报告为每个绘制的发现都提供了工作量和影响时，才显示优先级矩阵
• 颜色须符合 WCAG AA 对比度要求
• 每个可视化内容都附有文字摘要
• 仪表板需适配桌面、平板和移动设备
• 数据内嵌，不进行外部数据获取
• 文件保存到正确目录，并采用正确的命名约定
• Mermaid 图表须使用有效语法，并能在 GitHub、GitLab 和 Notion 中正确渲染
• 包含来源标记：“由 Design System Ops — visual-report 生成”