Stagecraft：用设计规范与工作流指南，让AI代码助手生成高级感UI

1. 项目概述：当AI代码助手学会“设计品味”

最近在折腾各种AI代码助手（Claude Code、Cursor、GitHub Copilot）时，我一直在琢磨一件事：这些工具生成代码的速度是快，但出来的UI界面，总感觉差了那么点意思。要么是布局过于“朴素”，缺乏视觉层次；要么是动效要么没有，要么就是滥用，显得廉价。对于一个追求产品质感的开发者来说，每次生成完还得花大量时间手动调整间距、颜色和动画，这“最后一公里”的体验优化，反而成了最耗时的部分。

直到我遇到了Stagecraft。这个项目精准地戳中了我的痛点。它不是一个运行时库，不往你的package.json里塞任何依赖。本质上，它是一套精心编写的Markdown设计规范与工作流指南，专门“教”AI代码助手如何产出具有Keynote风格的、精致且克制的用户界面。你可以把它理解为一个“设计品味”插件，一旦安装，当你对AI说出“premium”（高级感）、“polished”（精致感）或“cinematic”（电影感）这样的触发词时，AI就会自动调用这套规范，生成或重构出黑暗、极简、带有精妙动效的UI代码，而不是一堆需要你反复打磨的“毛坯房”。

对于前端开发者、全栈工程师，或者任何需要快速构建高质量演示界面、落地页、产品展示页的从业者来说，Stagecraft 相当于为你配备了一位随叫随到的资深UI动效设计师。它把主观的“设计感”转化为了AI可理解、可执行的客观规则和代码片段，让“一键生成高级UI”从幻想变成了可重复的工程实践。

2. 核心理念与设计哲学拆解

Stagecraft 的成功，不在于它提供了多少行代码，而在于它背后一套清晰、克制且可操作的设计哲学。这套哲学被编码进了几个核心的Markdown文件中，成为了AI代理的“设计宪法”。

2.1 约束即自由：建立不可动摇的设计系统

很多AI生成的UI之所以显得杂乱，根本原因在于缺乏统一的约束。颜色、字体、间距、圆角、阴影……每个值都是AI根据训练数据“即兴发挥”的，组合在一起自然不协调。

Stagecraft 的visual-system.md文件彻底解决了这个问题。它定义了一套极其严格、完整的视觉设计系统：

1. 色彩系统：一个固定的深色主题调色板。背景、表面、文本、边框颜色都是预先定义好的十六进制或CSS变量值。特别是强调色，整个界面只允许使用一种，确保了视觉焦点的纯粹性。AI不再需要“发明”颜色，而是从有限的、经过验证的选项中选择。
2. 排版尺度：字体大小、字重、行高被规范为一个清晰的阶梯（例如，text-xs到text-6xl）。这避免了标题和正文大小关系失衡的问题。
3. 间距网格：严格遵循4px基准网格。所有内外边距（padding,margin）、间隙（gap）都必须是4的倍数（如4px, 8px, 12px, 16px…）。这个简单的规则强制产生了整齐的视觉节奏感，是界面显得“专业”的关键。
4. 阴影与圆角：只定义两个层级的阴影（例如，一个用于卡片悬浮，一个用于模态框深层叠加）和有限的几种圆角值。这杜绝了花里胡哨的阴影堆砌。

实操心得：这套系统的妙处在于“零发明”。它告诉AI：“你不许自己创造任何新的样式值，所有视觉属性都必须从这个清单里选取。” 这极大地降低了AI的决策复杂度，同时保证了输出结果的一致性。在实际使用中，你会发现AI生成的代码里，类似mt-6(Tailwind CSS 中的margin-top: 1.5rem)、bg-surface、text-primary这样的类名会高频、一致地出现。

2.2 动效的语法：从乱舞到编排

动效是区分“普通”和“高级”UI的重要维度，但也最容易用错。Stagecraft 的motion-tokens.md文件为动效设计引入了“设计令牌”的概念。

它定义了7个命名的动效令牌，例如：

• fade-in: 淡入
• slide-up: 向上滑入
• scale-in: 缩放进入
• stagger-children: 子元素错开出现

每个令牌都精确绑定了：

