motion-skill-kit：给 AI 编程助手装上前端设计能力

motion-skill-kit：给 AI 编程助手装上前端设计能力

从页面层级、布局、排版与配色，到极光背景、滚动叙事和艺术风格套件，我把这些能力组织成了一套可以检索、复用、校验和持续扩展的 Agent Skill。本文完整介绍 motion-skill-kit 的功能、架构、接入方式和工程取舍。

项目地址：ergou-yu/motion-skill-kit

本文基于v1.2.1，功能与代码核对日期为2026 年 10 月 21 日。对应代码快照：e7367d8。

一、为什么要把前端设计做成一套 Skill？

使用 AI 编程助手开发页面时，一个常见的问题是：代码结构基本完整，页面也能运行，但视觉效果总是差一点。

这种“差一点”往往能拆成具体问题：标题、说明和操作的权重接近，看不出重点；表单留白很多，却分不清帮助文字属于哪个字段；品牌色被用于每一个按钮，主要操作反而不突出；桌面端看起来整齐，到了中间宽度就开始挤压；加上动效之后，页面更热闹，任务却没有更清楚。

如果只给 AI 一句“做得高级一点”，它需要同时猜测内容层级、设计气质、组件状态和动画强度。下一次换一个页面，这些判断又可能从头开始。

我的做法是，把可复用的设计判断和代码实现放到同一个工作流程里：

1. 用设计参考说明应该先解决什么问题。
2. 用结构化索引找到合适的风格或效果。
3. 用模式文档说明适用条件、实现思路和成本。
4. 用代码片段完成具体实现。
5. 用校验脚本减少索引、文档和代码之间的不一致。

这就是motion-skill-kit。它支持直接阅读和复用，也可以作为技能安装到支持本地 Skill 的 AI 编程环境中。

二、当前版本已经实现了哪些功能？

先看全景图：

图 1：设计基础、视觉片段、风格套件、检索、参数和工程维护组成完整的使用链路。

2.1 一组可以直接核对的规模数据

这里有两个容易混淆的计数：21 套风格已经包含在 50 个片段里；设计参考和模板也不计入这 50 个片段。

2.2 九大分类的具体内容

2.3 二十一套风格，提供的是设计语言样板

风格套件把颜色、排版、间距、边界和标志性组件放在一个 HTML 演示里，便于观察它们如何配合。

这些分组只是阅读导航。实际选型仍要看内容、品牌和用户任务。例如，艺术方向可以集中在首页标题和主视觉，数据表格、输入框和业务反馈继续保持清楚易用。

三、设计基础：先把页面关系处理好

当前版本加入的设计基础，使这套 Skill 能处理“页面不好看，但没有明确特效需求”的任务。

五份实施参考分别覆盖以下问题：

3.1 从任务建立页面结构

以库存补货页为例，先回答三个问题：

• 用户需要判断哪些商品缺货？
• 决定补货量时，需要看到哪些数据？
• 提交之后，如何知道成功、失败或需要修正？

明确这些关系后，再组织“筛选工具栏、结果数量、商品与数量表格、提交反馈”。页面骨架有了依据，侧栏、卡片和装饰才有合适的位置。

已有项目还要保留原来的组件和数据契约。比如，为了减少表格列数，把商品名和规格放进一个单元格是可以讨论的，但不能同时丢掉原有排序、筛选或导出能力。

3.2 用层级和间距表达信息归属

层级并不意味着把所有标题放大。关键是让用户知道先看什么、哪些信息属于一组、哪个操作最重要。

当每个图标、数字和按钮都醒目时，可以先减轻次要元素的重量；当字段之间缺乏归属感时，可以调整组内与组间距离；当宽屏正文过长时，可以限制内容宽度，而不是把文字拉满容器。

参考材料也提醒：标签和数值谁更醒目，应由任务决定。查询参数时，属性名可能是扫描锚点；比较指标时，数值可能需要更高权重。

3.3 给文字和颜色分配角色

文字可以按页标题、区块标题、正文、说明、数值和控件划分角色。颜色可以按画布、表面、文字、边界、动作、焦点和业务状态划分角色。

