Skills 项目 `illustration-teal-spot`：用 teal3d.mjs 生成青白双色 3/4 视角 SVG 插画卡片的完整指南-育师

【免费下载链接】Skills

Agent skills for designers and builders using Codex, Claude, Cursor, and other AI coding agents

项目地址：https://gitcode.com/gh_mirrors/skills48/Skills

本指南讲解 Skills 仓库中agent-skills/illustration/illustration-teal-spot这套 Agent Skill：如何用一套无依赖、可复现的 Node 生成器teal3d.mjs，把"键盘、数据库鼓、Git 提交图、收件箱"这类设计与编程概念画成单主体、青白双色的 480×360 SVG 卡片，用于空状态、功能插画与引导步骤等无人物场景。读完你将掌握 11 色严格调色板、固定斜投影相机、硬阴影、凹陷/凸起结构与浮动装饰的完整画法与可脚本化生产流程，并能复制配套的生成器直接产出自己的卡片。

这套风格解决什么问题

illustration-teal-spot的定位是"把一个对象放大到卡片尺寸的产品图标"：浅灰卡片上只有一个像小实体模型一样的主体对象——白色主面、青色侧面、利落的深色描边、一块向右下方硬投的深青阴影，外加几个悬浮小道具暗示动作。它被明确指定用于空状态（empty state）、功能插画（feature spot）、引导步骤（onboarding step）以及 404 / 错误插画、博客头图、营销卡片、产品图标场景，核心约束是"一个强对象，没有人"。

它在同一仓库的插画体系中做了严格边界划分（见 SKILL.md）：

需要 6–8 个对象、带柔光平台的完整等距场景时，改用illustration-isometric-mono；
需要表现人物工作时，改用illustration-framed-panel或illustration-outlined-cartoon；
需要高饱和多色簇状构图时，改用illustration-bold-pop。

这套风格来自一组 42 张原创设计与编程概念卡片（14 种风格）中的子集，examples/目录下的三张 SVG 就是它的出厂卡片（command-k.svg、git-merge.svg、backup.svg），由盲评评委对照商业插画包打分而来，是检验"同手笔、同系列"的基准。

风格一句话定义

一个白色对象采用固定斜投影，只有右侧面是青色，全部边缘用 1.2px 深青色描边，通过一块从不模糊、永远向右下方投射的深青色硬阴影"落"在浅灰卡面上。

这句话同时是 style.json 中mechanism字段的原文，也是整套生成器的约束总纲。

调色板：11 个颜色，别无其他

调色板从三张示例卡片中实测提取，共 11 色，每色的用途都已固定（与 style.json 的palette数组一一对应，也对应 teal3d.mjs 顶部的C常量）：

角色	Hex	用在哪里
卡片背景	`#ebebeb`	满幅矩形，其余什么都不用
Ink	`#0e3f3d`	所有描边、浅色面上的字形笔画
Deep teal	`#0e4a48`	所有硬阴影、星光、深色字形、青色件的右侧面
Teal dark	`#299c96`	青色件的前/左面、凹槽壁
Teal	`#36c3b0`	白色件的右侧面、强调件顶面、LED、高亮 UI 行
Mid teal	`#7fd8ca`	浅色件的侧面、凹槽地板、硬币侧面
Pale-mid	`#a8e5e0`	仅弧线刻度
Pale teal	`#d8f2ed`	键与卡片的侧面、白色面上的高光条、搜索框
White	`#ffffff`	主体的顶/前/左面、卡片顶面、青色面上的字形
Grey	`#d5d8d8`	标签胶囊、占位文字条、开关柄
Grey dark	`#b9c0c0`	小型灰色件的右侧面

三条硬性纪律：

无渐变、无透明度、无滤镜、无模糊、无<text>——字母与数字一律是描边路径；
白色面占对象视觉主体，如果青色覆盖超过主体可见面积约三分之一，就不属于这套风格；
Deep teal#0e4a48只以阴影或星光的形式接触灰背景，永远不作主体的面。

