Universal

An open-source AI art director for React interfaces built with coding agents.

Website · Install · MCP Reference · Contribute · Roadmap

Coding agents are good at producing functional React code, but they often fall back to the same visual defaults: generic heroes, repeated card grids, arbitrary gradients, and weak hierarchy. Universal adds a design-direction step before implementation and a critique step after it.

Universal gives a compatible coding agent:

• structured discovery, a creative brief, and explicit approval;
• distinct art directions with a selected visual thesis;
• composition, typography, color, imagery, motion, and accessibility constraints;
• a versioned design plan that carries intent into implementation;
• implementation review that identifies generic or off-direction choices; and
• trusted local React generation, production builds, and previews, from a source checkout.

Install

Universal is published on npm as @7shep/universal-mcp. It requires Node.js 22 or newer and runs locally over stdio. Universal does not read model API keys; your MCP client's existing model authors the source.

System requirements

Fourteen of the sixteen tools — discovery through Design Plan v2, the Phase 1 compatibility API, and review_implementation — work from npx with nothing else installed. That tier alone is a complete, useful path: structured design direction plus a critique loop against your own code.

prepare_react_generation and build_react_project additionally require a checkout of this repository with pnpm install --frozen-lockfile already run once, with network access, to warm the pnpm store the runtime installs from offline. That offline install is a deliberate security boundary for executing model-authored code, not a bug; see Run the local Studio, ADR 0004, and the runtime contributor workflow.

Run the server without a global install:

npx -y @7shep/universal-mcp@alpha

Install all twenty workflow skills in your project for the full Universal experience:

npx -y @7shep/universal-mcp@alpha install-skills

Claude Code

claude mcp add universal -- npx -y @7shep/universal-mcp@alpha

MCP client configuration

For Claude Desktop and other clients that accept JSON MCP configuration:

{
  "mcpServers": {
    "universal": {
      "command": "npx",
      "args": ["-y", "@7shep/universal-mcp@alpha"]
    }
  }
}

Codex uses TOML. See Connect Universal MCP to Codex for the complete configuration and verification steps. Visit the installation page for the visual setup guide.

How it works

project context
      |
      v
discovery questions -> approved creative brief
      |
      v
art directions -> selected direction -> Design Plan v2
      |
      v
source and visual review -> prioritized findings

That much runs from npx alone: review_implementation critiques any source you hand it, whether or not you continue to generation. Continuing into generation needs the source-checkout setup in System requirements:

MCP host model authors React source
      |
      v
trusted materialization -> locked build -> local Vite preview
      |
      v
review_implementation again, against the generated source

The creative brief, approval, selected direction, and Design Plan v2 are digest-bound. Revising an upstream decision invalidates stale downstream artifacts instead of silently carrying them forward. Stable request IDs make mutations safely retryable.

MCP tools

The published server exposes 16 tools. Fourteen work from npx alone; two require the source-checkout setup in System requirements. See the MCP tool reference for the tool-by-tool list.

Art-direction workflow (npx)

start_art_direction
  -> get_discovery_questions
  -> submit_discovery_answers
  -> get_creative_brief
  -> approve_creative_brief
  -> develop_art_direction
  -> get_selected_direction
  -> create_design_plan_v2

• revise_creative_brief changes a reviewed brief and invalidates stale downstream artifacts.
• get_art_direction_session validates and inspects a serialized session.
• Every workflow response returns the serialized session required by the next operation.

Design intelligence and compatibility (npx)

• create_design_plan provides the lower-level design-plan compatibility API.
• get_design_rules returns category-specific design constraints.
• get_taste_profile returns the active taste and anti-pattern policy.
• review_implementation critiques React and CSS against the intended direction; it needs only the source you give it, not a build.

Generation (source checkout required)

prepare_react_generation
  -> host model authors allowed React source and assets
  -> build_react_project
  -> immutable workspace and locked production build

The runtime owns dependencies, scripts, configuration, materialization, build supervision, and the loopback preview. Submitted source is validated before it reaches the trusted workspace. Both tools need the pnpm store warmed by a source-checkout pnpm install, because the runtime then installs offline as a security boundary for executing model-authored code.

See the MCP tool reference for request shapes, response envelopes, phase preconditions, idempotency behavior, and error codes.

Agent skill commands

Universal includes twenty repository-local workflow skills under .agents/skills. They coordinate MCP tools with source inspection, verification, and design-quality gates.

