name: visual-explainer description: 生成自包含的 HTML 页面，用于可视化解释系统、数据故事、调查、编辑工作流程和代码变更。当用户请求图表、架构视图、视觉差异、数据表格、时间线、源映射或任何结构化可视化（在终端输出中难以阅读时）使用。对于具有 4 行以上或 3 列以上的表格也会激活。改编自 nicobailon/visual-explainer，具有新闻、新闻编辑室和学术设计感。 version: 0.1.0 license: MIT

可视化解释器

生成自包含的 HTML 文件，用于技术图表和数据可视化。始终在浏览器中打开结果。当此技能加载时，切勿回退到 ASCII 艺术。

主动表格渲染：当即将输出具有 4 行以上或 3 列以上的表格时，将其渲染为样式化的 HTML 而非 ASCII。在浏览器中打开。

工作流程

1. 思考（5 秒，而非 5 分钟）

受众：开发者？编辑？记者？项目经理？公共读者？
图表类型：从下方的路由表中选择。
美学方向：选择适合的风格。不要每次都默认相同外观。
- 单色终端
- 编辑大报
- 蓝图 / 技术
- 霓虹仪表板
- 纸张和墨水
- 手绘草图
- IDE 灵感
- 数据密集 / 新闻社
- 渐变网格
- 新闻编辑室板（软木/图钉）
- 调查墙（红绳）
- 杂志专题
- 学术 / 研究论文

交换测试：如果将样式替换为通用暗色主题而没人会注意到差异，则您尚未设计任何东西。进一步推进。

2. 结构

在生成前阅读参考模板：

./templates/architecture.html — 文本密集型架构 / 编辑结构
./templates/mermaid-flowchart.html — 流程图、序列图、图表
./templates/data-table.html — 数据表格、审计、比较

阅读 ./references/css-patterns.md 获取 CSS 和布局模式。阅读 ./references/responsive-nav.md 获取多节页面与粘性导航。阅读 ./references/libraries.md 获取 Mermaid 主题化、Chart.js、anime.js 和字体配对。

按图表类型的渲染方法

类型	方法	原理
架构（文本密集型）	CSS 网格卡片 + 流向箭头	丰富的卡片内容需要 CSS 控制
架构（拓扑）	Mermaid	连接需要自动边路由
流程图 / 管道	Mermaid	自动节点定位和边路由
序列图	Mermaid	生命线和激活框需要布局
数据流	Mermaid 带边标签	连接和数据描述
ER / 模式	Mermaid	关系线需要自动路由
状态机	Mermaid	带标签边的状态转移
思维导图	Mermaid	分层分支定位
数据表格 / 比较	HTML `<table>`	语义标记和可访问性
时间线 / 年代学	CSS（中心线 + 卡片）	简单线性布局
仪表板 / 指标	CSS 网格 + Chart.js	带嵌入式图表的卡片网格
源网络	Mermaid 或 CSS 网格	映射源之间的关系
编辑工作流程	Mermaid 流程图	从提案到发布的故事生命周期
调查地图	CSS 网格卡片 + Mermaid	连接实体、文档、事件
故事结构	CSS 网格	可视化叙事弧和章节

Mermaid 主题化

使用 theme: 'base' 带自定义 themeVariables — 内置主题忽略大多数覆盖。
使用 look: 'handDrawn' 获取草图美学，look: 'classic' 获取简洁。
使用 layout: 'elk' 用于复杂图形（需要 @mermaid-js/layout-elk CDN 导入）。
始终在 .mermaid-wrap 容器上包含缩放控件（+/-/重置按钮）。
支持 Ctrl/Cmd+滚动缩放和点击拖动平移。

3. 样式

排版：从 Google Fonts 中选择独特的字体配对（显示/标题 + 等宽或正文）。切勿使用 Inter、Roboto、Arial 或 system-ui 作为主要字体。对于编辑上下文，衬线显示字体效果良好（如 Playfair Display、Libre Baskerville、Source Serif Pro）。通过 <head> 中的 <link> 加载。包括系统字体后备。

颜色：使用 CSS 自定义属性。定义最少：--bg、--surface、--border、--text、--text-dim，加上 3–5 种强调色（每种有完整和暗淡变体）。语义命名。支持两种主题：

/* 亮色优先 */
:root { /* 亮色值 */ }
@media (prefers-color-scheme: dark) { :root { /* 暗色值 */ } }

/* 暗色优先 */
:root { /* 暗色值 */ }
@media (prefers-color-scheme: light) { :root { /* 亮色值 */ } }

表面：通过微妙的亮度变化（2–4% 级别间）构建深度，而非戏剧性颜色变化。边框应为低不透明度 rgba（rgba(255,255,255,0.08) 暗色，rgba(0,0,0,0.08) 亮色）。

背景：不要使用平坦实心颜色。使用微妙渐变、CSS 淡网格图案或轻柔径向发光。

视觉权重：并非每个章节都值得同等对待。执行摘要和关键指标主导视口。参考章节保持紧凑。使用 <details>/<summary> 用于有用但非主要内容。

表面深度：变化卡片深度以指示重要性：

英雄章节：提升阴影、强调色调背景（node--hero）
正文内容：平坦默认（.node）
次要内容：凹陷感（node--recessed）

动画：页面加载时的交错淡入几乎总是值得的。按角色混合动画类型：

fadeUp 用于卡片
fadeScale 用于 KPI 和徽章
drawIn 用于 SVG 连接器
countUp 用于英雄数字

始终尊重 prefers-reduced-motion。主要使用 CSS 过渡和关键帧。对于编排序列，可通过 CDN 使用 anime.js。

