Design in your repo.

A visual design workspace for your project.
Editable on a canvas. Readable by people and agents. Versioned with your code.

Workflow illustration: one design, shared by the canvas, your files, and your tools.

What is UIDX?

UIDX brings a design canvas into your application's repository. Install
@uidxkit/uidx as a local development dependency, run npm run uidx, and
work on designs stored in your project's .uidx/ folder.

A .uidx file combines Markdown describing a design's purpose with a declarative
node tree describing its appearance. Edit the canvas and the file updates. Edit
the file and the canvas follows. Changes produce focused text diffs you can
review in a pull request.

• A visual workspace. Create pages, draw shapes, edit text, and adjust layout
  and styling from the canvas and inspector.
• Reusable design systems. Components, instances, variants, slots, and design
  tokens share a document namespace.
• Your project owns the files. Keep designs, assets, and fonts next to your
  application and version them with Git.
• A shared workflow for people and agents. The CLI and MCP bridge let external
  tools inspect and edit the same files the viewer uses.
• Local by default. The viewer and project server run on your machine. Canvas
  synchronization does not require an LLM or a hosted design service.

UIDX is an early release. The file format and APIs may change
before 1.0. It is a design workspace; it does not render your application's
existing UI components as Storybook stories.

Install

Requires Node.js 22.19 or newer. Node 24 is recommended.

Run these commands inside your application's repository:

npm install --save-dev @uidxkit/uidx
npm run uidx

Installation adds the uidx and uidx:mcp scripts and creates .uidx/ when it
doesn't exist. Existing scripts, configuration, and designs are preserved.
The CLI, server, viewer, WASM, and bundled fonts live in your project's
node_modules; a global UIDX installation is not required.

If npm install scripts are disabled, initialize once with
npx --no-install uidx init. If your project already uses a script named uidx,
choose another with npx --no-install uidx init --script design, then run
npm run design.

Your design workspace

your-project/
├── package.json          # @uidxkit/uidx devDependency and npm scripts
├── .mcp.json             # connection for MCP clients
├── src/
└── .uidx/
    ├── config.json       # project settings
    ├── uidx.json         # document name, page patterns, and asset patterns
    ├── welcome.uidx      # initial page for a new workspace
    ├── assets/
    └── fonts/

Open the viewer, click New page, give it a name, and start designing. New
pages are saved in your design folder and appear in the overview. Commit your
project's .uidx/ files alongside application code.

Configuration

Set the shared viewer and MCP port in .uidx/config.json:

{
  "port": 4400
}

Restart npm run uidx after changing it. Use npm run uidx -- --port 4500 for a
one-time override. If the requested port is busy, UIDX tries the next available
one and reports its actual address. Configuration currently uses JSON.

The separate .uidx/uidx.json manifest controls which files belong to the document:

{
  "id": "my-project",
  "files": ["**/*.uidx"],
  "assets": ["assets/**"]
}

CLI and MCP

npm run uidx starts the local viewer, file synchronization server, and MCP HTTP
endpoint on one port. MCP clients use the generated .mcp.json to launch
npm run --silent uidx:mcp, a stdio bridge to that running project server.

npx --no-install uidx status
npx --no-install uidx check
npx --no-install uidx fmt --check

The CLI also supports reading, creating, editing, and rendering pages. See the
CLI guide and agent architecture.

Documentation

• Drawing icons and custom graphics
• Fonts
• Property vocabulary
• Architecture decisions
• Release guide
• Changelog

Contributing and license

Bug reports, documentation improvements, and pull requests are welcome.
See Contributing for development setup and checks.
Follow the Code of Conduct and report vulnerabilities through
the security policy. Changes to main are merged by the owner.

UIDX is MIT licensed. Third-party code and fonts retain their
respective licenses.