architecture-diagram

Name: architecture-diagram
Author: cocoon-ai

github.com/cocoon-ai设计与 UI7.5k2.1k 次安装24 周前更新

代码仓库

关于 architecture-diagram

architecture-diagram 是用于制作自包含 HTML 架构图的技能，面向需要统一视觉规范和导出选项的技术文档作者。它定义了 SVG 布局、组件样式、间距与边界规则，并包含 PNG 和 PDF 导出工具栏。

主要功能

01生成自包含 HTML 文件
02内嵌 SVG 与 CSS
03按组件类型设定配色
04提供布局与间距规范
05支持复制、PNG 和 PDF 导出

适用场景

01记录服务与基础设施架构
02按统一组件样式绘制图表
03将图表导出为 PNG 或 PDF

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cocoon-ai/architecture-diagram-generator --skill architecture-diagram

安装后在 Claude Code 中输入/architecture-diagram确认已加载。

附带文件resources/template.html

详细介绍

架构图技能

创建专业的技术架构图，输出为包含内嵌 SVG 图形和 CSS 样式的独立 HTML 文件。

Version 1.1 · MIT License · 作者：Cocoon AI

设计系统

配色方案

为不同类型的组件使用以下语义颜色：

组件类型	填充色（rgba）	描边色
前端	`rgba(8, 51, 68, 0.4)`	`#22d3ee` (cyan-400)
后端	`rgba(6, 78, 59, 0.4)`	`#34d399` (emerald-400)
数据库	`rgba(76, 29, 149, 0.4)`	`#a78bfa` (violet-400)
AWS/Cloud	`rgba(120, 53, 15, 0.3)`	`#fbbf24` (amber-400)
安全	`rgba(136, 19, 55, 0.4)`	`#fb7185` (rose-400)
消息总线	`rgba(251, 146, 60, 0.3)`	`#fb923c` (orange-400)
外部/通用	`rgba(30, 41, 59, 0.5)`	`#94a3b8` (slate-400)

排版

所有文本均使用 JetBrains Mono（等宽字体，营造技术感）：

<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">

字号：组件名称为 12px，副标签为 9px，注释为 8px，微型标签为 7px。

视觉元素

背景： #020617 (slate-950)，搭配微妙的网格图案：

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

组件框： 圆角矩形（rx="6"），描边宽度为 1.5px，填充色为半透明。

安全组： 使用虚线描边（stroke-dasharray="4,4"）、透明填充和玫瑰色。

区域边界： 使用更大的虚线描边（stroke-dasharray="8,4"）、琥珀色和 rx="12"。

箭头： 使用 SVG marker 绘制箭头：

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

箭头的 z 顺序： 在 SVG 中尽早绘制连接箭头（背景网格之后），使其显示在组件框后方。SVG 元素按文档顺序绘制，因此先绘制的箭头会显示在后绘制的形状后方。

遮挡半透明填充后方的箭头： 由于组件框使用半透明填充（rgba(..., 0.4)），其后方的箭头会透出。若要完全遮挡箭头，应先在相同位置绘制不透明背景矩形（例如 fill="#0f172a"），再在其上方绘制半透明样式矩形：