这样做的直接收益是，样式调整能够围绕语义进行。例如，修改主要动作色时，可以改对应 token，而不必逐个查找按钮里的十六进制色值。

深色主题也需要重新检查角色之间的关系。背景变暗后，辅助文字、边界、状态色和阴影都可能需要调整；直接反转颜色难以保证可读性。

3.4 组件状态也是设计的一部分

同一个列表页面，首次使用、筛选无结果和加载失败，应该给出不同的下一步。

首次使用可能需要创建或导入入口；筛选无结果应该保留条件并提供清除入口；加载失败应该支持重试，且不能让用户以为自己的数据消失了。

因此，设计验收会同时检查默认、悬停、聚焦、选中、禁用、错误，以及加载、空、失败和成功等状态。具体检查范围跟随本次修改，不要求每个小改动都建立庞大的测试套件。

四、仓库架构：让 Agent 知道“去哪找、先读什么”

核心目录如下：

motion-skill-kit/ ├── SKILL.md # 技能入口、触发边界与工作流程 ├── skill.json # 本项目维护的补充元数据 ├── data/ │ ├── index.json # 50 个片段的结构化索引 │ └── foundations.json # 设计基础材料索引 ├── references/ # 设计实施、验收和参考资料 ├── patterns/ # 50 篇模式文档 ├── snippets/ # 50 个实现片段 ├── templates/ # 参数与技术起步模板 └── scripts/ ├── build-patterns.ts # 从源码生成文档示例 └── validate.ts # 静态校验

4.1SKILL.md：定义入口和行为边界

SKILL.md说明技能适用于前端视觉设计、UI 改版以及艺术效果需求。普通组件可以只使用设计基础；纯后端或与视觉无关的逻辑任务，无需套用这套流程。

Skill 的入口包含名称、描述和执行指引。支持该机制的工具可以根据描述选择技能，也可以由用户显式调用。它不会修改模型权重，也不会凭空生成一个后台执行服务。

关于 Skill 的文件结构、按需加载与调用机制，可参阅 OpenAI 官方 Build skills 文档。

4.2 双索引：基础设计与视觉效果分别检索

遇到“表单拥挤、标题不清楚、颜色太杂”时，先查data/foundations.json。

遇到“需要极光背景、图片揭示、瑞士网格风格”时，再查data/index.json。后者通过knowledgeIndex指向基础材料索引，使两类资源能够衔接。

下面是极光背景的实际索引结构：

{"id":"aurora-background","name":"极光流动背景","category":"backgrounds","tags":["渐变","模糊","氛围","科技感","官网Hero","暗色主题","aurora"],"tech":["react","css"],"dependencies":[],"files":["snippets/backgrounds/aurora-background.tsx"],"doc":"patterns/backgrounds/aurora-background.md","performance":"low-cost","reducedMotionFallback":"静态色雾构图（CSS animation: none）"}

这些字段分别回答：它叫什么、属于哪一类、如何匹配需求、使用什么技术、有哪些额外依赖、源码与文档在哪里、成本分级如何，以及减少动画时会发生什么。

dependencies: []也要结合技术上下文理解。这里表示没有额外列出的效果库依赖，React 片段仍然要求宿主项目提供 React。

4.3patterns：补齐代码之外的使用条件

每篇模式文档使用三段结构：

实际使用时，Agent 先筛选索引，再读候选文档，最后读取源码。这样可以缩小阅读范围，也能避免只根据名称复制一个不适合当前页面的效果。

五、一条完整的设计与接入流程

图 2：基础设计是共同起点，风格与动效按需求进入；已有明确效果需求时，也可以直接检索该效果。

5.1 明确内容、任务和约束

输入最好包含页面用途、主要操作、真实内容、品牌约束和现有技术栈。比如，“给一个已有 React 项目的产品首页改善视觉，保留组件接口，主要目标是让用户了解产品并进入试用”。

5.2 先建立静态结构

先处理标题、说明、主要动作、内容分区和小屏结构。静态页面已经清楚，后续效果才能围绕重点服务。

5.3 按需要选择风格和效果

用户指定风格时直接检索；没有指定时，结合品牌、内容和气质选择候选。无法判断时，可以先保持静态。

