visual-explainer

视觉说明

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

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

工作流

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

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

谁会查看？ 是要了解系统的开发者？了解整体情况的 PM？评审提案的团队？这会影响信息密度和视觉复杂度。

图表类型是什么？ 架构图、流程图、时序图、数据流图、模式／ER 图、状态机、思维导图、数据表格、时间线或仪表盘。每种类型都有各自的布局需求和渲染方式（参见下方的图表类型）。

采用什么美学风格？ 选择一种并坚持下去：

• 单色终端风格（黑底绿／琥珀色，全篇等宽字体）
• 编辑风格（衬线标题、宽松留白、柔和配色）
• 蓝图风格（技术制图质感、网格线、精确布局）
• 霓虹仪表盘（深色背景搭配高饱和点缀色和发光边缘）
• 纸墨风格（暖米色背景、手绘质感、粗略边框）
• 手绘／草图风格（Mermaid 的 handDrawn 模式、弯曲线条、随性的白板质感）
• IDE 风格（借鉴真实配色方案：Dracula、Nord、Catppuccin、Solarized、Gruvbox、One Dark）
• 高密度数据风格（小字号、紧凑间距、信息量最大化）
• 渐变网格风格（大胆渐变、玻璃拟态、现代 SaaS 质感）

每次都要更换风格。如果上一个图表是深色技术风格，下一个就改用明亮的编辑风格。进行替换测试：如果换成通用的深色主题后没人能看出区别，那就说明你还没有设计出任何东西。

2. 结构

生成前先阅读参考模板。 不要死记模板——每次都重新阅读，了解其中的模式。

• 对于文字内容比拓扑关系更重要的架构概览：阅读 ./templates/architecture.html
• 对于流程图、时序图、ER 图、状态机、思维导图：阅读 ./templates/mermaid-flowchart.html
• 对于数据表格、比较、审计、功能矩阵：阅读 ./templates/data-table.html

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

对于包含 4 个或更多章节的页面（评审、回顾、仪表盘），还要阅读 ./references/responsive-nav.md，以了解如何实现章节导航：桌面端使用固定侧边目录，移动端使用可水平滚动的导航栏。

选择渲染方式：

图表类型	方案	原因
架构（文本密集型）	CSS Grid 卡片 + 流程箭头	卡片内容丰富（描述、代码、工具列表），需要 CSS 控制
架构（侧重拓扑结构）	Mermaid	组件之间的连接需要自动路由边线
流程图 / 流水线	Mermaid	自动定位节点并路由边线；也可使用手绘模式
序列图	Mermaid	生命线、消息和激活框需要自动布局
数据流	Mermaid，带边线标签	连接和数据描述需要自动路由边线
ER / 架构图	Mermaid	多个实体之间的关系线需要自动路由
状态机	Mermaid	带标签边线的状态转换需要自动布局
思维导图	Mermaid	层级分支需要自动定位
数据表	HTML <table>	语义化标记、无障碍访问和复制粘贴行为
时间线	CSS（中央线 + 卡片）	简单的线性布局无需布局引擎
仪表板	CSS Grid + Chart.js	包含嵌入式图表的卡片网格

**Mermaid 主题：**始终使用 theme: 'base' 和自定义 themeVariables，让颜色与页面配色相匹配。使用 look: 'handDrawn' 营造手绘风格，或使用 look: 'classic' 呈现简洁线条。复杂图表使用 layout: 'elk'（需要 @mermaid-js/layout-elk 包——CDN 导入方式请参阅 ./references/libraries.md）。使用 CSS 覆盖 Mermaid 的 SVG 类，以实现像素级精准控制。完整主题指南请参阅 ./references/libraries.md。

**Mermaid 缩放控件：**始终为每个 .mermaid-wrap 容器添加缩放控件（+/-/重置按钮）。复杂图表渲染后尺寸较小，需要缩放才能看清。在容器上加入 Ctrl/Cmd+滚动缩放功能。请参阅 ./references/css-patterns.md 中的缩放控件模式，以及 ./templates/mermaid-flowchart.html 中的参考模板。

**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. 风格

将以下原则应用于每个图表：

