Communitygithub.com

Craft UI

设计技能。根据参考图、简讯或产品截图生成布局,但在编写任何代码之前,先通过三个发现代理理解产品与需求。

Craft UI 是什么?

Craft UI 是一个为 AI 代理(如 Claude Code、Cursor、Codex)设计的技能,旨在解决常见的“AI 生成式布局”问题——即看起来合理但缺乏实际内容、结构随机、充满占位符的设计。该技能强制要求,所有结构和视觉决策必须追溯至三个明确来源之一:实际产品、用户需求、或用户提供的参考。它通过三个并行运行的发现代理(生产站点分析、请求与参考分析、技能/路由决策)来收集证据,并生成一份“设计合约”,在未通过该合约审核之前,禁止编写任何代码。Craft UI 支持从现有网站优化、基于参考图生成、Dashboard/CRM/落地页等多种场景,并内置了严格的质量检查清单(内容、视觉保真度、响应式、可访问性、性能)。其工作流包括分诊、发现、合约、计划、构建、视觉验证和回复七个阶段,旨在确保证据驱动、避免默认值和 AI 生成内容的常见陷阱。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓OpenCode
npx skills add https://github.com/Fast4gc/craft-ui/tree/HEAD/skills/craft-ui

在你喜欢的 AI 中提问

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

文档

Craft UI 是做什么的?

参考图输入,工作布局输出——但只有在理解了产品和需求之后。

这个技能旨在防止的失败:一个由随机区域、占位文案、默认渐变和空白带组成的看似合理的页面。当代理根据类型习惯而非证据进行设计时,就会发生这种情况。这里的每一个结构和视觉决策都必须追溯到三个来源之一:实际产品、用户的简述、或实际看到的参考。如果缺少某个来源,则收集它或请求它。永远不要用默认值来填补空白。

不可协商的规则

  1. 在「设计合约」(步骤 2)之前编写代码。 即使是“快速”页面也不例外:discovery: lite 会缩短合约,但不会移除它。经济性由路由器处理,而不是通过跳过上下文来处理。
  2. 证据优先于默认值。 每个令牌、区域和文案行都必须标明其来源。“落地页的典型做法”并不是一个来源。
  3. 结构是脊柱,而不是自助餐。 区域的存在仅仅是为了回答访问者的问题或实现简述中的目标。请参阅 references/anti-ai-slop.md。
  4. 真实内容。 产品名称、标签、数据和语言均来自网站/简述。没有 Lorem Ipsum,没有伪造 Logo,没有杜撰的指标,没有“您的产品在此”,除非用户批准了占位符。
  5. 用用户的语言回复,并用产品的语言构建 UI(例如,pt-BR 产品使用 pt-BR 文案)。
  6. 一个令人难忘的动效,而不是在每个区域都使用淡入效果。
  7. 令牌优先于组件。 颜色、圆角、字体、间距、阴影和缓动函数都存在于 CSS 变量中;组件只读取这些变量。
  8. 经济性是一个决定。 路由器设置详细程度和运行哪些技能。只阅读适用的参考章节。
  9. 专业质量标准。 references/quality-bar.md 是完成的定义——内容、视觉保真度、响应式、WCAG AA、性能和交接。terse 模式会静默检查;它永远不会被跳过。

工作流

0. 分诊(主代理,秒级)

  • 逐字捕获用户的请求;注意任何 URL、附件、“não quero”约束和详细程度提示(“só o código”、“rápido”、“me explica”)。
  • 检查可用的工具:子代理/Task 工具、浏览器或 web fetch、本地仓库、skills/MCP 列表。
  • 如果请求是对现有文件的小调整(一个颜色值、一个间距值),通知路由器——它可能会设置 discovery: lite。新页面或重新设计总是使用 discovery: full。
  • 如果用户说现有布局“amador”、“precisa melhorar”、“conserta essa landing”,或指向一个带有代码的线上站点,请阅读 references/polish-existing-site.md 并遵循该路径:对真实代码库进行增量润色,而不是重建。在接触文件之前运行 git status。

1. 三个发现代理(并行运行)

使用你的子代理工具——OpenCode subagent、Claude Code Task/Agent、Codex spawn_agent、Cursor 后台代理。如果没有子代理工具,则在主代理中依次运行三个流程,并用各自的标题标记每个流程。发现代理不编写代码。

代理任务为合约提供的内容
A — 生产站点分析师理解站点在生产环境中的现状:产品、受众、真实文案、当前结构、品牌令牌、约束条件。站点上下文简述
B — 请求与参考分析师解码实际请求,并仅从实际看到的参考中提取风格 DNA;当未提供参考时搜索参考。请求简述 + 风格 DNA
C — 技能路由器/经济性为本次运行选择最小的额外技能/工具集,并设置详细程度。路由决策

完整规范、输出模式和字数预算:references/agents.md。将绝对技能根路径、其角色说明、用户的原始请求以及 URL/附件传递给每个代理。将其返回结果限制在其字数预算内。

当涉及参考图像时,还需阅读 references/pattern-transfer.md。风格令牌是可移植的;构图配方则不是。永远不要仅仅根据参考采用其 Hero 或区域模式——它必须由产品(A)和请求(B)证明其合理性。

