ai-ui-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI UI Generation

AI UI生成

Patterns for generating, reviewing, and integrating UI components produced by AI tools (json-render, v0, Bolt, Cursor). json-render is the first choice for multi-surface, MCP visual output, and type-safe catalog workflows. AI-generated UI is 80% boilerplate, 20% custom — the human reviews, refactors, and owns the output. These rules ensure AI output meets design system, accessibility, and quality standards before shipping.

本内容介绍由AI工具（json-render、v0、Bolt、Cursor）生成的UI组件的生成、审查与集成模式。json-render是多端渲染、MCP视觉输出以及类型安全目录工作流的首选工具。AI生成的UI代码80%是模板代码，20%是定制内容——由人工进行审查、重构并对最终交付内容负责。这些规则可确保AI输出在交付前符合设计系统、无障碍访问及质量标准。

Quick Reference

快速参考

Category	Rules	Impact	When to Use
json-render Integration	1	HIGH	Multi-surface output, MCP visual output, type-safe catalogs
Prompt Engineering	2	HIGH	Writing prompts for component generation
Quality Assurance	2	CRITICAL/HIGH	Reviewing and gating AI-generated code
Design System Integration	2	HIGH	Injecting tokens, refactoring for conformance
Tool Selection & Workflow	2	MEDIUM	Choosing the right AI tool, iterating prompts

Total: 8 rules across 5 categories

分类	规则数量	影响级别	适用场景
json-render集成	1	高	多端输出、MCP视觉输出、类型安全目录
提示工程	2	高	编写组件生成的提示词
质量保障	2	关键/高	审查与管控AI生成代码
设计系统集成	2	高	注入设计令牌、为符合规范进行重构
工具选择与工作流	2	中	选择合适的AI工具、迭代提示词

总计：5个分类下的8条规则

Decision Table — json-render vs v0 vs Bolt vs Cursor

决策表 — json-render vs v0 vs Bolt vs Cursor

Scenario	Tool	Why
Multi-surface / MCP visual output	json-render	Single catalog renders to any surface — FIRST CHOICE
Type-safe component catalog	json-render	Schema-driven specs with per-platform registries
Streaming UI from AI agents	json-render	Structured JSON specs render progressively
New component from scratch	v0	Full scaffold with shadcn/ui, Tailwind, a11y
Full-stack prototype/app	Bolt	Includes backend, routing, deployment
Incremental change in existing codebase	Cursor	Understands project context, imports, tokens
Refactor existing component	Cursor	Reads surrounding code, respects conventions
Explore visual design variations	v0	Fast iteration on look-and-feel
Add feature to running app	Bolt	Hot-reload preview, full environment
Fix bug in existing component	Cursor	Inline edits with full project awareness

场景	工具	原因
多端/ MCP视觉输出	json-render	单一组件目录可渲染至任意端——首选工具
类型安全组件目录	json-render	基于Schema的规范，搭配各平台注册表
AI Agent流式UI	json-render	结构化JSON规范支持渐进式渲染
从零创建新组件	v0	基于shadcn/ui、Tailwind、无障碍标准的完整脚手架
全栈原型/应用	Bolt	包含后端、路由与部署功能
现有代码库的增量修改	Cursor	理解项目上下文、导入依赖与设计令牌
重构现有组件	Cursor	读取周边代码，遵循项目约定
探索视觉设计变体	v0	快速迭代外观与风格
为运行中应用添加功能	Bolt	热重载预览、完整环境支持
修复现有组件的Bug	Cursor	基于全项目认知的在线编辑

Quick Start

快速开始

Structured Prompt Example

结构化提示词示例

Generate a React signup form component using:
- Framework: React 19 + TypeScript
- Styling: Tailwind CSS v4 + shadcn/ui
- 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

Generate a React signup form component using:
- Framework: React 19 + TypeScript
- Styling: Tailwind CSS v4 + shadcn/ui
- 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

Review Example — After AI Generation

审查示例 — AI生成后

tsx

// 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>

tsx

// 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>

Rule Details

规则详情

json-render Integration

json-render集成

json-render is the first choice for AI UI generation when output must render across multiple surfaces (web, mobile, CLI, MCP). Define a catalog of components once, generate JSON specs from AI, and render on any target surface. See

ork:json-render-catalog

for catalog authoring patterns.

Rule	File	Key Pattern
json-render Patterns	`rules/json-render-patterns.md`	Catalog-first: define once, render anywhere via per-platform registries

当输出需要支持多端（网页、移动端、CLI、MCP）渲染时，json-render是AI UI生成的首选工具。只需定义一次组件目录，即可通过AI生成JSON规范，然后在任意目标端进行渲染。组件目录编写模式可参考

ork:json-render-catalog

。

规则	文件	核心模式
json-render模式	`rules/json-render-patterns.md`	目录优先：一次定义，通过各平台注册表实现多端渲染

Prompt Engineering

提示工程

Structured prompts that specify framework, tokens, a11y, and states upfront.

Rule	File	Key Pattern
Prompt Patterns	`rules/ai-prompt-patterns.md`	Constraint-first prompts with framework, tokens, a11y
Iteration Patterns	`rules/ai-iteration-patterns.md`	Multi-pass prompts for complex interactive states