• 持续时间：例如300ms或500ms。
• 缓动曲线：例如cubic-bezier(0.4, 0, 0.2, 1)（Material Design 的标准缓入缓出）。这是动效显得“自然”的物理基础，避免了生硬的线性运动。
• 实现代码：同时提供React + Framer Motion和纯CSS两种实现。这确保了无论你的技术栈是什么，都能直接复制粘贴使用。

更重要的是，它规定了动效的使用逻辑：一个屏幕通常只使用一种主要的揭示模式，并搭配1-2个动效令牌，禁止无意义的叠加。这就像电影导演，只使用必要的镜头语言来叙事，而不是滥用特效。

2.3 揭示模式：控制用户的注意力流

好的UI呈现是有节奏的，像一场演讲或一部电影的开场。reveal-patterns.md文件定义了5种内容揭示模式，指导AI如何安排界面元素的出场顺序：

1. 场景入场：整个“场景”（如一个卡片）作为一个整体淡入或滑入。适用于简单的静态展示。
2. 焦点优先：最重要的元素（如标题、主按钮）首先出现，吸引用户注意力，次要元素随后跟进。
3. 逐行显示：文本内容按行依次出现，营造一种“正在输入”的沉浸感，非常适合代码展示或关键宣言。
4. 分块显示：将界面按逻辑块（如图片区、文本区、操作区）依次揭示，逻辑清晰。
5. 渐进披露：先显示核心框架和占位符，然后数据或复杂内容再加载进来，适合数据驱动的界面。

AI会根据你界面的内容结构和你的指令（如“做一个产品发布风格的英雄区域”），自动选择最合适的模式。这保证了动效服务于内容，而不是炫技。

2.4 审计清单：从重设计到精准优化

这是Stagecraft中最体现“工程师思维”的部分。audit-checklist.md不是一个主观的“好看与否”检查表，而是一个包含8个维度的客观评分卡：

1. 视觉层次：是否有明确的主次关系？
2. 间距节奏：是否遵循4px网格？
3. 色彩对比：文本可读性是否达标？
4. 动效一致性：是否滥用或缺少动效？
5. 响应式布局：在不同屏幕尺寸下是否正常？
6. 交互状态：悬停、点击状态是否清晰？
7. 内容密度：信息是否过载或过于稀疏？
8. 代码质量：生成的代码是否简洁、可维护？

当你要AI“审计”一个现有界面时，它会基于这份清单逐项检查，给出分数并指出具体问题（如“此处间距为18px，违反了4px网格规则，建议改为16px”），然后提供一个按优先级排序的差异化修改建议，而不是推倒重来。这让你能精准、高效地优化现有界面，成本极低。

3. 集成与实战：让主流AI助手“学会”Stagecraft

Stagecraft 的另一个精妙之处在于其“一次编写，多处运行”的架构。核心规范写在skills/stagecraft/目录下，然后通过脚本自动生成适配不同AI平台的“包装器”。

3.1 在 Claude Code 中安装与使用

Claude Code 是目前对 Stagecraft 原生支持最好的环境，因为它有官方的插件市场机制。

安装步骤：

1. 在 Claude Code 项目中，打开终端。
2. 首先，将 Stagecraft 的仓库添加为插件市场源。这相当于告诉 Claude Code：“可以去这个地址找插件。”

   /plugin marketplace add gg-mo/stagecraft-agent-skill

3. 然后，从这个市场源安装 Stagecraft 插件。

   /plugin install stagecraft@stagecraft-agent-skill

安装完成后，Claude Code 会自动加载插件的SKILL.md文件。当你需要时，直接在对话中使用触发词即可。

实战指令示例：

• 全新生成：“基于这个产品描述，用 Stagecraft 风格生成一个高级的、电影感的产品展示英雄区域。”
• 优化现有：“审计当前这个设置页面的UI，并用 Stagecraft 的规范让它变得更精致。”
• 具体调整：“把这个按钮的交互动效做得更有质感，使用 Stagecraft 的scale-in令牌。”

AI在响应时，会明确引用它正在遵循的 Stagecraft 工作流和规范条目，过程非常透明。

3.2 在 Cursor 中作为规则使用

Cursor 使用.mdc文件作为AI代理的规则。Stagecraft 为其生成了一个专用的规则文件。

