visual-explainer

可视化讲解

生成独立的 HTML 文件，用于展示技术图表、编辑性可视化内容和数据表格。始终在浏览器中打开结果。加载此技能后，绝不回退到 ASCII 艺术。

主动渲染表格。 当你准备在终端中以 ASCII 框线表格的形式呈现表格数据时（比较、审计、功能矩阵、状态报告、来源核验网格，以及任何结构化的行列数据），请改为生成 HTML 页面。判断标准：如果表格有 4 行或以上，或 3 列或以上，就应该在浏览器中呈现。不要等用户提出要求，自动将其渲染为 HTML，并告知文件路径。你仍可在聊天中附上简短的文字摘要，但表格本身应放在 HTML 页面中。

可用命令

详细的提示词模板位于 ./commands/。在 Claude Code 中使用带命名空间的命令（/visual-explainer:diff-review）。在 Pi 中，这些是斜杠命令（/diff-review）。在 Codex 中，使用 /prompts:diff-review（如果已安装到 ~/.codex/prompts/），或调用 $visual-explainer 并描述工作流。

命令	功能
generate-web-diagram	为任意主题生成 HTML 图表
generate-visual-plan	为某项功能生成可视化实现计划
generate-slides	生成杂志级别的幻灯片
diff-review	结合架构比较和代码审查进行可视化差异审查
plan-review	对照代码库审查计划并评估风险
project-recap	创建项目心智模型快照，便于切换回项目时恢复上下文
fact-check	根据实际代码核验文档的准确性
share-page	将 HTML 页面部署到 Vercel 并获取可访问的 URL

工作流

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

编写 HTML 之前，先确定设计方向。不要每次都默认采用“蓝色点缀的深色主题”。

始终以视觉呈现为默认。 即使是随笔、博客文章和报道，也要进行视觉设计，将内容结构提炼为卡片、图表、网格和表格。

文字模式（导语段落、引述、提示框）是视觉页面中的点缀元素，而非独立模式。用它们突出重点或留出呼吸空间，但页面结构仍应以视觉呈现为主。

文字点缀元素请参阅 ./references/css-patterns.md 中的 “Prose Page Elements”。其他内容则采用下方美学方向中的标准自由布局方式。

谁在看？ 是在理解系统的开发者？重新审视调查报道的记者？审阅故事的编辑？纵览全局的 PM？审核研究方法的学者？这会影响信息密度和视觉复杂度。

内容类型是什么？ 架构、流程图、时序图、数据流、模式／ER 图、状态机、思维导图、类图、C4 架构、数据表、时间线、仪表板、消息来源网络、调查关系图、编辑工作流、故事结构，还是以文字为主的页面？每种类型都有各自的布局需求和渲染方式（请参阅下方的图表类型）。

采用什么美学风格？ 选一种并贯彻到底。受约束的风格（Blueprint、Editorial、Paper/ink）更稳妥，它们有具体要求，可避免产出千篇一律的设计。灵活的风格（受 IDE 启发）则需要更多自律。

受约束的美学风格（优先采用）：

• Blueprint（技术制图风格，搭配浅色网格背景、深石板蓝色调、等宽字体标签、精确边框）
• Editorial broadsheet（衬线标题，如 Playfair Display 或 Crimson Pro，留白充足，采用柔和大地色或深海军蓝 + 金色）
• Paper and ink（暖奶油色 #faf7f5 背景，搭配陶土色／鼠尾草绿点缀，氛围轻松，适合新闻特写）
• Magazine feature（大号展示衬线字体、偏轴构图、醒目引述、以照片为主导）
• Academic / research paper（Libre Baskerville 或 Source Serif，克制的配色、脚注式细节、宽裕的页边距）
• Newsroom board（软木／图钉质感、手写风格便笺、图钉卡片布局，适用于编辑策划和故事图）
• Investigation wall（红线风格、实体关联、方格纸背景、单色搭配红色点缀，适用于关系图）
• Monochrome terminal（近黑背景上的绿色／琥珀色，全部使用等宽字体，可选 CRT 光晕）

灵活的美学风格（谨慎使用）：

• IDE 风格（借鉴真实且具名的配色方案：Dracula、Nord、Catppuccin Mocha/Latte、Solarized Dark/Light、Gruvbox、One Dark、Rosé Pine）；贯彻实际配色，不要近似仿制
• 高密度数据／通讯社风格（小字号、紧凑间距、信息量最大化、柔和配色）
• 手绘草图（Mermaid look: 'handDrawn'、随意的批注，适用于白板讨论／早期构思）

明确禁止：

• 霓虹仪表板（深色背景上的青色 + 洋红色 + 紫色），总会产出 AI 垃圾
• 渐变网格（粉色／紫色／青色的色块），过于千篇一律
• Inter 字体 + 紫罗兰色／靛蓝色点缀 + 渐变文字的任意组合

每次都要更换选择。如果上一张图表采用深色技术风格，下一张就改用明亮的编辑风格。替换测试：如果把你的样式换成通用深色主题，却没人能察觉区别，那你就根本没有做设计。

2. 结构

**生成前请阅读参考资料。**不要死记硬背，而要每次都阅读，以熟悉其中的模式。

