Semantic Line-Art SVG Diagrams

HTML 语义框线 SVG

把原内容中的对象、关系、状态与阅读顺序，重新编码为克制的技术文档式框线图。先保证图能准确复述教学判断，再处理构图与 SVG 细节；不要把原插图机械描摹成矢量轮廓。每次交付同时生成一份自包含的线框图提示词，使同一语义设计能够被复用、复核和继续迭代。

开始前

1. 读取目标内容、相邻内容、现有图片或草图、承载它的 HTML/CSS 和可用空间。
2. 在 course-design 中工作时，读取根目录 AGENTS.md、docs/design/STYLE_DNA.md、目标页面使用的设计 token 与更具体的目录规范。
3. 由其他 skill 调用时，回到调用它的上层工作流：遵守上层 skill 规定的事实来源、源文件、素材登记、追溯记录、生成物和验证范围，不固定绑定 tailor-html-to-slide、ppt-like-html 或任何单一载体。独立调用时，遵守目标项目与目标文件所在目录的规则。
4. 保护原结论、概念边界、方向、状态与数量。无法从材料确认的关系不要画成箭头。

工作流

1. 写语义规格与可选 Mermaid 关系结构

在画图前写出一个最小规格；可放在工作笔记中，不要求成为最终页面文字。

teaching_claim: 这张图必须让读者看懂的一个判断
objects:
  - id: object-a
    label: 对象名称
    role: interface | agent | task | container | document | state
relations:
  - from: object-a
    to: object-b
    type: flow | dispatch | claim | sync | association | compare | contains
    direction: forward | bidirectional | none
    path: primary | alternative
    payload: 可选；仅在理解交接物时填写
states:
  - target: object-b
    type: added-later | waiting | incomplete | fading | persistent | warning | blocked
visible_labels:
  - text: 对读者可见的文字
    role: group-title | object-label | relation-label | caption
layout_constraints:
  peer_alignment: visual-center-y | top | baseline | none
  alignment_tolerance: "0.5% of viewBox height"
  minimum_safe_gap: "2% of viewBox width"
  containment_label_zone: top | side | none
reading_order: left-to-right | top-to-bottom | center-out | board-to-peers

只保留支持 teaching_claim 的信息。名称、数量、箭头方向、实线或虚线都必须能在规格中找到语义理由。path 区分主流程与非主流程；payload 仅在不说明交接物就无法理解关系时填写，不要为每条箭头强行补产物。visible_labels 用来提前发现相邻层级的重复文字；layout_constraints 写相对约束，不写只适用于某一张图的坐标。

当图以节点关系为主时，优先在 YAML 之前或之后补一段 Mermaid，把它作为可执行、可预览的关系结构规格。系统架构、流程、Agent 协作、状态转换、时序交互、类关系和实体关系通常适合；GUI 页面线框、纯视觉对比和难以抽象为节点关系的插图可以省略。选择语法和写法时参考 Mermaid 官方图表语法文档，并从该页导航到 Flowchart、Architecture、Sequence、State、Class、Entity Relationship 等对应图型。

Mermaid 规格遵循以下要求：

• 使用稳定、可读的节点 ID；把必须展示的文字写成显式标签。
• 写清分组、关系动词、箭头方向和可确认的状态；材料没有依据的连接不要添加。
• 选择能表达语义的最小图型，不为展示 Mermaid 功能而增加节点形状、颜色或关系。
• 把 Mermaid 的节点、分组和边视为语义依据，不把自动布局、折线路径、坐标或默认样式视为最终设计。
• Mermaid 不能替代 teaching_claim、对象角色、状态歧义说明、可见标签、布局约束、阅读顺序和窄屏行为；仍用 YAML 或紧邻 Mermaid 的文字补齐这些信息。

示例：

flowchart TB
    scheduler["调度器"]
    subgraph agents["执行层"]
        agent_a["Agent A"]
        agent_b["Agent B"]
    end
    scheduler -->|派发| agent_a
    scheduler -->|派发| agent_b

