Polyxd README

Polyxd

An open spec, renderer and verifier for interfaces generated on demand — rendered natively in your design system, operable by people and agents alike, and checked before anyone sees them.

A request comes in. Something — a model, a backend, a rules engine, a person — writes a UI document: a small JSON file of semantic components ("a choice", "a confirmation", "a table") bound to data your app provides. A renderer turns it into your design system's components. A verifier checks it for accessibility, safety and whether an agent can operate it. Then it's used, and thrown away.

request ──► generator (any model or program that emits spec-valid JSON)
                      │  UI document: meaning only — no pixels, colours or fonts
                      ▼
              renderer (@polyxd/react, themed by a design-system pack)
                      │
                      ▼
              verifier → score, findings, agent task results

Site and docs: polyxd.com · Live gallery: polyxd.com/gallery

Packages on npm

All 37 packages are on npm under the @polyxd organisation: the twelve below, the polyxd CLI among them, then thirteen design-system packs and twelve templates.

Package	What it is	Version
@polyxd/spec	The spec: components, patterns, the action registry and the JSON Schema
@polyxd/react	The React renderer
@polyxd/web	The Web Components renderer (Vue and Svelte adapters in its README)
@polyxd/core	What both renderers share
@polyxd/verifier	The verifier: schema, patterns, accessibility, contrast and agent tasks

What works today

All 24 examples score 100 across 1,248 renders (13 packs × 2 widths × light and dark), 936 of 936 agent tasks complete by name alone, and the verifier catches 20 of 20 deliberately injected defects.

There is no bundled model. Any generator that emits spec-valid JSON drives Polyxd. See Bring your generator.

The design systems

	Design system	Pack	Version
	Material 3	@polyxd/ds-material3
	IBM Carbon	@polyxd/ds-carbon
	Ant Design	@polyxd/ds-antd
	Microsoft Fluent 2	@polyxd/ds-fluent

Each logo is its owner's own file, unaltered, used to identify the design system a pack is modelled on (where a system has no mark of its own, its company's logo). Several owners' guidelines restrict logo use without permission; each pack's README records the source and the guidelines. GOV.UK's crown and logotype are protected, so it is named in words alone. Twelve original templates (sketch, wireframe, editorial, brutalist, glass, terminal, pastel, civic, finance, health, neon, mono) sit beside them, each with a mark drawn from its own tokens.

The templates

Twelve original packs, made to be copied and changed.

Template	Pack	Version
Brutalist	@polyxd/ds-brutalist
Civic	@polyxd/ds-civic
Editorial	@polyxd/ds-editorial
Finance	@polyxd/ds-finance
Glass	@polyxd/ds-glass

Try it

npm install @polyxd/react @polyxd/spec

Render a document:

import { PolyxdSurface } from "@polyxd/react";
import "@polyxd/react/styles.css";
import "@polyxd/react/themes/carbon.css";

<PolyxdSurface
  document={doc}                     // a UI document
  data={{ quote }}                   // your data; the document binds to it
  theme="carbon"
  mode="light"
  onAction={({ name, context }) => {  // capabilities the document may trigger
    if (name === "transfer.confirm") sendMoney(context.quoteId);
  }}
/>

Validate and verify it:

npx polyxd-validate my-ui.json                 # schema and structural rules, from @polyxd/spec
npm install -D @polyxd/verifier playwright && npx playwright install chromium
npx polyxd-verify my-ui.json --themes carbon   # rendered light and dark, phone and desktop; axe, contrast, layout

Point it at your design system:

npx polyxd pack ./src/tokens.css

It reads your CSS custom properties, maps what it can onto the contract, writes a pack plus a mapping file of every guess it made, and reports what's still missing — including any of your own colour pairs that fail contrast. How it guesses.

From source

Tested on Node 26; the repository's scripts run TypeScript directly, so you need a Node that strips types without a flag.

git clone https://github.com/visualfart/polyxd.git && cd polyxd
npm install
npm run dev -w @polyxd/gallery          # every example, in every pack, at phone, tablet and desktop
npm run test:all                        # every workspace's tests, with one total
npm run verify:packs -w @polyxd/verifier   # the 1,248 renders
npm run conformance -w @polyxd/verifier    # both renderers, every document, 13 packs: same DOM, ARIA, text and findings

Polyxd is for surfaces, generated or authored. A designer can write the same document on purpose, as a screen of the product; it renders in the same design system and is verified by the same rules. Since spec 0.3 the product's shell (the frame, app bar, navigation and footer around every screen) can be a document too: authored once per product, never generated, with the validator refusing shell components anywhere else. See the demos: three products in three design systems, with generated and authored screens side by side.

Who it's for

• Products with an assistant that can answer in text but can't show the confirmation dialog, because building a screen per intent is unbounded work. Especially where generated UI has to be safe and accessible, not just plausible.
• Server-driven UI, with no AI at all. The document format is the product; anything that emits JSON can drive it.
• Internal tools — the long tail of admin screens nobody will fund as code.
• Design teams who want to author screens once, in meaning, and have them render in every design system they ship and be checked before release. Studio has a Screens editor for exactly that.
• Anyone whose product someone else's agent will operate. Every surface is operable through its accessibility tree by construction.

Not for: a handful of intents in one design system (hand-build them), or the flagship flow that is your product.

Bring your generator

Polyxd ships no model. Any model or program that emits spec-valid JSON drives it: Claude, GPT, Gemini, a model you run yourself, a template, or plain code. Give the generator the spec and the data, take the UI document it writes, and pass it to the renderer. The verifier checks what it wrote, in every pack, mode and width, before anyone sees it. Taste comes from Design Direction, which a designer sets once and the verifier holds every surface to.

@polyxd/runtime does the generating part for you: it builds the prompt from the spec and your Direction, calls Claude, GPT, Gemini or a local model behind an OpenAI-compatible endpoint, checks the answer and sends problems back for repair, streams, and remembers the screen shown for each intent. See Runtime.

@polyxd/server puts the runtime behind an HTTP API with streaming, for when the model key has to stay on a server or the code that wants a screen isn't JavaScript. Run it with npx @polyxd/server or the Docker image ghcr.io/visualfart/polyxd-server. See Generation server.

Repository

PLAN.md is the project plan; docs/decisions/ records why things are the way they are.

Contributing

Issues and pull requests are welcome. The most useful single contribution is a pack for a design system that isn't here — polyxd pack does most of the work, and Design systems explains the rule every pack follows: where a role fails contrast, move along that system's own ramp, and write down why.

Before a pull request: npm run test:all and npm run check:licences.

Licence

Code is Apache-2.0, except Studio (apps/studio), which is FSL-1.1-ALv2: free to run for your own team or company, not as a competing hosted service, and Apache-2.0 two years after each release; the spec and documentation are CC-BY-4.0. NOTICE lists every vendored source and its licence.

The design-system packs are Polyxd's work, reading each system's published tokens. Polyxd is not affiliated with, endorsed by or sponsored by any of those projects or their owners, and each name is the trademark of its owner.