可访问性：所有生成的页面必须达到 WCAG 2.1 AA 最低标准。这意味着：

颜色对比比：文本 4.5:1，大文本和 UI 组件 3:1
状态指示器使用形状/文本伴随颜色（切勿仅颜色）
表格具有适当的 <thead>、<th scope> 和 <caption> 元素
图表包括数据表格替代方案
焦点指示器对键盘导航可见
在 <html lang="en"> 中声明语言

4. 交付

输出位置：~/.agent/diagrams/

文件名：基于内容的描述性。示例：authentication-flow.html、source-network.html、budget-analysis.html、editorial-pipeline.html。

在浏览器中打开：

macOS：open ~/.agent/diagrams/filename.html
Linux：xdg-open ~/.agent/diagrams/filename.html

告诉用户文件路径。

图表类型 — 详情

架构 / 系统图表

文本密集型概览：CSS 网格带明确放置、圆角卡片、彩色边框、等宽标签、垂直流向箭头。适用于新闻编辑室系统、CMS 架构、数据管道概览。

拓扑重点：Mermaid 带自动边路由。适用于显示系统如何连接。

流程图 / 管道

Mermaid。使用 graph TD（自上而下）或 graph LR（从左到右）。使用 look: 'handDrawn' 获取草图。通过 classDef 或 themeVariables 颜色编码节点。适用于编辑工作流程（提案 → 分配 → 草稿 → 编辑 → 发布）、FOIA 请求过程、验证工作流程。

序列图

Mermaid sequenceDiagram。生命线、消息、激活框、注释、带自动布局的循环。适用于显示记者、编辑、源和系统之间的交互。

数据表格 / 比较 / 审计

真实 <table> HTML 元素用于语义标记和可访问性。主动用于任何结构化行/列。

布局模式：

粘性 <thead>
通过 tr:nth-child(even) 交替行背景（2–3% 亮度变化）
宽表可选第一列粘性
响应式包装器带 overflow-x: auto
通过 <colgroup> 或 th 宽度提示列宽
行悬停高亮

状态指示器（样式化 <span>，切勿表情符号）：

匹配/通过/是：彩色点或复选标记带绿色背景
差距/失败/否：彩色点或交叉带红色背景
部分/警告：琥珀色指示器
中性/信息：暗淡文本或静音徽章

单元格内容：

自然换行长文本
使用 <code> 用于技术参考
次要细节在 <small> 中带暗淡颜色
右对齐数字列带 tabular-nums

时间线 / 年代学

垂直或水平时间线带中心线（CSS 伪元素）。阶段标记为圆圈。内容卡片分支左/右（交替）或一侧。线上日期标签。颜色从过去（暗淡）到未来（鲜艳）递进。适用于调查时间线、事件年代学、项目历史。

仪表板 / 指标概览

卡片网格布局。英雄数字大而突出。通过内联 SVG <polyline> 火花线。通过 CSS linear-gradient 进度条。对于真实图表使用 Chart.js 通过 CDN。KPI 卡片带趋势指示器（向上/向下箭头、百分比增量）。适用于新闻编辑室分析、赠款报告仪表板、受众指标。

源网络

映射调查或故事中源之间的关系。可使用 Mermaid 用于连接密集型地图或 CSS 网格卡片用于细节密集型源配置文件。包括：源名称、角色、可信度指示器、提供内容、其他源的交叉引用。

调查地图

连接实体（人、组织、文档、事件）带视觉链接。CSS 网格卡片用于实体配置文件，Mermaid 用于关系图表。按实体类型颜色编码。显示连接强度。适用于调查性报道、跟踪资金、映射权力结构。

编辑工作流程

Mermaid 流程图显示故事生命周期：提案 → 分配 → 研究 → 草稿 → 编辑 → 法律审查 → 发布 → 分发。颜色编码阶段。显示决策门（终止/修订/批准）。包括转换上的角色标签。

故事结构

CSS 网格可视化叙事弧。显示章节、字数、源分布、多媒体放置。适用于规划长篇专题或在发布前审查故事架构。

文件结构

每个图表是单个自包含 .html 文件。无外部资产，除了 CDN 链接。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>描述性标题</title>
  <link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
  <style>
    /* CSS 自定义属性、主题、布局、组件 — 全部内联 */
  </style>
</head>
<body>
  <!-- 语义 HTML：章节、标题、列表、表格、内联 SVG -->
  <!-- 可选：<script> 用于 Mermaid、Chart.js 或 anime.js，当使用时 -->
</body>
</html>

质量检查

交付前验证：

眯眼测试：模糊眼睛。仍能感知层次吗？章节视觉上可区分吗？
交换测试：通用暗色主题替换会使此与模板无法区分吗？如果是，进一步推进美学。
两种主题：切换操作系统亮/暗色。两者应看起来有意设计。
信息完整性：图表传达用户请求的内容吗？
无溢出：调整浏览器到不同宽度。无裁剪。每个网格/弹性子项需要 min-width: 0。避免在 <li> 上使用 display: flex 用于标记（改用绝对定位）。参见 ./references/css-patterns.md 中的溢出保护。
Mermaid 缩放控制：每个 .mermaid-wrap 需要 +/-/重置按钮、Ctrl/Cmd+滚动缩放、点击拖动平移。光标更改为 grab/grabbing。
可访问性：颜色对比通过。状态指示器不依赖仅颜色。表格具有适当的语义标记。
文件干净打开：无控制台错误、无损坏字体、无布局移位。

可视化解释器Skill visual-explainer