visual-explainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual explainer

可视化解释器

Generate self-contained HTML files for technical diagrams and data visualizations. Always open the result in the browser. Never fall back to ASCII art when this skill is loaded.

Proactive table rendering: When about to output a table with 4+ rows or 3+ columns, render it as styled HTML instead of ASCII. Open in browser.

为技术图表和数据可视化生成独立的HTML文件。始终在浏览器中打开生成结果。加载本技能后，绝不要退而使用ASCII艺术图。

主动渲染表格：当要输出的表格包含4行及以上或3列及以上时，将其渲染为带样式的HTML而非ASCII表格，并在浏览器中打开。

Workflow

工作流程

1. Think (5 seconds, not 5 minutes)

1. 构思（耗时5秒，而非5分钟）

Audience: Developer? Editor? Reporter? PM? Public reader?
Diagram type: Pick from the routing table below.
Aesthetic direction: Pick one that fits. Don't default to the same look every time.
- Monochrome terminal
- Editorial broadsheet
- Blueprint / technical
- Neon dashboard
- Paper and ink
- Hand-drawn sketch
- IDE-inspired
- Data-dense / wire service
- Gradient mesh
- Newsroom board (cork/pushpin)
- Investigation wall (red string)
- Magazine feature
- Academic / research paper

The swap test: If you replaced your styling with a generic dark theme and nobody would notice the difference, you haven't designed anything. Push further.

受众：开发者？编辑？记者？产品经理？普通读者？
图表类型：从下方的路由表中选择。
美学风格：选择符合场景的风格，不要每次都默认使用同一种风格。
- 单色终端风
- 大报编辑风
- 蓝图/技术风
- 霓虹仪表盘风
- 纸墨风
- 手绘草图风
- IDE灵感风
- 数据密集/通讯社风
- 渐变网格风
- 编辑部公告板（软木板/图钉）风
- 调查墙（红线连接）风
- 杂志专题风
- 学术/研究论文风

替换测试：如果将你的样式替换为通用深色主题后，没人能看出区别，说明你还没有做出独特设计。要进一步优化。

2. Structure

2. 结构设计

Read reference templates before generating:

```
./templates/architecture.html
```
— text-heavy architecture / editorial structure
```
./templates/mermaid-flowchart.html
```
— flowcharts, sequences, diagrams
```
./templates/data-table.html
```
— data tables, audits, comparisons

Read

./references/css-patterns.md

for CSS and layout patterns. Read

./references/responsive-nav.md

for multi-section pages with sticky navigation. Read

./references/libraries.md

for Mermaid theming, Chart.js, anime.js, and font pairings.

生成前先参考模板：

