name: tesseron-diagram
description: 使用Tesseron文档可视化语言创建专业的技术图表（架构图、序列图、状态图、流程图）——深灰板岩底色搭配单一琥珀色强调，点状网格背景，渐变卡片，Lucide风格图标，高斯模糊发光强调节点，以及Inter + JetBrains Mono字体。适用于为Tesseron风格项目、任何希望采用克制单色加一个强调色美学的Starlight/Astro文档站点创建文档图表，或当用户说“使用我们的Tesseron设计系统”时。
license: MIT
metadata:
    version: "1.1"
    author: Tesseron / Kenny Vaneetvelde
    based-on: Cocoon-AI/architecture-diagram-generator (methodology)
    changelog:
        - "1.1 — codified hard rules from iterative visual QA: pill-on-arrow, line+polygon arrows (no SVG markers), centered icons, 10×10 arrowheads, ASCII-only content."

Tesseron 图表技能

生成包含嵌入式 CSS 和内联 SVG 的自包含 HTML 文件，沿用 Tesseron 文档美学。

核心原则

一种强调色。其他一切保持中性。 彩虹调色板是业余水平的第一标志。强调色（琥珀色）仅保留给每张图中的单个“新颖”或“特色”节点。所有其他节点均为中性石板卡片。

---

⚠️ 硬性规则（经验教训——请勿偏离）

这些是通过视觉 QA 建立的不容商榷的惯例。这里每一条规则的存在都是因为违反它会产生可见的 Bug。

1. 所有文本内容仅限 ASCII

智能引号式后处理器（Astro、MDX 以及许多静态站点流水线）会静默地将 ' 转换为 '、" 转换为 "、... 转换为 …。这些字符随后会被未正确声明 UTF-8 的浏览器误编码为 ’、“、…。完全避免这类问题：

• 使用 '（直撇号），绝不使用 '。
• 使用 "（直双引号），绝不使用 " "。
• 使用 ...（三个点），绝不使用 …。
• 使用 -（连字符），绝不使用 – —。
• 使用 | 或 , 或 + 作为装饰分隔符，绝不使用 ·，绝不使用 ↔，绝不使用 → 在文本标签内。

如果宿主框架在构建时启用了智能引号，请禁用它（例如 Astro：markdown: { smartypants: false }）。

2. 箭头：线条 + 多边形，而非 SVG <marker>

带有 refX、缩放以及各种 markerUnits 模式的 <marker> 是排列错误的永久来源：由于 refX 与 viewBox 缩放以及 linecap 行为，线条描边会始终在箭头尖端之外多渲染一个或两个像素。完全放弃标记。 每个箭头绘制为：

• 一条 <line>，带有 stroke-linecap="butt"，其 x2 恰好是三角形的 底边 x 坐标（而非尖端）。
• 一个内联的 <polygon> 作为箭头头，底边与线条末端对齐，尖端指向实际目标。

通过构造，线条和多边形之间完全没有重叠，因此描边物理上不可能超出尖端绘制。

规范箭头（右指，尖端在 TIP_X）：

<!-- 箭头尖端在 TIP_X。底边在 TIP_X-10。主体从 x1 延伸到底边。 -->
<line x1="X1" y1="Y" x2="TIP_X-10" y2="Y"
      stroke="var(--dgm-line-strong)" stroke-width="1.75" stroke-linecap="butt"/>
<polygon points="TIP_X-10,Y-5  TIP_X,Y  TIP_X-10,Y+5"
         fill="var(--dgm-line-strong)"/>

对于双向箭头：左三角形，然后是两个底边 x 之间的线条，然后是右三角形——共三个元素，而非一个。

3. 箭头尺寸：10 × 10

宽度 10，半高 5（因此三角形总体宽 10、高 10）。平衡——既不拉伸也不压扁。更大显得笨重，更小显得单薄。

4. 标签药丸放置在箭头线上，居中

药丸垂直中心 = 箭头 y。药丸宽度 < 间隙宽度，因此每侧约 20-30 像素的箭头保持可见。

• rect 药丸位于 y = arrowY - 11，height = 22。
• text 基线位于 y = arrowY + 4。
• fill = var(--dgm-pill-bg)（不透明）以便清晰地打断下方的线条。
• 如果边缘是强调色，则 stroke = var(--dgm-accent)，否则 stroke = var(--dgm-pill-border)。