2. 设计合约——硬性关卡

阅读 references/design-contract.md。将 A + B + C 合并为一个合约。然后检查:

  • 结构脊柱已排序;每个区域都有一个任务、一个来源、从参考中逐字复制的拓扑结构和真实内容;没有空白带。
  • 每个令牌和文案行都引用了一个来源;未知项被标记,而不是被发明。
  • 代理/站点/参考之间的冲突已通过向用户提出一个整合后的问题(最多 3 项)来解决,而不是通过猜测。
  • 详细程度和技能列表来自 C;没有技能是“仅仅因为存在”而运行的。
  • 模式采用分类账存在:每个 adopt/adapt/drop 都引用了 A 和 B;没有 Hero/区域模式仅来自参考(请参阅 references/pattern-transfer.md)。
  • 构图对于不同领域的无关产品来说不会显得合理。令牌是可移植的;Hero 配方则不是。

发现代理绝不询问用户——它们只报告 Gaps / Unknowns。主代理收集所有三个简述,提出一个整合后的问题(最多 3 项),并在问题得到回答之前保持关卡关闭。如果某个重要事实仍然未知(产品名称、受众、真实内容、参考图像),请询问并停止。不要开始步骤 3。

3. 计划

紧凑计划:令牌、脊柱的 ASCII 线框图、真实文案/数据银行,以及一次动效时刻及其触发器和原因。与参考和站点简述进行比较;任何是默认值而非观察到的东西都将被修改或删除。

4. 构建

  • 默认情况下为单个自包含 HTML 文件(CSS 变量作为令牌,Google 字体附真实后备字体)。仅当用户项目已经使用 React/Tailwind 时才使用。
  • 动效配方:references/motion-and-effects.md。GSAP 使用固定的 cdnjs 版本。
  • 保持代码精简:不包含布局不需要的库或抽象。
  • 响应式支持 1440 / 768 / 390 宽度,可见的焦点状态,尊重 prefers-reduced-motion。
  • 在构建时重新阅读 references/anti-ai-slop.md——尤其是关于空白带和区域自助餐的行。

5. 视觉验证

渲染并与参考和站点简述进行并排比较。在可用时使用浏览器工具(由 C 路由)。运行 references/quality-bar.md 中的验证协议:1440 / 768 / 390 宽度的全页截图、区域顺序和内容存在性、无空白带或裁剪文本、无水平滚动、实际像素对比度、键盘焦点、减少动效和控制台错误。检查层次结构、间距节奏、圆角/阴影一致性、密度和语言。修正轮次:terse 详细程度时为 1 轮,full 时最多 3 轮;首先修复最大的可见差异,并在检查清单通过时停止。

6. 回复

根据 C 的详细程度格式化。terse:3–5 行——构建的内容、使用的证据、验证结果。full:还需列出从何处获取了哪些参考特征、使用/跳过的技能以及一个建议的下一步更改。遵循 references/quality-bar.md 中的交接标准,一次性说明已知限制,并始终用用户的语言书写。

使用其他技能

代理 C 每次运行时决定这一点;首先检查会话中实际可用的技能。缺少技能 → 使用后备方案,并在最后提及一次。

阶段如果 C 说使用后备方案
计划/设计方向Impeccable(/impeccable shape,然后 craft);每个会话运行一次其上下文步骤frontend-design,或步骤 3 的计划
审查与润色Impeccable critique、polish、audit根据合约进行自审
动效质量emil-design-eng 用于缓动、持续时间、弹簧、悬停/按压references/motion-and-effects.md
视觉验证Browser MCP(Chrome DevTools / Claude in Chrome / developer-mcp-chrome):在 3 种宽度下截图,检查控制台描述检查项并请求用户提供截图
3D Logo 或物体img2threejs 仅当参考包含值得重建的 3D 物体时;说明其限制:一张图片无法揭示隐藏面扁平 SVG 或 CSS
保持代码小巧ponytail 在添加任何依赖之前纯 CSS + 一个 GSAP 时间线

仅在其阶段适用时调用技能。静态落地页不需要 img2threejs。

原创性与安全性

  • 重建模式,而不是资源。永远不要复用参考中的 Logo、插图、品牌名称或精确文案。使用来自 A/B 的用户品牌和真实内容。
  • 许多图钉链接到商业 UI 套件。仅匹配风格和结构。
  • 参考的外观是起点。如果它损害了可用性(低对比度、小字体),保留氛围,修复问题,并说明原因。

文件

  • references/agents.md — 三个发现代理、模式和预算。
  • references/design-contract.md — 合并模板和硬性关卡。
  • references/anti-ai-slop.md — 通用、堆叠、空白布局的症状和修复方法。
  • references/quality-bar.md — 专业完成的定义和验证协议。
  • references/pattern-transfer.md — 防止参考图像将相同的 Hero 配方移植到无关产品中。
  • references/polish-existing-site.md — 当任务是提升现有生产布局时的增量工作流。
  • references/categories.md — 类型基线(最低可行性,而非区域菜单)。
  • references/style-dna.md — 参考阅读模板;需要证据。
  • references/motion-and-effects.md — CSS 效果和 GSAP 配方。
  • assets/refs.json — 已知参考链接(仍需查看)。

相关技能