• 对于文字较多的架构概览（卡片内容比拓扑结构更重要）：阅读 ./templates/architecture.html
• 对于流程图、时序图、ER 图、状态机、思维导图、类图、C4：阅读 ./templates/mermaid-flowchart.html
• 对于数据表、对比、审计、功能矩阵、来源核验表：阅读 ./templates/data-table.html
• 对于幻灯片演示文稿（提供 --slides 标志或调用 /generate-slides 时）：阅读 ./templates/slide-deck.html 和 ./references/slide-patterns.md
• 对于以文字为主、可发布的页面（README、文章、博客文章、随笔）：阅读 ./references/css-patterns.md 中的“Prose Page Elements”部分，以及 ./references/libraries.md 中的“Typography by Content Voice”部分

对于 CSS/布局模式和 SVG 连接线，请阅读 ./references/css-patterns.md。

对于包含 4 个或更多部分的页面（评测、回顾、仪表板），还请阅读 ./references/responsive-nav.md，了解如何使用粘性侧边目录（桌面端）和可水平滚动的导航栏（移动端）进行章节导航。

选择渲染方式：

内容类型	方式	原因
架构（文字较多）	CSS Grid 卡片 + 流程箭头	丰富的卡片内容（描述、代码、工具列表）需要 CSS 控制
架构（以拓扑结构为主）	Mermaid	组件之间的连接需要自动布线
流程图 / 管道	Mermaid	自动定位节点并布线
时序图	Mermaid	生命线、消息和激活框需要自动布局
数据流	Mermaid，带边标签	连接和数据描述需要自动布线
ER 图 / 模式图	Mermaid	多个实体之间的关系线需要自动布线
状态机	Mermaid	带标签的状态转换需要自动布局
思维导图	Mermaid	层级分支需要自动定位
类图	Mermaid	继承、组合、聚合关系线需要自动布线
C4 架构	Mermaid	使用 graph TD + subgraph 表示 C4（不要使用原生 C4Context，它会忽略主题）
数据表 / 对比 / 审计	HTML <table>	语义化标记、无障碍性和复制粘贴体验更好
时间线 / 编年史	CSS（中间线 + 卡片）	简单的线性布局不需要布局引擎
仪表板 / 指标	CSS Grid + Chart.js	带嵌入式图表的卡片网格
来源网络	Mermaid 或 CSS Grid 卡片	映射调查或故事中各来源之间的关系
编辑工作流	Mermaid 流程图	展示故事从提案到发布和分发的生命周期
调查地图	CSS Grid 卡片 + Mermaid	连接调查工作中的实体、文档和事件
故事结构	CSS Grid	在发布前可视化叙事弧线、章节和来源分布

**Mermaid 主题。**始终使用 theme: 'base' 和自定义 themeVariables，使颜色与页面配色相匹配。对于复杂图表，使用 layout: 'elk'（需要本地打包的 @mermaid-js/layout-elk 包，参见 ./references/libraries.md）。使用 CSS 覆盖 Mermaid 的 SVG 类，以实现像素级精准控制。完整的主题指南请参见 ./references/libraries.md。

**Mermaid 容器。**始终使用 display: flex; justify-content: center; 将 Mermaid 图表居中。为每个 .mermaid-wrap 容器添加缩放控件（+／−／重置／展开）。加入点击展开 JavaScript，以便点击图表（或 ⛶ 按钮）时在新标签页中以全尺寸打开图表。 切勿使用裸 <pre class="mermaid">。 它虽然能渲染，但没有缩放／平移控件，图表会变得很小，无法使用。始终使用 journalism mermaid-flowchart.html 模式：用 .mermaid-wrap 容器包裹 .mermaid 元素，并在其中加入 .zoom-controls（＋／−／重置／展开按钮）。容器的 CSS 会处理溢出和拖动平移功能；随附的 JS 会连接缩放按钮、Ctrl＋滚轮缩放、按住鼠标点击并拖动平移，以及点击后在新标签页中展开。请完整复制模板，而不是重新拼凑此模式；同时复制其同级的 templates/vendor/ 目录，以确保固定版本的 Mermaid 导入路径仍然有效。

Mermaid 缩放。 包含 10 个或更多节点的图表默认渲染得太小。对于 10–12 个节点，将 themeVariables 中的 fontSize 增大到 18–20px，并将 INITIAL_ZOOM 设为 1.5–1.6。对于 15 个或更多元素，不要尝试缩放，改用混合模式（简洁的 Mermaid 概览图＋CSS Grid 卡片）。参见下方的“架构／系统图”。

Mermaid 布局方向。 复杂图表优先使用 flowchart TD（从上到下），而不是 flowchart LR（从左到右）。LR 布局会横向延伸，节点较多时标签将难以辨认。仅在简单的 3–4 节点线性流程中使用 LR。参见 ./references/libraries.md 中的“布局方向：TD 与 LR”。

Mermaid 流程图标签中的换行。 在带引号的标签内使用 <br/>。切勿使用转义换行符，例如 \n（Mermaid 会在 HTML 输出中将其渲染为字面文本）。示例：A["Pitch desk<br/>weekly intake"]。

