JSON Render Catalog

Upstream version reference: @json-render/core 0.21.0 (2026-09-30).

json-render Component Catalogs

json-render (Vercel Labs, 12.9K stars, Apache-2.0) is a framework for AI-safe generative UI. AI generates flat-tree JSON (or YAML) specs constrained to a developer-defined catalog — the catalog is the contract between your design system and AI output. If a component or prop is not in the catalog, AI cannot generate it.

Storybook → catalog import (#1529, 2026-04)

When the project ships a Storybook setup, import the catalog from Storybook stories instead of hand-writing one. The bundled importer at scripts/storybook-to-catalog.mjs reads a @storybook/addon-mcp list-all-documentation manifest and emits a Zod-typed catalog.ts plus a components.tsx registry.

node "${CLAUDE_SKILL_DIR}/scripts/storybook-to-catalog.mjs" storybook-manifest.json \
  --out src/genui/catalog.ts \
  --components src/genui/components.tsx \
  --project-root .

Storybook becomes the single source of truth — adding a story automatically expands the AI-allowed surface; removing one shrinks it. AI safety is enforced at import: callbacks, raw object props, and z.any() are dropped. Full mapping: references/storybook-import.md. Companion fixture for testing: references/storybook-fixture.json.

New in 2026-04 → 2026-08 (json-render 0.14 → 0.20)

• Named slots (0.20) — UIElement gains slots?: Record<string, string[]>, a catalog declares which it accepts via slots: ["default", "header", "footer"], and a React registry component receives named content as slots?.header while children stays the default slot. Prefer this over encoding layout regions as separate sibling elements.
• Nested repeats and item-scoped visibility (0.20) — repeat.statePath accepts an item-relative {"$item": "employees"} form (new RepeatStatePath type plus resolveRepeatStatePath / resolveRepeatItemStatePath), and a repeat combined with visible: {"$item": "status", "eq": "todo"} on the same element now filters items instead of erroring. validateSpec gains invalid_visible, repeat_without_children, repeat_item_outside_scope and repeat_state_mismatch issue codes.
• Custom directives API (0.19) — @json-render/core now ships defineDirective, letting you declare new JSON shapes (e.g. $format, $math) that resolve to computed values at render time. Directives compose by nesting and resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution. This is the safe escape hatch for computed values without widening the catalog to z.any().
• @json-render/directives package (0.19) — seven ready-made directives: $format (date / currency / number / percent via Intl), $math (add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs), $concat, $count, $truncate, $pluralize, $join. Plus createI18nDirective for $t translation keys with {{param}} interpolation, and standardDirectives for one-line registration. Register once, use in any spec — AI no longer needs string-mangling or duplicated literals.
• Devtools ecosystem (0.18) — five new packages: @json-render/devtools core + framework adapters for React, Vue, Svelte, Solid. Inspector panel has six tabs (Spec, State, Actions, Stream, Catalog, Pick) with DOM element picking that maps back to spec keys. Tree-shakes to null in production. Companion Next.js demo app shipped with AI-chat + catalog integration. Action observer infrastructure exposed for adapters to mirror events into the panel.
• Zod 4 fix (0.18) — formatZodType now correctly handles z.record(), z.default(), and z.literal() (previously produced empty/wrong prompt output).
• Three edit modes (0.14) — patch (RFC 6902), merge (RFC 7396), diff (unified) for progressive AI refinements. buildEditUserPrompt() + diffToPatches() + deepMergeSpec() in @json-render/core.
• @json-render/yaml (0.14) — official YAML wire format + streaming parser; buildUserPrompt({ format: 'yaml' }).
• @json-render/ink (0.15) — render catalogs to terminal UIs (Ink-based, 20+ components) using the same spec.
• @json-render/next (0.16) — generate full Next.js apps (routes, layouts, SSR, metadata) from a single spec.
• @json-render/shadcn-svelte (0.16) — 36-component Svelte 5 + Tailwind mirror of the React shadcn catalog.
• shadcn catalog at 36 components (was documented as 29 — the count was wrong even at 0.13). Use @json-render/shadcn as-is, or spread shadcnComponentDefinitions together with your own definitions.
• @json-render/react-three-fiber ships 19 components (verified 2026-07-31 against the upstream skill; do not restate the roster here, see Upstream coverage).
• @json-render/mcp — upgrade plain MCP tool JSON into interactive iframes inside Claude/Cursor/ChatGPT conversations. See the ork:mcp-visual-output skill.
• MCP multi-surface: same spec renders to React, PDF (@json-render/react-pdf), email (@json-render/react-email), terminal (Ink), Next.js apps, and Remotion videos.

Directives — @json-render/directives (0.19)

Directives are the safe escape hatch for computed values. AI emits a $-prefixed object, the renderer resolves it inside-out before the component receives props — the catalog stays strict (no z.any() widening) and the spec stays declarative. The @json-render/directives package ships seven prebuilt directives plus an i18n factory; standardDirectives exports them as one array for one-line registration. Directives nest freely (e.g. $format wrapping $math) and are resolved by all four renderer integrations (React, Vue, Svelte, Solid).

Registration

import { defineRegistry, JSONUIProvider, Renderer } from '@json-render/react'
import { standardDirectives, createI18nDirective } from '@json-render/directives'

const directives = [
  ...standardDirectives,
  createI18nDirective({
    locale: 'en',
    fallbackLocale: 'en',
    messages: { en: { greeting: 'Hello, {{name}}!' } },
  }),
]

const { registry } = defineRegistry(catalog, { components })

// directives register on the provider (RendererProps has no directives prop)
<JSONUIProvider registry={registry} directives={directives}>
  <Renderer spec={spec} registry={registry} />
</JSONUIProvider>

The seven prebuilt directives

createI18nDirective({ locale, messages, fallbackLocale? }) registers a $t directive with {{param}} interpolation: { "$t": "greeting", "params": { "name": "Ada" } }.

Custom directives via defineDirective

defineDirective lives in @json-render/core (0.19+). A directive declares a Zod schema for its JSON shape and a resolve(raw, ctx) function — use resolvePropValue(raw.field, ctx) to recursively resolve any nested directive or state reference before computing.

import { defineDirective, resolvePropValue } from '@json-render/core'
import { z } from 'zod'

export const initialsDirective = defineDirective({
  name: '$initials',
  description: 'First letter of each word, uppercased.',
  schema: z.object({ $initials: z.unknown() }),
  resolve(raw, ctx) {
    const text = String(resolvePropValue(raw.$initials, ctx) ?? '')
    return text.split(/\s+/).map((w) => w[0]?.toUpperCase() ?? '').join('')
  },
})

Spread into the renderer alongside standardDirectives: directives={[...standardDirectives, initialsDirective]}. Keep the schema tight — directives are the only place where AI gets to emit non-catalog JSON, so let Zod enforce shape just like a component prop.

Upstream coverage (do not restate)

json-render ships its own per-package skills. This skill wraps them and keeps only the delta: our Storybook import path, our catalog constraints, and the scars in references/ork-delta.md. Do not copy vendor rosters or API tables back in.

Our delta, the part no upstream doc carries: references/ork-delta.md.

Quick Reference

Total: 3 rules across 3 categories

How json-render Works

1. Developer defines a catalog — Zod-typed component definitions with constrained props
2. AI generates a spec — flat-tree JSON/YAML referencing only catalog components
3. Runtime renders the spec — <Renderer> component validates and renders each element

The catalog is the safety boundary. AI can only reference types that exist in the catalog, and props are validated against Zod schemas at runtime. This prevents hallucinated components and invalid props from reaching the UI.

Quick Start — 3 Steps

Step 1: Define a Catalog

import { defineCatalog } from '@json-render/core'
import { schema } from '@json-render/react/schema'
import { z } from 'zod'

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({
        title: z.string(),
        description: z.string().optional(),
      }),
      children: true,
    },
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(['default', 'destructive', 'outline', 'ghost']),
      }),
      children: false,
    },
    StatGrid: {
      props: z.object({
        items: z.array(z.object({
          label: z.string(),
          value: z.string(),
          trend: z.enum(['up', 'down', 'flat']).optional(),
        })).max(20),
      }),
      children: false,
    },
  },
})