视觉效果为 ---[ label ]--->，而非线条上方的浮动标签。

5. 图标在标题上方水平居中

图标为 20 × 20，其自身局部原点在 (0,0)。要在宽度为 w、中心为 cx 的卡片内水平居中：

<g class="dgm-icon" transform="translate(cx - 10, y + 16)"> ... </g>

不要缩放图标（不要使用 scale(1.15)）——保持 1.5 像素描边清晰。

6. 卡片垂直布局（120 像素高的卡片）

• y + 16..36 — 图标（高 20，水平居中）
• y + 50 — 标题（居中，大写，13.5 px / 600）
• y + 74 — 第一行副标题（居中，12.5 px / 400）
• y + 90 — 第二行副标题（如果两行副标题）
• y + 110 — 等宽字体代码标识符（如果存在）

对于单行副标题 + 代码，将副标题放在 y + 74，代码放在 y + 94。

7. 节点间距

对于大约 1200 px 画布上的 4 卡水平架构：

• pad = 30，card w = 180，gap = 140
• 画布 = 4 × 180 + 3 × 140 + 2 × 30 = 1200

间隙 = 140 是能够容纳居中 88 px 药丸 + 每侧约 26 px 可见箭头的最小值。

8. 发光椭圆尺寸

在强调节点（尺寸 w × h）后方：

• rx = 0.6 × w，ry = 0.7 × h
• opacity = 0.33
• 滤镜 stdDeviation = 14

较大的 ry（例如 0.95）会导致发光在紧凑的 SVG viewBox 的顶部/底部被裁剪。请保持约束。

9. Z 顺序（绘制顺序很重要）

1. 点状网格背景
2. 强调发光椭圆
3. 箭头线条 + 箭头多边形
4. 节点卡片（带投影）
5. 图标、标题、副标题、代码标识符
6. 边标签药丸（放置在其行中所有元素之上）

10. 开发中的 SVG 渲染——如果 width: 100% 会使文本缩小，则不要使用

如果你将 SVG 嵌入到 CSS 强制 width: 100% 的文档页面中，宽 viewBox 会被缩放，所有字体大小也会按比例缩小。要么：

• 在 <svg> 上设置等于画布大小的显式 width 和 height 属性；将父元素包裹在 overflow-x: auto 中，以便窄视口水平滚动，或者
• 加宽宿主内容列（例如 Starlight：--sl-content-width: 64rem）。

永远不要留下 width: 100% + 大 viewBox + 无滚动容器的组合。这就是“小字”Bug。

---

调色板

背景 / 画布

中性卡片（大多数节点）

强调卡片（每张图一个）

危险卡片（仅拒绝/错误路径）

文本 + 线条

药丸（边标签）

排版

• 无衬线字体：Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif
• 等宽字体："JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace

图标（Lucide 风格，20 × 20）

每个图标是一组 SVG 路径，位于一个组内，带有 fill="none"、stroke-width="1.5"、stroke-linecap="round"、stroke-linejoin="round"。描边颜色：中性为 var(--dgm-icon)，强调色为 var(--dgm-accent)，危险色为 var(--dgm-danger)。

user:     <circle cx="10" cy="7" r="3.6"/><path d="M3 20 a7 7 0 0 1 14 0"/>
window:   <rect x="1" y="2" width="18" height="16" rx="2"/><path d="M1 6 H19"/>
          <circle cx="4" cy="4" r="0.7" fill="currentColor" stroke="none"/>
          <circle cx="7" cy="4" r="0.7" fill="currentColor" stroke="none"/>
bridge:   <path d="M3 7 H17"/><path d="M14 4 L18 7 L14 10"/>
          <path d="M17 13 H3"/><path d="M6 10 L2 13 L6 16"/>
agent:    <path d="M10 1.5 L12 8 L18.5 10 L12 12 L10 18.5 L8 12 L1.5 10 L8 8 Z"/>
shield:   <path d="M10 2 L17 5 V10 C17 14 14 17 10 19 C6 17 3 14 3 10 V5 Z"/>
lock:     <rect x="3" y="9" width="14" height="10" rx="2"/>
          <path d="M6 9 V6 a4 4 0 0 1 8 0 V9"/>
cube:     <path d="M10 2 L18 6 V14 L10 18 L2 14 V6 Z"/>
          <path d="M2 6 L10 10 L18 6"/><path d="M10 10 V18"/>