Mermaid CSS 类名冲突限制。 切勿将 .node 定义为页面级 CSS 类。Mermaid.js 会在 SVG <g> 元素上使用 .node，并通过 transform: translate(x, y) 定位。页面级 .node 样式（悬停变换、阴影）会泄漏到图表中，破坏布局。卡片组件请使用带命名空间的 .ve-card 类。为 Mermaid 的 .node 添加样式的唯一安全方式，是将其限定在 .mermaid 下（例如 .mermaid .node rect）。

AI 生成的插图（可选）。 如果可以使用 surf-cli，你可以通过 Gemini 生成图片，并将其嵌入页面，用于创意表达、说明、阐释、教育或装饰。使用 which surf 检查是否可用。如果可用：

# Generate to a temp file (use --aspect-ratio for control)
surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9

# Base64 encode for self-containment (macOS)
IMG=$(base64 -i /tmp/ve-img.png)
# Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)

# Embed in HTML and clean up
# <img src="data:image/png;base64,${IMG}" alt="descriptive alt text">
rm /tmp/ve-img.png

图片容器样式（横幅、行内插图、说明文字）参见 ./references/css-patterns.md。

适用场景： 奠定页面视觉基调的横幅。用于表达 Mermaid 无法呈现的抽象系统的概念插图（物理基础设施、用户旅程、思维模型）。适合艺术化或照片级写实呈现的教育图示。强化整体美感的装饰元素。

不适用场景： Mermaid 或 CSS 能够妥善处理的内容。无法传达意义的通用装饰。图片会造成干扰的数据密集型页面。务必确保优雅降级：如果无法使用 surf，就跳过图片，不要报错。页面仅凭 CSS 和字体排版也应完整呈现。

提示词撰写： 让图片风格与页面的配色方案和美学方向相匹配。指定风格（3D 渲染、技术插画、水彩、等距、扁平矢量等），并提及 CSS 变量中的主色调。横幅使用 --aspect-ratio 16:9，行内插图使用 --aspect-ratio 1:1。提示词要具体，例如“深海军蓝背景上带有青色节点的消息队列等距插画”，就比“队列示意图”更好。

3. 样式

对每个图表应用以下原则：

字体排版就是图表本身。 从 ./references/libraries.md 的列表中选择一组有特色的字体搭配。每个页面都应使用与近期生成内容不同的字体搭配。新闻风格的字体搭配（适用于报纸社论风格的 Playfair Display + Source Serif Pro、适用于学术风格的 Libre Baskerville + Fira Code、适用于新闻编辑室风格的 Bitter + Inconsolata）与上游技术类字体搭配一同列出。 禁止用作 --font-body： Inter、Roboto、Arial、Helvetica、单独使用 system-ui。这些都是 AI 敷衍作风的信号。

推荐的上游字体组合（请使用）：

• DM Sans + Fira Code（技术感强、精准）
• Instrument Serif + JetBrains Mono（编辑风格、精致）
• IBM Plex Sans + IBM Plex Mono（可靠、易读）
• Bricolage Grotesque + Fragment Mono（醒目、有个性）
• Plus Jakarta Sans + Azeret Mono（圆润、亲和）

推荐的新闻业字体组合（用于编辑、学术或新闻编辑室场景）：

• Playfair Display + Source Serif Pro（经典报纸风格）
• DM Serif Display + DM Sans（现代杂志风格）
• Libre Baskerville + Fira Code（研究论文风格）
• Bitter + Inconsolata（新闻编辑室工作文档风格）
• Instrument Serif + JetBrains Mono（通讯社／数据风格）

通过 <link> 在 <head> 中加载。请在 font-family 栈中加入系统字体作为回退，以确保离线时也能正常显示。

色彩讲述故事。 使用 CSS 自定义属性定义完整调色板。至少定义：--bg、--surface、--border、--text、--text-dim，以及 3–5 种强调色。每种强调色都应有完整色和暗淡色变体（用于背景）。尽可能使用语义化的变量名（例如 --pipeline-step，而不是 --blue-3）。同时支持两种主题。

禁止使用的强调色： #8b5cf6 #7c3aed #a78bfa（靛蓝／紫罗兰）、#d946ef（紫红色）、青色—洋红色—粉色组合。这些都是 Tailwind 默认配色，会显得毫无设计意图。

推荐的强调色调色板（请使用）：

• 赤陶色 + 鼠尾草绿（#c2410c、#65a30d），温暖、自然（新闻编辑室、纸与墨）
• 蓝绿色 + 石板灰（#0891b2、#0369a1），技术感强、精准（架构、蓝图）
• 玫瑰色 + 蔓越莓色（#be123c、#881337），编辑风格、精致（验证审计）
• 琥珀色 + 翠绿色（#d97706、#059669），侧重数据（仪表盘）
• 深蓝色 + 金色（#1e3a5f、#d4a73a），高端、精致（学术、管理层）

将主视觉风格放在 :root 中，将备用风格放在媒体查询中：

/* Light-first (editorial, paper/ink, blueprint, academic): */
:root { /* light values */ }
@media (prefers-color-scheme: dark) { :root { /* dark values */ } }

