ai-ui-generation

AI UI 生成

用于生成、审查和集成 AI 工具（json-render、v0.app、Google Stitch、Bolt Cloud、Cursor）产出 UI 组件的模式。对于多端界面、MCP 视觉输出和类型安全的目录工作流，json-render 是首选。AI 生成的 UI 中，80% 是样板代码，20% 是定制内容——由人来审查、重构并负责最终产出。这些规则可确保 AI 产出在发布前符合设计系统、无障碍和质量标准。

截至 2026-04 的工具格局：

• v0.dev → v0.app（2026 年 1 月更名）——从组件脚手架扩展到完整栈应用生成，并支持发布目标（Vercel、Cloudflare、Railway）。v0.app MCP 服务（@vercel/v0-mcp）将生成功能作为 MCP 工具公开，因此 Agent 可以通过编程方式调用。
• Google Stitch——通过 stitch.withgoogle.com/docs/mcp 实现设计优先的生成。可生成多屏应用（最多 5 个相互关联的屏幕），并提供 React/HTML + PNG。当输入为截图、URL 或 DESIGN.md 文件时，效果出色。
• Bolt Cloud（StackBlitz，2026 年）——Bolt 现在在云端运行开发环境（不再使用本地 WebContainer）。可与 GitHub 集成并支持持久化数据库。最适合带后端和部署功能的全栈原型。
• v0.app 和 Stitch 均集成了 shadcn/ui 样式；搭配 shadcn apply <style> CLI（v4）可复用生成的产出。

快速参考

类别	规则	影响	适用场景
json-render 集成	1	HIGH	多端输出、MCP 视觉输出、类型安全的目录
提示词工程	2	HIGH	编写用于生成组件的提示词
质量保证	2	CRITICAL/HIGH	审查并把关 AI 生成的代码
设计系统集成	2	HIGH	注入设计令牌，重构以符合规范
工具选择与工作流	2	MEDIUM	选择合适的 AI 工具，迭代提示词

总计：5 个类别中的 8 条规则

决策表 — json-render vs v0.app vs Stitch vs Bolt Cloud vs Cursor

场景	工具	原因
多端界面 / MCP 视觉输出	json-render	单一目录即可渲染到任何界面——首选
类型安全的组件目录	json-render	由架构驱动的规范，配有各平台注册表
来自 AI Agent 的流式 UI	json-render	结构化 JSON 规范可渐进式渲染
从零开始创建新组件	v0.app	完整脚手架，包含 shadcn/ui、Tailwind、无障碍支持。搭配 shadcn apply <style> 保持样式一致
带部署功能的全栈应用	v0.app	2026 年 1 月扩展——一次生成即可包含路由、数据库、身份验证以及 Vercel/Cloudflare 部署
由设计驱动（截图/URL/DESIGN.md）	Google Stitch	generate_screen_from_text（一次，不重试）+ get_screen(name="projects/{project}/screens/{screen}")
根据视觉素材生成多屏流程	Google Stitch	以现有设计为依据时效果最佳
带持久化后端的全栈原型	Bolt Cloud	云端开发环境、GitHub 集成、数据库
在现有代码库中进行增量修改	Cursor	理解项目上下文、导入内容和设计令牌
重构现有组件	Cursor	读取周边代码并遵循约定
探索视觉设计变体	v0.app 或 Stitch	v0.app 适合自由探索；有参考素材时选 Stitch
为运行中的应用添加功能	Bolt Cloud	云端预览、完整环境，并可在会话间保持状态
修复现有组件中的错误	Cursor	基于完整项目上下文进行内联编辑

快速入门

结构化提示词示例

Generate a React signup form component using:
- Framework: React 19 + TypeScript
- Styling: Tailwind CSS v4 + shadcn/ui (Luma style — rounded-4xl, shadow-md elevation)
- Style: run `npx shadcn@latest apply luma` (CLI v4, Apr 2026) after generation
- Tokens: use color.primary, color.destructive, spacing.md from our design system
- A11y: ARIA labels on all inputs, error announcements via aria-live
- States: default, loading (disabled + spinner), error (inline messages), success
- Responsive: stack on mobile (<640px), 2-col on desktop

审查示例 — AI 生成后

// AI generated: hardcoded hex value
<button className="bg-[#3b82f6] text-white px-4 py-2">Submit</button>

// After human review: design token applied
<Button variant="default" size="md">Submit</Button>

