Generative UI

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.

Current Baseline

Verify package versions before implementation with bun pm view <package> version. The tested stable baseline is json-render 0.19.0 with React 19, Zod 4, and Tailwind 4. Pin a coherent release line; do not mix stable packages with unreleased main behavior.

Use the flat React spec shape published by @json-render/react: root is an element key and elements is a map whose children arrays contain keys. Validate every generated spec before rendering and retry or fall back to text on failure.

Renderer Selection

Always invoke the renderer-specific skill for implementation details. This skill covers when and why; the renderer skills cover how.

For React work, invoke json-render-core and json-render-react together. Add json-render-directives for deterministic display calculations and json-render-devtools during development.

Catalog Design Principles

1. Pick, don't spread — Explicitly select components from shadcnComponentDefinitions. Never spread all 36 into your catalog.
2. Minimal catalog — Start with 5-8 components. Add more only when the AI needs them.
3. Custom components — Define with Zod schemas. Use slots for children, actions for interactivity.
4. Two entry points — @json-render/shadcn/catalog (server-safe schemas) and @json-render/shadcn (React implementations).
5. Stable semantics outside the spec — Keep authoritative IDs, permissions, and domain rules in application state or server code. Let the generated spec choose presentation, not truth.
6. Text escape hatch — Every generated workflow needs an accessible plain-text fallback.

Refinement and Directives

Use patch, merge, or diff edit modes to refine an existing surface instead of regenerating it wholesale. Start pilots with complete validated specs; add streaming only when progressive rendering materially improves the experience.

Use standard directives for locale-aware formatting, arithmetic, concatenation, counts, truncation, pluralization, joins, and translation. Keep policy decisions and privileged calculations server-side; directives are deterministic presentation helpers.

GemSkills Integration

Generate visual assets within generative UI workflows:

Pipeline: browsing-styles (pick style) -> generate-image (create) -> edit-image (refine) -> optimize-images (compress)

MCP Apps Delivery

Generative UI specs can be delivered inside hosts that negotiate the MCP Apps extension. Serve a static ui:// resource and pass dynamic data through tool results. Always return useful text content alongside UI data so unsupported hosts still work.

Delivery path:

1. AI generates a json-render spec (JSON)
2. MCP tool returns a text summary plus validated UI data, preferably in structuredContent
3. The MCP App View (sandboxed iframe) receives it via ontoolresult
4. View's embedded <Renderer> component renders the spec as interactive UI
5. 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 where supported.

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(mcp-dev:mcp-apps).

Delivery Channels

MCP Apps delivery is available for browser renderers. A single-file bundle is the most portable default, but it is not a protocol requirement when every referenced asset and origin is declared through exact resource CSP metadata.

@json-render/mcp@0.19.0 is useful scaffolding, not a complete production boundary: its helper serializes specs through text and uses broad CSP defaults. Wrap or replace that boundary when strict structuredContent, exact CSP, or app-only submission tools are required. Use the official MCP client matrix rather than assuming every host behaves the same.

Dithered primitives

dither-kit (Boring-Software-Inc) is a shadcn-style registry of Bayer-matrix dithered chart and identity primitives, vendored per-component:

bunx --bun shadcn@latest add Boring-Software-Inc/dither-kit/<component>

Charts (area, bar, pie, radar, sparkline):

<DitherBarChart data={rows} color="blue" />

Avatar — deterministic placeholder identity, same name -> same glyph:

<DitherAvatar name={seed} />

Standalone (button, gradient):

<DitherButton color="green">Ship</DitherButton>

Palette constraint: charts/buttons take a color prop locked to a 7-value enum (green/blue/purple/pink/orange/red/grey) — fork the vendored palette.ts for exact brand RGB triples. DitherAvatar and gradient take a continuous hue (0-360) instead, with no enum limit. Skip the dither treatment on dense tables or text-heavy surfaces, where the ordered-dither texture fights readability.

Reference Files

• references/renderer-guide.md — Deep dive on each renderer's API and patterns
• references/component-libraries.md — Available components and custom component patterns