The UI spec format
@kimen/catalog is the GenUI boundary of Kimen: the machine-readable schema
of what agents may emit — every published ki-* element with typed props,
slots, events and when-to-use guidance — plus the validation entry point
that accepts or rejects agent-emitted UI specs before anything renders. The
catalog artifact is generated from the committed Custom Elements Manifest of
@kimen/elements and gated against drift, so it can never disagree with the
components.
A UI spec is data, never code: a JSON tree of catalog components, typed props, slotted children and declared actions.
import { catalogData, validateUiSpec } from '@kimen/catalog';
// What may an agent emit? One entry per published element:catalogData.components['ki-button'].props.variant;// { type: 'enum', values: ['ghost', 'primary', 'quaternary', 'secondary'], ... }
// Validate an agent-emitted UI spec before anything renders:const report = validateUiSpec({ version: 1, actions: ['confirm-order'], root: { component: 'ki-card', slots: { header: ['Confirm your order'], footer: [ { component: 'ki-button', props: { variant: 'primary' }, action: 'confirm-order', slots: { '': ['Confirm'] }, }, ], }, },});report.ok; // true — or false with issues naming each offender and locationUse values when generating enum props. The optional deprecatedValues
field lists older values the runtime still accepts for existing specs.
What validation rejects
Section titled “What validation rejects”Validation rejects — naming the offender — unknown components, unknown
props, wrong-typed values, undeclared slots, bindings to actions the spec’s
actions list never declares, prototype-pollution keys (__proto__,
constructor, prototype) anywhere in the document, payloads beyond the
size budget and nesting beyond the depth budget.
Object input crosses an iterative purity wall before any other check:
validation never invokes getters or toJSON on the input (accessor
properties, functions and other non-JSON values are rejected as not-data),
shared object references and cycles are rejected (a spec is a JSON tree),
and every later check runs on a plain-data snapshot — so mutating the
original mid-validation changes nothing.
The v1 spec format exposes no styling surface: no CSS values, no
per-spec token reassignment (a layout div takes spacing token steps, never
CSS), and no style, class, slot or id attribute written from spec
data (no catalog, built-in or registered, can declare those props).
Appearance stays at the consuming application’s token layer.
Native primitives
Section titled “Native primitives”Next to catalog components a spec may carry a closed set of native HTML
elements (spec 037), listed in NATIVE_PRIMITIVE_TAGS:
- Text:
h2,h3,h4,p, andstrong/eminside them. No attributes; the text takes the host page’s typography (the renderer writes none).h1is the host’s. - Image:
imgwithsrc(held to the URL policy),alt(required: a description, or exactly""for a decorative image; white space alone is rejected) and optionalwidth/heighthints. The renderer pinsreferrerpolicy="no-referrer"and container-fit sizing. - Layout:
divwithdirection(column|row),gap(a spacing token step:zero,xs,sm,md,lg,xl,3xl,7xl, written asvar(--ki-space-<step>)),align,justifyandwrap. The layout is written through the CSSOM, never as astyleattribute, so a page whose Content-Security-Policy forbids inline styles keeps working.
{ "version": 1, "root": { "component": "div", "props": { "gap": "lg" }, "slots": { "": [ { "component": "h2", "slots": { "": ["Resumen"] } }, { "component": "p", "slots": { "": ["Ventas de ", { "component": "strong", "slots": { "": ["marzo"] } }] } }, { "component": "img", "props": { "src": "/img/ventas.png", "alt": "Gráfico de ventas" } }, { "component": "ki-button", "slots": { "": ["Ver detalle"] } } ] } }}Every other element (script, iframe, a, span, SCRIPT, …) is
unknown-component, and every other attribute (style, class, on*,
srcset, …) is unknown-prop. Headings, paragraphs and emphasis accept
only text, strong and em (invalid-child otherwise), and no native
element binds an action (action-not-allowed). The primitives come with
the built-in catalog and with catalogs that extend it; a consumer
definition can never declare one, and the renderer renders a native tag
only when the catalog in use carries exactly Kimen’s definition of it.
The guarded renderer
Section titled “The guarded renderer”renderUiSpec renders an untrusted spec into a host-owned surface,
fail-closed and atomic — full validation precedes the first attach, so a
rejected spec never touches the DOM:
import { renderUiSpec } from '@kimen/catalog';
const result = renderUiSpec(spec, { surface: document.querySelector('#genui'), onAction: (event) => console.log(event.action, event.data), budgets: { maxDepth: 32, maxNodes: 512, maxBytes: 262_144 }, catalogSchemaVersion: '1.0.0',});if (!result.ok) console.warn(result.diagnostics); // machine-readable, inertOver the validation layer it enforces the safe-render semantics:
- No code path from spec data. Text is attached as inert text nodes,
never parsed as markup; the catalog exposes no event-handler props;
URL-typed props accept only
http,httpsand relative references — every other scheme is rejected naming the prop and scheme. - Declared budgets. Depth, node count and payload size — a spec exactly at a budget renders, one beyond it is rejected before any node attaches.
- Version skew. A spec declaring an unsupported
catalogSchemaVersionis rejected naming both versions. - Declarative actions only. A bound control dispatches its one declared
action, as data, on the single
onActionchannel — exactly one action fires even for nested action-bound nodes; no other callback exists.
A re-render on the same surface replaces the previous tree (and its action
listeners) atomically once validation succeeds; a rejected re-render leaves
the previous content intact. Every rejection is a RenderDiagnostic — node
path, violated rule and offending value — pure data, safe to display because
a host renders it as text.
Streaming
Section titled “Streaming”createStreamingRenderer renders a streamed spec progressively: a node
attaches only after it fully validates; an invalid node halts the stream
fail-closed while previously validated content remains; the budgets bind the
accumulated stream, so a stream that never closes still trips its payload
budget; and once halted — by an invalid node, a tripped budget, version skew
or close() — every further push is rejected.
What validation does not protect against
Section titled “What validation does not protect against”URL-scheme allowlisting and markup inertness are render-path invariants owned by the guarded renderer: catalog validation is a schema boundary, never content sanitization. A host that renders outside the guarded renderer is outside the guardrail.
Registering your own components
Section titled “Registering your own components”The catalog a spec validates against does not have to be the built-in one.
createCatalog accepts a data-only definition of your components — the
exact entry shape the generated catalog uses (tag, usage guidance, typed
prop constraints, slots, events) — and returns an immutable catalog value
that validateUiSpec, renderUiSpec and createStreamingRenderer take
through their catalog option:
import { catalogData, createCatalog, renderUiSpec } from '@kimen/catalog';
const created = createCatalog( { components: { 'acme-kpi-card': { tag: 'acme-kpi-card', description: 'A KPI card for Acme dashboards.', whenToUse: 'Show one operational metric with its trend.', whenNotToUse: 'Tabular breakdowns of many metrics.', props: { tone: { type: 'enum', values: ['ok', 'warn', 'critical'], description: 'Semantic severity of the metric.', }, }, slots: { '': 'The metric label.' }, events: {}, }, }, }, { extend: catalogData }, // omit to build a standalone catalog);if (created.ok) { renderUiSpec(spec, { surface, catalog: created.catalog });}“Outside the catalog” then means outside the catalog in use; nothing else
about validation or rendering changes, and when the option is absent the
built-in catalog remains the boundary. The definition itself is treated as
hostile input — it crosses the same purity wall as UI specs, plus tag,
collision and guidance rules, and every rejection is a coded
RegistrationIssue naming its offender. The returned catalog is deeply
frozen: mutating it later can never alter validation or render outcomes.
The catalog carries contracts, never implementations — your bundle keeps
customElements.define ownership, and your components’ accessibility
remains your contract.
The full registration surface, acceptance rules and security model live in
the
@kimen/catalog README.
Protocol adapters
Section titled “Protocol adapters”The catalog and the ki-* elements are the durable assets; protocol
adapters are deliberately disposable translations onto this one boundary:
- A2UI adapter — declarative A2UI messages.
- MCP Apps adapter —
ui://surfaces for MCP hosts.
The canonical package documentation lives in the repository:
packages/catalog.