packages: <rect x="1.5" y="1.5" width="7" height="7" rx="1"/>
          <rect x="11.5" y="1.5" width="7" height="7" rx="1"/>
          <rect x="6.5" y="11.5" width="7" height="7" rx="1"/>
server:   <rect x="2" y="3" width="16" height="6" rx="1.5"/>
          <rect x="2" y="11" width="16" height="6" rx="1.5"/>
          <circle cx="6" cy="6" r="0.7" fill="currentColor" stroke="none"/>
          <circle cx="6" cy="14" r="0.7" fill="currentColor" stroke="none"/>
database: <ellipse cx="10" cy="4" rx="8" ry="2.2"/>
          <path d="M2 4 V16 a8 2.2 0 0 0 16 0 V4"/>
          <path d="M2 10 a8 2.2 0 0 0 16 0"/>

放入卡片中（卡片中心 cx，卡片顶部 y）：

<g class="dgm-icon" transform="translate(cx - 10, y + 16)"> ... </g>

视觉定义

点状网格（首先绘制，覆盖整个画布）：

<pattern id="dgm-dots" width="22" height="22" patternUnits="userSpaceOnUse">
  <circle cx="1.2" cy="1.2" r="1.2" fill="var(--dgm-grid)"/>
</pattern>
<rect width="100%" height="100%" fill="url(#dgm-dots)"/>

卡片填充渐变（微妙的顶部到底部）：

<linearGradient id="dgm-card-neutral" x1="0" y1="0" x2="0" y2="1">
  <stop offset="0" stop-color="var(--dgm-card-neutral-1)"/>
  <stop offset="1" stop-color="var(--dgm-card-neutral-2)"/>
</linearGradient>

强调边框渐变：

<linearGradient id="dgm-border-accent" x1="0" y1="0" x2="0" y2="1">
  <stop offset="0" stop-color="var(--dgm-accent-border-1)"/>
  <stop offset="1" stop-color="var(--dgm-accent-border-2)"/>
</linearGradient>

强调发光滤镜（作为单独的 <ellipse> 绘制在强调卡片后方）：

<filter id="dgm-glow-accent" x="-30%" y="-60%" width="160%" height="220%">
  <feGaussianBlur stdDeviation="14" result="b"/>
  <feColorMatrix in="b" type="matrix"
    values="0 0 0 0 0.98   0 0 0 0 0.73   0 0 0 0 0.14   0 0 0 0.45 0"/>
</filter>

<ellipse cx="CARD_CX" cy="CARD_CY"
  rx="CARD_W*0.6" ry="CARD_H*0.7"
  fill="var(--dgm-accent)" filter="url(#dgm-glow-accent)" opacity="0.33"/>

卡片投影（两层 feDropShadow——无 90 年代斜面效果）：

<filter id="dgm-shadow" x="-10%" y="-10%" width="120%" height="130%">
  <feDropShadow dx="0" dy="4" stdDeviation="6"
    flood-color="var(--dgm-shadow-color)" flood-opacity="0.06"/>
  <feDropShadow dx="0" dy="1" stdDeviation="1.5"
    flood-color="var(--dgm-shadow-color)" flood-opacity="0.04"/>
</filter>

节点卡片模式

中性：

<rect x="X" y="Y" width="W" height="H" rx="14"
      fill="url(#dgm-card-neutral)" stroke="var(--dgm-border)" stroke-width="1.25"
      filter="url(#dgm-shadow)"/>

强调（渐变边框）：

<rect x="X" y="Y" width="W" height="H" rx="14"
      fill="url(#dgm-card-accent)" stroke="url(#dgm-border-accent)" stroke-width="1.25"
      filter="url(#dgm-shadow)"/>

完整卡片（强调）带居中图标 + 标题 + 副标题 + 代码：

<g>
  <rect x="670" y="90" width="180" height="120" rx="14"
        fill="url(#dgm-card-accent)" stroke="url(#dgm-border-accent)" stroke-width="1.25"
        filter="url(#dgm-shadow)"/>
  <g class="dgm-icon dgm-icon-accent" transform="translate(750,106)"> ... </g>
  <text x="760" y="150" text-anchor="middle" class="dgm-title dgm-title-accent">GATEWAY</text>
  <text x="760" y="174" text-anchor="middle" class="dgm-sub dgm-sub-accent">WebSocket + MCP bridge</text>
  <text x="760" y="194" text-anchor="middle" class="dgm-code dgm-code-accent">@tesseron/mcp :7475</text>
