UJL Framework

No more off-brand websites.

An AI-native framework that generates accessible, on-brand UI from structured content and design rules.

Documentation · Getting Started · Live Demo

---

What is UJL?

UJL (Unified JSON Layout) is an open-source framework for building web content with brand compliance and WCAG accessibility built in, not bolted on. Unlike traditional page builders where design rules can be broken, UJL enforces them architecturally through strict separation of content and design.

The problem: Editors want to create content quickly. Designers need brand guidelines to hold. Developers get caught in the middle. Reviews, approvals, and fixes eat time.

The solution: UJL moves enforcement into the architecture. Content and design rules are described in a way that the system can only produce valid, compliant results. Not by convention. Not by process. By construction.

Key Features

• Brand Compliance by Design – Design changes apply globally and instantly. Editors compose freely within guardrails they cannot override.
• Accessibility Guaranteed – WCAG contrast ratios and semantic HTML are enforced architecturally, not verified after the fact.
• AI-Native – Structured JSON optimized for language models. Schema validation ensures AI-generated content is always compliant.
• Open Source & Integrable – MIT licensed and framework-agnostic. Embed the full editor anywhere, or use the lean Svelte adapter inside your own stack.

Quick Start

Install

npm install @ujl-framework/crafter

Minimal Example

import { UJLCrafter } from "@ujl-framework/crafter";

new UJLCrafter({ target: "#app" });

With Document and Theme

The Crafter is stateless. Pass it a document and theme, it calls you back on changes. How and where you persist data is entirely up to you.

import { UJLCrafter } from "@ujl-framework/crafter";

const crafter = new UJLCrafter({
	target: "#app",
	content: ujlcDocument, // your .ujlc.json document
	tokenSet: ujltTokenSet, // your .ujlt.json theme
	onChange: (updatedDoc) => {
		// persist however you like
		saveDocument(updatedDoc);
	},
});

Try the Demo

Clone this repository and run the included demo:

git clone https://github.com/mainzcript/ujl.git
cd ujl
pnpm install
pnpm --filter @ujl-framework/demo dev

Open http://localhost:5174 to see the Crafter in action.

Project Structure

ujl/
├── packages/
│   ├── core/           # Schemas, Validator, Renderer, Composer
│   ├── types/          # TypeScript types and Zod schemas
│   ├── ui/             # Shadcn-svelte UI Components
│   ├── crafter/        # Visual UJL Editor (~600 KB gzip)
│   ├── adapter-svelte/ # Svelte 5 Adapter (~120 KB gzip)
│   ├── adapter-web/    # Web Components Adapter (~280 KB gzip)
│   └── examples/       # Example Content & Test Data
└── apps/
    ├── demo/           # Minimal Crafter integration demo (Vite)
    └── docs/           # Documentation Website (VitePress)

Packages

Package	Purpose	Size (gzip)	npm
@ujl-framework/crafter	Full visual editor, embed anywhere	~600 KB
@ujl-framework/adapter-web	Web Components rendering, no editor	~280 KB
@ujl-framework/adapter-svelte	Svelte 5 native rendering for SvelteKit	~120 KB
@ujl-framework/core	Composition utilities	~50 KB
@ujl-framework/types	TypeScript definitions	~10 KB

Documentation

• Full Documentation – Architecture, guides, and API reference
• Getting Started – Installation and first steps
• Live Demo – Try the Crafter in your browser
• Packages Overview – What each package does
• Roadmap – Where UJL is going

Core Concepts

Strict Content/Design Separation

Content lives in .ujlc.json files (UJL Content Document). Design rules live in .ujlt.json files (UJL Theme Document). The Composer combines them into an Abstract Syntax Tree (AST), which Adapters render into your target framework.

.ujlc.json (content) + .ujlt.json (theme) → Composer → AST → Adapter → Output

Because design rules aren't embedded in content, a theme update propagates everywhere instantly. Because editors only touch .ujlc, they literally cannot change colors or typography—the data model doesn't allow it.

AI-Native Architecture

Structured JSON is optimized for language models. Schema validation ensures AI-generated content is always compliant. Small models, big results.

Not a CMS

UJL is a visual layout layer, not a content management system. It doesn't handle routing, user accounts, publishing workflows, or content storage. It integrates with existing CMS and frontend stacks—it doesn't replace them.

Contributing

We welcome contributions! Please read our Contributing Guide for details on:

• Development setup
• Testing and code review
• Release process
• Pull request guidelines

For AI assistants working on this project, see AGENTS.md for a high-level overview.

Community

• Issues – Report bugs or request features
• Website – Full documentation and guides

Built by

UJL is developed and maintained by mainzcript GbR, a young software studio based in Mainz, Germany.

License

MIT – see LICENSE for details.

---

Documentation · Getting Started · GitHub