源码层面，lint.mjs --palette style.json会把 SVG 中出现的所有十六进制色与style.json比对，偏离调色板即输出 WARN，这套风格要求零 WARN（lint.mjs）。

线条与填充：描边宽度、面着色与高光

描边规则

描边色统一#0e3f3d，480 宽度下主体用1.2px，stroke-linejoin="round"，开放折痕用圆头线帽；
卡面上的小型 UI 部件（按钮、图标）用 1.0–1.1px，并加vector-effect="non-scaling-stroke"——否则mat()面变换会拉伸内部描边；
LED 与极小的点用 0.8px；
轮廓是画在平涂填充之上的三类线：实体的剪影包络、顶环、以及两色面交界处的竖向折痕；单个平面内不画内部轮廓线。

板块的 stroke-behind 技巧

盾牌、云朵、条状物这类薄板块（slab）采用"描边垫底"画法：每个侧面四边形先用 Ink 填充并以2.9px描边，再以侧面颜色自描 0.5px 重填，最后正面以 1.2px 轮廓收尾。这就是示例 SVG 里stroke-width="2.9"大量出现的原因；源码在 teal3d.mjs 的slab()中实现：2 * lw + 0.5 = 2.9。

分面着色：一阶色调，永不用渐变

每种部件的顶/前/左/右面各有固定色，规则如下（SKILL.md 原文表格）：

部件	顶（盖）	前、左、后	右面
主体	白	白	teal`#36c3b0`
浅色件（键、UI 卡）	白	pale`#d8f2ed`	mid`#7fd8ca`
强调件（按钮、分支圆盘）	teal	teal dark`#299c96`	deep`#0e4a48`
硬币（数据令牌）	pale	mid	teal
强调硬币（徽章、计数）	teal	teal dark	deep
小型凹槽（插座、井）	（开口）	壁 teal dark	地板 mid
大型开放凹槽（托盘，超过顶面四分之一）	（开口）	壁 mid	地板 pale

这套"按朝向取色"的机制在源码中由sideKey()（teal3d.mjs）实现：法向量 z>0.62 判为上（up），再按方位角把侧面切成 front/right/back/left 四个朝向；solid()据此为每段可见侧面 run 填色，并在 run 之下先垫一块基色填充，防止 2 倍放大时侧面颜色交界处出现 1px 灰缝（这也是 craft.md 的高清检查项）。

字形与高光条

字形：青色面上用白色（宽 2.8–5），白色/浅色面上用 deep 或 ink（宽 2.4–2.8），一律圆头线帽圆角连接；平印在平面上的细节（如井底标记）是带 1.0–1.1 ink 描边的青色圆盘或圆角方加白色字形；
高光条：两段短划（一长一短，间隙约为边长的 6%），宽 2.2（小件 1.8–1.9），圆头，画在白色前面上边缘下约 8 单位处，色用 pale#d8f2ed；青色面上改用 teal 或 mid。每面最多一条，整卡最多四条。源码对应streak()（teal3d.mjs），默认两段比例为[0, 0.78]与[0.84, 0.95]。

阴影：永远硬、永远向右下

所有阴影都是平涂#0e4a48形状（自描 0.6px 封口防止接缝）：

地面阴影：把落点轮廓按SHD = [0.78, -0.48]（世界单位/每单位高度）向右下推出，源码常量在 teal3d.mjs，floorShadow()计算凸包；
悬浮道具：用该道具的屏幕轮廓整体偏移(8.5, 7.6) px（常量FSH），对应liftShadow()（teal3d.mjs）；
立于某面上的部件：用castShadow(pts3, z, 0.6)把世界点投到它站立的表面（如 Git 图圆盘投到瓦片顶面），k=0.6 与示例一致；只对真正接触该表面的部件使用，悬浮板投到远处地面会变成一条细长暗条。

角色塑造：一个实体对象，不要散件

这套风格没有人物、手、脸，主体对象顶替了它们的位置，四条塑造原则：

