等轴测图(线条风格) 是做什么的?
你将一个简短的需求("画廊等轴测图"、"空收件箱状态")转化为一个绘制并带有动画的对象,作为一个完整的状态组件交付:包括插画、标题、一行描述文字和一个按钮。每个对象都由 3D 基本图元在世界坐标系中构建,并通过真正的等轴测投影呈现,因此它与使用本技能创建的所有其他对象共享同一个网格、轮廓和外观。
外观,用一句话概括:一个对象,若为扁平对象则正面展示,若为立体对象则以真实等轴测角度展示;1 像素轮廓,纸白色表面,一个品牌色小标记,无阴影,无发光,一段动画,然后归于静止。
你不能跳过任何阶段。在检查器通过并且你审视了其图纸之前,你不能认为一个对象已经完成。
目录
| 文件 | 何时阅读 |
|---|---|
SKILL.md | 始终阅读:工作流程和规则 |
references/brief-to-concept.md | 阶段 1–2:将模糊需求转化为三个概念 |
references/motion.md | 阶段 4:选择和编排动画节奏 |
references/line-style.md | 阶段 3–5:所有绘图规则、注意事项及其原因 |
references/engine-api.md | 构建过程中:引擎和线条工具包 |
references/isometric-math.md | 当形状需要引擎未提供的数学计算时 |
examples/*.tsx | 构建之前:从最接近的示例开始 |
engine/iso-core.tsx, engine/iso-line.tsx | 每个项目复制一次 |
scripts/check.mjs | 阶段 5:严格的渲染检查 |
设置(每个项目一次)
这些对象是适用于使用 Tailwind CSS 和 shadcn/ui(它们使用 @/lib/utils 的 cn 和 @/components/ui/button)以及 motion 包的 React 客户端组件。
-
检查是否存在
components/isometrics/iso-core.tsx。如果缺失,将本技能中的engine/iso-core.tsx和engine/iso-line.tsx复制到components/isometrics/目录下(或用户偏好的文件夹;对象会相对导入它们,因此它们应位于同一文件夹中)。 -
如果项目没有
motion:安装它(npm i motion,或使用项目的包管理器)。如果没有 shadcn 的 Button:运行npx shadcn@latest add button。 -
对于检查器,需要 Playwright:
npm i -D playwright和npx playwright install chromium(或者它可以使用已安装的 Chrome)。 -
创建一个用于单独渲染一个对象的页面,并用
PlayOnHover包裹(检查器通过悬停来触发动画),例如在 Next.js 中的app/isometrics-preview/<name>/page.tsx,或项目中路由器的相应路由:import { PlayOnHover } from "@/components/isometrics/iso-line"; import { MapPin } from "@/components/isometrics/map-pin"; export default function Page() { return ( <main className="flex min-h-svh items-center justify-center p-10"> <PlayOnHover><MapPin /></PlayOnHover> </main> ); }为每个对象创建这样的页面;告知用户这是一个预览页面,可以删除。
永远不要为了适配单个对象而编辑引擎。如果确实缺少某个形状,在对象自身的文件中添加一个基于 3D 构建的辅助函数,并告知用户。
工作流程
阶段 1 · 理解需求
在开始任何工作之前,将请求转化为三个答案:
- 主题: 事物或话题("画廊" → 照片、相册、图片)。
- 用途: 服务的状态:空(这里还没有任何东西)、阻塞(无法访问、关闭、未连接、未找到)、未找到任何内容(搜索、筛选)、成功/全部清除,或功能卡片中的 局部 插画。
- 信息: 该状态说的一句平实的句子("你还没有任何照片")。
如果用途未明确说明,需求通常可能对应多个状态;这正是概念阶段需要做的事情。请参阅 references/brief-to-concept.md。
阶段 2 · 三个概念,然后等待
除非需求已经明确指定了一个对象和一个状态,否则向用户展示三个概念的表格,并停下来等待用户的选择:
| 对象 | 信息(标题) | 一段动画 | |
|---|---|---|---|
| A ★ | … | … | … |
| B | … | … | … |
| C | … | … | … |
每个概念必须通过全部四项测试:
- 缩放到 120 像素时轮廓可辨认。 人们不用看颜色就能识别的剪影。
- 圆润优于方正。 在线条风格中,圆润的对象读起来更友好;普通的方框读起来像个包裹或线框。
- 单个对象。 不是场景,也不是一堆。只有当第二小部分从属于整体对象(如盖子、旗帜、手)时才是可以的。
- 动画传达信息。 动画是句子中的动词(参见
references/motion.md)。如果你无法命名这个动画,那说明对象选错了。
用 ★ 标记你的推荐,并用一行说明理由。确保三个概念有所变化:不同的对象、不同的动画。当需求很具体时("一个带托盘的收件箱空状态"),跳过表格,说明你的选择及动画,然后继续进行。
阶段 3 · 将对象分解为部件
在编写代码前,用世界坐标系单位创建一个部件表格:每个部件,它由哪个图元构成(Extrude、Slice、Ring、FacePath、Box…),其在 0.5 网格上的尺寸和位置,是否移动,以及哪个部件是品牌标记。然后是文案:标题(不超过 28 个字符)、一两句描述、按钮标签(不超过 22 个字符)及其图标(图标应遵循动词含义:只有在操作是添加时才使用加号)。
决定部件的规则(全部在 references/line-style.md 中):
- 首先选择视图。 扁平或薄的对象(如页面、徽章、磁盘)使用
view="front";立体或厚的对象(如打印机、盒子、服务器、托盘、桌子上的棍子)使用view="isometric"。正面视角的方框会像带有双重线条的扁平贴纸。 - 构建时面向 +y 方向,关于 x=0 对称,立于 z=0 平面。
- 三个细节层级:外形、人们用来识别它的部件、以及安静标记(如螺丝、通风口、接缝、标签)。
- 线条整洁:正面视角的实体没有深度,或具有明确的深度(条带厚度 ≥ ~4 像素);一个部件要么齐平,要么突出 ≥ 0.5;圆形堆叠共享同一个半径和一条接缝线。
- 扁平物体(如纸张、标签、屏幕)是面,而不是实体。
- 圆形实体是水平圆圈之间的切片,从底部向上绘制。
- 非凸起轮廓需要绘制其远边。
- 从外壳中滑出的部件应在外壳处切割,而不是悬浮。
- 一个品牌标记(调色板
main);其他所有部分均为纸色(surface)。
阶段 4 · 选择并编写动画
从信息中选择动画(references/motion.md),然后在文件顶部绘制代码之前编写故事板注释:时间、移动什么、移动多远、为何这样移动。每个值都使用命名常量。动画在插画滚动进入视野后延迟 400 毫秒开始,持续 1.2–2.4 秒,仅播放一次。当用户的代码传入 active 时,它会在每次 active 变为 true 时播放(延迟 80 毫秒),不会自行播放。减少动画模式显示静止的结束姿态。
阶段 5 · 构建、渲染、检查、审视、修复
-
从
examples/中最接近的示例开始(参见下文表格)。保持其结构:故事板、TIMING、几何体、轨迹、姿态、部件、LineState。 -
在其预览页面上渲染它并运行检查器:
node <skill>/scripts/check.mjs http://localhost:3000/<preview-path>/<name> --duration <wait+beat ms>它会在明亮和暗黑模式下渲染,通过在插画上悬停并在一个假时钟上触发动画来播放(因此预览页面必须使用
<PlayOnHover>包裹对象),在动画的 0%、25%、50%、75%、100% 及之后保存帧,并检查:- 在明亮、暗黑和减少动画模式下,没有 hydration 或控制台错误;
- 当传递
active时播放动画,且插画内部没有按钮; - 动画结束时精确回到其静止姿态;
- 减少动画模式下保持静止,显示静止姿态,忽略
active; - 每个轮廓大约 1 像素;没有滤镜、发光、阴影或渐变绘制;
- 静止绘制的画面适配其容器;
- 绘图相对于标题居中,偏差在 2 像素以内;
- 线条整洁:在 4 倍放大下的暗黑模式中,持续的双重线条(长度方向上相距 0.5–2 像素的两条线)不超过轮廓总长度的 6%(线条交汇处的小点不计入),记录在
lines.png中,双重线条在lines-marked.png中以红色标记; - 其视觉尺寸符合设定的范围(√(宽×高) 在 140–175 像素之间)。
-
查看
sheet.png和lines.png(二者都打开)并逐一检查下面的清单。检查器无法看到设计问题;但你可以。 -
修复并重新运行。 最多三轮。如果三轮后仍有不足,停止并明确告知用户是什么问题,同时提供图纸。
-
报告: 概念、故事板、检查器结果、你在审视后修复了什么、仍然存在的不足、以及图纸的路径。
审视图纸:检查清单
可读性
- 没有标题的情况下,一个陌生人能否在缩略图大小下认出这个对象?
- 没有任何东西看起来像一个偶然的人脸(两个圆形部件位于曲线之上)。
- 品牌标记是一个小部件,并且是眼睛应该停留的部分。
静止笔直
- 在静止状态下,每个竖直部分都是垂直的,每条边都是水平的;没有东西倾斜,没有东西歪斜地悬挂着,第二张纸是偏移的,而不是旋转的。
- 静止姿态与减少动画姿态相同(检查器比较像素;你需要检查它看起来是有意为之的)。
线条(查看 lines.png:暗黑模式,4 倍放大)
- 所有地方的轮廓线粗细一致;没有双重边线、没有填充之间的发丝接缝、没有曲线轮廓上缺失的远边、没有填充物突出到轮廓之外、没有线条在空中结束。
- 每个部件要么齐平,要么明显突出(≥ 0.5);没有细条。
真实感
- 正确的视图:扁平物体正面展示,立体物体等轴测展示。
- 三个细节层级:外形、可识别的部件、安静标记。拥有此物的人会说“是的,那是一台打印机”吗?
- 顶部条带(从 30° 俯角看到的厚度)存在于实体上,而扁平面上没有。
动画
- 动画传达信息;每个动作都由前一个动作引发(延迟、跟随、稳定)。
- 铰接部件绝不会摆过其外壳;末端绝不会越过静止位置;摆动幅度很小(悬挂部件 ≤ 6°,翻盖部件 ≤ 25°)。
- 没有淡入或淡出效果;出现的事物通过缩放从小变大。
适配页面
- 相对于文案居中;框架内没有填充死空间。
- 在暗黑模式下看起来正常:纸色面变为深色纸色,品牌标记保持品牌色。
不再重犯:本技能曾犯过的错误
以下每个错误都曾交付过一次,在审查中被发现,并成为了一条规则。在报告一个对象之前,请对照每一条进行检查。
| 错误 | 现在的规则 |
|---|---|
| 正面视角绘制的方框看起来像扁平的贴纸 | 首先选择视图:扁平物体正面,立体物体使用 view="isometric"(line-style.md) |
| 薄的顶部条带、仅微微突出的部件和阶梯状圆环绘制出了双重、脏乱的线条 | 没有细条;要么齐平,要么突出 ≥ 0.5;圆形堆叠使用统一半径;检查器的整洁线条测试必须通过,并且你需要查看 lines.png(暗黑模式,4 倍放大) |
| 对象仅仅是轮廓(“不够真实”) | 三个细节层级:外形、可识别的部件、安静标记 |
| 集合中对象的尺寸跳跃不定 | 通过 defaultArtClassName 确保视觉尺寸在 140–175 像素之间 |
| 页面飞出框架 3 个单位 | 动画限制在插画的空间内;至多超出边框一点 |
| 两个卡扣、一条全宽条纹作为“一个品牌标记” | 一个真正的小标记 |
| 圆点上的槽、接缝上的两个卡扣看起来像一张脸 | 在缩略图尺寸下检查是否出现偶然的人脸 |
| 朝向观看者的角落翻转在正面视角中不可见 | 朝向观看者的转动即使角度很小也难以察觉;优先选择画面平面内的移动,否则需要大幅度转动(motion.md) |
| 在其平面内倾斜的页面在等轴测视角下发生了剪切 | 在等轴测视图中,只能围绕部件自身的法线或边缘上的铰链旋转部件(motion.md) |
| 一个部件在首次播放时闪现了一帧其起始姿态 | 由 clock 状态驱动的部件在剪辑切换时重置,并在停止时保持静止姿态(engine-api.md) |
| 薄的托盘壁看起来像薄塑料 | 坚固的墙壁需要厚度(≥ 0.5);薄面仅用于纸张 |
| 每个对象单独看起来不错,但放到一起就不协调了 | 在报告前,将整个批次并排审视,同时检查明亮和暗黑模式 |
| 铃铛体、U 形环、指针在曲线部分绘制了双重轮廓 | 正面视角下,弯曲部件是一个扁平的面(或一个明确有深度的面);给指针平行的边,绝不使用锥形 |
| 在玻璃轮廓上绘制的沙子形成了一条粗的污迹 | 内容物应位于内凹墙壁内部,绝不能绘制在容器的轮廓线上 |
| 比其盒子突出 0.25 的门使拱形加倍 | 与开口形状相同的门在静止状态下共享一个轮廓 |
| 在等轴测视图中 32° 角的保险柜门看起来像侧边视图 | 等轴测图中的门和盖子打开约 24–26°,以便其正面仍可辨认 |
| 钥匙环悬在钥匙上方,而不是穿过它们的孔(“环不在钥匙环内部”) | 穿过的部件相互交织:环在其孔的一侧穿过每个部件的后面,在另一侧穿过前面(line-style.md) |
| 将对象缩小到其尺寸后,双重线条再次出现 | 先设置默认宽度,然后为绘制得小的对象确保条带厚度 ≥ 0.5 |
| 一个“!!!”徽章未能通过线条检查 | 将标记绘制为具有明确间隙的形状;避免使用文字中的空格类字形 |
不可协商的规则
- 只能用真正的等轴测投影。 轴相对于水平线成 30° 角,彼此成 120° 角,等比例缩放。绝不使用 2:1 的“游戏”投影(26.565°)。
- 几何优先。 以世界坐标系单位放置基本图元。绝不手动编写投影后的屏幕路径。
- 单一网格。 位置和尺寸基于 0.5 世界单位;面部细节基于 0.25 世界单位。
- 统一外观。
variant="ink"(默认)或"line";绝不在一个对象中混合使用外观。1 像素轮廓,纸色墙壁,无阴影,无发光,无渐变。 - 从主题令牌获取颜色。 颜色仅来自用户的 shadcn 主题,通过
--iso-*变量获取。对象文件中不使用十六进制或 oklch 颜色值。品牌标记遵循tone(默认为primary)。 - 使用属性,而不是分支。 文案、色调、变体、笔画宽度、动画开关等都是带有文档注释的属性(
LineStateProps)。绝对不要将内容属性命名为title:它是无障碍名称。 - 可访问且可嵌入。 插画是装饰性的,除非提供了
title