例如，科技产品首页可以讨论暗色表面与极光背景；设计作品集可以讨论网格排版和局部图片揭示；后台管理页往往更需要密度、数值对齐和状态反馈。

这些都是任务中的候选方向，不是行业到风格的一一映射。

5.4 复用片段并局部调参

效果类片段主要调整顶部CONFIG；风格套件主要调整:root中的设计 token。这样能够把“视觉适配”集中在少数位置，降低随意改动实现的概率。

迁入真实项目后，样式作用域、组件接口、路由和资源路径仍需要适配。尤其是完整 HTML 风格演示中的全局选择器，应按项目范围收敛，避免覆盖已有页面。

5.5 检查状态、视口和降级

完成后检查实际页面：长文案、窄屏、中间宽度、键盘焦点、触屏输入，以及减少动画模式。静态校验只覆盖仓库结构和部分代码规则，实际展示结果需要另行观察。

六、三个具体实现点：参数、主题和交互

6.1 极光背景：用参数描述视觉差异

aurora-background.tsx的实现使用 CSS 渐变、模糊和 transform 动画。下面节选实际参数：

const CONFIG = { blobs: [ { color: "#3a86ff", x: "15%", y: "20%", size: 55 }, { color: "#8338ec", x: "60%", y: "10%", size: 50 }, { color: "#06d6a0", x: "40%", y: "60%", size: 45 }, { color: "#ff006e", x: "75%", y: "55%", size: 35 }, ], blur: 90, opacity: 0.55, duration: 26, baseColor: "#050510", } as const;

品牌色变化时调整色块；正文被背景干扰时降低透明度；节奏需要更缓时增加周期。参数集中后，这些变化可以局限在明确的区域。

减少动画时，组件会停止色块漂移，保留静态色雾。这里保留了视觉主题，也让主要内容不依赖运动才能理解。

6.2 CSS 参数模板：从语义变量开始

templates/ui-foundation-tokens.css提供间距、文字、内容宽度、圆角、颜色、焦点和阴影变量，并包含显式深色主题。

下面节选部分实际变量：

