visual-explainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual Explainer

可视化解释器

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

Proactive table rendering. When you're about to present tabular data as an ASCII box-drawing table in the terminal (comparisons, audits, feature matrices, status reports, any structured rows/columns), generate an HTML page instead. The threshold: if the table has 4+ rows or 3+ columns, it belongs in the browser. Don't wait for the user to ask — render it as HTML automatically and tell them the file path. You can still include a brief text summary in the chat, but the table itself should be the HTML page.

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

主动表格渲染：当你准备在终端中以ASCII框线表格形式展示表格数据（对比内容、审计结果、功能矩阵、状态报告、任何结构化行/列内容）时，改为生成HTML页面。阈值规则：如果表格有4行及以上或3列及以上，就适合在浏览器中展示。不需要等用户提出要求——自动将其渲染为HTML并告知用户文件路径。你仍然可以在聊天中附上简短的文字总结，但表格本身应该放在HTML页面中。

Workflow

工作流

1. Think (5 seconds, not 5 minutes)

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

Before writing HTML, commit to a direction. Don't default to "dark theme with blue accents" every time.

Who is looking? A developer understanding a system? A PM seeing the big picture? A team reviewing a proposal? This shapes information density and visual complexity.

What type of diagram? Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, data table, timeline, or dashboard. Each has distinct layout needs and rendering approaches (see Diagram Types below).

What aesthetic? Pick one and commit:

Monochrome terminal (green/amber on black, monospace everything)
Editorial (serif headlines, generous whitespace, muted palette)
Blueprint (technical drawing feel, grid lines, precise)
Neon dashboard (saturated accents on deep dark, glowing edges)
Paper/ink (warm cream background, hand-drawn feel, sketchy borders)
Hand-drawn / sketch (Mermaid
```
handDrawn
```
mode, wiggly lines, informal whiteboard feel)
IDE-inspired (borrow a real color scheme: Dracula, Nord, Catppuccin, Solarized, Gruvbox, One Dark)
Data-dense (small type, tight spacing, maximum information)
Gradient mesh (bold gradients, glassmorphism, modern SaaS feel)

Vary the choice each time. If the last diagram was dark and technical, make the next one light and editorial. The swap test: if you replaced your styling with a generic dark theme and nobody would notice the difference, you haven't designed anything.

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

受众是谁？ 是理解系统的开发人员？是看全局的产品经理？还是评审方案的团队？这会决定信息密度和视觉复杂度。

图表类型是什么？ 架构图、流程图、时序图、数据流图、schema/ER图、状态机、思维导图、数据表、时间线、或者仪表盘。每种图表都有不同的布局需求和渲染方式（见下方图表类型说明）。

选用什么视觉风格？ 选择一种并坚持：

单色终端风（黑底绿/琥珀色，全用等宽字体）
编辑出版风（衬线标题，充足留白，低饱和度配色）
蓝图风（技术图纸质感，网格线，精准风格）
霓虹仪表盘风（深底色+高饱和点缀，发光边框）
纸墨风（暖奶油色背景，手绘质感，粗糙边框）
手绘/草图风（Mermaid
```
handDrawn
```
模式，波浪线，非正式白板质感）
IDE灵感风（借用真实配色方案：Dracula、Nord、Catppuccin、Solarized、Gruvbox、One Dark）
高密度数据风（小字号，紧凑间距，最大化信息承载）
渐变网格风（大胆渐变，玻璃态效果，现代SaaS质感）

每次选择不同的风格。如果上一个图表是深色技术风，下一个就用浅色编辑风。替换测试：如果你把样式换成通用深色主题，没人能看出区别，说明你没有做任何设计。

2. Structure

2. 结构搭建

Read the reference template before generating. Don't memorize it — read it each time to absorb the patterns.

For text-heavy architecture overviews (card content matters more than topology): read
```
./templates/architecture.html
```
For flowcharts, sequence diagrams, ER, state machines, mind maps: read
```
./templates/mermaid-flowchart.html
```
For data tables, comparisons, audits, feature matrices: read
```
./templates/data-table.html
```

For CSS/layout patterns and SVG connectors, read

./references/css-patterns.md

For pages with 4+ sections (reviews, recaps, dashboards), also read

./references/responsive-nav.md

for section navigation with sticky sidebar TOC on desktop and horizontal scrollable bar on mobile.

Choosing a rendering approach:

