Communitygithub.com

等距SVG动画

通过构建脚本生成等距架构图的动画SVG。适用于需要等距或2.5D系统、管道或架构图、网站动画SVG流程图,或修改以此方式构建的图表时。

等距SVG动画 是什么?

这是一个用于生成等距(2.5D)架构动画SVG的技能。它通过一个Node.js构建脚本(`node build.mjs`),在**计划单位**中定义每个形状的位置,然后将其投影为等距视图,最终生成一个独立的`diagram.svg`文件(包含CSS关键帧动画,可作为普通`<img>`使用)和`preview.html`文件。该技能支持Claude Code、Cursor、Codex等AI编码代理。其核心理念是“一切由代码驱动”——没有任何手工绘制,每次修正都是代码变更和重新构建。技能文档提供了从故事构思、布局设计、静态构建到动画添加的完整工作流程,并详细阐述了内容、几何、文字、布局、线条、色调、动画和渲染成本等原则。它将几何逻辑(所有尺寸基于计划单位)与动画(CSS关键帧,根据路径长度计算时间轴)巧妙结合,确保最终输出专业、一致且性能优化的等距架构图。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/413ZERO/isometric-svg-animation/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

等距SVG动画 是做什么的?

一个脚本(node build.mjs)放置每个形状的计划单位,将其投影为等距,并写入一个独立的diagram.svg(内含CSS关键帧,可作为普通<img>播放)以及preview.html(嵌入相同SVG并缩放至窗口)。没有任何手工绘制:每次修复都是代码更改和重新构建。

在编写脚本之前,请阅读 references/generator.md:其章节,以及用于投影、卡片、地面文字、路径、关键帧、平台和组装的核 心代码。

步骤

  1. 故事。 阅读系统自身的文档,然后用一句话写出图表的故事:输入什么,处理什么,驱动什么,输出什么。流程从左下到右上读取。当流程中的每个阶段都是一个可以用一到三个词命名的节点,并且用户同意这个流程时,完成。
  2. 简报。 获取一张参考图片以了解风格(线宽、密度、平台样式);当用户没有时,展示 references/examples.md 中的图表,让他们挑选。确定主题、宽高比(1.6:1适合一个浏览器窗口)以及SVG将存放的位置。当所有四项都位于脚本的头部注释中时,完成。
  3. 静态构建。 平台、节点、路径、标签;尚无动画。当构建的审计报告显示没有重叠和没有过紧的转角,并且用户已签署布局截图时,完成。
  4. 动画。 添加循环。当一次循环按顺序讲述一次故事,并且减少动画显示已完成状态时,完成。
  5. 导出。 参见下面的导出。

每轮审查:逐一处理用户的笔记,在更改任何内容之前先回答问题,在进行大更改前将当前构建复制到 versions/ 中,并回复截图。当用户在名称或图标之间选择时,并排呈现选项。

原则

内容

  • 一个流程,少量细节。每个节点以其实际功能命名;当名称存在争议时,说明哪个准确以及原因,然后让用户选择。
  • 每个标签对陌生人来说都能独立理解。需要解释的标签将被重写或删除。
  • 只有真正是一堆东西(例如报告的书页)时才使用堆叠的板;其他每个节点都是单张卡片。
  • 诚实的旁路路径应该保留(跳过某个阶段的输入),即使它们占用空间。
  • 外部系统位于与内部系统相同填充色的平台上;仅用虚线边缘标记其为外部。
  • 松散的输入平放在地面上,下方没有平台。

几何

  • 到处都是计划单位:a 沿流程方向(屏幕右上),b 横跨流程方向(屏幕右下),z 向上。位置、大小、间隙和路径都是计划单位;屏幕像素只存在于投影中。
  • 一张卡片由一个顶面和一个侧面带(其顶部和底部轮廓的凸包)组成,外轮廓有一条描边,面与厚度相接处没有线条。平台则对其顶面进行描边,因为该面位于网格上。
  • 每个卡片和模块胶囊使用一种厚度。名称药丸平放,没有厚度。
  • 按层绘制(地面、平台、连线、对象、标签),每层内按深度排序。