安装步骤：

1. 在你的项目根目录下，创建规则文件夹（如果不存在）。

   mkdir -p .cursor/rules

2. 使用curl命令下载 Stagecraft 规则文件到该目录。

   curl -L https://raw.githubusercontent.com/gg-mo/stagecraft-agent-skill/main/integrations/cursor/stagecraft.mdc \ -o .cursor/rules/stagecraft.mdc

使用方法：安装后，在 Cursor 的 AI 聊天框中，通过@stagecraft来调用这条规则。例如：“@stagecraft 帮我重新设计这个登录框，要那种苹果发布会的感觉。”

注意事项：Cursor 的规则系统与 Claude Code 的插件机制不同，它更像是给AI的一个强提示。效果同样显著，但交互过程可能不如 Claude Code 插件那样有深度集成感。确保你的 Cursor 代理设置中启用了读取项目规则的功能。

3.3 在 Codex 或 Gemini CLI 中通过项目文档集成

对于 Codex（Cursor 的底层模型）或 Google 的 Gemini CLI 这类通过项目上下文工作的AI，Stagecraft 将核心技能文件内容整合进了一个AGENTS.md或GEMINI.md文件。

安装步骤：你只需要将这个文件的内容追加到你项目根目录的对应文件中即可。

# 对于 Codex curl -L https://raw.githubusercontent.com/gg-mo/stagecraft-agent-skill/main/integrations/codex/AGENTS.md >> AGENTS.md # 对于 Gemini CLI curl -L https://raw.githubusercontent.com/gg-mo/stagecraft-agent-skill/main/integrations/gemini/GEMINI.md >> GEMINI.md

这样，当AI分析你的项目时，这份详尽的设计指南就会成为其上下文的一部分，从而影响其输出。

3.4 在 GitHub Copilot CLI 中作为技能链接

Copilot CLI 使用一个本地的技能目录。

安装步骤：

1. 将 Stagecraft 仓库克隆到本地 Copilot 的技能源码目录。

   git clone https://github.com/gg-mo/stagecraft-agent-skill ~/.copilot/skills/stagecraft-src

2. 创建一个符号链接，指向仓库内的具体技能文件夹。这比直接复制更利于更新。

   ln -s ~/.copilot/skills/stagecraft-src/skills/stagecraft ~/.copilot/skills/stagecraft

之后，在 Copilot CLI 对话中提及相关触发词，它就有可能调用这套技能。

4. 核心工作流与AI协作实战解析

理解了理念和安装，我们来看看Stagecraft如何具体指挥AI工作。其核心是一个5步工作流，被定义在SKILL.md中。

4.1 第一步：识别场景与触发

这不是AI的步骤，而是你的步骤。你需要明确何时调用Stagecraft。根据文档，最佳场景是：

• 产品展示页、启动页、营销落地页
• 仪表盘概览、数据可视化焦点图
• 模态框、通知、过渡页面

你需要使用明确的触发词来启动这个流程。除了“premium”、“polished”，像“audit this UI”（审计此UI）、“apply the keynote style”（应用主题演讲风格）也是有效的指令。清晰的指令是成功协作的一半。

4.2 第二步：AI加载规范与审计（针对优化场景）

如果你要求“审计”或“优化”一个现有界面，AI会首先进入审计模式。

1. AI会逐条对照8维审计清单，扫描你提供的代码。
2. 对每个维度进行评分（例如，色彩对比：8/10），并标记出不符合Stagecraft规范的具体代码行。
3. 生成一份审计报告，并按照问题严重性和修复成本进行优先级排序。例如，它会建议你先修改违反间距网格的padding，再考虑优化动效。

这个步骤的输出不是新代码，而是一份清晰的优化路线图。这让你在动手前就心中有数，避免了盲目修改。

4.3 第三步：选择揭示模式与动效令牌

无论是新建还是优化，AI接下来会根据界面类型和你的指令，从5种揭示模式中选择一种作为该屏幕的“叙事主线”。

例如，对于一个产品功能列表，它可能选择“分块显示”模式，让每个功能卡片依次出现。对于一个重要的数据看板，它可能选择“焦点优先”模式，让核心指标首先突出显示。

