AI UI Generation
Patterns for generating, reviewing, and integrating UI components produced by AI tools (json-render, v0.app, Google Stitch, Bolt Cloud, 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.
Tool landscape as of 2026-04:
- v0.dev → v0.app (Jan 2026 rebrand) — expanded from component scaffolding to full-stack app generation with shipping targets (Vercel, Cloudflare, Railway). v0.app MCP server (
@vercel/v0-mcp) exposes generation as an MCP tool, so agents can call it programmatically.
- Google Stitch — design-first generation via
stitch.withgoogle.com/docs/mcp. Produces multi-screen apps (up to 5 interconnected screens) with React/HTML + PNG. Strong when input is a screenshot, URL, or DESIGN.md file.
- Bolt Cloud (StackBlitz, 2026) — Bolt now runs the dev environment in the cloud (no local WebContainer). Integrates with GitHub and supports persistent databases. Best for full-stack prototypes with backend + deploy.
- v0.app and Stitch both integrate with shadcn/ui styles; pair with the
shadcn apply <style> CLI (v4) to reuse generated output.
Quick Reference
Total: 8 rules across 5 categories
Decision Table — json-render vs v0.app vs Stitch vs Bolt Cloud 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.app |
Full scaffold with shadcn/ui, Tailwind, a11y. Pair with shadcn apply <style> for style consistency |
| Full-stack app with deploy |
v0.app |
Jan 2026 expansion — routes, DB, auth, Vercel/Cloudflare deploy in one generation |
| Design-driven (screenshot/URL/DESIGN.md) |
Google Stitch |
build_site + get_screen_code / get_screen_image, up to 5 screens |
| Multi-screen flow from a visual source |
Google Stitch |
Strongest when grounded in an existing design |
| Full-stack prototype with persistent backend |
Bolt Cloud |
Cloud dev env, GitHub integration, databases |
| 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.app or Stitch |
v0.app for freeform, Stitch when grounded in a reference |
| Add feature to running app |
Bolt Cloud |
Cloud preview, full environment, persists between sessions |
| Fix bug in existing component |
Cursor |
Inline edits with full project awareness |
Quick Start
Structured Prompt Example
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
Review Example — After AI Generation
// 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 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 |
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 |
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 |
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 |
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 |
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, shadcn style (Luma/Nova/etc.), 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.
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.app for incremental changes — v0.app 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.
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 |
Related Skills
ork:json-render-catalog — json-render catalog authoring, schema validation, and registry patternsork:mcp-visual-output — MCP visual output rendering with json-render specsork:multi-surface-render — Cross-platform rendering from a single component catalogork:ui-components — shadcn/ui component patterns and CVA variantsork:accessibility — WCAG compliance, ARIA patterns, screen reader supportork:animation-motion-design — Motion library animation patternsork:responsive-patterns — Responsive layout and container query patternsork:design-system-tokens — Design token architecture and theming
1---2name: ai-ui-generation3description: AI-assisted UI generation patterns for json-render, v0.app, Google Stitch, Bolt Cloud, and Cursor workflows. Covers prompt engineering for component and full-stack app generation, review checklists for AI-generated code, design token injection, refactoring for design system conformance, and CI gates for quality assurance. Use when generating UI components with AI tools, rendering multi-surface MCP visual output, reviewing AI-generated code, or integrating AI output into design systems.4license: MIT5---6
7# AI UI Generation
8
9Patterns for generating, reviewing, and integrating UI components produced by AI tools (json-render, v0.app, Google Stitch, Bolt Cloud, 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.
10
11> **Tool landscape as of 2026-04:**
12> - **v0.dev → v0.app** (Jan 2026 rebrand) — expanded from component scaffolding to full-stack app generation with shipping targets (Vercel, Cloudflare, Railway). v0.app MCP server (`@vercel/v0-mcp`) exposes generation as an MCP tool, so agents can call it programmatically.
13> - **Google Stitch** — design-first generation via `stitch.withgoogle.com/docs/mcp`. Produces multi-screen apps (up to 5 interconnected screens) with React/HTML + PNG. Strong when input is a screenshot, URL, or DESIGN.md file.
14> - **Bolt Cloud** (StackBlitz, 2026) — Bolt now runs the dev environment in the cloud (no local WebContainer). Integrates with GitHub and supports persistent databases. Best for full-stack prototypes with backend + deploy.
15> - **v0.app** and **Stitch** both integrate with shadcn/ui styles; pair with the `shadcn apply <style>` CLI (v4) to reuse generated output.
16
17## Quick Reference
18
19| Category | Rules | Impact | When to Use |
20|----------|-------|--------|-------------|
21| [json-render Integration](#json-render-integration) | 1 | HIGH | Multi-surface output, MCP visual output, type-safe catalogs |
22| [Prompt Engineering](#prompt-engineering) | 2 | HIGH | Writing prompts for component generation |
23| [Quality Assurance](#quality-assurance) | 2 | CRITICAL/HIGH | Reviewing and gating AI-generated code |
24| [Design System Integration](#design-system-integration) | 2 | HIGH | Injecting tokens, refactoring for conformance |
25| [Tool Selection & Workflow](#tool-selection--workflow) | 2 | MEDIUM | Choosing the right AI tool, iterating prompts |
26
27**Total: 8 rules across 5 categories**
28
29## Decision Table — json-render vs v0.app vs Stitch vs Bolt Cloud vs Cursor
30
31| Scenario | Tool | Why |
32|----------|------|-----|
33| Multi-surface / MCP visual output | json-render | Single catalog renders to any surface — FIRST CHOICE |
34| Type-safe component catalog | json-render | Schema-driven specs with per-platform registries |
35| Streaming UI from AI agents | json-render | Structured JSON specs render progressively |
36| New component from scratch | v0.app | Full scaffold with shadcn/ui, Tailwind, a11y. Pair with `shadcn apply <style>` for style consistency |
37| Full-stack app with deploy | v0.app | Jan 2026 expansion — routes, DB, auth, Vercel/Cloudflare deploy in one generation |
38| Design-driven (screenshot/URL/DESIGN.md) | Google Stitch | `build_site` + `get_screen_code` / `get_screen_image`, up to 5 screens |
39| Multi-screen flow from a visual source | Google Stitch | Strongest when grounded in an existing design |
40| Full-stack prototype with persistent backend | Bolt Cloud | Cloud dev env, GitHub integration, databases |
41| Incremental change in existing codebase | Cursor | Understands project context, imports, tokens |
42| Refactor existing component | Cursor | Reads surrounding code, respects conventions |
43| Explore visual design variations | v0.app or Stitch | v0.app for freeform, Stitch when grounded in a reference |
44| Add feature to running app | Bolt Cloud | Cloud preview, full environment, persists between sessions |
45| Fix bug in existing component | Cursor | Inline edits with full project awareness |
46
47## Quick Start
48
49### Structured Prompt Example
50
51```
52Generate a React signup form component using:
53- Framework: React 19 + TypeScript
54- Styling: Tailwind CSS v4 + shadcn/ui (Luma style — rounded-4xl, shadow-md elevation)
55- Style: run `npx shadcn@latest apply luma` (CLI v4, Apr 2026) after generation
56- Tokens: use color.primary, color.destructive, spacing.md from our design system
57- A11y: ARIA labels on all inputs, error announcements via aria-live
58- States: default, loading (disabled + spinner), error (inline messages), success
59- Responsive: stack on mobile (<640px), 2-col on desktop
60```
61
62### Review Example — After AI Generation
63
64```tsx
65// AI generated: hardcoded hex value
66<button className="bg-[#3b82f6] text-white px-4 py-2">Submit</button>
67
68// After human review: design token applied
69<Button variant="default" size="md">Submit</Button>
70```
71
72## Rule Details
73
74### json-render Integration
75
76json-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.
77
78| Rule | File | Key Pattern |
79|------|------|-------------|
80| json-render Patterns | `rules/json-render-patterns.md` | Catalog-first: define once, render anywhere via per-platform registries |
81
82### Prompt Engineering
83
84Structured prompts that specify framework, tokens, a11y, and states upfront.
85
86| Rule | File | Key Pattern |
87|------|------|-------------|
88| Prompt Patterns | `rules/ai-prompt-patterns.md` | Constraint-first prompts with framework, tokens, a11y |
89| Iteration Patterns | `rules/ai-iteration-patterns.md` | Multi-pass prompts for complex interactive states |
90
91### Quality Assurance
92
93Systematic review and CI gating for AI-generated components.
94
95| Rule | File | Key Pattern |
96|------|------|-------------|
97| Review Checklist | `rules/ai-review-checklist.md` | 10-point checklist for every AI-generated component |
98| CI Gate | `rules/ai-ci-gate.md` | Automated quality gates before merge |
99
100### Design System Integration
101
102Ensuring AI output uses design tokens and conforms to the design system.
103
104| Rule | File | Key Pattern |
105|------|------|-------------|
106| Token Injection | `rules/ai-token-injection.md` | Pass token names in prompts, reject hardcoded values |
107| Refactoring Conformance | `rules/ai-refactoring-conformance.md` | Steps to refactor raw AI output for design system |
108
109### Tool Selection & Workflow
110
111Choosing the right AI tool and iterating effectively.
112
113| Rule | File | Key Pattern |
114|------|------|-------------|
115| Tool Selection | `rules/ai-tool-selection.md` | Match tool to use case: v0, Bolt, Cursor |
116| Iteration Patterns | `rules/ai-iteration-patterns.md` | Iterative refinement for complex states |
117
118## Key Principles
119
1201. **Own the output** — AI generates a draft; the engineer reviews, refactors, and is accountable for what ships.
1212. **Tokens over literals** — Never accept hardcoded colors, spacing, or typography values. Always map to design tokens.
1223. **Constraint-first prompts** — Specify framework, tokens, shadcn style (Luma/Nova/etc.), a11y, and states upfront. Vague prompts produce vague output.
1234. **Iterative refinement** — Complex components need 2-3 prompt passes: structure first, states second, polish third.
1245. **CI is non-negotiable** — Every AI-generated component goes through the same CI pipeline as hand-written code.
1256. **Accessibility by default** — Include a11y requirements in every prompt; verify with automated checks post-generation.
126
127## Anti-Patterns (FORBIDDEN)
128
129- **Shipping raw AI output** — Never merge AI-generated code without human review and design system refactoring.
130- **Vague prompts** — "Make a nice form" produces inconsistent, non-conformant output. Always specify constraints.
131- **Hardcoded hex/rgb values** — AI tools default to arbitrary colors. Replace with OKLCH design tokens.
132- **Skipping CI for "simple" components** — AI-generated code has the same bug surface as hand-written code.
133- **Using v0.app for incremental changes** — v0.app generates from scratch; use Cursor for changes within an existing codebase.
134- **Single-pass complex components** — Multi-state components (loading, error, empty, success) need iterative prompting.
135- **Trusting AI a11y claims** — AI tools add ARIA attributes inconsistently. Always verify with axe-core or Storybook a11y addon.
136
137## Detailed Documentation
138
139| Resource | Description |
140|----------|-------------|
141| [references/ai-ui-tool-comparison.md](references/ai-ui-tool-comparison.md) | json-render vs v0 vs Bolt vs Cursor vs Copilot comparison |
142| [references/prompt-templates-library.md](references/prompt-templates-library.md) | Copy-paste prompt templates for common components |
143| [references/ai-ui-failure-modes.md](references/ai-ui-failure-modes.md) | Top 10 failure modes and fixes |
144
145## Related Skills
146
147- `ork:json-render-catalog` — json-render catalog authoring, schema validation, and registry patterns
148- `ork:mcp-visual-output` — MCP visual output rendering with json-render specs
149- `ork:multi-surface-render` — Cross-platform rendering from a single component catalog
150- `ork:ui-components` — shadcn/ui component patterns and CVA variants
151- `ork:accessibility` — WCAG compliance, ARIA patterns, screen reader support
152- `ork:animation-motion-design` — Motion library animation patterns
153- `ork:responsive-patterns` — Responsive layout and container query patterns
154- `ork:design-system-tokens` — Design token architecture and theming
yonatangross