Diagram type	Approach	Why
Architecture (text-heavy)	CSS Grid cards + flow arrows	Rich card content (descriptions, code, tool lists) needs CSS control
Architecture (topology-focused)	Mermaid	Visible connections between components need automatic edge routing
Flowchart / pipeline	Mermaid	Automatic node positioning and edge routing; hand-drawn mode available
Sequence diagram	Mermaid	Lifelines, messages, and activation boxes need automatic layout
Data flow	Mermaid with edge labels	Connections and data descriptions need automatic edge routing
ER / schema diagram	Mermaid	Relationship lines between many entities need auto-routing
State machine	Mermaid	State transitions with labeled edges need automatic layout
Mind map	Mermaid	Hierarchical branching needs automatic positioning
Data table	HTML `<table>`	Semantic markup, accessibility, copy-paste behavior
Timeline	CSS (central line + cards)	Simple linear layout doesn't need a layout engine
Dashboard	CSS Grid + Chart.js	Card grid with embedded charts

Mermaid theming: Always use

theme: 'base'

with custom

themeVariables

so colors match your page palette. Use

look: 'handDrawn'

for sketch aesthetic or

look: 'classic'

for clean lines. Use

layout: 'elk'

for complex graphs (requires the

@mermaid-js/layout-elk

package — see

./references/libraries.md

for the CDN import). Override Mermaid's SVG classes with CSS for pixel-perfect control. See

./references/libraries.md

for full theming guide.

Mermaid zoom controls: Always add zoom controls (+/−/reset buttons) to every

.mermaid-wrap

container. Complex diagrams render at small sizes and need zoom to be readable. Include Ctrl/Cmd+scroll zoom on the container. See the zoom controls pattern in

./references/css-patterns.md

and the reference template at

./templates/mermaid-flowchart.html

AI-generated illustrations (optional). If surf-cli is available, you can generate images via Gemini and embed them in the page for creative, illustrative, explanatory, educational, or decorative purposes. Check availability with

which surf

. If available:

bash

undefined

生成前阅读参考模板，不要死记硬背——每次都阅读以吸收设计模式：