字体排版就是图表。 从 Google Fonts 中挑选一组风格鲜明的字体。搭配一款有个性的展示／标题字体，以及一款用于技术标签的等宽字体。不要将 Inter、Roboto、Arial 或 system-ui 用作主要字体。通过 <link> 在 <head> 中加载字体。在 font-family 字体栈中加入系统字体作为回退，以确保离线时仍可正常显示。

色彩讲述故事。 使用 CSS 自定义属性定义完整的调色板。至少定义：--bg、--surface、--border、--text、--text-dim，以及 3 至 5 种强调色。每种强调色都应有完整色和暗淡变体（用于背景）。尽可能使用语义化的变量名（例如 --pipeline-step，而非 --blue-3）。同时支持两种主题。将主要视觉风格放在 :root 中，将替代主题放在媒体查询中：

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

/* Dark-first (neon, IDE-inspired, terminal): */
: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。

表面纵深建立层级。 通过调整卡片纵深来凸显重要内容。主视觉部分使用提升的阴影和带强调色的背景（node--hero 模式）。正文内容保持扁平（默认 .node）。代码块和次要内容应呈现凹陷效果（node--recessed）。详见 ./references/css-patterns.md 中的纵深层级。不要让所有内容都显得凸起——如果一切都很突出，就没有任何内容真正突出。

动画应有其用处。 页面加载时使用依次出现的淡入动画通常很值得——它们能引导视线浏览图表的层级。根据用途混合动画类型：卡片使用 fadeUp，KPI 和徽章使用 fadeScale，SVG 连接线使用 drawIn，主视觉数字使用 countUp。为具有交互感的元素添加悬停过渡效果，让图表更具活力。始终遵循 prefers-reduced-motion。大多数情况下，CSS 过渡和关键帧即可满足需求。对于需要协调多个元素的序列，可通过 CDN 使用 anime.js（参见 ./references/libraries.md）。

4. 交付

输出位置： 写入 ~/.agent/diagrams/。根据内容使用描述性文件名，例如：modem-architecture.html、pipeline-flow.html、schema-overview.html。该目录会跨会话保留。

在浏览器中打开：

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

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

图表类型

架构／系统图

根据重点所在，有两种方法：

以文本内容为主的概览（卡片内容比连接关系更重要）：使用 CSS Grid 明确设置行／列位置。各部分用带彩色边框的圆角卡片表示，并使用等宽字体标签。各部分之间用垂直流程箭头连接。子系统使用嵌套网格。./templates/architecture.html 中的参考模板展示了这种模式。适用于卡片需要包含描述、代码引用、工具列表或其他 Mermaid 节点无法承载的丰富内容的情况。

以拓扑结构为主的图（连接关系比卡片内容更重要）：使用 Mermaid。 使用 graph TD 或 graph LR，并设置自定义 themeVariables，即可生成具有自动边缘布线的规范图表。使用 look: 'handDrawn' 营造随意的感觉，或使用 look: 'classic' 呈现简洁线条。适用于重点是展示组件之间的连接方式，而不是详细描述各组件功能的情况。

流程图／管道

使用 Mermaid。 自动定位节点和布置边缘，可生成带连接线、判断菱形和并行分支的规范图表，效果远胜于使用箭头字符的 CSS flexbox。使用 graph TD 表示从上到下的布局，或使用 graph LR 表示从左到右的布局。使用 look: 'handDrawn' 营造草图风格。使用 Mermaid 的 classDef 为节点类型设置颜色，或依靠 themeVariables 自动设置样式。

序列图

使用 Mermaid。 生命线、消息、激活框、注释和循环都需要自动布局。使用 Mermaid 的 sequenceDiagram 语法。通过对 .actor、.messageText、.activation 类进行 CSS 覆盖，为参与者和消息设置样式。

数据流图

使用 Mermaid。 数据流图强调连接关系而非方框，这正是 Mermaid 的优势所在。使用 graph LR 或 graph TD，并通过边标签描述数据。为主要数据流设置更粗的彩色边。使用 Mermaid 的 classDef 为源／汇节点设置与转换节点不同的样式。

架构／ER 图

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

状态机／决策树