/* Dark-first (terminal, IDE-inspired): */
:root { /* dark values */ }
@media (prefers-color-scheme: light) { :root { /* light values */ } }

表面效果应含蓄，而非喧宾夺主。 通过细微的明度变化（层级之间相差 2–4%）来营造纵深感，不要使用差异过大的颜色。边框应使用低不透明度的 rgba（暗色模式下为 rgba(255,255,255,0.08)，浅色模式下为 rgba(0,0,0,0.08)），看得见时能察觉，不留意时则不会分散注意力。

背景营造氛围。 页面背景不要使用平涂的纯色。可使用细腻的渐变、通过 CSS 实现的淡网格图案，或在焦点区域背后添加柔和的径向光晕。背景应让人感觉身处一个空间，而非虚空。

视觉权重传递重要性。 并非每个部分都值得同等对待。页面加载时，执行摘要和关键指标应在视口中占据主导地位（字号更大、内边距更多、背景区域带有微妙的强调色调）。参考部分（文件映射、依赖项列表、决策日志、来源列表）应保持紧凑，不要喧宾夺主。对于有用但非主要的部分，请使用 <details>/<summary>；可折叠模式见 ./references/css-patterns.md。

表面层次构建信息层级。 通过不同的卡片纵深来凸显重要内容。主视觉区域应使用突出的阴影和带有强调色调的背景（ve-card--hero 模式）。正文内容保持扁平（默认 .ve-card）。代码块和次要内容应有凹陷感（ve-card--recessed）。请参阅 ./references/css-patterns.md 中的纵深层级。不要让所有内容都显得突出；如果每样东西都很醒目，就没有重点了。

动画应发挥作用。 页面加载时使用错开的淡入效果通常很值得，它能引导视线沿着图表的层级移动。根据作用混合使用动画类型：卡片使用 fadeUp，关键绩效指标和徽章使用 fadeScale，SVG 连接线使用 drawIn，主视觉数字使用 countUp。为具有交互感的元素添加悬停过渡效果，让图表更有活力。务必遵循 prefers-reduced-motion。大多数情况下，CSS 过渡和关键帧即可满足需求。对于需要编排多个元素的序列，请使用 ./references/libraries.md 中本地随附的 anime.js 资源。 禁止的动画：

• 发光的动态框阴影（@keyframes glow { box-shadow: 0 0 20px... }），这是 AI 垃圾内容
• 静态内容上的脉动／呼吸效果
• 页面加载后持续运行的动画（进度指示器除外）

让动画发挥明确作用：入场展示、悬停反馈和用户主动触发的交互。任何元素都不应自行发光或脉动。

无障碍性。 所有生成的页面都必须至少符合 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

告知用户文件路径，以便他们重新打开或分享。

图表类型

架构／系统图

根据复杂度采用三种方案：

简单拓扑（少于 10 个元素）： 使用 Mermaid。使用自定义 themeVariables 的 graph TD 可生成易读的图表，并自动布局连线。

文本较多的概览（少于 15 个元素）： 使用 CSS Grid 并明确指定行／列位置。各部分用带彩色边框和等宽字体标签的圆角卡片呈现。各部分之间用垂直流程箭头连接。./templates/architecture.html 中的参考模板展示了这种模式，示例为新闻编辑部 CMS。适用于卡片需要包含说明、代码引用、工具列表或 Mermaid 节点无法承载的其他丰富内容时。

复杂架构（15 个及以上元素）： 使用混合模式：先用简单的 Mermaid 概览图（5–8 个节点展示模块关系），再用详细的 CSS Grid 卡片展示各模块的内部结构。这样既能呈现可视化拓扑，又能清晰展示细节。概览图使用模块名称，并用 <small> 标签标注关键函数名称。下方的卡片展示完整的函数列表，并标记新增／修改项。切勿试图将 15 个及以上元素塞进单张 Mermaid 图表；即使有缩放控件，图表也会缩得难以阅读。

流程图／流水线

使用 Mermaid。 自动节点定位和连线布局可生成规范的图表，包含连接线、菱形决策节点和并行分支，效果远胜于使用箭头字符的 CSS flexbox。优先使用 graph TD（自上而下）；只有在简单的 3–4 节点线性流程中才使用 graph LR。使用 Mermaid 的 classDef 对节点类型进行颜色编码，或使用 themeVariables 自动设置样式。适用于编辑工作流（选题提案 → 分配任务 → 撰稿 → 编辑 → 发布）、FOIA 请求流程、核实工作流和报道路由流水线。

时序图

使用 Mermaid。 生命线、消息、激活框、注释和循环都需要自动布局。使用 Mermaid 的 sequenceDiagram 语法。通过 CSS 覆盖 .actor、.messageText、.activation 类，为参与者和消息设置样式。适用于展示记者、编辑、消息源和系统之间的交互。

数据流图

使用 Mermaid。 数据流图强调连接关系而非方框，这正是 Mermaid 的强项。使用 graph TD（或用于简单线性流程的 graph LR），并用边标签描述数据。主要数据流使用更粗的彩色连线。通过 Mermaid 的 classDef 为源／汇节点和转换节点设置不同样式。