规则详情

json-render 集成

当输出必须在多个界面（Web、移动端、CLI、MCP）上渲染时，json-render 是 AI UI 生成的首选方案。只需定义一次组件目录，即可根据 AI 生成的 JSON 规范，并在任意目标界面上渲染。有关目录编写模式，请参阅 ork:json-render-catalog。

规则	文件	关键模式
json-render 模式	rules/json-render-patterns.md	目录优先：定义一次，通过各平台注册表随处渲染

提示词工程

提前明确指定框架、令牌、a11y 和状态的结构化提示词。

规则	文件	关键模式
提示词模式	rules/ai-prompt-patterns.md	约束优先的提示词，指定框架、令牌和 a11y
迭代模式	rules/ai-iteration-patterns.md	针对复杂交互状态的多轮提示词

质量保证

对 AI 生成的组件进行系统化审查和 CI 门禁检查。

规则	文件	关键模式
审查清单	rules/ai-review-checklist.md	每个 AI 生成组件都要经过 10 项检查
CI 门禁	rules/ai-ci-gate.md	合并前执行自动化质量门禁

设计系统集成

确保 AI 输出使用设计令牌并符合设计系统规范。

规则	文件	关键模式
令牌注入	rules/ai-token-injection.md	在提示词中传入令牌名称，拒绝硬编码值
重构规范	rules/ai-refactoring-conformance.md	将原始 AI 输出重构为符合设计系统规范的步骤

工具选择与工作流

选择合适的 AI 工具并有效迭代。

规则	文件	关键模式
工具选择	rules/ai-tool-selection.md	根据用例匹配工具：v0、Bolt、Cursor
迭代模式	rules/ai-iteration-patterns.md	针对复杂状态进行迭代优化

核心原则

1. 对输出负责 — AI 生成初稿；工程师负责审查、重构，并对最终交付内容负责。
2. 优先使用令牌，而非字面值 — 绝不接受硬编码的颜色、间距或排版值。始终映射到设计令牌。
3. 约束优先的提示词 — 提前指定框架、令牌、shadcn 风格（Luma/Nova 等）、a11y 和状态。模糊的提示词会产生模糊的输出。
4. 迭代优化 — 复杂组件需要 2-3 轮提示：先处理结构，再处理状态，最后进行润色。
5. CI 不可妥协 — 每个 AI 生成的组件都必须经过与手写代码相同的 CI 流程。
6. 默认保证无障碍性 — 在每条提示词中加入 a11y 要求；生成后通过自动化检查进行验证。

反模式（禁止）

• 直接交付原始 AI 输出 — 未经人工审查和设计系统重构，绝不合并 AI 生成的代码。
• 模糊的提示词 — “做一个漂亮的表单”会产生不一致且不符合规范的输出。始终明确指定约束。
• 硬编码的 hex/rgb 值 — AI 工具默认会使用随意的颜色。应替换为 OKLCH 设计令牌。
• 因组件“简单”而跳过 CI — AI 生成的代码与手写代码具有相同的缺陷风险。
• 使用 v0.app 进行增量修改 — v0.app 会从头生成；要在现有代码库中修改，请使用 Cursor。
• 一次生成复杂组件 — 多状态组件（加载、错误、空状态、成功）需要通过多轮提示迭代生成。
• 轻信 AI 关于 a11y 的声明 — AI 工具添加 ARIA 属性的方式并不一致。始终使用 axe-core 或 Storybook a11y addon 进行验证。

详细文档

资源	描述
references/ai-ui-tool-comparison.md	json-render、v0、Bolt、Cursor 与 Copilot 的对比
references/prompt-templates-library.md	常见组件的即用提示词模板
references/ai-ui-failure-modes.md	10 大失败模式及修复方法

相关技能

• ork:json-render-catalog — json-render 目录编写、架构验证和注册表模式
• ork:mcp-visual-output — 使用 json-render 规范渲染 MCP 可视化输出
• ork:multi-surface-render — 基于单一组件目录进行跨平台渲染
• ork:ui-components — shadcn/ui 组件模式和 CVA 变体
• ork:accessibility — WCAG 合规性、ARIA 模式和屏幕阅读器支持
• ork:animation-motion-design — Motion 库动画模式
• ork:responsive-patterns — 响应式布局和容器查询模式
• ork:design-system-tokens — 设计令牌架构和主题设置