artisign

# Artisign

An artificial artisan for UI design: agents build screens, a design system keeps them consistent.

Local-first UX design tool for AI agents. Agents design through MCP, the human reviews in the browser, state lives in plain files.

One Node process on `127.0.0.1`. No database, no accounts, no hosting.

**Status:** Stable (`1.1.4`) — CLI, store, parser/model, the 24-tool MCP surface, browser preview with live reload/flows/comments, screen variants with side-by-side compare, the design system (tokens, variants, drift warnings, `promote_to_system`), and packaging are all implemented. Artisign designs its own browser preview — see [Designed with itself](#designed-with-itself).

## Why

1. **Consistency across screens** — the design system is first-class; screens store refs, never inline values
2. **Token efficiency** — tiered reads, field selection, diff mode on writes
3. **Flows as first-class** — click routes are data, not documentation
4. **Render determinism** — the preview renders the source, so preview equals output by construction

## Install

Node.js ≥ 20.19, on **macOS or Linux**. **Windows is not supported** — the store's atomic writes (write temp file, then `rename`) and its path handling have never been verified there, so the tool is not shipped for it. `package.json` declares this via `os`, which makes `npm install` refuse the platform rather than fail somewhere later.

**Two ways to run it.** `npx artisign` fetches the package on first use, starts the daemon and opens the preview in your browser — no setup, the fastest way to try it. Installing it into a directory of your own is the other path, and the one the commands below are written for. Screenshots are not the difference between them: the two screenshot tools need Playwright, which a local install can sit next to and which the npx path reaches through `ARTISIGN_PLAYWRIGHT_DIR` — both routes are under **Optional: screenshots** below.

```bash
mkdir artisign && cd artisign
npm install artisign
```

The commands below are written as `npx artisign`. With a local install, run `./node_modules/.bin/artisign` instead — or `npm install -g artisign` and just `artisign`.

**Canonical quickstart.** The local install, from an empty directory to a connected agent. Start the daemon before registering the MCP server — the HTTP registration below runs against an already-running daemon:

```bash
mkdir artisign && cd artisign
npm install artisign
./node_modules/.bin/artisign start ./my-project
claude mcp add --transport http artisign "http://127.0.0.1:4711/mcp?project=/absolute/path/to/my-project"
```

The first two lines repeat the install above on purpose: the point of this block is that nothing has to be assembled from elsewhere. On the npx path, drop them and start with `npx artisign start ./my-project` instead — the screenshot tools then need `ARTISIGN_PLAYWRIGHT_DIR`, as described below.

**Optional: screenshots.** `get_screenshot` and `inspect_node` need a real browser, which is intentionally not bundled (`npx artisign` stays light without it). Playwright is an **optional peer dependency** — npm neither installs it nor its ~150 MB of browser binaries unless you ask for them by name. Two ways to do that:

1. **Next to Artisign.** In the directory you installed `artisign` into:

   ```bash
   npm install --no-save playwright && npx playwright install chromium
   ```

   `--no-save` matters: it installs the package without writing it into `package.json` or the lockfile, which is the whole point of Playwright being optional. Without the flag npm edits both files; with some npm versions a plain `npm install playwright` even reports `up to date` and installs nothing, because an optional peer counts as satisfied when absent.

2. **Anywhere, named by `ARTISIGN_PLAYWRIGHT_DIR`.** Install Playwright once into a directory of its own and point Artisign at it:

   ```bash
   mkdir -p ~/.artisign-playwright && cd ~/.artisign-playwright
   npm init -y >/dev/null && npm install playwright && npx playwright install chromium
   export ARTISIGN_PLAYWRIGHT_DIR=~/.artisign-playwright   # in the shell that starts the daemon
   ```

   This is the route that also works when `artisign` runs from npx's cache, and the one to use when the first route leaves the repo dirty. The variable has to be set for the process that runs the daemon — for a stdio MCP server, that is the `env` block of the host's config.

`artisign` imports Playwright dynamically, so without the variable Node resolves it from the tree `artisign` itself lives in: installing Playwright into your design project has no effect. If Playwright isn't installed, or is installed but broken (a partial copy, a symlink whose target is gone), both tools fail with the fix in the error message rather than crashing the server; every other tool works without it. A Playwright installed *after* the daemon started is picked up on the next call; a *repaired* one needs a daemon restart, and the error says so.

**Register the MCP server.**

Claude Desktop — stdio, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "artisign": {
      "command": "npx",
      "args": ["artisign", "mcp", "/absolute/path/to/my-project"]
    }
  }
}
```

Claude Code — stdio:

```bash
claude mcp add artisign -- npx artisign mcp /absolute/path/to/my-project
```

Recommended — against the running daemon (`npx artisign start`), streamable HTTP instead of spawning a second process. Bake the project into the URL, one stable entry per coding project:

```bash
claude mcp add --transport http artisign "http://127.0.0.1:4711/mcp?project=/absolute/path/to/my-project"
```

The `?project=` parameter scopes every tool call to that project (auto-opening it on first use), so several coding projects can share one daemon without ever restarting it. Without the parameter, calls go to the project currently active in the browser UI. `init_project` works even while no project is open.

**Privacy.** Artisign collects nothing — no telemetry, no account, no server beyond the local one it runs, no update check. Two things reach the network, neither of them about you: `import_html` fetches whatever URL you hand it, and the first render of a project fetches the font families named in your tokens — plus the Material Symbols Rounded icon font, always — from Google Fonts, then caches them locally (see [Fonts & icons](#fonts--icons)).

## Quickstart

First run, in this order:

```bash
npx artisign init ./my-project    # scaffold an empty project
npx artisign start ./my-project   # start the daemon in the background and open the preview in the browser
npx artisign status               # pid, port, open projects
```

`npx artisign` on its own is `npx artisign start`, and takes the same arguments (`npx artisign --port 4800 ./my-project`). `start` opens `http://127.0.0.1:<port>/` in your default browser once the daemon is healthy — also when it was already running. Pass `--no-open` (or set `ARTISIGN_NO_OPEN=1`) to skip that; it is skipped anyway when `CI` is set or stdout is not a terminal, and when no browser can be opened the URL is printed and that is all. `serve`, `mcp`, `status`, `stop` and `init` never open a browser.