把 Mermaid 转为 SVG 时，保留节点身份、分组边界、关系动词、方向和阅读顺序；根据真实页面空间重新构图，不机械复刻 Mermaid 渲染结果。若使用 Mermaid，后续线框图生成提示词必须包含最终采用的 Mermaid 代码或等价的完整关系说明。

2. 生成线框图提示词

根据语义规格起草一份自包含的“线框图生成提示词”，并在 SVG 完成验证后按最终实现同步修订。提示词不是工作过程摘要，也不是给位图模型的氛围描述；它应让另一个具备 HTML/SVG 能力的实现者在看不到当前对话和成品的情况下，仍能重建语义一致的框线图。

提示词必须覆盖：

1. 任务与教学结论：说明要生成 HTML 语义框线 SVG，以及读者必须理解的一个核心判断。
2. 对象与可见文字：列出对象、角色、分组、数量和需要原样显示的标签。
3. 关系、方向与状态：逐条说明谁连接谁、关系动词、箭头方向、线型和特殊状态；没有依据的关系不写进提示词。
4. 布局与阅读顺序：说明构图类型、分组方式、共同锚点、阅读方向、目标画布或适用视口行为和安全间距。除非精确坐标本身具有复现价值，否则使用相对约束，不固化调试坐标。
5. 视觉语法：写明颜色的语义用途、实线与虚线含义、字体、圆角和禁用效果。
6. SVG 技术约束：要求 viewBox、语义分组、文本保留为 <text>、唯一 ID、vector-effect、<title>、<desc> 和 aria-labelledby。
7. 验收与输出：要求检查语义、结构、几何、视觉、目标画布或适用视口与可访问性，并输出完整可编辑 SVG，而非位图或仅提供解释。

使用 Mermaid 时，在“关系、方向与状态”中附上最终采用的 Mermaid 关系结构，随后补充 Mermaid 无法表达的角色、状态含义和布局约束；不要把 Mermaid 自动生成的样式或坐标写成 SVG 必须照抄的要求。

使用与用户一致的主要语言书写提示词；代码名、字段和命令保留原文。提示词应引用实际内容，而不是保留 [对象名称] 一类未填占位符。不要包含临时文件路径、调试过程、无法确认的关系或与最终 SVG 不一致的旧设计。

提示词使用下面的固定结构：

# 线框图生成提示词

请根据以下规格生成一张可访问、响应式、可编辑的 HTML 语义框线 SVG。

## 任务与教学结论
[填写图的用途和唯一核心判断]

## 对象与可见文字
[填写对象、角色、分组、数量和必须出现的标签]

## 关系、方向与状态
[逐条填写关系、动词、方向、线型和状态]

## 布局与阅读顺序
[填写构图、对齐、分隔、安全距离、阅读方向和目标画布或适用视口行为]

## 视觉语法
[填写颜色语义、线框、字体、圆角和禁止项]

## SVG 技术约束
[填写结构、响应式、ID、文本、描边和无障碍要求]

## 验收与输出
[填写验证要求，并要求输出完整 SVG]

3. 选择关系语法与最小图型

先按语义决定连接方式，再选择构图。箭头只表示材料能够确认的方向，不是默认连接符。

• 对比：两个同尺度容器并列，只突出发生变化的关系或状态。
• 层级或派发：上游对象置顶，下游对象水平排布，箭头沿单一方向流动。
• 交接物：仅当任务、数据、文档或产物对理解关系必不可少时，才把它作为关系标签放在箭头附近；非必要时不标注。标签距箭头较远时，从箭头线中点引出橙色无箭头指示线，不要让读者将它误认为新流程。
• 公共环境与自主协作：环境或看板占一侧，平级参与者占另一侧，用“认领”等动词标注关系。
• 人机双界面：GUI 用页面线框，LUI 用机器可读字段；补建用单向关系，同步设计用双向关系。

如果一张图需要多条交叉线、三层以上嵌套或大量说明文字，先拆图、换为编号步骤或删减非核心信息。

4. 整理标签与布局契约