架构／ER 图

使用 Mermaid。 实体之间的关系线需要自动布局。使用 Mermaid 的 erDiagram 语法，并添加实体属性。通过 themeVariables 和针对 .er.entityBox、.er.relationshipLine 的 CSS 覆盖来设置样式。

状态机／决策树

使用 Mermaid。 对带标注转换的状态使用 stateDiagram-v2。支持嵌套状态、分叉、汇合和注释。决策树可以使用带菱形决策节点的 graph TD。

stateDiagram-v2 标签注意事项： 转换标签使用严格的解析器，冒号、括号、<br/>、HTML 实体和大多数特殊字符都会导致静默解析失败（“Syntax error in text”）。如果标签需要包含其中任何内容（例如 cancel()、curate: true、多行标签），请改用带圆角节点和带引号边标签（|"label text"|）的 flowchart TD。流程图可以处理所有特殊字符，并支持使用 <br/> 换行。仅在标签简单、为单个词或纯文本时使用 stateDiagram-v2。

思维导图／层级分解

使用 Mermaid。 使用 mindmap 语法，从根节点开始进行层级分支。Mermaid 会自动处理放射状布局。使用 themeVariables 控制各层级节点的颜色。

类图

使用 Mermaid。 使用 classDiagram 语法进行领域建模、面向对象设计和实体关系建模。支持以下关系：关联（-->）、组合（*--）、聚合（o--）和继承（<|--）。添加多重性标签（例如 "1" --> "*"）以及抽象类／接口标记（<<interface>>、<<abstract>>）。对于不涉及面向对象语义的简单实体框（没有方法、没有继承），优先使用 erDiagram，它能为纯数据建模生成更清晰的图表。

C4 架构图

使用 Mermaid 流程图语法，而非原生 C4。 使用带 subgraph 块的 graph TD 表示 C4 边界。原生 C4Context 会硬编码尖角、自带字体、蓝色图标和不受 themeVariables 影响的内联 SVG 颜色，始终会与自定义配色冲突。

以流程图呈现 C4 的模式： 人员 → 圆角节点 (("Name"))，系统 → 矩形 ["Name"]，数据库 → 圆柱体 [("Name")]，边界 → subgraph 块，关系 → 带标签的箭头 -->|"protocol"|。使用 classDef 和 :::className 对外部系统进行视觉区分（例如，使用虚线边框）。与其他 Mermaid 图表一样，这种方式会继承 themeVariables、fontFamily 和 CSS 覆盖设置。

数据表／比较／审计

使用真正的 <table> 元素，不要用 CSS Grid 假装表格。表格天然支持无障碍访问、复制粘贴和列对齐。./templates/data-table.html 中的参考模板展示了以下所有模式，并以来源核验审计为例。

主动使用。 每当你想在终端中绘制 ASCII 框线表格时，都应改为生成 HTML 表格。包括：需求审计（请求与计划对比）、功能比较、状态报告、配置矩阵、测试结果摘要、依赖项列表、权限表、API 端点清单、来源核验网格、FOIA 请求日志、文档清单、逐条声明审计，以及任何按行列组织的结构化内容。

布局模式：

• 使用固定的 <thead>，以便长表格滚动时表头仍保持可见
• 使用 tr:nth-child(even) 设置交替行背景色（亮度变化轻微，为 2–3%）
• 对需要水平滚动的宽表格，可选用固定首列
• 使用带 overflow-x: auto 的自适应包装容器，以适应宽度超出视口的表格
• 通过 <colgroup> 或 th 宽度提示列宽，让文本较多的列有足够空间
• 鼠标悬停时高亮行，方便浏览

状态指示器（使用带样式的 <span> 元素，绝不使用表情符号）：

• 匹配／通过／是／已核验：带绿色背景的彩色圆点或勾号
• 缺失／失败／否／未核验：带红色背景的彩色圆点或叉号
• 部分／警告：琥珀色指示器
• 中性／信息：暗淡文本或柔和的徽标

单元格内容：

• 让长文本自然换行，不要截断，也不要强制单行显示
• 在单元格内使用 <code> 展示技术参考信息
• 使用颜色较暗的 <small> 显示次要细节
• 数值列右对齐，并使用 tabular-nums

时间线 / 编年史 / 路线图

垂直或水平时间线，中间有一条线（CSS 伪元素）。阶段标记为线上的圆圈。内容卡片向左/右分支（交替排列），或全部放在一侧。日期标签标在线上。颜色从过去（柔和）渐变到未来（鲜明）。适用于调查时间线、事件编年史、项目历史。

仪表板 / 指标概览

卡片网格布局。醒目突出的大号核心数字。通过内联 SVG <polyline> 绘制迷你趋势图。通过 div 上的 CSS linear-gradient 绘制进度条。对于实际图表（柱状图、折线图、饼图），请使用 ./references/libraries.md 中本地供应的 Chart.js 资源。KPI 卡片带趋势指示器（上/下箭头、百分比变化）。适用于新闻编辑部分析、资助报告仪表板、受众指标。

来源关系网