The remaining commands, for reference — this block is a catalogue, not a sequence:

```bash
npx artisign serve ./my-project   # foreground daemon (development); opens the project on start
npx artisign mcp ./my-project     # stdio MCP server for Claude Desktop / Claude Code
npx artisign stop                 # stop the daemon
```

`artisign --help` lists the flags each command accepts.

The daemon is **multi-project**: it runs permanently on `127.0.0.1:4711` and can hold several projects open at once. Open or create projects from the browser UI (project picker in the topbar), or let agents address any project directly via the MCP URL — no restart when you switch projects. The port comes from `~/.artisign/config.json` or `--port N` on `start` and `serve` (a `settings.port` in a project's `artisign.json` is deprecated and ignored).

Daemon-level state — that config plus the `daemon.lock` holding the running pid and port — lives in `~/.artisign`. Set `ARTISIGN_HOME` to move it somewhere else; that, together with `--port`, is what lets a second daemon run fully isolated from the first, which is worth doing before you try anything destructive against projects you care about.

## The 24 tools

| Bucket | Tool | Does |
|---|---|---|
| Reads | `get_guide` | The design methodology guide (`docs/agent-guide.md`), on demand. |
| Reads | `get_project` | Screen list, design-system pointer, counts. Tiered, cold-start read; `tree` also carries each screen's `viewport` (`{ width, height, declared }` — the frame it renders at, 390×844 when the root declares no px width) and each variant screen's `variant_of`/`variant_kind`. |
| Reads | `get_screen` | One screen with comment/flow indicators. Tiered + field selection; `full` adds its direct `variants` and `reached_from`. |
| Reads | `get_node` | Subtree of one node, addressed as `<screen>.<node-id>`. Tiered + field selection. |
| Reads | `get_design_system` | Tokens, components (with variants and the default variant's slot names), and patterns. `tree` carries every token value, grouped by bucket. |
| Reads | `find_nodes` | Where-query across screens (style ref, component ref, variant, comments, text, flow). |
| Reads | `list_comments` | Open/resolved comments, filtered by screen or node. |
| Reads | `get_mockup` | A mockup's variants — raw HTML, outside the ref model. |
| Writes | `write_html` | Create or fully replace a screen from augmented HTML. |
| Writes | `patch_html` | Surgical patch by node ref or CSS selector: replace, insert, delete, set attr. |
| Writes | `update_refs` | Change a node's token/component/variant bindings without a full HTML parse. |
| Writes | `set_tokens` | Design-system token mutation — one call re-resolves every bound screen. |
| Writes | `set_flow` | Mutate a flow edge in `flows.json` w