一个实体对象：主题必须是一个可触摸的物理物（瓦片、鼓、键盘壳）。本质是"图表"的想法（Git 图、流水线）要架在或嵌入一个实体上，绝不能散成一地零件——Git Merge 第一版就是散落的环和管，只得了 7 分，把同一张图装进一块厚白瓦片后升到 8 分。
真实厚度：主体高 28–40 单位，键与卡 8–14，硬币 5.5，板块 7–8；圆角半径：主体 18–24，键与卡 4–9。
正面细节就是产品细节：一条高光条、一个灰标签胶囊（26–30 × 4.4，半径 2.2）、一个靠近顶沿右前方的青色 LED（4.6–5 圆，0.8 描边）。把平面形状贴到深度为 D 的盒体正面上时，用pr([x, -D / 2 - 0.05, z])映射 (x, z) 点；贴到顶沿用pr([x, y, H + 0.01])。
给泛型形状一个"身份特征"：普通圆角盒只读作"一个盒子"，必须加能命名对象的那一个特征——键帽之于键盘、凹槽之于数据库鼓、指槽之于信件托盘（scoop()）、卡槽之于读卡器。

装饰与道具：悬浮件、星光与弧线刻度

悬浮额外件 2–4 个，每个都是同一投影下的小实体：倾斜 UI 卡（约 84–114 × 50–58，厚 8–9，向后倾斜 28°）、硬币（半径 17–19，面上有数字或图标）、立式板块（盾牌、云朵、信封，深 7–8）。每个都投自己的硬阴影（偏移 8.5, 7.6）或在下方留一个小地面椭圆（半径 10–17）；
星光每卡 3 个，deep teal 的四点凹星：一个大号（6–7）配一个小号（3.6–5，距它 12–16px）放在某个额外件旁，另一侧额外件旁再放一个单独的小号（4–5）；
弧线刻度 0–3 条：20–40° 短弧贴在悬浮件半径 +7–9 处，宽 3.4–3.6，pale-mid 或 teal，语义是"它刚动过"——Backup 卡 0 条，Command K 在弹起的两个键周围有 3 条；
卡片上的 UI 内容：4.4 高半径 2.2 的灰条；一条 teal 高亮行（半径 4–6）配白条；半径 4 的 teal 小方图标配白色字形；
永不出现：人物、植物、作为背景涂鸦的轮廓云、地面线、整场景平台、文字标签、光晕。

源码中spark()与arc()是屏幕空间函数（teal3d.mjs），在card()完成整体居中后、以卡片坐标系放置，因此不参与包围盒计算。

构图：480×360 的黄金位置

背景：一个无rx的方形满幅<rect width="480" height="360" fill="#ebebeb">；
整组（主体、阴影、额外件）以包围盒中心 (240, 181) 居中，宽度占卡58–90%，高度占58–75%，四边留白至少 30px；主体本身约占卡宽的 55%；
主体略低于中心；额外件绕行于左上、右上、左侧空隙，保证没有象限空置、任何东西不碰到主体轮廓；
额外件错落不同高度（一个高、一个与主体沿齐平）；三个同一高度的额外件排成一行会读作"工具栏"而非散点；
包围盒包含所有额外件，每移动一个额外件向外，主体就会因重新居中而缩小——card()每次移动后打印宽度百分比，保持在 90% 及以下；
硬地面阴影属于剪影的一部分：在底座右下方延伸 20–60px，是对象"锚地"；
每个示例文件的结构固定为：<rect id="P-bg">→<g id="P-scene" transform="translate(TX TY)">（装载所有投影内容）→<g id="P-decor">（星光与弧线，卡片坐标）。card()源码在 teal3d.mjs。

技术内核：teal3d.mjs 的五件武器

所有技法都来自scripts/teal3d.mjs（源码全文），零依赖、完全确定性——同样的输入永远得到同样的 SVG，这对 Agent 可重复生产至关重要。

