UI8Kit Codegen 2.0 (xgen)

One spec, eight runtimes, the same DOM and ARIA.

Spec-driven generation for UI8Kit: bricks (primitives), components and blocks are written once as JSON specs and a TypeScript builder, and xgen generates idiomatic source for Svelte 5, React 19, Vue 3 and SolidJS and server templates for Go templ, Twig, Latte and Jinja2. Every brick and block case of the template runtimes is rendered with the real engine and compared with React; identity across runtimes is a gate, not a convention.

This is the engine behind the public ui8kit 2.0 registry (ui.buildy.tw, npx ui8kit add <name>, CLI ui8kit 2.0.x, registry roots https://registry.buildy.tw/<runtime>).

Fact	Value
Bricks / parts	40 / 72 (xgen/specs/ui)
Components and blocks	23 parts, 36 patterns, 184 organisms; 92 blocks with 474 variants (xgen/specs/{parts,patterns,organisms,blocks})
Screens	15 screen specs (themes, gallery, catalog, site, plans, skins), served by 4 host apps
Runtimes	svelte, react, vue, solid, templ, twig, latte, jinja2
Data contract	Codex v0.4 via @ui8kit/contract (77 fixture collections, 733 entries)
Skins	default + 15 (CSS variables only, shadcn tokens)
Version	2.0.0 (not published to npm) - upgrading from 0.1: MIGRATION.md
License	MIT, (c) UI8Kit

---

Runtimes

Runtime	Package (generated)	Files	Checked by
Svelte 5	packages/svelte/ui (@ui8kit/svelte-ui)	src/primitives/<brick>/<part>.svelte, src/components, src/blocks	host app + e2e DOM pair
React 19	packages/react/ui (@ui8kit/react-ui)	.tsx per brick / organism	reference DOM of every parity gate
Vue 3	packages/vue/ui (@ui8kit/vue-ui)	.vue SFCs	host app + e2e DOM pair
SolidJS 1.9	packages/solid/ui (@ui8kit/solid-ui)	.tsx	server render vs React (xgen check, group solid)
Go templ	packages/templ/ui (module github.com/ui8kit/codegen/packages/templ/ui)	.templ + _gen.go + Go helpers	templ generate, go vet, go build, DOM vs React
Twig	packages/twig/ui	.html.twig + PHP extension	real twig/twig (PHP + composer), DOM vs React
Latte	packages/latte/ui	.latte + PHP extension	real latte/latte, DOM vs React
Jinja2	packages/jinja2/ui	.html.j2 + Python helpers (py/ui8kit_jinja)	real Jinja2 (Python venv), DOM vs React

The TypeScript packages are source only (no build step; the consumer's Vite compiles them). Peer dependencies: the framework, tailwindcss v4, clsx, tailwind-merge.

Quick start

Prerequisites: Bun 1.4+. Go, PHP 8.1+ with Composer and Python 3 are optional: each template runtime group skips without its toolchain (UI8KIT_REQUIRE_ALL_RUNTIMES=1 turns a skip into a failure, as in CI).

bun install
bun run build     # xgen build: specs + fixtures + content -> packages/*/ui (8 runtimes), packages/shared/app, apps/host-*
bun run check     # xgen check: every gate, drift included, and the real-engine parity of templ, solid, twig, jinja2, latte
bun run test      # bun test of xgen/*
bun run verify    # check + codex:validate + typecheck + test (what CI runs)

More: bun run typecheck (svelte-check, tsc, vue-tsc on the packages and hosts), bun run build:hosts, bun run e2e (every screen in every host, screenshots, DOM pair test; needs Playwright browsers), bun run lint:px (ui8px gate on the class sets), bun run rules / rules:baseline, bun run codex:manifest / codex:validate / codex:blocks. Full list: docs/cli.md.

Layout

xgen/        the generation layer: self-contained @ui8kit/xgen-* packages (schema, spec, screens, generator, check, cli, runtimes/*)
  specs/       ui (bricks), parts, patterns, organisms, blocks, recipes, presets, screens, assets (Lucide)
  fixtures/    Codex v0.4 collections (sample data), taxonomies
  content/     the text dictionary (content/ui/en.json): views never hold literal text
  schema/      JSON Schemas + codex/ (manifest.json, blocks.json: the data contract of every block)
packages/    generated packages: {svelte,react,vue,solid}/ui, {templ,twig,jinja2,latte}/ui, shared/app; tooling (gates)
apps/        generated host apps host-{svelte,react,vue,solid}; the only hand-written file in each is xgen.app.json
rules/       composition rules (zones, baselines, self-test fixtures, html-validate config)
docs/        guides

Nobody edits packages/*/ui, packages/shared/app or apps/host-* by hand. Every file starts with Code generated by xgen. DO NOT EDIT. and names its source. xgen check (group drift) regenerates everything in memory and fails on any difference.

Design rules enforced by xgen check

• 8 + 4 grid. Spacing uses whole Tailwind steps on the 8 px grid; 4 px steps only inside controls; no half steps (gap-1.5, px-2.5) anywhere in specs, builder or kit assets (group spacing). Controls share one scale: sm / default / lg = h-8 / h-10 / h-12.
• Tokens only. Colours are shadcn CSS variables (bg-primary, text-muted-foreground); no palette colours, hex, arbitrary values or gradients (hardcode). One corner token: plain rounded reads --radius (corners); shadows only on floating layers (shadows).
• Lucide icons (LucideIcon, registry xgen/specs/assets/lucide-icons.json, ISC).
• Identical DOM and ARIA in every runtime (a11y, parity groups, e2e DOM pair); no literal text in views (text, dictionary); portability contract (nonportable, xgen/specs/_nonportable.json).

Data: Codex and @ui8kit/contract

Sample data are Codex v0.4 collections (xgen/fixtures/*.json), validated with validateCollectionV04 from @ui8kit/contract. xgen/schema/codex/manifest.json describes every kind and field, blocks.json lists for every block and screen which collection, record type and fields it reads. See docs/contract.md.

Documentation

• docs/README.md - index
• docs/specs-guide.md - authoring specs end to end (start here)
• docs/architecture.md - packages, flow, checks
• docs/runtimes.md - the eight targets and how to consume them
• docs/contract.md - Codex fixtures, manifest, block data
• docs/registry.md - the public registry (ui8kit/site, ui8kit/cli) and how it maps to this repo
• MIGRATION.md - 0.1 -> 2.0
• xgen/README.md and the README of every xgen package

License

MIT, see LICENSE. Lucide icon data: ISC (https://lucide.dev). Skins: see xgen/runtimes/core/assets/styles/skins/NOTICE.md.