Uidx

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](packages/cli/README.md) and [agent architecture](packages/agent/README.md).

Documentation

• [Drawing icons and custom graphics](docs/graphics-tools.md)
• [Fonts](docs/fonts.md)
• [Property vocabulary](docs/property-vocabulary.md)
• [Architecture decisions](docs/decisions)
• [Release guide](docs/releasing.md)
• [Changelog](CHANGELOG.md)

Contributing and license

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

UIDX is [MIT licensed](LICENSE). Third-party code and fonts retain their [respective licenses](THIRDPARTYNOTICES.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: uidxkit
• Source: uidxkit/uidx
• License: MIT

Install and usage instructions live in the source repository linked above.