simbajigege HTML 语义框线 SVG
把原内容中的对象、关系、状态与阅读顺序，重新编码为克制的技术文档式框线图。先保证图能准确复述教学判断，再处理构图与 SVG 细节；不要把原插图机械描摹成矢量轮廓。每次交付同时生成一份自包含的线框图提示词，使同一语义设计能够被复用、复核和继续迭代。
开始前
- 读取目标内容、相邻内容、现有图片或草图、承载它的 HTML/CSS 和可用空间。
- 在
course-design中工作时，读取根目录AGENTS.md、docs/design/STYLE_DNA.md、目标页面使用的设计 token 与更具体的目录规范。 - 由其他 skill 调用时，回到调用它的上层工作流：遵守上层 skill 规定的事实来源、源文件、素材登记、追溯记录、生成物和验证范围，不固定绑定
tailor-html-to-slide、ppt-like-html或任何单一载体。独立调用时，遵守目标项目与目标文件所在目录的规则。 - 保护原结论、概念边界、方向、状态与数量。无法从材料确认的关系不要画成箭头。
工作流
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 能力的实现者在看不到当前对话和成品的情况下，仍能重建语义一致的框线图。
提示词必须覆盖：
- 任务与教学结论：说明要生成 HTML 语义框线 SVG，以及读者必须理解的一个核心判断。
- 对象与可见文字：列出对象、角色、分组、数量和需要原样显示的标签。
- 关系、方向与状态：逐条说明谁连接谁、关系动词、箭头方向、线型和特殊状态；没有依据的关系不写进提示词。
- 布局与阅读顺序：说明构图类型、分组方式、共同锚点、阅读方向、目标画布或适用视口行为和安全间距。除非精确坐标本身具有复现价值，否则使用相对约束，不固化调试坐标。
- 视觉语法：写明颜色的语义用途、实线与虚线含义、字体、圆角和禁用效果。
- SVG 技术约束：要求
viewBox、语义分组、文本保留为<text>、唯一 ID、vector-effect、<title>、<desc>和aria-labelledby。 - 验收与输出：要求检查语义、结构、几何、视觉、目标画布或适用视口与可访问性，并输出完整可编辑 SVG，而非位图或仅提供解释。
使用 Mermaid 时，在“关系、方向与状态”中附上最终采用的 Mermaid 关系结构，随后补充 Mermaid 无法表达的角色、状态含义和布局约束；不要把 Mermaid 自动生成的样式或坐标写成 SVG 必须照抄的要求。
使用与用户一致的主要语言书写提示词；代码名、字段和命令保留原文。提示词应引用实际内容，而不是保留 [对象名称] 一类未填占位符。不要包含临时文件路径、调试过程、无法确认的关系或与最终 SVG 不一致的旧设计。
提示词使用下面的固定结构：
# 线框图生成提示词
请根据以下规格生成一张可访问、响应式、可编辑的 HTML 语义框线 SVG。
## 任务与教学结论
[填写图的用途和唯一核心判断]
## 对象与可见文字
[填写对象、角色、分组、数量和必须出现的标签]
## 关系、方向与状态
[逐条填写关系、动词、方向、线型和状态]
## 布局与阅读顺序
[填写构图、对齐、分隔、安全距离、阅读方向和目标画布或适用视口行为]
## 视觉语法
[填写颜色语义、线框、字体、圆角和禁止项]
## SVG 技术约束
[填写结构、响应式、ID、文本、描边和无障碍要求]
## 验收与输出
[填写验证要求，并要求输出完整 SVG]
3. 选择关系语法与最小图型
先按语义决定连接方式，再选择构图。箭头只表示材料能够确认的方向，不是默认连接符。
| 关系 | 图形语法 |
|---|---|
| 主流程中的流转、派发、认领、调用 | 蓝色实线单向箭头；方向与动词一致 |
| 非主流程、备选路径、可选起点或跳转 | 蓝色虚线单向箭头；用关系标签说明具体含义 |
| 双向同步 | 蓝色双向箭头 |
| 无方向关联、配对、接触 | 黑色实线，不加 marker |
| 包含、仍然存在于某范围内 | 内外嵌套框，不画箭头；外层标签占独立安全区 |
| 并列证据、三种情况、同级对象 | 同尺度、同锚点对齐的分组，不互相连线 |
| 状态变化 | 对象位置尽量不动，改变线型或状态标签；只有明确的时间或转移关系才加箭头 |
- 对比：两个同尺度容器并列，只突出发生变化的关系或状态。
- 层级或派发：上游对象置顶，下游对象水平排布，箭头沿单一方向流动。
- 交接物：仅当任务、数据、文档或产物对理解关系必不可少时，才把它作为关系标签放在箭头附近；非必要时不标注。标签距箭头较远时，从箭头线中点引出橙色无箭头指示线，不要让读者将它误认为新流程。
- 公共环境与自主协作：环境或看板占一侧，平级参与者占另一侧，用“认领”等动词标注关系。
- 人机双界面：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
- 使用稳定的
viewBox坐标系，优先从0 0 600 250起步，再按内容调整。 - 使用
<g>按对象、关系和状态分组；使用<rect>、<line>、<path>、<text>、<tspan>与<marker>。需要几何验收时可添加data-align-group、data-boundary、data-relation等语义属性。 - 保留文字为 SVG 文本，不把文字转路径，不使用
<foreignObject>。 - 为每张图添加
role="img"、aria-labelledby、带唯一 ID 的<title>与<desc>。desc要说明对象、关系、方向和特殊状态，不只重复标题。 - 同一 HTML 文档内所有
id唯一，尤其是箭头 marker。以页面或组件 ID 作为前缀，例如s07-native-arrow-end。 - 对线条使用
vector-effect: non-scaling-stroke；箭头与关系线使用同一语义颜色。交接物指示线使用橙色、不加 marker，并与主关系线分组。 - 让 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。
8. 生成 PNG 预览
- 完成 SVG 并通过结构检查后，默认生成一份同内容的 PNG，作为可直接查看、分享和插入不支持 SVG 的载体中的正式交付物；只有用户明确要求省略时才不生成。
- 创建独立 SVG 文件时，将 PNG 保存为同目录、同 basename 的
<basename>.preview.png。直接修改 HTML 时，按目标组件或页面命名预览图，并在交付摘要中写明对应关系。 - 使用 Chromium、Chrome 或等价的标准浏览器渲染引擎，在白色背景上按 SVG 的原始
viewBox宽高比和目标交付尺寸进行栅格化；固定画布按目标像素尺寸输出，响应式页面按上层 skill 指定的代表性视口输出。 - 禁止使用 macOS Quick Look、文件管理器缩略图或其他会错误缩放
vector-effect: non-scaling-stroke、marker、字体或虚线的缩略图管线生成正式 PNG。 - 页面依赖 Web Font、外部 CSS 或脚本时，等待资源与布局稳定后再截图。PNG 不得通过二次拉伸、压缩或裁切改变 SVG 的长宽比。
- 生成后核对 PNG 像素尺寸，并与浏览器中的 SVG 并排检查：节点位置、文字换行、线宽层级、虚线节奏、箭头尺寸和颜色语义应视觉一致。若不一致，修复渲染流程或 SVG，再重新生成 PNG；不要把失真的 PNG 作为交付物。
9. 验证
依次检查：
- 语义：图是否准确表达
teaching_claim；逐条核对关系语法，确认箭头、虚线与颜色都有依据，且没有相邻重复标签。- 使用 Mermaid 时，先在可用的 Mermaid 渲染器中预览或做语法检查，再逐项核对 Mermaid 与最终 SVG 的节点、分组、关系动词和方向；无法执行渲染时明确记录未检查。
- 结构：运行
node <html-line-svg-skill-dir>/scripts/validate-line-svg.mjs <svg-or-html> [...]，其中<html-line-svg-skill-dir>是本 skill 的实际安装目录；不要假设项目内存在本地副本。该脚本检查 SVG 结构，不替代几何验收。 - 几何：在上层 skill 要求的真实画布或视口中，测量同级主体的对齐偏差、对象到分隔线的安全距离、嵌套框的包含关系，以及文字、框线和连线之间的碰撞；同时检查
viewBox裁切与溢出。含三组以上同级对象、分隔线或嵌套框时必须做此项。固定尺寸的 Presentation 或 PPT 式载体只测目标演示尺寸；响应式网页才检查桌面与窄屏视口。 - 视觉：查看目标画布或适用视口的真实页面截图，并与正式 PNG 预览并排核对，确认阅读顺序、视觉重心和留白稳定，不因技术上“未相交”就忽略贴边或失衡；同时确认主线、虚线、框线和指示线在真实交付尺寸中层级清晰，没有过细、粘连或因栅格化而异常增粗。
- 连线可追踪性：在真实交付尺寸中逐条从关系的起点追到箭头终点，确认每条关系都有唯一、连续、无需猜测的视觉路径。线尾应明确离开源对象边界，箭头应清晰落到目标对象边界；除非语义上存在明确的汇合或分叉节点，否则禁止多条关系长距离共用同一线段。出现同轴重叠、路径粘连、交叉后无法判断去向、连线被对象或文字遮断、箭头与目标脱节时，直接判定为不合格。优先重新分配连接端口、拉开平行路径、减少交叉或拆图；长距离回流、跨层跳转或密集折线仍难以追踪时，改用平滑的二次或三次贝塞尔曲线箭头。曲线必须保持单一走向，不穿过无关对象或文字，也不能制造新的交叉歧义；无法在目标画布内解决时继续拆图，不要勉强保留复杂网络。
- 可访问性：确认
<title>、<desc>与aria-labelledby对应，正文即使不看图也能理解核心判断。 - 提示词一致性：逐项对照最终 SVG 与提示词，确认对象、文字、关系、布局、颜色语义和输出要求一致；实现过程中已经放弃的方案不得残留在提示词中。
- PNG：确认 PNG 的像素尺寸、长宽比与目标画布一致，且节点、文字、线条、marker、虚线和颜色与浏览器渲染的 SVG 视觉一致。
- 集成：执行目标项目已有的构建和验证命令；不要只验证孤立 SVG。
标准输出
每次使用本技能，默认交付以下五项；只有用户明确要求省略时才减少：
- SVG 成品：完整的内联 SVG、目标 HTML 修改，或独立
.svg文件。 - PNG 预览：由标准浏览器按目标交付尺寸从最终 SVG 渲染得到的
.preview.png，不得使用会造成描边或 marker 失真的缩略图工具。 - 线框图生成提示词：按第 2 步的固定结构填写，内容与最终 SVG 一致且可独立复用。
- 交付摘要：用简短文字说明图型、核心对象、关键关系和特殊状态。
- 验证结果：说明结构、几何、视觉、PNG 一致性、连线可追踪性、目标画布或适用视口、可访问性和项目集成检查的结果；没有执行的检查必须明确标注。
使用 Mermaid 时，再交付一份可复制的 Mermaid 关系结构规格；可以放在线框图生成提示词的“关系、方向与状态”中，不要求另建文件。Mermaid 只作为中间语义资产，SVG 仍是最终图形交付物。
创建独立文件时，将提示词保存为与 SVG 同名的 <basename>.prompt.md，例如：
agent-collaboration.svg
agent-collaboration.preview.png
agent-collaboration.prompt.md
直接修改 HTML 或在对话中返回内联 SVG 时，在交付信息中用独立的 Markdown 代码块输出完整提示词。不要把提示词只藏在工作笔记、SVG 注释或 <desc> 中。
复用示例
需要选择构图、比较视觉语义或复制起始结构时，读取 references/example-catalog.md，并查看 assets/examples/ 中四张可独立打开的 SVG：
centralized-agent-dispatch.svgdistributed-agent-claim.svggui-lui-retrofit.svggui-lui-native.svg
复制示例后必须重写标题、描述、ID、文字、数量与关系；示例是视觉语法，不是内容模板。
完成标准
- 图的教学判断可以用一句话复述。
- 标准输出包含与最终图一致、没有未填占位符、可脱离当前对话独立使用的线框图生成提示词。
- 每个对象、关系、状态和强调色都有明确语义。
- 使用 Mermaid 时，其节点、分组、关系动词和方向与最终 SVG 一致，且最终构图没有机械照搬 Mermaid 自动布局。
- 相邻层级没有重复标签，蓝色只表达真实的方向或链接语义。
- SVG 可内联、可缩放、可访问，文档内 ID 不冲突。
- 默认生成与最终 SVG 视觉一致、尺寸明确的 PNG 预览；PNG 未经二次拉伸或裁切，线宽、箭头、虚线、字体和颜色没有因栅格化而失真。
- 同级主体对齐且与分隔线保持安全距离；嵌套框的标签、边界和内容不碰撞。
- 每条有向关系都能在真实交付尺寸中从源对象连续追踪到目标对象；不存在需要猜测去向的共线、粘连或交叉路径，复杂回流已通过重新布线、曲线箭头或拆图消除歧义。
- 在上层 skill 规定的目标画布和适用视口中均无溢出、裁切或不可读文字。
- 风格保持纯白、少色、线宽层级清晰、无阴影，不抢夺正文注意力。
- 修改现有课件时，源文件、追溯文件、生成物和验证结果保持一致。