.ui-foundations{--ui-space-2:0.5rem;--ui-space-4:1rem;--ui-space-6:1.5rem;--ui-text-body:1rem;--ui-text-title:clamp(1.75rem,1.25rem + 2vw,3rem);--ui-content-max:72rem;--ui-canvas:#f4f6f8;--ui-surface:#ffffff;--ui-ink:#17212b;--ui-action:#155f55;--ui-focus:#1a65b3;}

规则限制在.ui-foundations内，可以先在一个区域试用。已有设计系统时，应将需要的关系映射到原有 token，避免同时维护两套相互竞争的变量。

加载完整模板后，可以用以下静态结构观察排版与表面效果：

<divclass="ui-foundations"data-ui-theme="dark"><mainclass="ui-shell ui-main"><sectionclass="ui-panel ui-stack"><h1class="ui-title">先建立清楚的信息层级</h1><pclass="ui-copy ui-muted">用真实内容检查标题、正文、空间和主题之间的关系。</p></section></main></div>

这些值是实施起点，需要按品牌、内容和目标设备调整。模板本身没有动画。

6.3 磁吸按钮：把高频更新放在合适的位置

magnetic-button.tsx使用ref保存目标值和当前值，通过requestAnimationFrame逐步逼近目标，再更新元素的 transform。

它避免在每次指针移动时调用 ReactsetState，使高频位置更新不必每次触发组件渲染。组件还检测粗指针和减少动画偏好，在这些情况下跳过磁吸逻辑，保留普通按钮表现。

这类设计可以改善实现方式，但实际开销仍受组件数量、页面内容和设备影响。接入后应在目标页面检查，而不是把某个实现技巧当成帧率保证。

七、如何安装和开始使用？

7.1 先下载仓库，直接查看效果

gitclone https://github.com/ergou-yu/motion-skill-kit.gitcdmotion-skill-kit

下载完成后，可以用浏览器打开以下文件：

snippets/styles/swiss-grid.html snippets/styles/vaporwave.html snippets/styles/ink-wash.html snippets/shaders/fragment-ripple.html

原生 HTML 示例适合先看方向。涉及 CDN 的示例需要相应网络访问；迁入项目时，还需要检查资源地址和加载方式。

如果需要维护、校验或扩展仓库，在具备 Node.js 与 npm 的环境中执行：

npmcinpmrun validate

这里安装的是tsx、typescript等开发工具。仅查看 HTML 示例，不需要先运行这组维护命令。

7.2 在 Codex 中使用

可以让内置安装器从 GitHub 仓库根目录安装。示例提示词如下：

使用 $skill-installer，安装 GitHub 仓库 https://github.com/ergou-yu/motion-skill-kit 中的 skill。 SKILL.md 位于仓库根目录，安装名称使用 motion-skill-kit。

安装后，可以显式调用：

使用 $motion-skill-kit，检查这个页面的视觉层级、间距和配色， 先解决静态布局与可读性问题，再判断是否需要动效。

如果希望将技能随项目维护，也可以使用官方支持的项目技能目录，在目标项目根目录执行：

gitclone https://github.com/ergou-yu/motion-skill-kit.git .agents/skills/motion-skill-kit

安装器与手动放置二选一即可，避免同名技能出现多个副本。Codex 支持从项目.agents/skills发现技能，也会检测技能变化；若安装后没有出现，可重新启动后检查。具体目录和机制见 OpenAI 官方技能文档。

7.3 在其他 AI 编程工具中使用

如果工具支持本地 Skill，按照该工具的安装规则放置完整目录。仅复制SKILL.md会丢失它引用的索引、设计参考和源码。

如果工具只支持项目指令或规则文件，可以明确告诉它仓库位置和阅读顺序：

本项目使用 motion-skill-kit，目录位于：<填写实际路径>。 处理前端视觉任务时： 1. 页面布局、文字、颜色或状态问题，先查 data/foundations.json。 2. 风格或效果需求，查 data/index.json。 3. 阅读候选片段的 doc 文档，再读取 files 中的源码。 4. 优先调整 CONFIG 或设计 token，保留减少动画降级。 5. 完成后检查本次修改涉及的状态、视口和输入方式。

这是一种显式引用方式，效果取决于工具能否读取对应文件，以及是否实际遵循这些指令。

7.4 把 React 片段接入现有项目

以极光背景为例，先将对应源码复制到项目组件目录，例如：

src/components/visuals/AuroraBackground.tsx

下面给出一个集成示意。由于该片段使用绝对定位和负z-index，宿主容器需要明确定位与层叠范围：

import AuroraBackground from "./components/visuals/AuroraBackground"; export default function ProductHero() { return ( <section style={{ position: "relative", isolation: "isolate", overflow: "hidden", minHeight: "70vh", padding: "clamp(32px, 7vw, 96px) 24px", color: "#fff", }} > <AuroraBackground /> <div style={{ position: "relative", maxWidth: "64rem", marginInline: "auto", }} > <h1>让主要内容先被看见</h1> <p>用背景建立气氛，用层级和文案说明产品价值。</p> </div> </section> ); }

这段代码用于说明宿主结构，导入路径、排版和布局需要按实际项目调整。接入后继续检查背景层是否可见、文字是否清楚，以及移动端是否出现裁切。

HTML 演示迁入 React 时，工作通常还包括拆分标记、收敛 CSS 作用域、把初始化逻辑放入合适的生命周期，以及清理事件、动画帧和绘图资源。

八、怎样提需求，才能更好地发挥这套 Skill？

提示词中最有价值的信息是页面目标和边界。下面三组示例可以直接修改后使用。

8.1 产品首页：明确视觉重点与效果预算

使用 motion-skill-kit 改善这个 React 产品首页。 目标：让首次访问者快速理解产品，并找到试用入口。 保留现有导航、组件接口和品牌主色。 先完成静态层级、内容宽度、文字角色和移动端布局。 主视觉可以使用 aurora-background，正文区保持稳定阅读。 不要在整页叠加持续动画，保留 prefers-reduced-motion 降级。 完成后说明关键修改，并检查宽屏、窄屏和键盘焦点。

重点在于先确定主要任务，再把动效限制在能产生作用的位置。

8.2 后台改版：只使用设计基础

使用 motion-skill-kit 的设计基础，优化这个库存补货页。 不添加背景特效、滚动动画或自定义光标。 重点检查筛选条件、商品信息、数量和提交操作的层级。 保留已有排序、筛选、分页、导出和提交逻辑。 用长商品名、不同位数的数量、空结果和错误状态检查布局。

这类任务可以完整使用技能中的设计流程，同时保持页面静态。

8.3 指定艺术风格：把表达集中到合适区域

参考 motion-skill-kit 的 ink-wash 风格套件，设计一个文化展览页面。 内容包括展览介绍、作品列表、时间地点和预约说明。 让标题和主视觉表达水墨气质，正文与预约信息保持清楚易读。 先复用已有风格 token，再按真实内容调整。 不要把演示中的装饰交互写成已经完成的预约功能。

这里同时给出了风格、内容结构和功能边界，可以减少只有气氛、缺少信息的结果。

九、工程质量：让索引、文档和源码保持一致

图 3：自动校验覆盖结构与部分静态规则；浏览器中的视觉、交互和性能验证由目标项目继续完成。

9.1 源码作为文档示例的来源

代码片段和文档示例分别维护，容易出现“文档是旧的，源码已经更新”的问题。

项目使用build-patterns.ts读取 snippet，并把完整代码嵌入模式文档的Example段。文档通过锚点指向来源：

## Example <!-- EMBED:START:snippets/backgrounds/aurora-background.tsx --> ```tsx 这里由构建脚本写入源码内容。 ``` <!-- EMBED:END -->

修改源码后运行：

npmrun build:docsnpmrun validate

校验器会比较嵌入示例和源码，比较时会去掉行尾空白和首尾空白。这里检查的是规范化后的内容一致性。

9.2validate.ts实际检查了什么？

脚本出现 error 时退出码为 1；只有 warning 时退出码为 0。因此，接入自动化流程时，应理解它的失败规则。

本次核对当前版本时，运行结果为：

索引解析： 1 pass TSX 语法： 18 pass 代码一致： 50 pass 设计基础索引： 7 pass 材料可达： 7 pass 版本一致： 1 pass 总计：84 pass · 0 warn · 0 error 片段 50 个 / 文档 50 篇

这84 条是当前报告中显式记录的通过项，并不等同于 84 个浏览器测试，也不意味着每一条校验规则都会产生一条 pass 记录。

9.3 自动校验的实际边界

TSX 语法解析没有执行完整项目类型检查；HTML 基础结构检查也不是完整 HTML 标准验证器。检测到减少动画相关代码，不能代替运行后观察降级是否正确。

同样，当前脚本不会自动判断一个页面是否好看，不会替代设备性能测试，也没有把键盘、焦点、触屏和读屏体验全部自动化。

这些边界决定了交付顺序：先用脚本减少结构性错误，再在目标项目中进行对应的构建、交互和视觉检查。

十、性能与依赖：按实际成本选择效果

10.1 性能标签是选型提示

当前索引中的标签分布为：

技能入口给出了组合预算：同页high最多 1 个、medium最多 2 个，一次组合通常控制在 4～5 个效果以内。

这些数量是本库的选型约束，不是统一设备上的实测阈值。即使标签是low-cost，大面积模糊、多层混合或大量元素叠加也可能产生明显开销。

因此，选型时还要结合元素数量、视口面积、像素密度和目标设备检查。

10.2 优先原生实现，并明确外部资源

大部分片段使用 CSS、Canvas、Web Animations API、IntersectionObserver 或 WebGL，不要求额外安装 GSAP、Framer Motion 等动画库。

实际依赖仍需要按片段区分：

• React 片段需要宿主项目提供 React。
• p5-flow-field通过 CDN 使用 p5.js。
• pixel-art示例包含可移除的 Google Fonts 字体资源。
• p5.js、Three.js 起步模板使用时，要检查各自外部资源。

所以，接入时应同时阅读索引中的dependencies和源码。索引用于快速筛选，源码用于确认最终加载与运行方式。

10.3 保留减少动画模式

降级目标是保留内容、操作和反馈。不同效果可以有不同策略：极光停止漂移、文字直接显示、磁吸按钮恢复普通按钮、滚动揭示直接呈现内容。

故障文字和欧普艺术等高刺激效果，技能入口要求不主动选入，除非用户点名。即使选择使用，也应继续控制强度，并核查对应文档中的使用条件。

十一、如何增加一个新的效果或风格？

这套 Skill 的扩展能力来自明确的维护流程：Agent 在具备相应工具、网络访问和修改权限时，能够按规则补齐代码、文档与索引。

它没有常驻后台自动抓取素材，也不会通过一次对话训练新的模型。

11.1 从未收录的需求开始

例如，用户提出“增加一套侘寂气质的页面样板”。先检查现有索引，确认没有可直接满足需求的条目，再决定是否扩展。

调研需要提炼可实施的关系：字体气质、色彩角色、材料与形状、空间组织，以及适用内容。查到的事实与实施者自己的判断要分开记录。

11.2 同时补齐四类内容

以新增风格为例：

snippets/styles/<new-id>.html # 可查看的实现样板 patterns/styles/<new-id>.md # 场景、思路和示例 data/index.json # 检索记录 相关元数据 # 按变更需要同步

片段保留集中参数区和减少动画降级；文档说明适用条件、来源与实现取舍；索引补上名称、标签、技术、性能分级和降级表现。

新分类还需要更新分类白名单和导航。改动完成后生成文档示例，再运行校验。

11.3 先验证，再沉淀

完整链路可以概括为：

检查已有资源 → 调研与提炼 → 实现演示 → 检查目标场景 → 补齐文档和索引 → 构建示例与校验 → 按项目约定提交

提交、推送和其他外部操作遵循当前任务授权。扩展后的另一个安装副本也需要实际更新，不能仅凭仓库修改就认为所有环境自动同步。

十二、适合什么场景？当前还缺什么？

12.1 适合的使用场景

12.2 当前版本的边界

当前仓库提供的是文件、示例、工作流程和维护脚本。它尚未提供可视化编辑器、在线风格商城、一键发布平台，或自动视觉评分服务。

片段也没有构成一个统一 props、主题协议和发布节奏的完整组件产品。18 个 React 片段与 32 个 HTML 示例，进入真实业务后仍需要适配项目结构。

当前没有把 npm 包发布作为安装入口，npm ci服务于仓库维护。效果选择中的性能标签也没有附带统一设备上的完整基准报告。

这些事实有助于确定合理的使用方式：把它作为设计与实现的起点，结合目标项目完成工程集成和验证。

十三、常见问题

13.1 装上 Skill 后，每个页面都会自动加动画吗？

不会。技能明确允许只使用设计基础，并在信息不足时先保持静态。是否选用动效，要结合任务、内容和用户要求。

13.2 不使用 AI，也能用吗？

可以。直接阅读设计参考、查看模式文档和复用源码即可。结构化索引同样可以用普通 JSON 工具读取。

13.3 我已经有设计系统，还需要复制整份 CSS 模板吗？

通常先复用现有 token 和组件。模板可以帮助识别缺少的角色与尺度，再选择性合并；不必为使用本库建立第二套全局主题。

13.4 静态校验全绿，能直接认为上线完成吗？

还需要目标项目自己的检查。至少确认构建与类型检查、资源加载、真实内容、主要操作、响应式和本次涉及的动画降级。

13.5 它的“持续扩展”需要什么条件？

需要执行者读取现有材料、完成实现并维护索引与文档。如果任务涉及在线调研，还需要网络能力；如果涉及提交和推送，还需要相应权限与授权。Skill 提供操作依据，执行由实际环境完成。

结语：把可复用的判断留在项目里

motion-skill-kit 当前把设计基础、50 个视觉片段、21 套艺术风格，以及索引和校验工具组织到了一起。

在页面开发中，我希望它帮助解决的具体问题是：开始前能找到有用的判断依据，实施时能复用明确的代码与参数，完成后能说明改了什么、怎样验证，以及哪些部分仍需要继续检查。

如果你正在用 AI 编程助手开发官网、作品集或业务界面，可以先从一个小页面试用：阅读相关设计参考，选择少量片段，在真实内容和目标设备上检查，再把有效经验沉淀下来。

项目地址：GitHub · motion-skill-kit

实现入口：SKILL.md · 片段索引 · 设计基础索引