AI UI Generation

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.

Quick Reference

Total: 8 rules across 5 categories

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

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)
- Preset: --preset b2D0xPaDb (or read from project's components.json style field)
- 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.

Prompt Engineering

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

Quality Assurance

Systematic review and CI gating for AI-generated components.

Design System Integration

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

Tool Selection & Workflow

Choosing the right AI tool and iterating effectively.

Key Principles

1. Own the output — AI generates a draft; the engineer reviews, refactors, and is accountable for what ships.
2. Tokens over literals — Never accept hardcoded colors, spacing, or typography values. Always map to design tokens.
3. Constraint-first prompts — Specify framework, tokens, shadcn style (Luma/Nova/etc.), a11y, and states upfront. Vague prompts produce vague output.
4. Iterative refinement — Complex components need 2-3 prompt passes: structure first, states second, polish third.
5. CI is non-negotiable — Every AI-generated component goes through the same CI pipeline as hand-written code.
6. 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 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.

Detailed Documentation

Related Skills

• ork:json-render-catalog — json-render catalog authoring, schema validation, and registry patterns
• ork:mcp-visual-output — MCP visual output rendering with json-render specs
• ork:multi-surface-render — Cross-platform rendering from a single component catalog
• ork:ui-components — shadcn/ui component patterns and CVA variants
• ork:accessibility — WCAG compliance, ARIA patterns, screen reader support
• ork:animation-motion-design — Motion library animation patterns
• ork:responsive-patterns — Responsive layout and container query patterns
• ork:design-system — Design token architecture and theming