HTML图表与演示文稿 是做什么的?
此技能(一个代理技能:Claude Code、GitHub Copilot等代理均可读取)提供两个小型图形库、一个演示引擎、三个主题和三个模板。每个结果是一个HTML文件,GSAP缓存后可离线运行,遵循查看者的亮色或暗色主题,并可作为Claude Artifact发布。
| 路径 | 说明 |
|---|---|
lib/edgediagram.js | 声明式SVG图:zone、node、text、link(默认正交,带箭头、标签、数据流)、fan(一个点连接到多个节点)、bindFocus、steps,每个步骤均有布局检查 |
lib/edgesketch.js | 网格上的手绘图形:zone、box(自适应文本;垂直列和居中条)、arrow(直角,两个箭头)、connect(框到框)、fan、text;以及EdgeSketch.check,适用于任何SVG的布局检查,包含斜线和曲线 |
lib/icons.js | window.EDGE_ICONS:24单位网格上的50个线条图标(电网设备、计算、信任、运维) |
lib/edgedeck.js | EdgeDeck.run:1600×900幻灯片舞台,支持每幻灯片步骤、说明文字、键盘、滑动和#n链接 |
themes/*.css | 基于同一令牌约定的亮暗配色和字体主题:engineering(蓝绿灰背景,Archivo Narrow 和 IBM Plex)、indigo(靛蓝配薰衣草灰,Space Grotesk 和 Inter)、drafting(青绿配暖纸色,Barlow Condensed 和 Source Sans 3) |
templates/diagram.html | 带步骤的EdgeDiagram图形,包含说明文字、上一页/下一页按钮和圆点导航 |
templates/sketch.html | 手绘EdgeSketch图形:从左到右的区域、列、服务、双箭头、图例 |
templates/deck.html | 一张标题幻灯片加一张内容幻灯片,图形逐步构建 |
scripts/inline.py | 将库文件和主题内联到页面中,使其作为单个文件发布;如果找不到任何文件则报错 |
scripts/shot.sh | 无头截图(亮或暗,任意宽度,指定点击后,--only指定元素,--full整页)以及--check,对页面上的每个图形进行布局检查 |
scripts/todrawio.sh | 将构建页面中的一个图形导出为draw.io文件,以便在其中编辑:支持EdgeDiagram图形(带连接的链接)、手绘SVG图形、HTML图形 |
scripts/check_theme.py | 检查主题在亮暗模式下的WCAG对比度,并确保其两个暗色块一致 |
scripts/theme_from_design.py | 根据DESIGN.md文件(品牌的颜色和字体)生成亮暗主题,确保每对颜色的对比度 |
scripts/test.sh | 运行tests/中的测试;修改lib/、scripts/或themes/后运行 |
scripts/vendor.sh | 将库复制到另一个项目,--check显示副本是否落后 |
references/api.md | 两个库和演示引擎的每个选项 |
references/conventions.md | 令牌、每个色调的含义、布局规则、发布和要运行的检查 |
examples/ci-canary-deck.html | 一个完整的两张幻灯片演示文稿,主题为中性工作流(CI/CD,然后金丝雀发布) |
examples/isometric/ | 一个等距分层图形生成器(SGAM立方体),附带经验教训 |
examples/design-md/DESIGN.md | 一个示例DESIGN.md(Harbor),用于生成主题 |
工作流
- 确定图形要展示的内容。 命名机制、它所依赖的部分以及揭示的顺序。一个能更快说明问题的句子优于图形。
- 选择库。 由有意义的连线连接的部件图,逐步揭示:EdgeDiagram(
templates/diagram.html)。一个网格框、分层堆叠或从左到右的平台视图,其布局承载意义:EdgeSketch(templates/sketch.html)。演示文稿:templates/deck.html,其幻灯片上可使用任一库。 - 复制模板到工作目录,例如
cp <skill>/templates/sketch.html ./my-figure.html。修正<script src>和主题路径,使其指向<skill>/lib/和<skill>/themes/,或者最后使用--lib和--themes参数运行inline.py。 - 在网格上布局。 选择viewBox,然后是区域,接着是框(等大小,均匀间距),最后是连线(参见连接线)。将相互通信的框放在同一行或同一列,使其连线为一条直线。为有意义的链接添加
info。阅读references/api.md了解选项。 - 编写步骤(EdgeDiagram)。步骤0为静止状态。后续每一步添加一个概念并附带简短说明。使用
flows表示移动的数据,使用dim或hide表示步骤已过去的内容。 - 主题。 页面链接一个主题,
<link rel="stylesheet" href="../themes/engineering.css">;更改名称即可切换。engineering用于密集技术材料,indigo用于产品和软件交付,drafting用于类似文档的提案和研究。保持每个色调的含义(references/conventions.md)。如需品牌外观,从其DESIGN.md生成主题:python3 <skill>/scripts/theme_from_design.py DESIGN.md -o themes/<name>.css(examples/design-md/DESIGN.md为示例)。手动操作时,复制一个主题,保留所有令牌名称,更改值,并运行scripts/check_theme.py themes/<name>.css直至通过。 - 构建、检查并查看:
修复python3 <skill>/scripts/inline.py my-figure.html > build/my-figure.html <skill>/scripts/shot.sh --check build/my-figure.html # 每个图形;任何问题均退出并返回1 <skill>/scripts/shot.sh --only '#my-fig' build/my-figure.html /tmp/f-light.png light 1280 <skill>/scripts/shot.sh --only '#my-fig' build/my-figure.html /tmp/f-dark.png dark 1280 <skill>/scripts/shot.sh build/my-figure.html /tmp/sN.png dark 1280 'for(var i=0;i<5;i++)document.getElementById("next").click()'--check报告的所有问题。然后打开PNG文件,修复它无法看到的问题,例如偏离网格的框、碰撞的箭头或拥挤的标签,并在宽度420下再次查看。截图会冻结接近连线起点的数据包,因此在真实浏览器中判断运动。 - 按要求提供可编辑副本。
<skill>/scripts/todrawio.sh build/my-figure.html <svg id或选择器> out.drawio "名称"将图形的一个图形写入draw.io文件,采用亮色主题并显示在最后一步。说明其不支持的内容:运动、步骤、工具提示以及除矩形和椭圆之外的填充形状(它会打印出排除的数量)。 - 发布。 内联后的文件即为页面:将其作为文件共享、提交,或者在Claude中,提供给Artifact工具(重新发布相同的路径或URL以更新)。
连接线
连线是读者跟随的内容,因此必须看起来经过精心设计:
- 仅限水平和垂直。 永远不要使用对角线或曲线。EdgeDiagram链接默认是
ortho的:省略route。'straight'仅用于两端已对齐的情况,'curve'仅当用户要求时使用。在EdgeSketch中,使用s.arrow、s.connect和s.fan,它们以直角转弯。在手写的SVG中,使用H和V路径命令绘制连线,并仅圆角处理。 - 当框面对面时使用一条直线。 省略位置(
t),当两个框共享一个跨度时,EdgeDiagram或s.connect会自动将两端对齐。如果检查报告有几像素的偏移,移动框使两端对齐;不要微调t。 - 一个源连接到多个框应使用扇形连接,而不是一捆独立的线。
d.fan(id, {from: [src, 'bottom'], to: ['a', 'b', 'c']})或s.fan(src, 'bottom', [a, b, c])绘制一条主干、一个直角的总线和进入每个框的分支,每个连接点都有一个圆点。多个框连接到一个源则交换列表({from: [[...], ...], to: [...]}或{into: true})。 - 少拐弯,无交叉。 选择连线的两侧,使每条连线最多转弯两次。均匀分布共享同一侧的连线(
'auto')。绕开框走线,切勿穿过框。 shot.sh --check报告倾斜、弯曲和偏移的连线。像处理其他问题一样修复它们。对于故意例外的情况(例如等距图形),使用data-route="free"标记。
规则
- 请勿使用其他库。GSAP 3(来自cdnjs)是可选的:没有它,每个步骤都会显示其最终状态。
- 所有颜色均来自令牌,因此组件中绝不能包含字面颜色。
- 每个具有
info的节点、框或链接都应可通过键盘聚焦。SVG应具有role="img"和一个aria-label属性,说明该图形声称的内容。 - 宽度超过手机屏幕的图形应在自己的
overflow-x: auto容器内滚动,而不是在页面内。 - 确保内部名称、客户名称和地址不要出现在将要共享的页面中。