相机：全场景只用一个正交相机makeCam({ TH: -25, PH: 36, S })，S取 0.84–1.05 缩放。世界坐标约定：+x 指向屏幕右下，+y 远离观察者（右上），+z 向上；因此盒子显示顶面、长正面（法向 -y，左下）与短右面（法向 +x，右下）。不要手画"大概等距"的盒子——面会偏离平行，整套风格就崩了。投影实现见 teal3d.mjs，所有投影点收集进cam.BOX供card()居中。
实体与板块：solid({ fr, r0, z0, r1, z1, col })在两个环（rrect/circle）之间拉伸并按键朝向分色，键帽就是给一个更小的顶环；slab({ fr, pts, depth, face, side })拉伸任意平面轮廓（盾、云、信封）并自带.shadow()；mat(fr, z)把平面 2D 图案映射到面上（<g transform="${mat(fr, z)}">…字形…</g>）。solid()的完整实现见 teal3d.mjs。
硬阴影四连：见上文四种阴影的用法代码块，顺序是"地面阴影 → 主体 → 面细节 → 凹槽 → 凹槽内零件（后到前）→ 每个额外件先阴影后本体 → 装饰"（SKILL.md 的 Draw order）。
凹槽与井：recess({ ring, z, depth, id })在顶面开一个口（teal-dark 壁、mid 地板、裁剪），大托盘传wall: C.mid, floor: C.pale；well.onFloor(art)把图案裁剪到可见地板；坐在里面的零件在其后按dot(centre, cam.V)后到前绘制；scoop({ xa, xb, depth, y0, y1, zTop })在前壁上切一道浅弧，露出地板色、内面按朝向规则取色、两侧边缘上墨（teal3d.mjs）。
装饰：spark(x, y, size)与arc(cx, cy, r, a0, a1)，放在card({ prefix, scene, BOX, decor })移交的位移后包围盒锚点上。

圆环（torus().piece()）与扫掠管（tube()）用于环和管道：先画环的后半，再画穿过它的零件，最后画环的前半。当管轮廓自交时工具会打印[fold]警告，把管缩短或加粗直到消失（自交检测selfX与解缠untangle见 teal3d.mjs）。

常见失败模式（评审复盘）

SKILL.md 总结了 12 条由实战与自测得出的失败模式，是产出质量的最短教训清单：

散件读作图表而非 spot（Git Merge 7→8 分案例）；
青色正面属于另一套风格（Command K 早期青色机壳正面被否决，最终正顶白、仅右侧青）；
太薄的阴影读作描边而非投影（Backup 的地面阴影抛光时放大约四分之一，确保最宽处 ≥15px）；
两个方向的阴影破坏光照——所有阴影必须只向右下，永远不要为了平衡版式镜像一个；
侧色之间出现发丝接缝——保留solid内置的基色填充；
倾斜面上的 UI 描边被剪切变形——加vector-effect="non-scaling-stroke"；
管道轮廓打环成燕尾——减小弯度或半径；
装饰杂乱——背景轮廓云已被砍掉，装饰就是三个星光加至多三条弧线；
大青色洞把主体变成青色（Inbox Zero 自测）——大型凹槽要逐级变浅：壁 mid、地板 pale；
普通容器不自我介绍（自测的信件托盘）——前壁切指槽后 1 倍尺寸下才读出"信件托盘"；
悬浮板的投影变成游离暗条——悬浮件一律用 (8.5, 7.6) 屏幕偏移；
额外件碰到主体——额外件（含阴影）与主体剪影之间至少留 12px 灰。

三个出厂示例：每种技法的实物标本

Command K（command-k.svg）：键盘壳带内嵌键槽；⌘ 键（teal）与 K 键（pale）浮在空插座上方，命令面板卡斜悬其上。展示凹槽、小顶环键帽、作为阴影的插座、倾斜 UI 卡；
Git Merge（git-merge.svg）：厚白瓦片驮着方条 Git 图；青色分支拱起穿过升起的提交圆盘并入合并圆盘。展示投在瓦片顶面并被裁剪的阴影、提交圆盘、PR 卡、带地面椭圆的提交硬币；
Backup（backup.svg）：三盘数据库鼓套救生圈（torus 分白/青两段），配盾牌勾选板块、云上传板块与两枚数据硬币（1 和 0）。展示带凹槽的圆柱、前后两半绘制的圆环、投在鼓上的阴影、立式板块。