</g>

边缘模式（完整规范示例）

箭头从 (x1=216, y=150) 到尖端 (x=344, y=150)，强调色：

<line x1="216" y1="150" x2="334" y2="150"
      stroke="var(--dgm-accent)" stroke-width="1.75" stroke-linecap="butt"/>
<polygon points="334,145 344,150 334,155" fill="var(--dgm-accent)"/>

双向，在 TIP_LEFT=536 和 TIP_RIGHT=664 之间：

<polygon points="546,145 536,150 546,155" fill="var(--dgm-accent)"/>
<line x1="546" y1="150" x2="654" y2="150"
      stroke="var(--dgm-accent)" stroke-width="1.75" stroke-linecap="butt"/>
<polygon points="654,145 664,150 654,155" fill="var(--dgm-accent)"/>

边缘药丸（在 y=150 的箭头上居中于 MID_X=600）：

<rect x="556" y="139" width="88" height="22" rx="7"
      fill="var(--dgm-pill-bg)" stroke="var(--dgm-accent)" stroke-width="1"/>
<text x="600" y="154" text-anchor="middle" class="dgm-lbl dgm-lbl-accent">WebSocket</text>

布局（架构，4 卡水平）

画布 1200 × 310，节点中线 y=150：

箭头尖端位于卡片边缘：对于节点 0→1，线条为 x1 = 216, tip = 344（在居中于 x = 280 的 88 px 药丸每侧留下 30 px 的箭头）。

序列图

相同的设计令牌，不同的布局：

• 参与者 在顶部，均匀分布（参与者宽度 220，参与者间隙 110，上方使用卡片模式）。
• 生命线：从参与者底部到行底部的虚线垂直线。stroke="var(--dgm-line)" stroke-width="1.25" stroke-dasharray="3 5" opacity="0.6"。
• 消息：水平 <line> + <polygon> 箭头在行 y 处。标签药丸居中于箭头。
• 步骤编号：在源端放置 10 px 的圆，边框与箭头描边匹配，文本 11.5 px / 600。
• 注释：跨越一个或多个参与者的圆角矩形，高 30 px，斜体 14 px 文本。

输出

生成一个自包含的 .html 文件，包含：

• <style> 中的嵌入式 CSS。
• 内联 SVG。
• 通过 CSS 自定义属性和 @media (prefers-color-scheme: dark) 提供浅色和深色调色板。
• 无需 JavaScript。

起始模板

可随时自定义的模板位于 assets/template.html。它包含所有 <defs>、浅色 + 深色的 CSS 自定义属性、图表下方的三卡摘要以及一个带有工作边缘的示例节点对。复制并填充。

一个完整工作的 4 节点架构示例位于 examples/architecture.html。

反模式（永远不要这样做）

• 多种饱和颜色。 一种强调色。如果你为了“视觉趣味”而使用第二种颜色，不要这样做。
• 基于 SVG <marker> 的箭头。 无尽的 refX/linecap 对齐问题。始终使用线条 + 多边形。
• 药丸放在箭头上面。 药丸放在箭头上。视觉效果是 ---[ label ]--->。
• 图标在左上角而文本居中。 要么全部左对齐，要么全部居中——不匹配显得业余。
• dy > 4 或 opacity > 0.1 的投影。 硬阴影看起来像 90 年代斜面效果。
• 缩放图标（scale(1.15)） —— 1.5 px 描边会变得模糊。以 20 × 20 原始尺寸绘制图标。
• 混合图标集。 仅限 Lucide 风格。
• 标签中的非 ASCII 字符。 智能引号 + 浏览器编码 = ’。
• 旋转文本。 永远不要。
• 宽 SVG 上的 width: 100% 且无水平滚动。 会破坏文本可读性。

何时不使用本技能

• 手绘 / Excalidraw 美学 → 使用 coleam00/excalidraw-diagram-skill。
• 超过 12 个节点或需要大规模自动布局的嵌套层次结构 → 使用 D2 或 Mermaid。
• Cocoon-AI 的多色语义调色板（青色/翡翠色/紫色）→ 使用他们的技能。