绘制调查或报道中各来源之间的关系。关系复杂的网络图可使用 Mermaid，侧重细节的来源档案可使用 CSS Grid 卡片。包括：来源名称、角色、可信度指标、提供的信息，以及与其他来源的交叉引用。按来源类别使用颜色区分（官方记录、具名人士、匿名人士、文件、专家）。

调查关系图

通过可视化连线关联实体（人物、组织、文件、事件）。实体档案可使用 CSS Grid 卡片，关系图可使用 Mermaid。按实体类型使用颜色区分。展示关系强度。适用于调查报道、追踪资金流向、绘制权力结构。“调查墙”风格（红线、单色搭配红色点缀）很适合这种用途。

编辑工作流

使用 Mermaid 流程图展示报道生命周期：选题 → 分派 → 调查 → 撰稿 → 编辑 → 法务审核 → 文字编辑 → 排版 → 发布 → 分发。用颜色区分阶段。展示决策关卡（终止/修改/批准）。在流程转换处标注角色。./templates/mermaid-flowchart.html 中的参考模板展示了这种模式。

报道结构

使用 CSS Grid 可视化叙事弧线。展示各部分、字数、来源分布、多媒体位置。适用于规划长篇报道，或在发布前审阅报道架构。

实施计划

用于可视化实施计划、扩展设计或功能规格。目标是理解方案，而不是阅读完整源代码。

不要倾倒完整文件。 将整个源文件直接展示在页面上会让页面难以阅读，也背离了可视化说明的初衷。改为：

• 展示带说明的文件结构，并用一句话解释各函数/导出项
• 只展示关键代码片段，即用于说明核心逻辑的 5–10 行
• 如确有需要，使用可折叠区域展示完整代码

代码块需要明确的格式设置。 不设置 white-space: pre-wrap，代码就会连成一片，难以阅读。正确模式请参见 ./references/css-patterns.md 中的“代码块”一节。

实施计划的结构：

1. 概述/目的（要解决什么问题？）
2. 流程图（Mermaid 或 CSS 卡片）
3. 带说明的文件结构（不展示完整代码）
4. 关键实施细节（代码片段）
5. API/接口摘要
6. 用法示例

文档（README、库文档、API 参考）

可视化文档时，将内容结构提取为可视化元素：

内容	可视化呈现方式
功能	卡片网格（2–3 列）
安装/设置步骤	编号卡片或垂直流程
API 端点/命令	带固定表头的表格
配置选项	表格
架构	Mermaid 图或 CSS 卡片布局
对比	并排面板或表格
警告/备注	提示框

不要只对文字进行排版，要将其转化为可视化内容。功能列表应转换为卡片网格，安装步骤应转换为编号流程，API 参考应转换为表格。

正文强调元素

在视觉页面中谨慎使用这些元素，以突出重点或留出呼吸空间。CSS 样式模式请参阅 ./references/css-patterns.md 中的“正文页面元素”。

• 导语段落，使用较大的介绍性文本，在深入卡片/网格之前交代背景
• 引述，突出关键见解；每页最多使用一处
• 提示框，用于警告、提示和重要说明
• 分节线，在主要章节之间形成视觉分隔

**使用时机：**介绍一篇文章的视觉页面可以用导语段落呈现论点，再用卡片展示关键论据。README 的可视化呈现可以用提示框标出警告，但其他内容应以卡片/表格为主。

幻灯片模式

一种替代输出格式，可将内容呈现为杂志品质的幻灯片演示文稿，而不是可滚动页面。仅在用户选择时启用：只有当用户调用 /generate-slides、向现有提示词传入 --slides（例如 /diff-review --slides），或明确要求制作幻灯片演示文稿时，才生成幻灯片。绝不自动选择幻灯片格式。

生成幻灯片前，请阅读 ./references/slide-patterns.md（引擎 CSS、幻灯片类型、转场、导航界面、预设）和 ./templates/slide-deck.html（展示全部 10 种类型的参考模板）。还要阅读 ./references/css-patterns.md，了解共享模式；并阅读 ./references/libraries.md，了解 Mermaid/Chart.js 的主题设置。

幻灯片不是重新排版的页面。 它们是另一种媒介。每张幻灯片的高度恰好为一个视口（100dvh），且不能滚动。字体大小增加 2–3 倍。构图更加大胆。Agent 要构建叙事弧线（影响 → 背景 → 深入探讨 → 解决方案），而不是机械地为源内容分页。

内容完整性。 更换媒介不代表可以删减内容。在编写任何 HTML 之前，请遵循 slide-patterns.md 中的“根据源文档规划幻灯片演示文稿”流程：盘点源内容，将每一项映射到幻灯片，并核实覆盖情况。源文档中的每个章节、决策、数据点、规范和可折叠详情都必须出现在演示文稿中。如果计划有 7 个章节，演示文稿就要涵盖全部 7 个。如果有 6 项决策，就要展示全部 6 项，而不是只展示一张幻灯片放得下的 2 项。源文档中的可折叠详情要单独制作为幻灯片。增加幻灯片数量，而不是删减内容。涵盖全部内容的 22 张幻灯片，胜过外观精美却遗漏 40% 源内容的 13 张幻灯片。