完整工作流：从 Brief 到交付

在 skill 文件夹下运行命令（WORK是任意工作目录，产物为$WORK/card.svg，id 前缀xx-）：

Brief：写下主题与承载它的唯一对象，一行说明——主体对象、会动/会翘起的零件、2–4 个支撑主题的额外件。如果主题是流程，找出"装下它"的物理对象；
搭建生成器：
```
mkdir -p "$WORK" && cp scripts/teal3d.mjs scripts/starter.mjs "$WORK/" && mv "$WORK/starter.mjs" "$WORK/gen.mjs"
```
把P改成你的前缀并改label（starter.mjs 自带一个完整的极简示例卡，注释了每一步技法与其绘制顺序）；
只堵主体：仅用solid和slab搭轮廓（不画细节），渲染后在 1 倍尺寸下检查剪影与阴影可读性；
细化：画面细节、凹槽、翘起件，再画额外件与装饰，严格遵守上文 Draw order；
渲染（无头、2 倍）：node "$WORK/gen.mjs" "$WORK/card.svg" && node scripts/render.mjs "$WORK/card.svg" "$WORK/card.png"；
与示例并排：node scripts/render.mjs --sheet "$WORK/sheet.png" examples/*.svg "$WORK/card.svg"，问"同一只手、同一系列？"：面颜色、描边粗细、阴影方向与大小、白色占比；
放大检查（从矢量重渲染，绝不放大位图）：node scripts/render.mjs "$WORK/card.svg" "$WORK/z1.png" --zoom x,y,w,h --scale 8，查色面交界折痕、凹槽边缘、面上字形、每条阴影边缘；
评审：对照 references/craft.md 的五项评分（风格保真、角色绘制、姿态与实体感、构图、主题清晰与工艺，各 0/1/2 分，标准 8/10），其中第 2 项在本风格中变成"主体对象的构造：厚度、圆角、产品细节、零件可信度"。修复重来，预期三轮以上；
Lint：node scripts/lint.mjs "$WORK/card.svg" --prefix xx- --palette style.json，修掉每个 ERROR；本风格要求调色板零 WARN。

references/craft.md（全文）还持有适用于所有插画风格的文件契约（单文件自包含 SVG、viewBox="0 0 480 360"、禁<style>/<class>/<script>/<image>/<foreignObject>、短 id 前缀防冲突、满幅背景无rx）、原创性规则（禁止描摹参考图、禁止复用其姿态/道具/版式）与评审纪律（同一渲染两位评委取低分、对照只显示一个版本、修手只动手）。评审循环同样是无头渲染：绝不打开可见浏览器窗口检查卡片。

交付前验证清单（Agent 自查）

SKILL.md 末尾的勾选清单即最终验收标准，逐项对照：

背景是单个无rx的#ebebeb满幅矩形，卡片边缘无其他东西；
恰好一个主体对象；无人物、植物、平台、地面线；
每面平涂：主体顶/前白、右侧青；浅色件浅侧 + mid 右侧；
所有描边#0e3f3d1.2（UI 1.0–1.1，LED 0.8），无其他颜色描边；
每个阴影平涂#0e4a48且向右下；地面阴影最宽处 ≥15px；
每个悬浮额外件自带同向硬阴影或地面椭圆；
2–4 个额外件、3 个星光（一大一小成对 + 单个）、0–3 条弧线；
组包围盒约在 (240, 181) 居中，宽占 58–90%，留白 ≥30px；
每个白色正面一条高光条（长划 + 短划，pale，2.2）；
字形与数字为圆头描边路径，无<text>；
8 倍放大下侧色交界无发丝缝、填充与描边无缝隙；
只出现 11 个调色板颜色（lint.mjs --palette style.json无 WARN）；
1 倍尺寸、无说明文字也能读出主题。

对 Agent 的最终提示（来自 demo/PROMPT.md）示例：Use $illustration-teal-spot to draw a 480x360 SVG card of a white password vault with its teal dial turned, for an empty state about saved passwords.——一句话即可唤起这套完整的、可验证的风格契约。