<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(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>

身份验证/安全流程： 使用玫瑰色（#fb7185）虚线。

消息总线 / 事件总线： 在服务之间放置小型连接元素。使用橙色（#fb923c 描边，rgba(251, 146, 60, 0.3) 填充）：

<rect x="X" y="Y" width="120" height="20" rx="4" fill="rgba(251, 146, 60, 0.3)" stroke="#fb923c" stroke-width="1"/>
<text x="CENTER_X" y="Y+14" fill="#fb923c" font-size="7" text-anchor="middle">Kafka / RabbitMQ</text>

间距规则

重要： 垂直堆叠组件时，应确保间距适当，避免重叠：

标准组件高度： 服务为 60px，较大型组件为 80-120px
组件之间的最小垂直间距： 40px
内嵌连接器（消息总线）： 放置在组件之间的间隙中，不要与组件重叠

垂直布局示例：

Component A: y=70,  height=60  → ends at y=130
Gap:         y=130 to y=170   → 40px gap, place bus at y=140 (20px tall)
Component B: y=170, height=60  → ends at y=230

错误： 将消息总线放置在 y=160 处，而组件 B 从 y=170 开始（会导致重叠） 正确： 将消息总线放置在 y=140 处，居中于 40px 的间隙中（y=130 至 y=170）

图例位置

重要： 将图例放在所有边界框（区域边界、集群边界、安全组）之外。

计算所有边界的结束位置（y 坐标 + 高度）
将图例放在最低边界下方至少 20px 处
如有需要，扩展 SVG viewBox 的高度以容纳图例

示例：

Kubernetes Cluster: y=30, height=460 → ends at y=490
Legend should start at: y=510 or below
SVG viewBox height: at least 560 to fit legend

错误： 将图例放在 y=470 处，而集群边界在 y=490 处结束 正确： 将图例放在 y=510 处，位于集群边界下方，并扩展 viewBox 高度

布局结构

页眉 - 标题、带脉冲效果的圆点指示器、副标题和导出工具栏
主 SVG 图表 - 放在圆角边框卡片中
摘要卡片 - 图表下方排列 3 张卡片，展示关键详情
页脚 - 简短的元数据行

导出工具栏（内置）

每张图表的页眉中都带有一个低调的 ⋯ 切换按钮。点击后会显示三个按钮——📋 复制（高 DPI PNG 到剪贴板，缩放：2）、🖼️ PNG（下载高 DPI PNG）和 📄 PDF（通过 jsPDF 将 PNG 嵌入单页 PDF）。工具栏默认折叠回图标，以免遮挡图表。三种格式都使用相同的 html2canvas 截取方式（排除工具栏，并在内容周围留出 32px 的边距），因此 PDF 无需经过浏览器的打印对话框，也能保留深色主题。

生成新图表时，请在模板中保留以下内容：

<head> 中的两个 CDN 脚本（固定版本，带有 Subresource Integrity 哈希和 crossorigin="anonymous"）：
- https://cdn.jsdelivr.net/npm/[email protected]/dist/html2canvas.min.js — integrity="sha384-ZZ1pncU3bQe8y31yfZdMFdSpttDoPmOZg2wguVK9almUodir1PghgT0eY7Mrty8H"
- https://cdn.jsdelivr.net/npm/[email protected]/dist/jspdf.umd.min.js — integrity="sha384-en/ztfPSRkGfME4KIm05joYXynqzUgbsG5nMrj/xEFAHXkeZfO3yMK8QQ+mP7p1/"
- SRI 可确保生成的图表不会因 CDN 遭到入侵而被篡改。请勿修改哈希；如果升级版本，必须重新计算新哈希。
最外层 .container div 上的 id="report-container"（截取的就是此元素）
.toolbar 标记，其中包含 .toolbar-actions（默认折叠）和 .toolbar-toggle（⋯ 按钮）
.toolbar CSS，以及 @media print { .toolbar { display: none !important; } }
</body> 之前的 copyAsImage()、downloadPNG() 和 downloadPDF() 脚本；这些脚本都使用 getBoundingClientRect() 和 html2canvas(document.body, { x, y, width, height, ignoreElements })，精准截取留有适当边距且不包含工具栏的矩形区域

注意事项：剪贴板 API 需要用户手势和安全上下文（https/file/localhost）。SVG <foreignObject> 在 html2canvas 中的渲染效果不一致——请使用纯 <svg> 图形和 <text>。如需更高分辨率输出，可将 scale: 2 提高至 3 或 4。

组件框模式

<rect x="X" y="Y" width="W" height="H" rx="6" fill="FILL_COLOR" stroke="STROKE_COLOR" stroke-width="1.5"/>
<text x="CENTER_X" y="Y+20" fill="white" font-size="11" font-weight="600" text-anchor="middle">LABEL</text>
<text x="CENTER_X" y="Y+36" fill="#94a3b8" font-size="9" text-anchor="middle">sublabel</text>

信息卡片模式

<div class="card">
  <div class="card-header">
    <div class="card-dot COLOR"></div>
    <h3>Title</h3>
  </div>
  <ul>
    <li>• Item one</li>
    <li>• Item two</li>
  </ul>
</div>

模板

复制并自定义 resources/template.html 中的模板。主要自定义项：

更新 <title> 和页眉文本
根据需要修改 SVG viewBox 尺寸（默认值：1000 x 680）
添加、删除或重新定位组件框
绘制组件之间的连接箭头
更新三张摘要卡片
更新页脚元数据

输出

始终生成单个自包含的 .html 文件，其中包含：

嵌入式 CSS（除 Google Fonts 外，不使用外部样式表）
内联 SVG（不使用外部图像）
无需 JavaScript（纯 CSS 动画）

该文件应能在任何现代浏览器中直接打开并正确渲染。导出工具栏使用两个 CDN 脚本（html2canvas 和 jsPDF）——不依赖其他 JavaScript 库。

支持 Markdown

登录后评论