文字

  • 每个标签位于地平面,其基线沿 a 方向。构建时字形被轮廓化为路径,因此SVG在任何地方作为 <img> 渲染效果相同,且无需加载字体。
  • 字体大小来自一个小的表格(药丸、标签、小号、说明、标题)。平台标题使用等宽大写字母,并留有间距。

布局

  • 地面网格为2个单位。平台边缘向外对齐到网格线;平台之间以及行之间的间隙为整数个单元格;共享的主干线位于其间隙中心的网格线上。
  • 平台自动调整大小:每个节点和标签将其占用的空间注册到其平台,平台就是该框加上一个统一的边距,并对齐到网格。一行中的平台共享其相对的边缘。
  • 平台标题距离左边缘和距离前边缘(测量到其大写字母的底部)的距离相同,与内容左对齐。
  • 网格延伸至框架的每个边缘之外,并通过一个具有框架宽高比的椭圆淡出,因此图片没有硬边缘。背景透明。
  • 每次构建都会打印一份审计报告:每个平台的四个边距、平台之间的间隙、标签与标签以及标签与卡片的重叠,以及对于其半径来说过紧的转角。在展示任何内容之前先阅读它。

线条

  • 每个连接都是一条连续路径:正交,转角处为四分之一圆弧,固定半径,因此共享一段的路径完全共享该段,分支沿切线离开主干。先绘制路径,再在其上绘制节点;结果没有短截线、分叉或间隙。
  • 线条类型通过图案区分:实线表示流程,虚线表示外部轨道,圆点表示只读访问。

色调

  • 色调即状态。 仅使用中性色(R = G = B)。浅色表示尚未到达,加深一级表示其输入已准备就绪,最深色表示本轮已完成。图标和轮廓遵循相同规则,因此任何“为什么这个更深?”都有其状态作为答案。最深的墨水是中暗灰色;避免纯黑色和实心暗色块。
  • 线条保持非常浅色,只有在光线沿其传播后才变暗。
  • 颜色表示当前正在工作:卡片保持白色,同时其下方隐约透出一丝品牌渐变,并带有微弱的辉光。灯光颜色取自沿流程铺设在整个图片上的一个渐变。
  • 某个阶段(例如,拾取输入)的强调色仅在点亮时显示,然后恢复到其休息时的灰色。

动画

  • SVG动画:SVG内部的CSS关键帧,无脚本,作为 <img> 播放。仅在要求时提供渲染视频。
  • 静止样式是运行完成后的状态;关键帧从每轮循环开始时未接触的状态开始。因此,减少动画和静态导出显示完整的图表。
  • 时间来自几何。 灯光以固定的屏幕速度(约400像素/秒)传播;每次到达时间为开始时间 + 路径长度 ÷ 速度,下一个事件是此次到达加上一个暂停。移动节点,时间轴也随之移动。在编写任何关键帧之前,计算整个时间轴以及循环长度。
  • 一个循环讲述一次故事:输入进入,驱动程序从上到下运行,各个部分汇聚,输出组装,导出,保持,清除,重复。速度足够慢以便跟随(约20秒)。
  • 一盏灯是一个沿其路径运行的短破折号,带有更柔和、更宽的辉光;在循环清除之前,其后方会留下一条更暗的痕迹。正在工作的节点会上升几个像素,发光,并闪烁其渐变面。

渲染成本

作为 <img>,任何正在运行的动画都会使浏览器每帧重新光栅化整个图片。

  • 保持遮罩、滤镜和组较小:网格通过其自身的描边渐变淡出,遮罩紧贴其揭示的路径。
  • 任何不可见的内容都设置为 visibility: hidden(透明度为0且偏移路径的破折号仍会被绘制)。
  • 相同的关键帧只编写一次。

导出

  • 静态PNG:在启用减少动效模拟的情况下打开SVG文档本身并截图。在 <img> 内部,模拟永远不会到达SVG,您将捕获循环的第一帧。
  • 预览存在于本地提供的独立页面中,位于用户站点外部,直到用户放置SVG。

相关技能