提前指定框架、设计令牌、无障碍访问要求与组件状态的结构化提示词。

规则	文件	核心模式
提示词模式	`rules/ai-prompt-patterns.md`	约束优先的提示词，明确框架、令牌、无障碍要求
迭代模式	`rules/ai-iteration-patterns.md`	针对复杂交互状态的多轮提示词迭代

Quality Assurance

质量保障

Systematic review and CI gating for AI-generated components.

Rule	File	Key Pattern
Review Checklist	`rules/ai-review-checklist.md`	10-point checklist for every AI-generated component
CI Gate	`rules/ai-ci-gate.md`	Automated quality gates before merge

AI生成组件的系统化审查与CI管控。

规则	文件	核心模式
审查清单	`rules/ai-review-checklist.md`	适用于所有AI生成组件的10项审查清单
CI关卡	`rules/ai-ci-gate.md`	合并前的自动化质量关卡

Design System Integration

设计系统集成

Ensuring AI output uses design tokens and conforms to the design system.

Rule	File	Key Pattern
Token Injection	`rules/ai-token-injection.md`	Pass token names in prompts, reject hardcoded values
Refactoring Conformance	`rules/ai-refactoring-conformance.md`	Steps to refactor raw AI output for design system

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

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

Tool Selection & Workflow

工具选择与工作流

Choosing the right AI tool and iterating effectively.

Rule	File	Key Pattern
Tool Selection	`rules/ai-tool-selection.md`	Match tool to use case: v0, Bolt, Cursor
Iteration Patterns	`rules/ai-iteration-patterns.md`	Iterative refinement for complex states

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

规则	文件	核心模式
工具选择	`rules/ai-tool-selection.md`	根据场景匹配工具：v0、Bolt、Cursor
迭代模式	`rules/ai-iteration-patterns.md`	针对复杂状态的迭代优化

Key Principles

核心原则

Own the output — AI generates a draft; the engineer reviews, refactors, and is accountable for what ships.
Tokens over literals — Never accept hardcoded colors, spacing, or typography values. Always map to design tokens.
Constraint-first prompts — Specify framework, tokens, a11y, and states upfront. Vague prompts produce vague output.
Iterative refinement — Complex components need 2-3 prompt passes: structure first, states second, polish third.
CI is non-negotiable — Every AI-generated component goes through the same CI pipeline as hand-written code.
Accessibility by default — Include a11y requirements in every prompt; verify with automated checks post-generation.

对输出负责 —— AI生成草稿，由工程师进行审查、重构并对最终交付内容负责。
优先使用令牌而非字面量 —— 绝不接受硬编码的颜色、间距或排版值，始终映射到设计令牌。
约束优先的提示词 —— 提前明确框架、令牌、无障碍要求与状态。模糊的提示词会产生模糊的输出。
迭代优化 —— 复杂组件需要2-3轮提示词迭代：先确定结构，再处理状态，最后进行优化。
CI不可省略 —— 所有AI生成组件都需经过与手写代码相同的CI流水线。
默认支持无障碍访问 —— 在每个提示词中包含无障碍要求，生成后通过自动化检查进行验证。

Anti-Patterns (FORBIDDEN)

反模式（禁止）

Shipping raw AI output — Never merge AI-generated code without human review and design system refactoring.
Vague prompts — "Make a nice form" produces inconsistent, non-conformant output. Always specify constraints.
Hardcoded hex/rgb values — AI tools default to arbitrary colors. Replace with OKLCH design tokens.
Skipping CI for "simple" components — AI-generated code has the same bug surface as hand-written code.
Using v0 for incremental changes — v0 generates from scratch; use Cursor for changes within an existing codebase.
Single-pass complex components — Multi-state components (loading, error, empty, success) need iterative prompting.
Trusting AI a11y claims — AI tools add ARIA attributes inconsistently. Always verify with axe-core or Storybook a11y addon.

直接交付原始AI输出 —— 绝不合并未经人工审查与设计系统重构的AI生成代码。
模糊提示词 —— “做一个好看的表单”会产生不一致、不符合规范的输出，始终要明确约束条件。
硬编码十六进制/RGB值 —— AI工具默认使用随机颜色，需替换为OKLCH设计令牌。
为“简单”组件跳过CI —— AI生成代码的Bug风险与手写代码相同。
使用v0进行增量修改 —— v0从零开始生成代码，对现有代码库的修改应使用Cursor。
单轮生成复杂组件 —— 多状态组件（加载、错误、空状态、成功）需要多轮提示词迭代。
信任AI的无障碍访问声明 —— AI工具添加ARIA属性的方式不一致，始终需通过axe-core或Storybook无障碍插件进行验证。

Detailed Documentation

详细文档

Resource	Description
references/ai-ui-tool-comparison.md	json-render vs v0 vs Bolt vs Cursor vs Copilot comparison
references/prompt-templates-library.md	Copy-paste prompt templates for common components
references/ai-ui-failure-modes.md	Top 10 failure modes and fixes

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