**幻灯片类型（10 种）：**标题、章节分隔页、内容页、分栏页、图示页、仪表盘页、表格页、代码页、引述页、全出血页。每种类型在 slide-patterns.md 中都有指定的布局。如果内容超出单张幻灯片的密度限制，就拆分成多张幻灯片，绝不能在幻灯片内滚动。

视觉丰富度： 开始时检查 which surf。如果有 surf-cli，请在编写 HTML 前生成 2–4 张图片（标题页背景、全出血背景、可选的内容插图）；工作流程请参阅 slide-patterns.md 中的“主动图像生成”部分。还要使用 SVG 装饰元素、逐张幻灯片的背景渐变、内联迷你图和小型 Mermaid 图示。视觉优先，文字其次。

构图多样性： 相邻幻灯片必须采用不同的空间布局方式：居中、左侧偏重、右侧偏重、分栏、边缘对齐、全出血。连续出现三张居中的幻灯片时，应将其中一张改为偏轴布局。

精选预设： 四种专为幻灯片设计的预设可供选择作为起点（Midnight Editorial、Warm Signal、Terminal Mono、Swiss Clean），此外还有适配幻灯片的现有美学方向。选定一种并保持统一。预设 CSS 值请参阅 slide-patterns.md。

现有提示词中的 --slides 标志： 用户向 /diff-review、/plan-review、/project-recap 或其他提示词传入 --slides 时，Agent 应按照该提示词的常规数据收集说明收集数据，然后以幻灯片演示文稿而非可滚动页面的形式呈现内容。幻灯片版本以不同的结构和节奏讲述相同的内容，但覆盖范围必须一致。不得以幻灯片格式为借口，总结或跳过可滚动版本本应包含的章节。

文件结构

每个图示都是一个可部署的 .html 文件，并可选配一个本地 vendor/ 目录，用于存放已通过锁文件验证的库。Mermaid 参考模板会在 templates/vendor/ 中附带所需的核心包；复制模板时，请保留这个同级目录。不要从运行时 CDN 获取可执行代码。结构如下：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Descriptive Title</title>
  <link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
  <style>
    /* CSS custom properties, theme, layout, components, all inline */
  </style>
</head>
<body>
  
  
  
</body>
</html>

分享页面

如果有兼容 Pi 的 vercel-deploy 技能，可通过 Vercel 即时分享视觉解说页面。无需账户或身份验证。

使用已安装的技能路径：

bash ~/.pi/agent/skills/visual-explainer/scripts/share.sh <html-file>

如果技能安装在其他位置，请改用对应的安装路径，例如 ~/.codex/skills/visual-explainer/scripts/share.sh、~/.config/opencode/skill/visual-explainer/scripts/share.sh，或从仓库检出目录运行 ./plugins/visual-explainer/scripts/share.sh。

工作原理：

1. 从已安装的 visual-explainer 技能目录运行 share.sh 脚本
2. 将 HTML 文件复制到临时目录，并命名为 index.html
3. 通过兼容 Pi 的 vercel-deploy 技能进行部署
4. URL 会立即生效，可在任何浏览器中访问

要求：

• 在标准的兼容 Pi 的技能位置安装 vercel-deploy 技能（在 Pi 中：pi install npm:vercel-deploy）

注意：

• 部署为公开状态，任何知道 URL 的人都可以查看
• 预览部署的保留期限可配置（默认：30 天）
• 认领 URL 可让你将部署转移到自己的 Vercel 账户
• 其他运行环境可以正常生成并打开 HTML；/share-page 依赖可用的兼容 Pi 的 vercel-deploy 脚本

请参阅 ./commands/share-page.md 中的 /share-page 命令模板。

质量检查

交付前，请确认：

• 眯眼测试：眯起眼睛看，仍能辨认出层级吗？各个部分在视觉上是否清晰区分？
• 替换测试：如果把字体和颜色换成通用深色主题，它会不会看起来就像一个普通模板？如果会，就进一步强化美学风格。
• 两种主题：在操作系统的浅色和深色模式之间切换。两种模式都应经过精心设计，而不是显示异常。
• 信息完整性：图表是否确实传达了用户要求的信息？好看但不完整就是失败。
• 无溢出：将浏览器调整为不同宽度。任何内容都不应被裁切或溢出容器。每个网格和 flex 子项都需要 min-width: 0。并排面板需要 overflow-wrap: break-word。切勿在 <li> 上使用 display: flex 来显示标记字符，这会创建无法收缩的匿名 flex 项，导致含有许多行内 <code> 徽标的行溢出。应改用绝对定位来显示标记。请参阅 ./references/css-patterns.md 中的“溢出防护”部分。
• Mermaid 缩放控件：每个 .mermaid-wrap 容器都必须提供缩放控件（放大／缩小／重置／展开按钮）、Ctrl/Cmd+滚轮缩放、点击并拖动平移，以及点击展开（点击而未拖动时，会在新标签页中以完整尺寸打开图表）。展开按钮（⛶）提供相同功能。完整模式（包括 openMermaidInNewTab() 函数）请参阅 ./references/css-patterns.md。
• 无障碍性：颜色对比度符合要求。状态指示不能只依赖颜色。表格须使用恰当的语义标记。
• 文件可正常打开：没有控制台错误、字体加载失败或布局偏移。

