| name | arch-diagram-html |
| description | Generate dark-themed standalone HTML architecture diagrams with inline SVG, based on the Cocoon-style architecture diagram pattern, but adapted for Hermes. Use when the user wants a clean architecture diagram delivered as a single .html file that opens in any browser. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| tags | ["architecture-diagram","html","svg","system-design","visualization"] |
Architecture Diagram HTML Skill
产物：单文件 .html，内嵌 CSS 与 SVG，可直接浏览器打开。
适用：
- 系统架构图
- 云架构图
- 服务依赖图
- 安全边界图
- 技术组件关系图
不适用：
- 需在线协作编辑的手绘图 -> 用
excalidraw
- 需动画 -> 用
manim-video
核心规则
- 产物必须是单文件 HTML。
- 主图必须用 inline SVG，不依赖 JS。
- 默认深色主题：背景
#020617。
- 箭头先画，组件后画；避免 z-order 混乱。
- 组件若用半透明填充，先画一层不透明底色以遮住背后箭头。
- 图下方应有 3 张摘要卡片。
- 输出应可直接保存为
*.html 并在现代浏览器打开。
- 若用户未给精确布局，先按“左到右主流向、上到下辅助流”布图。
语义配色
| 类型 | Fill | Stroke |
|---|
| Frontend | rgba(8, 51, 68, 0.4) | #22d3ee |
| Backend | rgba(6, 78, 59, 0.4) | #34d399 |
| Database / Storage / AI | rgba(76, 29, 149, 0.4) | #a78bfa |
| Cloud / Infra | rgba(120, 53, 15, 0.3) | #fbbf24 |
| Security | rgba(136, 19, 55, 0.4) | #fb7185 |
| Message Bus | rgba(251, 146, 60, 0.3) | #fb923c |
| External / Generic | rgba(30, 41, 59, 0.5) | #94a3b8 |
字体
默认可用：
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
若用户要求完全离线：
- 去掉 Google Fonts
- 改
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
结构
标准 HTML 结构：
- Header
- Diagram container
- Main SVG
- 3 summary cards
- Footer
布局规则
- 主流向：左 -> 右
- 辅流向：上 -> 下
- 标准组件高度：60
- 大组件：80-120
- 垂直最小间距：40
- 图例必须位于所有边界框之外
- 若 legend 放不下，增大 SVG
viewBox 高度
SVG 必备片段
网格背景
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
箭头
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
</marker>
组件遮箭头模式
<rect x="X" y="Y" width="W" height="H" rx="6" fill="#0f172a"/>
<rect x="X" y="Y" width="W" height="H" rx="6" fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5"/>
输出流程
- 先从用户描述抽组件、边界、外部系统、数据流。
- 按语义分组：frontend / backend / storage / security / cloud / external。
- 再定主路径。
- 先布箭头，再布盒子与文字。
- 最后补三张 summary cards：
- Surface / Clients / Entry
- Services / Runtime / Processing
- Data / Infra / Security
- 输出完整 HTML 文件。
默认卡片内容策略
若用户未指定：
- Card 1: 接入层与客户端
- Card 2: 核心服务与运行时
- Card 3: 数据、基础设施与安全
风险与坑
- 不要把 legend 放进 region/security boundary 内。
- 不要让 message bus 压住上下组件。
- 不要只给 SVG 片段；默认给完整 HTML。
- 不要引入 JS 动画库；纯 CSS 即可。
- 若用户只给模糊描述，先做合理默认，不要卡住。
交付格式
默认直接产：
若用户要落盘：
- 用
write_file 保存 .html
- 再验证关键标题、组件名、文件存在
参考
references/template.html：Hermes 基础模板references/source-note.md：上游来源与吸收说明
