json-render-catalog

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_PLUGIN_ROOT}/skills/json-render-catalog/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.