Universal

An open-source AI Art Director for developers building React interfaces with coding agents.

Universal establishes composition and visual direction before implementation. It gives coding agents a structured design plan, reusable design rules, and a critique loop so generated interfaces feel deliberately art-directed instead of generically assembled.

What it provides Structured design plans Composition guidance Reusable design rules Anti-generic design critique Local MCP integration What it uses React and Vite TypeScript pnpm workspaces Turborepo Model Context Protocol

Project Status

Universal is in active early development. The monorepo, Studio and Preview applications, design contracts, and MCP prototype are in place. Some generation flows remain architectural placeholders while the design engine is built out.

See the roadmap for planned milestones and product principles for the project's direction.

Quick Start

Downstream product agents should use the canonical orchestration API instead of importing MCP transport internals.

Prerequisites

• Node.js 22 or newer
• pnpm 11 or newer
• Git

Install and run

git clone https://github.com/7shep/universal.git
cd universal
pnpm install
pnpm dev

pnpm dev starts the Studio and Preview applications together.

For a full production check:

pnpm lint
pnpm typecheck
pnpm build
pnpm format:check
pnpm test

pnpm test runs every maintained automated suite, including the MCP, design-linter, and design-taste policy tests.

MCP Prototype

Universal includes a local MCP server that exposes three tools to compatible coding agents:

• create_design_plan establishes the visual and compositional direction.
• get_design_rules returns category-specific design constraints.
• review_implementation critiques React and CSS output against the intended direction.

Build the server with:

pnpm --filter @universal/design-mcp build

See Connect Universal MCP to Codex for configuration, verification, troubleshooting, and a complete demo workflow.

Workspace

universal/
|-- apps/
|   |-- studio/                Design-direction workspace
|   `-- preview/               Isolated generated-project preview
|-- examples/
|   `-- demo-site/             Example MCP-driven React site
|-- packages/
|   |-- composition-library/   Page-composition schemas
|   |-- design-engine/         Design contracts and orchestration
|   |-- design-linter/         Anti-generic critique interfaces
|   |-- design-mcp/            Local MCP server
|   |-- prompts/               Versioned prompt assembly
|   |-- shared/                Shared domain types and utilities
|   `-- ui/                    Shared React UI primitives
|-- docs/                      Setup and integration guides
|-- PRODUCT.md                 Product principles and boundaries
`-- ROADMAP.md                 Milestones and future direction

Scripts

• pnpm dev starts all development tasks in parallel.
• pnpm build builds every workspace package through Turborepo.
• pnpm lint runs ESLint across the repository.
• pnpm typecheck type-checks all workspaces.
• pnpm test runs every maintained workspace test suite.
• pnpm format formats supported files with Prettier.
• pnpm format:check checks formatting without changing files.

Use pnpm filters to target one workspace, for example:

pnpm --filter @universal/studio dev
pnpm --filter @universal/design-mcp build

Contributing

Contributions are welcome. Bug reports, focused fixes, documentation improvements, design-rule proposals, and well-scoped feature discussions all help.

Read CONTRIBUTING.md before opening an issue or pull request. It covers local setup, project conventions, validation, commit guidance, and the review process.

License

Universal is available under the MIT License.