```
./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和字体搭配。

Rendering approach by diagram type

按图表类型选择渲染方式

Type	Approach	Rationale
Architecture (text-heavy)	CSS Grid cards + flow arrows	Rich card content needs CSS control
Architecture (topology)	Mermaid	Connections need auto edge routing
Flowchart / pipeline	Mermaid	Auto node positioning and edge routing
Sequence diagram	Mermaid	Lifelines and activation boxes need layout
Data flow	Mermaid with edge labels	Connections and data descriptions
ER / schema	Mermaid	Relationship lines need auto-routing
State machine	Mermaid	State transitions with labeled edges
Mind map	Mermaid	Hierarchical branching positioning
Data table / comparison	HTML `<table>`	Semantic markup and accessibility
Timeline / chronology	CSS (central line + cards)	Simple linear layout
Dashboard / metrics	CSS Grid + Chart.js	Card grid with embedded charts
Source network	Mermaid or CSS Grid	Map relationships between sources
Editorial workflow	Mermaid flowchart	Story lifecycle from pitch to publish
Investigation map	CSS Grid cards + Mermaid	Connect entities, documents, events
Story structure	CSS Grid	Visualize narrative arc and sections

类型	实现方式	理由
架构（文字密集型）	CSS Grid卡片 + 流向箭头	丰富的卡片内容需要CSS控制
架构（拓扑型）	Mermaid	系统连接需要自动边缘路由
流程图/流水线	Mermaid	自动节点定位和边缘路由
序列图	Mermaid	生命线和激活框需要自动布局
数据流	带边缘标签的Mermaid	展示连接关系和数据说明
ER/模式图	Mermaid	关系线需要自动路由
状态机	Mermaid	带标签边缘的状态转换
思维导图	Mermaid	层级分支定位
数据表/对比表	HTML `<table>`	语义化标记和无障碍支持
时间线/年表	CSS（中心线 + 卡片）	简洁的线性布局
仪表盘/指标概览	CSS Grid + Chart.js	嵌入图表的卡片网格
源网络	Mermaid或CSS Grid	展示源之间的关系
编辑工作流	Mermaid流程图	展示从选题到发布的故事生命周期
调查图谱	CSS Grid卡片 + Mermaid	连接实体、文档、事件
故事结构	CSS Grid	可视化叙事弧线和章节

Mermaid theming

Mermaid主题设置

Use
```
theme: 'base'
```
with custom
```
themeVariables
```
— built-in themes ignore most overrides.
Use
```
look: 'handDrawn'
```
for sketch aesthetic,
```
look: 'classic'
```
for clean.
Use
```
layout: 'elk'
```
for complex graphs (requires
```
@mermaid-js/layout-elk
```
CDN import).
Always include zoom controls (+/−/reset buttons) on
```
.mermaid-wrap
```
containers.
Support Ctrl/Cmd+scroll zoom and click-and-drag panning.

使用
```
theme: 'base'
```
搭配自定义
```
themeVariables
```
— 内置主题会忽略大多数自定义设置。
使用
```
look: 'handDrawn'
```
实现草图美学，
```
look: 'classic'
```
实现简洁风格。
复杂图形使用
```
layout: 'elk'
```
（需要引入
```
@mermaid-js/layout-elk
```
CDN资源）。
始终在
```
.mermaid-wrap
```
容器上添加缩放控件（+/−/重置按钮）。
支持Ctrl/Cmd+滚轮缩放和点击拖拽平移。

3. Style

3. 样式设计

Typography: Pick a distinctive font pairing from Google Fonts (display/heading + mono or body). Never use Inter, Roboto, Arial, or system-ui as primary. For editorial contexts, serif display fonts work well (Playfair Display, Libre Baskerville, Source Serif Pro). Load via

<link>

<head>

. Include system font fallback.

Color: Use CSS custom properties. Define minimum:

--bg

--surface

--border

--text

--text-dim

, plus 3–5 accent colors (each with full and dim variant). Name semantically. Support both themes:

css

/* Light-first */
:root { /* light values */ }
@media (prefers-color-scheme: dark) { :root { /* dark values */ } }

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

Surfaces: Build depth through subtle lightness shifts (2–4% between levels), not dramatic color. Borders should be low-opacity rgba (

rgba(255,255,255,0.08)

dark,

rgba(0,0,0,0.08)

light).

Backgrounds: Don't use flat solid colors. Use subtle gradients, faint grid patterns via CSS, or gentle radial glows.

Visual weight: Not every section deserves equal treatment. Executive summaries and key metrics dominate viewport. Reference sections stay compact. Use

<details>/<summary>

for useful but non-primary content.

Surface depth: Vary card depth to signal importance:

Hero sections: elevated shadows, accent-tinted backgrounds (
```
node--hero
```
)
Body content: flat default (
```
.node
```
)
Secondary content: recessed feeling (
```
node--recessed
```
)

Animation: Staggered fade-ins on page load almost always worth it. Mix animation types by role:

```
fadeUp
```
for cards
```
fadeScale
```
for KPIs and badges
```
drawIn
```
for SVG connectors
```
countUp
```
for hero numbers

Always respect

prefers-reduced-motion

. Use CSS transitions and keyframes primarily. For orchestrated sequences, anime.js via CDN is available.

Accessibility: All generated pages must meet WCAG 2.1 AA minimum. This means:

Color contrast ratios: 4.5:1 for text, 3:1 for large text and UI components
Status indicators use shape/text alongside color (never color alone)
Tables have proper
```
<thead>
```
,
```
<th scope>
```
, and
```
<caption>
```
elements
Charts include data table alternatives
Focus indicators visible for keyboard navigation
Language declared in
```
<html lang="en">
```

排版：从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个强调色（每个颜色包含正常和弱化变体）。语义化命名颜色。支持两种主题：

css

/* 浅色优先 */
: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
```
动画
KPI和徽章使用
```
fadeScale
```
动画
SVG连接线使用
```
drawIn
```
动画
英雄区数字使用
```
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. Deliver

4. 交付

Output location:

~/.agent/diagrams/

Filename: Descriptive, based on content. Examples:

authentication-flow.html

source-network.html

budget-analysis.html

editorial-pipeline.html

Open in browser:

macOS:
```
open ~/.agent/diagrams/filename.html
```

Linux:

xdg-open ~/.agent/diagrams/filename.html

Tell user the file path.

输出位置：

~/.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

告知用户文件路径。

Diagram types — detail

图表类型详情

Architecture / system diagrams

架构/系统图

Text-heavy overviews: CSS Grid with explicit placement, rounded cards, colored borders, monospace labels, vertical flow arrows. Good for newsroom systems, CMS architecture, data pipeline overviews.

Topology-focused: Mermaid with auto edge routing. Good for showing how systems connect.

文字密集型概览：使用CSS Grid显式布局、圆角卡片、彩色边框、等宽标签、垂直流向箭头。适用于新闻室系统、CMS架构、数据管道概览。

拓扑聚焦型：使用Mermaid自动边缘路由。适用于展示系统间的连接方式。

Flowcharts / pipelines

流程图/流水线

Mermaid. Use

graph TD

(top-down) or

graph LR

(left-right). Use

look: 'handDrawn'

for sketch. Color-code nodes via

classDef

themeVariables

. Good for editorial workflows (pitch → assign → draft → edit → publish), FOIA request processes, verification workflows.

使用Mermaid。采用

graph TD

（自上而下）或

graph LR

（从左到右）布局。草图风格使用

look: 'handDrawn'

。通过

classDef

或

themeVariables

为节点配色。适用于编辑工作流（选题→分配→撰写→编辑→发布）、FOIA请求流程、验证工作流。

Sequence diagrams

序列图

Mermaid

sequenceDiagram

. Lifelines, messages, activation boxes, notes, loops with auto layout. Good for showing interaction between reporters, editors, sources, and systems.

使用Mermaid

sequenceDiagram

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

Data tables / comparisons / audits

数据表/对比表/审计表

Real

<table>

HTML element for semantic markup and accessibility. Use proactively for any structured rows/columns.

Layout patterns:

Sticky
```
<thead>
```
Alternating row backgrounds via
```
tr:nth-child(even)
```
(2–3% lightness shift)
First column optionally sticky for wide tables
Responsive wrapper with
```
overflow-x: auto
```
Column width hints via
```
<colgroup>
```
or
```
th
```
widths
Row hover highlight

Status indicators (styled

<span>

, never emoji):

Match/pass/yes: colored dot or checkmark with green background
Gap/fail/no: colored dot or cross with red background
Partial/warning: amber indicator
Neutral/info: dim text or muted badge

Cell content:

Wrap long text naturally
Use
```
<code>
```
for technical references
Secondary detail in
```
<small>
```
with dimmed color
Right-align numeric columns with
```
tabular-nums
```

使用真实的

<table>

HTML元素实现语义化标记和无障碍支持。对于任何结构化行列内容，都要主动使用该方式。

布局模式：

粘性表头
```
<thead>
```
通过
```
tr:nth-child(even)
```
实现交替行背景（亮度差异2-3%）
宽表格可将第一列设置为粘性
带
```
overflow-x: auto
```
的响应式容器
通过
```
<colgroup>
```
或
```
th
```
设置列宽提示
行悬停高亮

状态指示器（使用样式化

<span>

，绝不要用emoji）：

匹配/通过/是：带绿色背景的彩色圆点或对勾
差距/失败/否：带红色背景的彩色圆点或叉号
部分/警告：琥珀色指示器
中性/信息：弱化文本或 muted 徽章

单元格内容：

长文本自动换行
技术引用使用
```
<code>
```
标签
次要详情使用
```
<small>
```
标签并设置弱化颜色
数字列使用
```
tabular-nums
```
并右对齐

Timeline / chronology

时间线/年表

Vertical or horizontal timeline with central line (CSS pseudo-element). Phase markers as circles. Content cards branching left/right (alternating) or one side. Date labels on line. Color progression from past (muted) to future (vivid). Good for investigation timelines, event chronologies, project histories.

使用CSS伪元素实现垂直或水平时间线的中心线。阶段标记为圆形。内容卡片交替左右分支或单侧分支。日期标签标注在中心线上。颜色从过去（弱化）到未来（鲜艳）渐变。适用于调查时间线、事件年表、项目历史。

Dashboard / metrics overview

仪表盘/指标概览

Card grid layout. Hero numbers large and prominent. Sparklines via inline SVG

<polyline>

. Progress bars via CSS

linear-gradient

. For real charts use Chart.js via CDN. KPI cards with trend indicators (up/down arrows, percentage deltas). Good for newsroom analytics, grant reporting dashboards, audience metrics.

卡片网格布局。英雄区数字大而醒目。通过内联SVG

<polyline>

实现迷你折线图。通过CSS

linear-gradient

实现进度条。如需真实图表，可通过CDN引入Chart.js。KPI卡片包含趋势指示器（上下箭头、百分比变化）。适用于新闻室分析、资助报告仪表盘、受众指标。

Source network

源网络

Map relationships between sources in an investigation or story. Can use Mermaid for connection-heavy maps or CSS Grid cards for detail-heavy source profiles. Include: source name, role, credibility indicators, what they provided, cross-references to other sources.

展示调查或报道中消息源之间的关系。连接密集的图谱可使用Mermaid，详情丰富的消息源档案可使用CSS Grid卡片。包含：消息源名称、角色、可信度指标、提供的内容、与其他消息源的交叉引用。

Investigation map

调查图谱

Connect entities (people, organizations, documents, events) with visual links. CSS Grid cards for entity profiles, Mermaid for relationship diagrams. Color-code by entity type. Show strength of connections. Good for investigative reporting, following the money, mapping power structures.

连接实体（人物、组织、文档、事件）。使用CSS Grid卡片展示实体档案，Mermaid展示关系图。按实体类型配色。展示连接强度。适用于调查报道、资金流向追踪、权力结构映射。

Editorial workflow

编辑工作流

Mermaid flowchart showing story lifecycle: pitch → assign → research → draft → edit → legal review → publish → distribute. Color-code stages. Show decision gates (kill/revise/approve). Include role labels on transitions.

使用Mermaid流程图展示故事生命周期：选题→分配→调研→撰写→编辑→法务审核→发布→分发。按阶段配色。展示决策节点（终止/修改/批准）。在转换路径上标注角色。

Story structure

故事结构

CSS Grid visualization of narrative arc. Show sections, word counts, source distribution, multimedia placement. Good for planning longform features or reviewing story architecture before publication.

使用CSS Grid可视化叙事弧线。展示章节、字数、消息源分布、多媒体位置。适用于策划长篇特稿或在发布前审查故事架构。

File structure

文件结构

Every diagram is a single self-contained

.html

file. No external assets except CDN links.

html

<!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>
  <!-- Semantic HTML: sections, headings, lists, tables, inline SVG -->
  <!-- Optional: <script> for Mermaid, Chart.js, or anime.js when used -->
</body>
</html>

每个图表都是独立的

.html

文件。除CDN链接外，无外部资源。