使用 Mermaid。 使用 stateDiagram-v2 表示带标签转换的状态。支持嵌套状态、分叉、汇合和注释。使用 look: 'handDrawn' 绘制非正式的状态图。决策树可使用带菱形判断节点的 graph TD。

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

思维导图／层级分解图

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

数据表格 / 对比 / 审计

使用真正的 <table> 元素，而不是用 CSS Grid 假装表格。表格天然具备无障碍支持、复制粘贴行为和列对齐功能。./templates/data-table.html 中的参考模板展示了以下所有模式。

主动使用。 每当你打算在终端中绘制 ASCII 框线表格时，都应改为生成 HTML 表格。这包括：需求审计（请求与计划对照）、功能对比、状态报告、配置矩阵、测试结果摘要、依赖项列表、权限表、API 端点清单——以及任何具有结构化行和列的内容。

布局模式：

• 使用固定的 <thead>，让表头在长表格滚动时保持可见
• 通过 tr:nth-child(even) 为交替行设置背景色（亮度变化幅度较小，为 2–3%）
• 对宽表格可选用固定首列，并支持水平滚动
• 使用 overflow-x: auto 设置响应式包装容器，以适配宽度超出视口的表格
• 通过 <colgroup> 或 th 宽度提示列宽，让文字较多的列有足够空间
• 为行添加悬停高亮，便于浏览

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

• 匹配 / 通过 / 是：带绿色背景的彩色圆点或勾号
• 存在差距 / 失败 / 否：带红色背景的彩色圆点或叉号
• 部分 / 警告：琥珀色指示器
• 中性 / 信息：暗淡文本或低调徽章

单元格内容：

• 自然换行显示长文本——不要截断，也不要强制单行显示
• 在单元格中使用 <code> 标记技术引用
• 使用颜色较暗的 <small> 显示次要详情
• 数值列保持右对齐，并使用 tabular-nums

时间线 / 路线图视图

使用垂直或水平时间线，并通过 CSS 伪元素绘制中央线。在线上以圆形标记阶段。内容卡片向左右交替分布，或统一分布在线的一侧。在线上标注日期。颜色从过去（低调）逐渐过渡到未来（鲜明）。

仪表板 / 指标概览

采用卡片网格布局。醒目的核心数字应使用大号字体。通过内联 SVG <polyline> 绘制迷你趋势图。使用 div 上的 CSS linear-gradient 绘制进度条。对于真实图表（柱状图、折线图、饼图），请使用通过 CDN 加载的 Chart.js（参见 ./references/libraries.md）。KPI 卡片应包含趋势指示器（上升 / 下降箭头、百分比变化）。

文件结构

每个图表都是一个独立的 .html 文件，无需其他资源，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>

质量检查

交付前，请确认：

• 眯眼测试：眯起眼睛时，仍能看出内容层级吗？各个部分在视觉上是否清晰区分？
• 替换测试：如果将字体和颜色替换为通用深色主题，这个页面是否会变得与模板毫无区别？如果会，就进一步强化视觉风格。
• 两种主题：将操作系统主题切换为浅色和深色。两种主题都应经过精心设计，而不是显示异常。
• 信息完整性：图表是否确实传达了用户要求的信息？好看但不完整就是失败。
• 无溢出：调整浏览器到不同宽度。内容不应被裁切或超出容器。每个网格和 Flex 子项都需要 min-width: 0。并排面板需要 overflow-wrap: break-word。切勿在 <li> 上使用 display: flex 来排列标记字符——这会创建无法收缩的匿名 Flex 项，导致包含许多内联 <code> 徽章的行溢出。请改用绝对定位放置标记。参见 ./references/css-patterns.md 中的 Overflow Protection 部分。
• Mermaid 缩放控件：每个 .mermaid-wrap 容器都必须提供缩放控件（+ / − / 重置按钮）、Ctrl/Cmd+滚轮缩放，以及单击并拖动平移功能。复杂图表若没有这些控件，渲染出来会太小。放大后，光标应变为 grab；拖动时应变为 grabbing。完整模式参见 ./references/css-patterns.md。
• 文件正常打开：没有控制台错误、字体加载失败或布局偏移。