Generative UI
Produce JSON specs constrained to a catalog of predefined components. Never write arbitrary JSX — generate structured JSON that a renderer turns into platform-specific UI.
For conceptual background, decision criteria, and common patterns, see
README.md.
Renderer Selection
| Need | Package | Skill |
|---|---|---|
| Web app UI | @json-render/react | json-render-react |
| shadcn/ui components | @json-render/shadcn | json-render-shadcn |
| Mobile native | @json-render/react-native | json-render-react-native |
| Video compositions | @json-render/remotion | json-render-remotion |
| HTML email | @json-render/react-email | json-render-react-email |
| OG/social images | @json-render/image | json-render-image |
| Vue web apps | @json-render/vue | (no skill yet) |
| PDF documents | @json-render/react-pdf | (no skill yet) |
Always invoke the renderer-specific skill for implementation details. This skill covers when and why; the renderer skills cover how.
Catalog Design Principles
- Pick, don't spread — Explicitly select components from
shadcnComponentDefinitions. Never spread all 36 into your catalog. - Minimal catalog — Start with 5-8 components. Add more only when the AI needs them.
- Custom components — Define with Zod schemas. Use slots for children, actions for interactivity.
- Two entry points —
@json-render/shadcn/catalog(server-safe schemas) and@json-render/shadcn(React implementations).
GemSkills Integration
Generate visual assets within generative UI workflows:
| Asset Type | Skill | Use Case |
|---|---|---|
| Hero images, backgrounds | generate-image | Dashboard headers, card backgrounds |
| Logos, vector graphics | generate-svg | Brand elements within generated UI |
| App icons | generate-icon | Platform-specific icon sets |
| Post-processing | edit-image | Crop, resize, style-transfer on generated images |
| Video backgrounds | generate-video | Remotion compositions with AI video |
| Style exploration | browsing-styles | Browse 169 visual styles before generating |
Pipeline: browsing-styles (pick style) -> generate-image (create) -> edit-image (refine) -> optimize-images (compress)
MCP Apps Delivery
Generative UI specs can be delivered directly inside chat hosts (Claude, ChatGPT, VS Code Copilot) via MCP Apps. The json-render React renderer runs inside a Vite-bundled single-file HTML served as a ui:// resource.
Delivery path:
- AI generates a json-render spec (JSON)
- MCP tool returns the spec as
structuredContent(a structured JSON response the host renders in the UI, separate from the text the model sees) - The MCP App View (sandboxed iframe) receives it via
ontoolresult - View's embedded
<Renderer>component renders the spec as interactive UI - User interacts — View calls server tools for fresh data, re-renders
This combines generative UI's guardrailed output with MCP Apps' context preservation and bidirectional data flow. No tab switching, no separate web app.
AI generates spec → MCP tool returns structuredContent
→ Host renders ui:// resource in iframe
→ View renders spec with json-render <Renderer>
→ User interacts → View calls tools → fresh spec
For building MCP Apps that deliver generative UI, use Skill(bopen-tools:mcp-apps).
Delivery Channels
| Renderer | Package | Delivery Channel |
|---|---|---|
| Web | @json-render/react | Web app or MCP App (ui:// resource) |
| shadcn/ui | @json-render/shadcn | Web app or MCP App (ui:// resource) |
| Mobile | @json-render/react-native | React Native app |
| Video | @json-render/remotion | Video file |
@json-render/react-email | Email (HTML) | |
| Images | @json-render/image | Image file (PNG/SVG) |
MCP Apps delivery is available for any renderer that targets the browser (React, shadcn). Bundle the renderer + catalog + registry into a single HTML file with Vite + vite-plugin-singlefile, serve it as a ui:// resource.
Reference Files
references/renderer-guide.md— Deep dive on each renderer's API and patternsreferences/component-libraries.md— Available components and custom component patterns