Install them into the current project with npx -y @7shep/universal-mcp@alpha install-skills. The installer is safe to re-run after upgrading the package. It compares the content of each installed skill against the bundled version and reports what it did, per target directory:

• Installed — the skill was not present yet.
• Updated — your copy matched what a previous run wrote and the bundled version has changed, so it was refreshed. Incomplete directories left by an interrupted run are repaired here too.
• Already up to date — your copy matches the bundled version; nothing was written.
• Preserved — you edited the skill locally, so it was left untouched.

By default the installer narrows to whichever agent directories already exist in your project: just .agents/skills if only .agents exists, just .claude/skills if only .claude exists, or both if both exist. Detection only ever narrows from that kind of real signal — if neither directory exists yet, there is nothing to narrow on, so it installs to both rather than guessing which single agent you use. Override this with --target=<agents|claude|both>. Add --dry-run to preview exactly what each target would do without writing anything (no skill files, no manifest), and --cwd=<path> to install into a directory other than the current one, e.g.:

npx -y @7shep/universal-mcp@alpha install-skills --target=claude --dry-run

Locally edited skills are never overwritten by a normal run. Passing --force deletes and replaces every skill directory within the selected target(s), discarding any local edits, so reach for it only when you want to reset to the bundled versions.

Each target directory carries a .universal-skills.json manifest recording what the installer wrote. Deleting it makes the installer treat every existing skill as locally authored.

The five original commands cover the broad workflow. The fifteen focused commands below them each own one dimension of interface quality.

Command	Purpose	Changes files?
/art-direct	Runs discovery, brief approval, direction selection, Design Plan v2, implementation, and review for a new or substantially redesigned interface.	Yes, after approval
/audit	Produces a prioritized, evidence-led audit of an existing route or component.	No
/polish	Applies bounded improvements to hierarchy, typography, spacing, responsiveness, and accessibility without redesigning behavior.	Yes
/cleanup	Removes verified redundant, inconsistent, obsolete, or generic UI patterns while preserving behavior and APIs.	Yes
/review-ui	Coordinates multiple design-review perspectives into one deduplicated, ranked report.	No
/accessibility	Audits accessibility with WCAG 2.2-cited findings; repairs semantics, keyboard, focus, labels, contrast, touch targets, and reduced motion only on request.	Only when requested
/animate	Adds purposeful motion — transitions, micro-interactions, scroll effects, loading feedback — with reduced-motion fallbacks.	Yes
/assets	Audits imagery, icons, and illustrations for quality, consistency, relevance, performance, and accessibility; replaces or generates only when authorized.	Only when authorized
/color	Improves palette cohesion, semantic color roles, contrast, interaction-state colors, and design-token usage without changing the established palette.	Yes
/compare	Compares the implementation against a screenshot, mockup, reference URL, DESIGN.md, or selected direction, and reports prioritized differences.	No
/consistency	Detects design-system drift across components and routes by inventorying actual values before judging; repairs only explicitly selected findings.	Only selected items
/copy	Improves interface language — headings, CTAs, nav labels, form and help text, empty states, errors, confirmations — without changing meaning or behavior.	Yes
/critique	Answers one focused design question with evidence from source, rendered UI, and the established design direction.	No
/document	Creates or updates a Google Stitch-compatible DESIGN.md from the actual implementation.	Yes, docs only
/final-pass	Orchestrates a release-readiness pass across the focused commands, applies bounded fixes, and reports a ready / ready-with-caveats / not-ready verdict.	Yes, within a fix budget
/layout	Improves composition, alignment, whitespace, section pacing, density, and visual hierarchy without redesigning or changing behavior.	Yes
/performance	Finds and repairs evidence-backed, user-visible frontend performance problems with before/after measurement.	Yes, when measured
/responsive	Reviews and repairs overflow, wrapping, navigation, touch targets, content order, density, and breakpoint composition across representative widths.	Yes
/states	Finds and completes missing interaction and application states (hover, focus-visible, active, selected, disabled, loading, empty, error, success, skeleton).	Yes
/typography	Refines font selection and loading, type scale, hierarchy, line length, weight, and vertical rhythm without changing layout or color.	Yes

Invoke a skill explicitly with a scoped request:

/art-direct Create an editorial landing page for a developer tool.
/audit frontend/src at desktop and mobile widths.
/polish Tighten the installation page typography and mobile spacing.
/cleanup Consolidate duplicated tokens in frontend/src/styles.css.
/review-ui Review the installation page against the selected direction.
/accessibility Audit the checkout form for label and contrast issues.
/animate Add a loading state to the newsletter submit button.
/assets Audit the hero imagery on frontend/src/pages/Home.
/color Fix low-contrast secondary text on the pricing page.
/compare the installation page against DESIGN.md.
/consistency Check button radii and spacing for drift across apps/studio/src/routes.
/copy Tighten the CTA labels on the pricing page.
/critique Is the hero CTA prominent enough on the landing page?
/document frontend, focusing on typography and color tokens.
/final-pass apps/studio/src/routes/Preview against the approved creative brief.
/layout Rebalance section pacing on the marketing homepage.
/performance Fix the oversized hero image on the marketing homepage.
/responsive Fix pricing table overflow on mobile at apps/studio/src/routes/Pricing.
/states Complete missing loading and error states on the settings form.
/typography Tighten the heading scale on the pricing page.

Read each skill's SKILL.md before changing its workflow or completion gates.

What is ready today

Universal is an early alpha. The public npm package provides discovery through Design Plan v2 and implementation review from npx alone; generation and builds need the source-checkout setup in System requirements.

Available	Still in progress
Public npm MCP package (@7shep/universal-mcp)	Stable 1.0 API guarantees
Discovery, brief approval, and direction selection	Production live-provider implementation
Design Plan v2 with digest-bound provenance	OS or container sandboxing
MCP-host-authored React generation (source checkout)	Hosted generation and public project previews
Trusted immutable workspaces and locked builds (source checkout)	One-command Studio desktop packaging
Isolated loopback previews and rendered QA (source checkout)	Broader subjective visual-quality automation
Windows, macOS, and Linux validation matrix	Official MCP Registry listing
Installable agent workflow skills and marketing site

Tool names, inputs, outputs, and serialized sessions may change before 1.0. The roadmap tracks planned milestones, and the architecture guide distinguishes implemented behavior from planned boundaries.

Run the local Studio

The repository also includes Studio, Preview, and an Axis 65 demo for contributors exploring the deterministic local workflow.

Requirements

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

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

Studio uses local deterministic fixtures, so exploring the art-direction sequence does not require model credentials. See the cross-platform setup guide for troubleshooting.

Repository map

Path	Responsibility
frontend	Public website and installation guide
.agents/skills	Repository-local design workflow skills
apps/studio	Design-direction workspace
apps/preview	Isolated preview surface
examples/demo-site	Example React/Vite interface
packages/design-engine	Design contracts and orchestration
packages/design-mcp	Published local MCP server
packages/composition-library	Page-composition schemas
packages/design-linter	Implementation critique contracts
packages/design-taste	Versioned taste policy
packages/design-benchmark	Deterministic quality benchmark
packages/generation	Provider-neutral generation boundary
packages/local-runtime	Trusted build and preview supervision
packages/prompts	Versioned prompt definitions and assembly
packages/runtime-contracts	Browser/runtime protocol contracts
packages/shared	Cross-package domain utilities
packages/ui	Shared React primitives

Read Architecture and ownership before changing cross-package contracts.

Contribute

You do not need to understand the entire monorepo to contribute.

If you enjoy...	A useful starting point
Documentation	Verify an install or setup guide and report unclear steps
Testing	Add a regression case around an MCP tool or validation boundary
React and accessibility	Improve keyboard, focus, contrast, or reduced-motion behavior
Design systems	Propose a focused composition rule or anti-pattern with fixtures and tests
Developer tooling	Improve diagnostics, packaging, or local setup
Evaluation	Add a benchmark brief or strengthen deterministic checks

Start with the contribution guide. If you are unsure where an idea fits, open a contribution question before writing a large patch.

Validation

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

Build and test only the published MCP package with:

pnpm --filter @7shep/universal-mcp build
pnpm --filter @7shep/universal-mcp test

Documentation

• Website
• Installation guide
• Product principles and non-goals
• Roadmap
• Cross-platform local setup
• Release readiness
• Design and provenance glossary
• Architecture and ownership
• Generation and local-runtime workflow
• Studio workflow
• Connect Universal MCP to Codex
• MCP tool reference
• Publishing and release operations
• Downstream orchestration API
• Security policy
• Code of Conduct

License

Universal is available under the MIT License.