选定模式后，AI会从7个动效令牌中挑选1到2个来具体实现这个模式。例如，为“分块显示”模式搭配stagger-children和fade-in令牌。所有的持续时间和缓动曲线都是预设好的，保证了动效的质感。

4.4 第四步：应用视觉系统并生成代码

这是AI“动手”的阶段。它会严格遵循visual-system.md：

1. 替换颜色：将任意颜色值替换为调色板中的标准色。
2. 规范化间距：将所有尺寸调整到4px的倍数。
3. 统一字体：应用标准的字体尺度。
4. 注入动效：将选定的动效令牌（如fade-in）的代码片段（Framer Motion 或 CSS）插入到组件的合适位置。
5. 生成最终代码：输出完整的、可运行的组件代码（通常是React/JSX + Tailwind CSS + Framer Motion）。

你得到的是一份“开箱即用”的代码，直接复制到项目中，视觉效果和动效就已经是调整好的状态。

4.5 第五步：输出与解释

AI不会默默地把代码扔给你。在返回代码的同时，它会附上一段解释：

• 本次使用了哪种揭示模式（及原因）。
• 应用了哪几个动效令牌。
• 对视觉系统做了哪些关键调整（如：“将背景色从gray-100改为surface-dark”）。
• 如果是审计后优化，会说明修复了审计清单中的哪些问题。

这让你不仅能拿到结果，还能理解AI的设计决策，学习其中的规范，久而久之也能提升自己的UI设计直觉。

5. 项目架构与定制化进阶指南

Stagecraft 项目本身的代码结构非常清晰，体现了优秀的工程化思想。了解它，你甚至可以定制自己的“技能”。

5.1 仓库结构解析

.claude-plugin/ # Claude Code 插件元数据 plugin.json # 插件声明文件 marketplace.json # 插件市场列表信息 skills/stagecraft/ # **核心技能目录** SKILL.md # **总入口文件**：工作流、触发词、约束 references/ # **渐进式披露的详细规范** visual-system.md # 视觉设计系统 motion-tokens.md # 动效令牌 reveal-patterns.md # 揭示模式 audit-checklist.md # 审计清单 examples/ # 前后对比示例 integrations/ # **自动生成的平台适配器**（勿手动编辑） cursor/stagecraft.mdc codex/AGENTS.md gemini/GEMINI.md scripts/ # 构建脚本 build-wrappers.sh # 根据核心技能生成 integrations/ 下的文件 verify.sh # 完整性校验脚本

核心原则：所有的人类可读、可编辑的内容都只在skills/stagecraft/目录下。integrations/目录下的文件全部由scripts/build-wrappers.sh脚本自动生成。这种分离保证了“单一事实来源”。

5.2 如何贡献或自定义

如果你觉得默认的深色主题不适合你的项目，或者想增加一个新的动效令牌，你可以直接 fork 这个仓库并进行修改。

修改流程：

1. 克隆或 fork 官方仓库。
2. 修改skills/stagecraft/references/下的任何一个.md文件。例如，在visual-system.md中增加一套浅色主题的配色变量。
3. 关键步骤：运行构建脚本，重新生成所有平台适配器。

   ./scripts/build-wrappers.sh

   这个脚本会读取你修改后的核心技能文件，并重新生成integrations/目录下用于 Cursor、Codex 等的所有包装文件。
4. 运行验证脚本，确保没有破坏性改动。

   ./scripts/verify.sh

5. 现在，你可以将你自定义的 Stagecraft 技能安装到你自己的AI工具中（例如，将你的仓库作为自定义市场源添加到 Claude Code）。

重要警告：绝对不要手动编辑integrations/目录下的任何文件！因为它们会在下次运行构建脚本时被完全覆盖。所有的修改都必须作用于核心的skills/目录。

5.3 与现有设计系统的融合

你可能会问：我的项目已经有了自己的设计系统（如一套自定义的 Tailwind CSS 配置），Stagecraft 会不会冲突？

答案是：不会，而且可以协作。Stagecraft 的定位是“高阶风格层”。你可以这样理解：

• 你的基础设计系统：定义了品牌色、基础间距、组件库。它解决的是“一致性”问题。
• Stagecraft：定义的是如何运用这些基础元素，在特定场景（如产品发布、焦点展示）下营造出“高级感”和“叙事性”。它解决的是“表现力”和“节奏感”问题。