LLM Structured Output Compatibility

Use jsonSchema({ strict: true }) to export catalog schemas compatible with LLM structured output APIs (OpenAI, Anthropic, Gemini):

// jsonSchema is a METHOD on the Catalog instance, not a top-level export.
const schema = catalog.jsonSchema({ strict: true })
// Pass to OpenAI response_format, Anthropic tool_use, or Gemini structured output

Step 2: Implement Components

import type { InferCatalogComponents } from '@json-render/core'
import type { catalog } from './catalog'

export const components: InferCatalogComponents<typeof catalog> = {
  Card: ({ title, description, children }) => (
    <div className="rounded-lg border p-4">
      <h3 className="font-semibold">{title}</h3>
      {description && <p className="text-muted-foreground">{description}</p>}
      {children}
    </div>
  ),
  Button: ({ label, variant }) => (
    <button className={cn('btn', `btn-${variant}`)}>{label}</button>
  ),
  StatGrid: ({ items }) => (
    <div className="grid grid-cols-3 gap-4">
      {items.map((item) => (
        <div key={item.label}>
          <span>{item.label}</span>
          <strong>{item.value}</strong>
        </div>
      ))}
    </div>
  ),
}

Step 3: Render a Spec

import { defineRegistry, Renderer } from '@json-render/react'
import { catalog } from './catalog'
import { components } from './components'

// defineRegistry returns DefineRegistryResult — destructure `registry`
const { registry } = defineRegistry(catalog, { components })

function App({ spec }: { spec: JsonRenderSpec }) {
  return <Renderer spec={spec} registry={registry} />
}

Spec Format

The JSON spec is a flat tree — no nesting, just IDs and references. Field-by-field documentation (root, elements, props, children, on, watch, state, and the $state / $bindState / $cond / $template / $computed expressions) is upstream in https://github.com/vercel-labs/json-render skills/core/SKILL.md.

{
  "root": "card-1",
  "elements": {
    "card-1": {
      "type": "Card",
      "props": { "title": "Dashboard" },
      "children": ["chart-1", "btn-1"]
    },
    "btn-1": {
      "type": "Button",
      "props": { "label": "View Details", "variant": "default" }
    }
  }
}