• 盘点卡片标题、分组标题、对象标签、关系标签和图注。相邻层级表达同一信息时只保留一处；图内小标题若只是复述卡片或分组标题，直接删除。
• 三组及以上同级图先确定共同锚点。对象尺寸不同时优先对齐视觉中心；标题、角标等附属文字不作为主体对齐基准。
• 先划定每组的边界和分隔线安全区，再放对象与连线。对象框线、文字和 marker 都不能压住分隔线或相邻分组。
• 包含关系先扩大外框，再为外层标签预留独立区域和内边距；内外标签、框线不得重叠。
• 使用相对容差和安全距离；可在调试时添加辅助线或测量边界，验收前移除辅助元素。

5. 应用视觉语法

遵循 docs/design/STYLE_DNA.md：纯白、极简、留白、克制、技术文档感。

• 白色 #FFFFFF：画布与对象内部。
• 黑色 #0A0A0A：对象框线、主要文字。
• 深灰 #171717：次级正文；中灰 #737373：标签、关系动词。
• 浅灰 #E5E5E5：分隔线、外层辅助边界。
• 蓝色 #0348ED：仅用于方向、链接、认领、派发、同步等关系；不要用作普通说明文字或大面积对象填充。
• 橙色 #FE7E0F：提示、任务角标、尚未成熟等警示，以及从主关系线指向较远交接物标签的无箭头指示线。
• 红色 #FF3700：阻碍、冲突、错误或缺口；没有负面语义时不要使用。
• 实线框：已存在、可用、确定的对象。
• 虚线框：后来补建、等待、未完成、正在退去或候选状态；必须由文字或上下文消除歧义。
• 等宽字：name、desc、参数、命令和其他机器可读字段。
• 圆角保持轻微，通常 rx="2" 到 8；不要做药丸化卡片。
• 建立线宽层级：主关系线与箭头最清晰，对象框线次之，交接物指示线可略细但不得成为发丝线。不要机械套用偏细默认值；在真实交付尺寸中确认线条可清晰辨认。

绝不添加渐变、阴影、滤镜、纹理、噪点、复杂背景、3D、科技感 UI、装饰图标或无语义连线。不要追求“可爱”“怪诞”“海报感”。

6. 构造 SVG

1. 使用稳定的 viewBox 坐标系，优先从 0 0 600 250 起步，再按内容调整。
2. 使用 <g> 按对象、关系和状态分组；使用 <rect>、<line>、<path>、<text>、<tspan> 与 <marker>。需要几何验收时可添加 data-align-group、data-boundary、data-relation 等语义属性。
3. 保留文字为 SVG 文本，不把文字转路径，不使用 <foreignObject>。
4. 为每张图添加 role="img"、aria-labelledby、带唯一 ID 的 <title> 与 <desc>。desc 要说明对象、关系、方向和特殊状态，不只重复标题。
5. 同一 HTML 文档内所有 id 唯一，尤其是箭头 marker。以页面或组件 ID 作为前缀，例如 s07-native-arrow-end。
6. 对线条使用 vector-effect: non-scaling-stroke；箭头与关系线使用同一语义颜色。交接物指示线使用橙色、不加 marker，并与主关系线分组。
7. 让 HTML/CSS 承担尺寸、字体和 token 映射，SVG 承担结构。需要独立 SVG 文件时，可内嵌最小 <style> 并沿用同一 token 值。

实现模式、CSS 容器和可访问性模板见 references/implementation-patterns.md。

7. 嵌入 HTML 并适配目标画布

• 外层容器设置 width: 100%、min-width: 0、适度内边距与 overflow: hidden。
• SVG 设置 display: block; width: 100%; height: auto;，用 max-height 控制卡片内视觉重量。
• 按调用它的上层 skill 继承画布与视口要求。固定尺寸的 HTML Presentation 或 PPT 式载体只验证目标演示尺寸；课程页或响应式网页需要窄屏时，堆叠后保持相同阅读顺序，不依赖仅桌面成立的箭头位置。
• 避免小字号与长句。标签优先使用 2–6 个字；需要换行时使用 <tspan x="…" dy="…"> 明确控制。
• 不使用 SVG 固定像素宽高来替代响应式 CSS。