在实际操作中，AI在应用 Stagecraft 时，会优先使用你项目中已存在的设计令牌（如果命名相似）。如果找不到，它会回退到 Stagecraft 自带的默认值。你可以将 Stagecraft 的调色板变量名（如--color-surface）与你项目中的 CSS 自定义属性或 Tailwind 扩展配置进行映射，从而实现无缝融合。

6. 常见问题、局限性与实战避坑指南

经过一段时间的深度使用，我总结了一些常见问题和需要注意的地方。

6.1 效果不理想？可能是你用错了场景

Stagecraft 有明确的适用边界。在以下场景中强行使用，可能会适得其反：

• 高密度数据表格/企业级仪表盘：这些界面优先考虑信息密度和读取效率，过多的动效和留白会成为干扰。Stagecraft 的极简美学在这里可能显得“空洞”。
• 游戏化或卡通风格界面：Stagecraft 追求的是苹果、Keynote 那种冷静、精致的感觉。对于需要活泼、夸张、趣味性视觉的界面，这套规范是束缚。
• 需要高度品牌个性化的页面：如果品牌本身是色彩斑斓、风格强烈的，Stagecraft 的深色极简主题可能需要大量调整才能匹配。

正确做法：将 Stagecraft 视为你的“武器库中的一把特种武器”，专门用于需要营造产品质感、聚焦用户注意力、创造仪式感的特定页面或组件，而不是用于整个应用。

6.2 AI没有调用技能？检查触发与安装

有时候你说了“premium”，但AI生成的代码还是老样子。

• 检查安装：确认 Stagecraft 技能已正确安装并激活。在 Claude Code 中，可以尝试输入/plugin list查看。在 Cursor 中，检查.cursor/rules目录下是否有stagecraft.mdc文件。
• 强化指令：使用更明确的指令组合。例如：“请严格按照 Stagecraft 设计规范，使用焦点优先的揭示模式和淡入动效，将这个英雄区域重构为高级的深色主题。” 明确的指令能更好地引导AI。
• 提供上下文：如果是对现有代码优化，最好将相关组件的代码块提供给AI，这样它才能进行有效的审计和差分修改。

6.3 生成的代码需要手动调整吗？

大多数情况下，生成的代码可以直接运行，视觉效果达标。但你可能仍需进行一些微调：

• 内容适配：AI生成的布局是基于你提供的内容描述的。如果实际内容长度、图片比例与描述有出入，可能需要手动调整一下flex或grid的属性。
• 交互细节：Stagecraft 主要关注“入场”动效。对于复杂的用户交互流程（如多步骤表单、拖拽排序），你可能需要在此基础上补充交互状态下的微动效。
• 性能考量：虽然动效都经过优化，但在低端设备或非常复杂的页面上，同时触发大量元素的错开动画（stagger-children）仍需注意性能。如果遇到卡顿，可以考虑减少错开动画的元素数量或增加延迟。

6.4 与其他UI库或框架的兼容性

Stagecraft 提供的代码片段主要是Tailwind CSS 工具类和Framer Motion 组件（或纯CSS）。这与当前前端主流技术栈完全兼容。

• React + Next.js / Vite：开箱即用。
• Vue / Svelte：需要将 Framer Motion 的 React 组件语法转换为对应框架的动画库（如 Vue Use Motion、Svelte Transition）的语法。但视觉系统（CSS类名）是通用的。
• 无Tailwind项目：你可以让AI根据visual-system.md中的规范，生成对应的纯CSS样式规则，而不是工具类。这需要更明确的指令。

我个人最深的体会是，Stagecraft 的价值远不止于它提供的几套样式和动画。它最大的贡献是建立了一套与AI协作的、关于“美”的客观协议。它把模糊的设计评审意见（“感觉不够高级”）变成了AI可执行的、具体的开发任务（“将间距调整为4px网格，应用fade-in动效，使用表面深色背景”）。这不仅是效率的提升，更是团队沟通和设计交付方式的一次进化。当你和团队成员甚至非技术成员都能用“Stagecraft 风格”来指代一种明确的视觉标准时，产品开发流程会变得异常顺畅。