visual-explainer by alexandergirardet/visual-explainer
npx skills add https://github.com/alexandergirardet/visual-explainer --skill visual-explainer生成用于技术图表、可视化和数据表格的自包含 HTML 文件。加载此技能后,始终在浏览器中打开结果。切勿回退到 ASCII 艺术。
主动表格渲染。 当您即将在终端中以 ASCII 框线表格形式呈现表格数据时(比较、审计、功能矩阵、状态报告、任何结构化的行/列),请改为生成一个 HTML 页面。阈值:如果表格有 4 行以上或 3 列以上,则应放在浏览器中查看。无需等待用户要求——自动将其渲染为 HTML 并告知他们文件路径。您仍然可以在聊天中包含简短的文本摘要,但表格本身应该是 HTML 页面。
在编写 HTML 之前,确定一个方向。不要每次都默认使用“深色主题搭配蓝色点缀”。
谁在看? 是理解系统的开发人员?是看大局的产品经理?是评审提案的团队?这决定了信息密度和视觉复杂度。
什么类型的图表? 架构图、流程图、序列图、数据流图、模式/ER 图、状态机、思维导图、数据表格、时间线或仪表板。每种都有不同的布局需求和渲染方法(见下文“图表类型”)。
什么美学风格? 选择一种并坚持:
handDrawn 模式,波浪线,非正式白板感)每次都要改变选择。如果上一个图表是深色和技术性的,就让下一个变成浅色和编辑风格的。交换测试:如果你用通用的深色主题替换了你的样式,而没有人会注意到区别,那说明你还没有设计出任何东西。
在生成前阅读参考模板。 不要死记硬背——每次都要阅读以吸收其中的模式。
./templates/architecture.html广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
./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 包——参见 ./references/libraries.md 了解 CDN 导入)。通过 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 检查可用性。如果可用:
# 生成到临时文件(使用 --aspect-ratio 控制)
surf gemini "描述性提示词" --generate-image /tmp/ve-img.png --aspect-ratio 16:9
# 为自包含性进行 Base64 编码 (macOS)
IMG=$(base64 -i /tmp/ve-img.png)
# Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)
# 嵌入 HTML 并清理
# <img src="data:image/png;base64,${IMG}" alt="描述性替代文本">
rm /tmp/ve-img.png
图像容器样式(横幅、内联插图、标题)请参见 ./references/css-patterns.md。
何时使用: 用于确立页面视觉基调的横幅。用于 Mermaid 无法表达的抽象系统的概念性插图(物理基础设施、用户旅程、心智模型)。受益于艺术或逼真渲染的教育性图表。用于强化美学风格的装饰性点缀。
何时跳过: 任何 Mermaid 或 CSS 能很好处理的内容。不传达意义的通用装饰。图像会分散注意力的数据密集型页面。始终优雅降级——如果 surf 不可用,跳过图像而不报错。页面应仅凭 CSS 和排版就能独立存在。
提示词技巧: 使图像与页面的调色板和美学方向相匹配。指定样式(3D 渲染、技术插图、水彩、等距、扁平矢量等),并提及 CSS 变量中的主色调。横幅使用 --aspect-ratio 16:9,内联插图使用 --aspect-ratio 1:1。保持提示词具体——“深海军蓝背景上带有青色节点的消息队列等距插图”比“队列的图表”更好。
将以下原则应用于每个图表:
排版就是图表。 从 Google Fonts 中选择一个独特的字体组合。一个有特色的展示/标题字体,加上一个用于技术标签的等宽字体。切勿使用 Inter、Roboto、Arial 或 system-ui 作为主要字体。通过 <head> 中的 <link> 加载。在 font-family 堆栈中包含系统字体回退,以提高离线恢复能力。
颜色讲述故事。 使用 CSS 自定义属性定义完整的调色板。至少定义:--bg、--surface、--border、--text、--text-dim 以及 3-5 个强调色。每个强调色都应有一个完整变体和一个暗淡变体(用于背景)。尽可能语义化地命名变量(--pipeline-step 而非 --blue-3)。支持两种主题。将您的主要美学风格放在 :root 中,备用方案放在媒体查询中:
/* 浅色优先(编辑风格、纸张/墨水、蓝图): */
: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。不要把所有东西都提升——当所有东西都突出时,就没有东西突出了。
动画有其用武之地。 页面加载时的交错淡入几乎总是值得的——它们引导视线浏览图表的层次结构。按角色混合动画类型:卡片用 fadeUp,KPI 和徽章用 fadeScale,SVG 连接器用 drawIn,关键数字用 countUp。交互感元素上的悬停过渡使图表感觉生动。始终尊重 prefers-reduced-motion。CSS 过渡和关键帧处理大多数情况。对于编排的多元素序列,可通过 CDN 使用 anime.js(参见 ./references/libraries.md)。
输出位置: 写入 ~/.agent/diagrams/。根据内容使用描述性文件名:modem-architecture.html、pipeline-flow.html、schema-overview.html。该目录在会话间持久存在。
在浏览器中打开:
open ~/.agent/diagrams/filename.htmlxdg-open ~/.agent/diagrams/filename.html告知用户 文件路径,以便他们可以重新打开或分享。
根据更重要的方面,有两种方法:
文本密集型概述(卡片内容比连接更重要):使用 CSS Grid 并明确指定行/列位置。各部分作为带彩色边框和等宽标签的圆角卡片。各部分之间的垂直流向箭头。子系统的嵌套网格。./templates/architecture.html 处的参考模板演示了此模式。当卡片需要描述、代码引用、工具列表或其他 Mermaid 节点无法容纳的丰富内容时使用。
关注拓扑的图表(连接比卡片内容更重要):使用 Mermaid。 带有自定义 themeVariables 的 graph TD 或 graph LR 可生成具有自动边路由的适当图表。使用 look: 'handDrawn' 获得非正式感,或使用 look: 'classic' 获得简洁线条。当重点是显示组件如何连接,而不是详细描述每个组件的功能时使用。
使用 Mermaid。 自动节点定位和边路由可生成带有连接线、决策菱形和平行分支的适当图表——远优于使用箭头字符的 CSS flexbox。自上而下使用 graph TD,从左到右使用 graph LR。使用 look: 'handDrawn' 获得草图美学风格。使用 Mermaid 的 classDef 对节点类型进行颜色编码,或依赖 themeVariables 进行自动样式设置。
使用 Mermaid。 生命线、消息、激活框、注释和循环都需要自动布局。使用 Mermaid 的 sequenceDiagram 语法。通过 CSS 覆盖 .actor、.messageText、.activation 类来设置参与者和消息的样式。
使用 Mermaid。 数据流图强调连接而非方框——这正是 Mermaid 擅长的。使用带边标签的 graph LR 或 graph TD 进行数据描述。主要流程使用更粗、彩色的边。通过 Mermaid 的 classDef 将源/汇节点与转换节点设置不同的样式。
使用 Mermaid。 实体之间的关系线需要自动路由。使用 Mermaid 的 erDiagram 语法和实体属性。通过 themeVariables 和 CSS 覆盖 .er.entityBox 和 .er.relationshipLine 来设置样式。
使用 Mermaid。 使用 stateDiagram-v2 处理带标签转换的状态。支持嵌套状态、分叉、合并和注释。使用 look: 'handDrawn' 获得非正式状态图。决策树可以使用带菱形决策节点的 graph TD。
stateDiagram-v2 标签注意事项: 转换标签有严格的解析器——冒号、括号、<br/>、HTML 实体和大多数特殊字符会导致静默解析失败(“文本中的语法错误”)。如果您的标签需要任何这些字符(例如 cancel()、curate: true、多行标签),请改用 flowchart LR,并使用圆角节点和带引号的边标签(|"标签文本"|)。流程图处理所有特殊字符,并支持 <br/> 换行。为简单的单字或纯文本标签保留 stateDiagram-v2。
使用 Mermaid。 使用 mindmap 语法处理从根节点开始的分层分支。Mermaid 自动处理径向布局。使用 themeVariables 设置样式,以控制每个深度级别的节点颜色。
使用真正的 <table> 元素——而不是假装成表格的 CSS Grid。表格天生具有可访问性、复制粘贴行为和列对齐功能。./templates/data-table.html 处的参考模板演示了以下所有模式。
主动使用。 任何时候您要在终端中渲染 ASCII 框线表格时,请改为生成 HTML 表格。这包括:需求审计(请求 vs 计划)、功能比较、状态报告、配置矩阵、测试结果摘要、依赖列表、权限表、API 端点清单——任何结构化的行和列。
布局模式:
<thead>,以便在滚动长表格时标题保持可见tr:nth-child(even) 交替行背景(微妙,2-3% 的亮度变化)overflow-x: auto,用于处理超出视口宽度的表格<colgroup> 或 th 宽度提供列宽提示——让文本密集的列有呼吸空间状态指示器(使用样式化的 <span> 元素,切勿使用表情符号):
单元格内容:
<code> 表示技术引用<small> 并调暗颜色tabular-nums带有中心线(CSS 伪元素)的垂直或水平时间线。阶段标记作为线上的圆圈。内容卡片向左/右分支(交替)或全部在一侧。线上的日期标签。颜色从过去(柔和)到未来(鲜艳)渐变。
卡片网格布局。关键数字大而突出。通过内联 SVG <polyline> 实现迷你图。通过 CSS linear-gradient 在 div 上实现进度条。对于真实图表(条形图、折线图、饼图),使用 通过 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>描述性标题</title>
<link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
<style>
/* CSS 自定义属性、主题、布局、组件——全部内联 */
</style>
</head>
<body>
<!-- 语义化 HTML:部分、标题、列表、表格、内联 SVG -->
<!-- 静态纯 CSS 图表无需脚本 -->
<!-- 可选:使用 Mermaid、Chart.js 或 anime.js 时的 <script> -->
</body>
</html>
交付前,验证:
min-width: 0。并排面板需要 overflow-wrap: break-word。切勿在 <li> 上使用 display: flex 来处理标记字符——这会创建无法收缩的匿名 flex 项,导致包含许多内联 <code> 徽章的行溢出。改为对标记使用绝对定位。溢出保护部分请参见 ./references/css-patterns.md。.mermaid-wrap 容器必须具有缩放控件(+/-/重置按钮)、Ctrl/Cmd+滚动缩放以及点击拖动平移。没有这些,复杂图表会渲染得太小。缩放时,光标应变为 grab,拖动时变为 grabbing。完整模式请参见 ./references/css-patterns.md。每周安装数
1
仓库
GitHub 星标数
2
首次出现
1 天前
安全审计
安装于
amp1
cline1
opencode1
cursor1
kimi-cli1
codex1
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.
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:
handDrawn mode, wiggly lines, informal whiteboard 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.
Read the reference template before generating. Don't memorize it — read it each time to absorb the patterns.
./templates/architecture.html./templates/mermaid-flowchart.html./templates/data-table.htmlFor 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 |
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:
# 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
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."
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> in <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:
/* 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).
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:
open ~/.agent/diagrams/filename.htmlxdg-open ~/.agent/diagrams/filename.htmlTell the user the file path so they can re-open or share it.
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 or 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.
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.
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.
Use Mermaid. Data flow diagrams emphasize connections over boxes — exactly what Mermaid excels at. Use graph LR or 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.
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.
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.
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.
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:
<thead> so headers stay visible when scrolling long tablestr:nth-child(even) (subtle, 2-3% lightness shift)overflow-x: auto for tables wider than the viewport<colgroup> or th widths — let text-heavy columns breatheStatus indicators (use styled <span> elements, never emoji):
Cell content:
<code> for technical references within cells<small> with dimmed colortabular-numsVertical 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).
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).
Every diagram is a single self-contained .html file. No external assets except CDN links (fonts, optional libraries). Structure:
<!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>
Before delivering, verify:
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.Weekly Installs
1
Repository
GitHub Stars
2
First Seen
1 day ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
amp1
cline1
opencode1
cursor1
kimi-cli1
codex1
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
31,600 周安装
| 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-wrapgrabgrabbing./references/css-patterns.md