Guides

Paper workflow

Design in Paper Desktop with the Yuno kit as the ground truth for tokens and components. One agent, two MCPs, zero drift from production.

Why Paper + kit

Paper Desktop is a browser-based design canvas that ships an MCP server. Wired next to the kit MCP, a single agent in Claude Code (or Cursor) can read the Paper canvas AND consult the kit at the same time. The kit MCP tells the agent what Yuno looks like; the Paper MCP is where the design lands. Same tokens, same components, no manual copy and paste.

Prerequisites

  • Node 22

    Node 25 breaks with a simdjson dylib issue. Install via nvm or Homebrew (`brew install node@22`).

  • Paper Desktop

    Download from paper.design. Opening any Paper file starts its MCP on http://127.0.0.1:29979/mcp automatically.

  • Claude Code

    Any recent version. Cursor works too, same setup shape.

  • A local clone of the kit

    `git clone https://github.com/yuno-payments/prototype-kit` and `cd prototype-kit && npm install`.

Setup in 10 minutes

  1. 1
    Install the kit MCP dependencies

    The kit ships its own MCP server under `mcp-server/`. Install its deps once.

    cd prototype-kit/mcp-server
npm install
  2. 2
    Register the Paper MCP with Claude Code (user scope)

    One-off. Paper Desktop must be running with a file open so the MCP is live on port 29979.

    claude mcp add paper --transport http http://127.0.0.1:29979/mcp --scope user
  3. 3
    Register the kit MCP at the project level

    Create `.mcp.json` at the root of your prototype folder. Project-scoped so each prototype resolves its own `KIT_ROOT`.

    {
  "mcpServers": {
    "yuno-kit": {
      "type": "stdio",
      "command": "node",
      "args": ["mcp-server/index.mjs"]
    }
  }
}
  4. 4
    Open Claude Code inside the prototype folder

    Run `claude` in the folder. Type `/mcp`. You should see both `paper` (http) and `yuno-kit` (stdio) as connected.

  5. 5
    Open (or fork) the Paper starter file

    The Yuno starter file ships all foundations pre-loaded: colors light and dark, typography scale, radius scale, spacing, shadows. Fork it once per prototype so tokens land in your canvas.

Your first prompt

With both MCPs connected and the starter file open, ask the agent in natural language. It will call `list_components` and `list_tokens` on the kit MCP before drawing artboards via the Paper MCP.

Try: "Create in Paper a Settings screen using the kit atoms. Use Sidebar + PageHeader + a Card with three switches. Match the Yuno tokens for colors and spacing."

Troubleshooting

  • /mcp does not show paper as connected

    Paper Desktop is not running or no file is open. Open any Paper file, then restart Claude Code.

  • /mcp does not show yuno-kit as connected

    Check that `.mcp.json` sits at the project root and that Node 22 is on the PATH. Run `node mcp-server/index.mjs` from the kit root. It should print `[yuno-kit-mcp] connected. KIT_ROOT=...` to stderr.

  • Agent invents components that are not in the kit

    Prompt it explicitly: 'Use list_components to survey the kit before creating anything. Refuse to invent components not returned by list_components.' The KIT-FIRST PROTOCOL in CLAUDE.md enforces this, but reinforcing in-prompt helps early sessions.

  • Tokens on the canvas do not match the kit

    You forked the starter file, right? If yes, run `list_tokens` on the kit MCP and compare against the tokens tab in Paper. Differences mean the starter is stale and needs a refresh from the kit.

Related