反模式（AI 垃圾内容）

以下模式明确禁止。它们会显露“AI 生成的模板”痕迹，破坏此技能制作独特、高质量图表的初衷。请根据此列表检查每个生成的页面。

字体排印

禁止作为主要 --font-body 使用的字体：

• Inter，这是最被滥用的 AI 默认字体
• Roboto、Arial、Helvetica，以及被提升为首选字体的通用系统回退字体
• 单独使用 system-ui、sans-serif，毫无特色，也没有设计意图

**要求：**从 ./references/libraries.md 中的字体搭配里进行选择。每次生成都应使用与上次不同的搭配。

配色

禁止使用的强调色：

• Indigo-500/violet-500（#8b5cf6、#7c3aed、#a78bfa），即 Tailwind 默认的紫色范围
• 青色 + 洋红色 + 粉色霓虹渐变组合（#06b6d4 → #d946ef → #f472b6）
• 任何可被描述为“带有紫色／粉色／青色强调色的 Tailwind 默认配色”的调色板

禁止使用的颜色效果：

• 标题上的渐变文字（background: linear-gradient(...); background-clip: text;），这会让页面一眼看上去像 AI 生成的
• 卡片上带动画的发光盒阴影（box-shadow: 0 0 20px var(--glow); animation: glow 2s...）
• 多个强调色径向光晕层叠，营造“霓虹薄雾”效果

必须： 以参考模板为基础构建配色（陶土色／鼠尾草绿、青绿色／青色、玫瑰色／蔓越莓色、石板灰／蓝色），或从真实 IDE 主题（Dracula、Nord、Solarized、Gruvbox、Catppuccin）中选取配色。强调色应经过精心设计，而不是使用默认配色。

分区标题

禁止：

• 在分区标题中使用表情符号图标（分区 UI 中完全不要使用装饰性表情符号）
• 所有分区标题都采用相同的圆角方框图标样式

必须： 使用带彩色圆点指示器的样式化等宽字体标签（参见模板中的 .section-label）、编号徽章（section__num 模式）或非对称分区分隔线。如果确实需要图标，请使用与配色相符的内联 SVG，而不是表情符号。

布局与层级

禁止：

• 所有内容都完美居中，且使用统一内边距
• 所有卡片都采用相同的边框圆角、阴影和间距
• 每个分区都采用相同的视觉权重，不区分主视觉／主要内容与次要内容
• 左右两侧互为镜像的对称布局

必须： 让视觉权重有所变化。主视觉区块应更突出（字号更大、内边距更多、背景带强调色）。参考区块应保持紧凑。使用不同的层次级别（主视觉 → 突出 → 默认 → 内凹）。非对称布局更能营造视觉趣味。

模板样式

禁止：

• 代码块上使用三个圆点的窗口装饰（红／黄／绿圆点），这已经是老套设计
• 每个指标都采用相同渐变文字效果的 KPI 卡片
• 选择“霓虹仪表盘”作为美学风格，这总会产生千篇一律的效果
• 背景中使用粉色／紫色／青色斑块的渐变网格

必须： 代码块使用简单的标题栏，并标明文件名或语言。KPI 卡片应根据重要性采用不同样式：主要指标使用醒目的数字，辅助指标则采用低调的样式。选择具有明确设计约束的美学风格：蓝图（必须体现技术感／精确性）、编辑风（必须留白充足并采用衬线字体）、纸张／墨水（必须温暖随性）、新闻编辑室看板（必须让人联想到软木板和图钉）。

俗套感测试

交付前请进行以下测试：开发者或编辑看到这个页面时，会不会立刻觉得“这是 AI 生成的”？ 以下是典型迹象：

1. Inter 或 Roboto 字体搭配紫色／紫罗兰色渐变强调
2. 每个标题都使用 background-clip: text 渐变
3. 每个分区前面都有表情符号图标
4. 卡片带有发光效果和动画阴影
5. 深色背景搭配青色－洋红色－粉色配色方案
6. 卡片网格完全统一，缺乏视觉层级
7. 代码块采用三个圆点的窗口装饰

如果上述现象出现两种或更多，这个页面就落入俗套了。请改用不同的美学方向重新生成，例如编辑风、蓝图、纸张／墨水、新闻编辑室看板、学术风格或特定 IDE 主题。这些风格有明确的视觉要求，不容易出错，因为它们能避免设计默认落入千篇一律的套路。

相关技能

• journalism-core/data-journalism，数据分析与故事讲述
• journalism-core/source-verification，SIFT 方法、核查轨迹
• journalism-core/editorial-workflow，任务跟踪、截止日期管理
• journalism-core/fact-check-workflow，主张核查
• dev-toolkit/accessibility-compliance，WCAG 合规、无障碍图表
• dev-toolkit/zero-build-frontend，本地 vendoring 依赖、React 运行时捆绑包、Leaflet 地图
• pdf-design，采用品牌体系的印刷就绪文档

---

改编自 nicobailon/visual-explainer（MIT），并融入 Anthropic's frontend-design skill 的设计原则。针对新闻、媒体和学术工作流量身定制。