对于文字密集的架构概述（卡片内容比拓扑关系更重要）：阅读
```
./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 / schema 图	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

检查是否可用，如果可用：

bash

undefined

Generate to a temp file (use --aspect-ratio for control)

生成到临时文件（用 --aspect-ratio 控制比例）

surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9

surf gemini "描述性提示词" --generate-image /tmp/ve-img.png --aspect-ratio 16:9

Base64 encode for self-containment (macOS)

Base64编码实现自包含（macOS）

IMG=$(base64 -i /tmp/ve-img.png)

Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)

Embed in HTML and clean up

嵌入HTML并清理临时文件

<img src="data:image/png;base64,${IMG}" alt="descriptive alt text">

<img src="data:image/png;base64,${IMG}" alt="描述性替代文本">

rm /tmp/ve-img.png


See `./references/css-patterns.md` for image container styles (hero banners, inline illustrations, captions).

**When to use:** Hero banners that establish the page's visual tone. Conceptual illustrations for abstract systems that Mermaid can't express (physical infrastructure, user journeys, mental models). Educational diagrams that benefit from artistic or photorealistic rendering. Decorative accents that reinforce the aesthetic.

**When to skip:** Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — if surf isn't available, skip images without erroring. The page should stand on its own with CSS and typography alone.

**Prompt craft:** Match the image to the page's palette and aesthetic direction. Specify the style (3D render, technical illustration, watercolor, isometric, flat vector, etc.) and mention dominant colors from your CSS variables. Use `--aspect-ratio 16:9` for hero banners, `--aspect-ratio 1:1` for inline illustrations. Keep prompts specific — "isometric illustration of a message queue with cyan nodes on dark navy background" beats "a diagram of a queue."

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. Style

3. 样式设计

Apply these principles to every diagram:

Typography is the diagram. Pick a distinctive font pairing from Google Fonts. A display/heading font with character, plus a mono font for technical labels. Never use Inter, Roboto, Arial, or system-ui as the primary font. Load via

<link>

<head>

. Include a system font fallback in the

font-family

stack for offline resilience.

Color tells a story. Use CSS custom properties for the full palette. Define at minimum:

--bg

--surface

--border

--text

--text-dim

, and 3-5 accent colors. Each accent should have a full and a dim variant (for backgrounds). Name variables semantically when possible (

--pipeline-step

not

--blue-3

). Support both themes. Put your primary aesthetic in

:root

and the alternate in the media query:

css

/* 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 */ } }

Surfaces whisper, they don't shout. Build depth through subtle lightness shifts (2-4% between levels), not dramatic color changes. Borders should be low-opacity rgba (

rgba(255,255,255,0.08)

in dark mode,

rgba(0,0,0,0.08)

in light) — visible when you look, invisible when you don't.

Backgrounds create atmosphere. Don't use flat solid colors for the page background. Subtle gradients, faint grid patterns via CSS, or gentle radial glows behind focal areas. The background should feel like a space, not a void.

Visual weight signals importance. Not every section deserves equal visual treatment. Executive summaries and key metrics should dominate the viewport on load (larger type, more padding, subtle accent-tinted background zone). Reference sections (file maps, dependency lists, decision logs) should be compact and stay out of the way. Use

<details>/<summary>

for sections that are useful but not primary — the collapsible pattern is in

./references/css-patterns.md

Surface depth creates hierarchy. Vary card depth to signal what matters. Hero sections get elevated shadows and accent-tinted backgrounds (

node--hero

pattern). Body content stays flat (default

.node

). Code blocks and secondary content feel recessed (

node--recessed

). See the depth tiers in

./references/css-patterns.md

. Don't make everything elevated — when everything pops, nothing does.

Animation earns its place. Staggered fade-ins on page load are almost always worth it — they guide the eye through the diagram's hierarchy. Mix animation types by role:

fadeUp

for cards,

fadeScale

for KPIs and badges,

drawIn

for SVG connectors,

countUp

for hero numbers. Hover transitions on interactive-feeling elements make the diagram feel alive. Always respect

prefers-reduced-motion

. CSS transitions and keyframes handle most cases. For orchestrated multi-element sequences, anime.js via CDN is available (see

./references/libraries.md

每个图表都要遵循这些原则：

排版就是图表本身：从Google Fonts选择有辨识度的字体组合，有特色的展示/标题字体，搭配技术标签用的等宽字体。不要用Inter、Roboto、Arial、system-ui作为主字体。通过

<head>

里的

<link>

加载字体，

font-family

栈里要包含系统字体 fallback 保证离线可用。

颜色传递信息：整个调色板用CSS自定义变量定义，至少要定义：

--bg

、

--surface

、

--border

、

--text

、

--text-dim

，以及3-5个强调色。每个强调色都要有全色和低饱和变体（用于背景）。变量名尽量语义化（用

--pipeline-step

不要用

--blue-3

）。支持双主题，主风格放在

:root

，替代风格放在媒体查询里：

css

/* 浅色优先（编辑风、纸墨风、蓝图风）： */
:root { /* 浅色变量值 */ }
@media (prefers-color-scheme: dark) { :root { /* 深色变量值 */ } }

/* 深色优先（霓虹风、IDE灵感风、终端风）： */
: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>

折叠，折叠模式见

./references/css-patterns.md

。

表面深度创建层级：调整卡片深度标识重要程度。首屏模块用提升的阴影和带强调色的背景（

node--hero

模式）。正文内容保持扁平（默认

.node

）。代码块和次要内容用凹陷效果（

node--recessed

）。深度层级见

./references/css-patterns.md

。不要把所有内容都做提升效果——如果所有内容都突出，就等于没有突出的内容。

动画要有用：页面加载时的 staggered 淡入效果几乎总是值得的——它们可以引导视线顺着图表层级走。按角色混合动画类型：卡片用

fadeUp

，KPI和徽章用

fadeScale

，SVG连接线用

drawIn

，首屏数字用

countUp

。有交互感的元素加hover过渡让图表更有生命力。始终尊重

prefers-reduced-motion

设置。大多数场景用CSS过渡和关键帧就可以实现。多元素编排动画可以用CDN引入的anime.js（见

./references/libraries.md

）。

4. Deliver

4. 交付

Output location: Write to

~/.agent/diagrams/

. Use a descriptive filename based on content:

modem-architecture.html

pipeline-flow.html

schema-overview.html

. The directory persists across sessions.

Open in browser:

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

Linux:

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

Tell the user the file path so they can re-open or share it.

输出位置： 写入

~/.agent/diagrams/

。根据内容使用描述性文件名：

modem-architecture.html

、

pipeline-flow.html

、

schema-overview.html

。该目录跨会话持久化。

在浏览器中打开：

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

Linux:

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

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

Diagram Types

图表类型

Architecture / System Diagrams

架构/系统图

Two approaches depending on what matters more:

Text-heavy overviews (card content matters more than connections): CSS Grid with explicit row/column placement. Sections as rounded cards with colored borders and monospace labels. Vertical flow arrows between sections. Nested grids for subsystems. The reference template at

./templates/architecture.html

demonstrates this pattern. Use when cards need descriptions, code references, tool lists, or other rich content that Mermaid nodes can't hold.

Topology-focused diagrams (connections matter more than card content): Use Mermaid. A

graph TD

graph LR

with custom

themeVariables

produces proper diagrams with automatic edge routing. Use

look: 'handDrawn'

for informal feel or

look: 'classic'

for clean lines. Use when the point is showing how components connect rather than describing what each component does in detail.

根据侧重内容有两种实现方式：

文字密集型概述（卡片内容比连接关系更重要）：用CSS Grid显式指定行/列位置，模块用带彩色边框和等宽标签的圆角卡片，模块间加垂直流动箭头，子系统用嵌套网格。参考模板

./templates/architecture.html

演示了这个模式。当卡片需要承载描述、代码引用、工具列表或其他Mermaid节点无法容纳的丰富内容时使用。

侧重拓扑的图表（连接关系比卡片内容更重要）：使用Mermaid。

graph TD

或

graph LR

搭配自定义

themeVariables

可以生成带自动边缘路由的标准图表。非正式风格用

look: 'handDrawn'

，简洁线条用

look: 'classic'

。当核心是展示组件如何连接，而不是详细描述每个组件的功能时使用。

Flowcharts / Pipelines

流程图/流水线

Use Mermaid. Automatic node positioning and edge routing produces proper diagrams with connecting lines, decision diamonds, and parallel branches — dramatically better than CSS flexbox with arrow characters. Use

graph TD

for top-down or

graph LR

for left-right. Use

look: 'handDrawn'

for sketch aesthetic. Color-code node types with Mermaid's

classDef

or rely on

themeVariables

for automatic styling.

使用Mermaid。自动节点定位和边缘路由可以生成带连接线、决策菱形、并行分支的标准图表——比CSS flexbox加箭头字符效果好得多。自上而下用

graph TD

，从左到右用

graph LR

。草图风格用

look: 'handDrawn'

。用Mermaid的

classDef

给节点类型配色，或者靠

themeVariables

实现自动样式。

Sequence Diagrams

时序图

Use Mermaid. Lifelines, messages, activation boxes, notes, and loops all need automatic layout. Use Mermaid's

sequenceDiagram

syntax. Style actors and messages via CSS overrides on

.actor

.messageText

.activation

classes.

使用Mermaid。生命线、消息、激活框、注释、循环都需要自动布局。用Mermaid的

sequenceDiagram

语法，通过CSS覆盖

.actor

、

.messageText

、

.activation

类来设置参与者和消息的样式。

Data Flow Diagrams

数据流图

Use Mermaid. Data flow diagrams emphasize connections over boxes — exactly what Mermaid excels at. Use

graph LR

graph TD

with edge labels for data descriptions. Thicker, colored edges for primary flows. Source/sink nodes styled differently from transform nodes via Mermaid's

classDef

使用Mermaid。数据流图强调连接而非框体——这正是Mermaid擅长的。用

graph LR

或

graph TD

，边标签放数据描述。主流程用更粗的彩色边，源/汇节点和转换节点用Mermaid的

classDef

区分样式。

Schema / ER Diagrams

Schema/ER图

Use Mermaid. Relationship lines between entities need automatic routing. Use Mermaid's

erDiagram

syntax with entity attributes. Style via

themeVariables

and CSS overrides on

.er.entityBox

and

.er.relationshipLine

使用Mermaid。实体间的关系线需要自动路由。用Mermaid的

erDiagram

语法搭配实体属性，通过

themeVariables

和CSS覆盖

.er.entityBox

、

.er.relationshipLine

类设置样式。

State Machines / Decision Trees

状态机/决策树

Use Mermaid. Use

stateDiagram-v2

for states with labeled transitions. Supports nested states, forks, joins, and notes. Use

look: 'handDrawn'

for informal state diagrams. Decision trees can use

graph TD

with diamond decision nodes.

stateDiagram-v2
label caveat: Transition labels have a strict parser — colons, parentheses,

<br/>

, HTML entities, and most special characters cause silent parse failures ("Syntax error in text"). If your labels need any of these (e.g.,

cancel()

curate: true

, multi-line labels), use

flowchart LR

instead with rounded nodes and quoted edge labels (

|"label text"|

). Flowcharts handle all special characters and support

<br/>

for line breaks. Reserve

stateDiagram-v2

for simple single-word or plain-text labels.

使用Mermaid。状态带标签转换用

stateDiagram-v2

，支持嵌套状态、分支、合并、注释。非正式状态图用

look: 'handDrawn'

。决策树可以用

graph TD

搭配菱形决策节点。

stateDiagram-v2
标签注意事项：转换标签的解析规则很严格——冒号、括号、

<br/>

、HTML实体和大多数特殊字符会导致静默解析失败（「文本语法错误」）。如果你的标签需要这些字符（比如

cancel()

、

curate: true

、多行标签），改用

flowchart LR

，用圆角节点和带引号的边标签（

|"label text"|

）。流程图支持所有特殊字符，也支持

<br/>

换行。仅当标签是简单的单个单词或纯文本时使用

stateDiagram-v2

。

Mind Maps / Hierarchical Breakdowns

思维导图/层级拆解

Use Mermaid. Use

mindmap

syntax for hierarchical branching from a root node. Mermaid handles the radial layout automatically. Style with

themeVariables

to control node colors at each depth level.

使用Mermaid。用

mindmap

语法实现从根节点出发的层级分支，Mermaid会自动处理放射状布局。用

themeVariables

设置样式，控制每个深度层级的节点颜色。

Data Tables / Comparisons / Audits

数据表/对比表/审计表

Use a real

<table>

element — not CSS Grid pretending to be a table. Tables get accessibility, copy-paste behavior, and column alignment for free. The reference template at

./templates/data-table.html

demonstrates all patterns below.

Use proactively. Any time you'd render an ASCII box-drawing table in the terminal, generate an HTML table instead. This includes: requirement audits (request vs plan), feature comparisons, status reports, configuration matrices, test result summaries, dependency lists, permission tables, API endpoint inventories — any structured rows and columns.

Layout patterns:

Sticky
```
<thead>
```
so headers stay visible when scrolling long tables
Alternating row backgrounds via
```
tr:nth-child(even)
```
(subtle, 2-3% lightness shift)
First column optionally sticky for wide tables with horizontal scroll
Responsive wrapper with
```
overflow-x: auto
```
for tables wider than the viewport
Column width hints via
```
<colgroup>
```
or
```
th
```
widths — let text-heavy columns breathe
Row hover highlight for scanability

Status indicators (use styled

<span>

elements, 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 — don't truncate or force single-line
Use
```
<code>
```
for technical references within cells
Secondary detail text in
```
<small>
```
with dimmed color
Keep numeric columns right-aligned with
```
tabular-nums
```

用原生

<table>

元素——不要用CSS Grid模拟表格。表格原生支持无障碍特性、复制粘贴行为、列对齐。参考模板

./templates/data-table.html

演示了以下所有模式。

主动使用：任何你想在终端渲染ASCII框线表格的场景，都改为生成HTML表格，包括：需求审计（请求 vs 计划）、功能对比、状态报告、配置矩阵、测试结果汇总、依赖列表、权限表、API端点清单——任何结构化的行列内容。

布局模式：

粘性
```
<thead>
```
，滚动长表格时表头保持可见
通过
```
tr:nth-child(even)
```
实现交替行背景（细微的2-3%亮度差异）
宽表格支持横向滚动时，第一列可选粘性固定
响应式包裹层加
```
overflow-x: auto
```
，适配比视口宽的表格
通过
```
<colgroup>
```
或
```
th
```
宽度给出列宽提示，给文字多的列留出足够空间
行悬停高亮提升可读性

状态指示器（用带样式的

<span>

元素，不要用emoji）：

匹配/通过/是：绿色背景的彩色圆点或对勾
差距/不通过/否：红色背景的彩色圆点或叉号
部分完成/警告：琥珀色指示器
中性/信息：低亮文字或 muted 徽章

单元格内容：

长文本自然换行——不要截断或强制单行
单元格内的技术引用用
```
<code>
```
次要说明文字用
```
<small>
```
搭配低亮颜色
数字列右对齐，用
```
tabular-nums
```
保证数字对齐

Timeline / Roadmap Views

时间线/路线图视图

Vertical or horizontal timeline with a central line (CSS pseudo-element). Phase markers as circles on the line. Content cards branching left/right (alternating) or all to one side. Date labels on the line. Color progression from past (muted) to future (vivid).

垂直或水平时间线，带中心线（CSS伪元素实现），阶段标记为线上的圆点，内容卡片左右交替排列或者全部排在一侧，线上标注日期。颜色从过去（低饱和）到未来（高饱和）渐变。

Dashboard / Metrics Overview

仪表盘/指标概览

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

<polyline>

. Progress bars via CSS

linear-gradient

on a div. For real charts (bar, line, pie), use Chart.js via CDN (see

./references/libraries.md

). KPI cards with trend indicators (up/down arrows, percentage deltas).

卡片网格布局，核心数字大而突出。用行内SVG

<polyline>

实现迷你走势图，用div上的CSS

linear-gradient

实现进度条。真实图表（柱状图、折线图、饼图）用CDN引入的Chart.js实现（见

./references/libraries.md

）。KPI卡片带趋势指示器（上升/下降箭头、百分比变化）。

File Structure

文件结构

Every diagram is a single self-contained

.html

file. No external assets except CDN links (fonts, optional libraries). Structure:

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 -->
  <!-- No script needed for static CSS-only diagrams -->
  <!-- Optional: <script> for Mermaid, Chart.js, or anime.js when used -->
</body>
</html>

每个图表都是单个独立的

.html

文件，除了CDN链接（字体、可选库）外没有外部资源。结构：

html

<!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：sections、headings、lists、tables、inline SVG -->
  <!-- 纯CSS静态图表不需要script -->
  <!-- 可选：用到Mermaid、Chart.js或anime.js时引入<script> -->
</body>
</html>

Quality Checks

质量检查

Before delivering, verify:

The squint test: Blur your eyes. Can you still perceive hierarchy? Are sections visually distinct?
The swap test: Would replacing your fonts and colors with a generic dark theme make this indistinguishable from a template? If yes, push the aesthetic further.
Both themes: Toggle your OS between light and dark mode. Both should look intentional, not broken.
Information completeness: Does the diagram actually convey what the user asked for? Pretty but incomplete is a failure.
No overflow: Resize the browser to different widths. No content should clip or escape its container. Every grid and flex child needs
```
min-width: 0
```
. Side-by-side panels need
```
overflow-wrap: break-word
```
. Never use
```
display: flex
```
on
```
<li>
```
for marker characters — it creates anonymous flex items that can't shrink, causing lines with many inline
```
<code>
```
badges to overflow. Use absolute positioning for markers instead. See the Overflow Protection section in
```
./references/css-patterns.md
```
.
Mermaid zoom controls: Every
```
.mermaid-wrap
```
container must have zoom controls (+/−/reset buttons), Ctrl/Cmd+scroll zoom, and click-and-drag panning. Complex diagrams render too small without them. The cursor should change to
```
grab
```
when zoomed in and
```
grabbing
```
while dragging. See
```
./references/css-patterns.md
```
for the full pattern.
File opens cleanly: No console errors, no broken font loads, no layout shifts.

交付前验证：

眯眼测试：眯起眼睛，你还能感知层级吗？模块之间视觉上有区分吗？
替换测试：把你的字体和颜色换成通用深色主题，会不会和模板没区别？如果是，要进一步强化视觉风格。
双主题测试：切换操作系统的深浅色模式，两种模式都应该是有意设计的，不是崩坏的。
信息完整性：图表真的传递了用户需要的内容吗？好看但不完整是失败的。
无溢出：把浏览器调整到不同宽度，没有内容被裁剪或溢出容器。每个Grid和Flex子元素都要设置
```
min-width: 0
```
。并列面板要加
```
overflow-wrap: break-word
```
。不要在
```
<li>
```
上用
```
display: flex
```
做标记符——会生成无法压缩的匿名Flex项，导致带很多行内
```
<code>
```
标签的行溢出。改用绝对定位实现标记符。溢出保护部分见
```
./references/css-patterns.md
```
。
Mermaid缩放控制：每个
```
.mermaid-wrap
```
容器必须有缩放控制（+/−/重置按钮）、Ctrl/Cmd+滚轮缩放、点击拖拽平移功能。复杂图表没有这些功能会渲染得太小无法阅读。缩放时光标要变成
```
grab
```
，拖拽时变成
```
grabbing
```
。完整模式见
```
./references/css-patterns.md
```
。
文件正常打开：没有控制台错误、没有字体加载失败、没有布局偏移。