--- name: html-line-svg description: 将文字、截图、手绘或“小黑”插图、已有 HTML 关系图提炼为有教学语义的极简框线图；关系密集型图可先用 Mermaid 编写可执行的关系结构规格，再实现为可访问、响应式的内联 SVG，并同步输出可复用的线框图生成提示词。用于 HTML Presentation、课程页和网页卡片中的对比图、架构图、流程图、界面或接口图、Agent 协作图与状态关系图；当用户要求“语义框线图”“线框插图”“把插图改成 SVG”“生成线框图提示词”“在卡片里画 GUI/LUI、Agent、任务或系统关系”，或要求沿用 course-design 的 STYLE_DNA 设计教学插图时使用。不用于照片、装饰海报、复杂数据图表、情绪型手绘插画或直接编辑二进制 PPTX。 --- # 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 关系结构 在画图前写出一个最小规格；可放在工作笔记中，不要求成为最终页面文字。 ```yaml 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 官方图表语法文档](https://mermaid.ai/open-source/syntax/flowchart.html)，并从该页导航到 Flowchart、Architecture、Sequence、State、Class、Entity Relationship 等对应图型。 Mermaid 规格遵循以下要求： - 使用稳定、可读的节点 ID；把必须展示的文字写成显式标签。 - 写清分组、关系动词、箭头方向和可确认的状态；材料没有依据的连接不要添加。 - 选择能表达语义的最小图型，不为展示 Mermaid 功能而增加节点形状、颜色或关系。 - 把 Mermaid 的节点、分组和边视为语义依据，不把自动布局、折线路径、坐标或默认样式视为最终设计。 - Mermaid 不能替代 `teaching_claim`、对象角色、状态歧义说明、可见标签、布局约束、阅读顺序和窄屏行为；仍用 YAML 或紧邻 Mermaid 的文字补齐这些信息。 示例： ```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`、语义分组、文本保留为 ``、唯一 ID、`vector-effect`、``、`<desc>` 和 `aria-labelledby`。 7. **验收与输出**：要求检查语义、结构、几何、视觉、目标画布或适用视口与可访问性，并输出完整可编辑 SVG，而非位图或仅提供解释。 使用 Mermaid 时，在“关系、方向与状态”中附上最终采用的 Mermaid 关系结构，随后补充 Mermaid 无法表达的角色、状态含义和布局约束；不要把 Mermaid 自动生成的样式或坐标写成 SVG 必须照抄的要求。 使用与用户一致的主要语言书写提示词；代码名、字段和命令保留原文。提示词应引用实际内容，而不是保留 `[对象名称]` 一类未填占位符。不要包含临时文件路径、调试过程、无法确认的关系或与最终 SVG 不一致的旧设计。 提示词使用下面的固定结构： ```text # 线框图生成提示词 请根据以下规格生成一张可访问、响应式、可编辑的 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 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](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. 验证 依次检查： 1. 语义：图是否准确表达 `teaching_claim`；逐条核对关系语法，确认箭头、虚线与颜色都有依据，且没有相邻重复标签。 - 使用 Mermaid 时，先在可用的 Mermaid 渲染器中预览或做语法检查，再逐项核对 Mermaid 与最终 SVG 的节点、分组、关系动词和方向；无法执行渲染时明确记录未检查。 2. 结构：运行 `node <html-line-svg-skill-dir>/scripts/validate-line-svg.mjs <svg-or-html> [...]`，其中 `<html-line-svg-skill-dir>` 是本 skill 的实际安装目录；不要假设项目内存在本地副本。该脚本检查 SVG 结构，不替代几何验收。 3. 几何：在上层 skill 要求的真实画布或视口中，测量同级主体的对齐偏差、对象到分隔线的安全距离、嵌套框的包含关系，以及文字、框线和连线之间的碰撞；同时检查 `viewBox` 裁切与溢出。含三组以上同级对象、分隔线或嵌套框时必须做此项。固定尺寸的 Presentation 或 PPT 式载体只测目标演示尺寸；响应式网页才检查桌面与窄屏视口。 4. 视觉：查看目标画布或适用视口的真实页面截图，并与正式 PNG 预览并排核对，确认阅读顺序、视觉重心和留白稳定，不因技术上“未相交”就忽略贴边或失衡；同时确认主线、虚线、框线和指示线在真实交付尺寸中层级清晰，没有过细、粘连或因栅格化而异常增粗。 5. 连线可追踪性：在真实交付尺寸中逐条从关系的起点追到箭头终点，确认每条关系都有唯一、连续、无需猜测的视觉路径。线尾应明确离开源对象边界，箭头应清晰落到目标对象边界；除非语义上存在明确的汇合或分叉节点，否则禁止多条关系长距离共用同一线段。出现同轴重叠、路径粘连、交叉后无法判断去向、连线被对象或文字遮断、箭头与目标脱节时，直接判定为不合格。优先重新分配连接端口、拉开平行路径、减少交叉或拆图；长距离回流、跨层跳转或密集折线仍难以追踪时，改用平滑的二次或三次贝塞尔曲线箭头。曲线必须保持单一走向，不穿过无关对象或文字，也不能制造新的交叉歧义；无法在目标画布内解决时继续拆图，不要勉强保留复杂网络。 6. 可访问性：确认 `<title>`、`<desc>` 与 `aria-labelledby` 对应，正文即使不看图也能理解核心判断。 7. 提示词一致性：逐项对照最终 SVG 与提示词，确认对象、文字、关系、布局、颜色语义和输出要求一致；实现过程中已经放弃的方案不得残留在提示词中。 8. PNG：确认 PNG 的像素尺寸、长宽比与目标画布一致，且节点、文字、线条、marker、虚线和颜色与浏览器渲染的 SVG 视觉一致。 9. 集成：执行目标项目已有的构建和验证命令；不要只验证孤立 SVG。 ## 标准输出 每次使用本技能，默认交付以下五项；只有用户明确要求省略时才减少： 1. **SVG 成品**：完整的内联 SVG、目标 HTML 修改，或独立 `.svg` 文件。 2. **PNG 预览**：由标准浏览器按目标交付尺寸从最终 SVG 渲染得到的 `.preview.png`，不得使用会造成描边或 marker 失真的缩略图工具。 3. **线框图生成提示词**：按第 2 步的固定结构填写，内容与最终 SVG 一致且可独立复用。 4. **交付摘要**：用简短文字说明图型、核心对象、关键关系和特殊状态。 5. **验证结果**：说明结构、几何、视觉、PNG 一致性、连线可追踪性、目标画布或适用视口、可访问性和项目集成检查的结果；没有执行的检查必须明确标注。 使用 Mermaid 时，再交付一份可复制的 Mermaid 关系结构规格；可以放在线框图生成提示词的“关系、方向与状态”中，不要求另建文件。Mermaid 只作为中间语义资产，SVG 仍是最终图形交付物。 创建独立文件时，将提示词保存为与 SVG 同名的 `<basename>.prompt.md`，例如： ```text agent-collaboration.svg agent-collaboration.preview.png agent-collaboration.prompt.md ``` 直接修改 HTML 或在对话中返回内联 SVG 时，在交付信息中用独立的 Markdown 代码块输出完整提示词。不要把提示词只藏在工作笔记、SVG 注释或 `<desc>` 中。 ## 复用示例 需要选择构图、比较视觉语义或复制起始结构时，读取 [references/example-catalog.md](references/example-catalog.md)，并查看 `assets/examples/` 中四张可独立打开的 SVG： - `centralized-agent-dispatch.svg` - `distributed-agent-claim.svg` - `gui-lui-retrofit.svg` - `gui-lui-native.svg` 复制示例后必须重写标题、描述、ID、文字、数量与关系；示例是视觉语法，不是内容模板。 ## 完成标准 - 图的教学判断可以用一句话复述。 - 标准输出包含与最终图一致、没有未填占位符、可脱离当前对话独立使用的线框图生成提示词。 - 每个对象、关系、状态和强调色都有明确语义。 - 使用 Mermaid 时，其节点、分组、关系动词和方向与最终 SVG 一致，且最终构图没有机械照搬 Mermaid 自动布局。 - 相邻层级没有重复标签，蓝色只表达真实的方向或链接语义。 - SVG 可内联、可缩放、可访问，文档内 ID 不冲突。 - 默认生成与最终 SVG 视觉一致、尺寸明确的 PNG 预览；PNG 未经二次拉伸或裁切，线宽、箭头、虚线、字体和颜色没有因栅格化而失真。 - 同级主体对齐且与分隔线保持安全距离；嵌套框的标签、边界和内容不碰撞。 - 每条有向关系都能在真实交付尺寸中从源对象连续追踪到目标对象；不存在需要猜测去向的共线、粘连或交叉路径，复杂回流已通过重新布线、曲线箭头或拆图消除歧义。 - 在上层 skill 规定的目标画布和适用视口中均无溢出、裁切或不可读文字。 - 风格保持纯白、少色、线宽层级清晰、无阴影，不抢夺正文注意力。 - 修改现有课件时，源文件、追溯文件、生成物和验证结果保持一致。