Connected Canvases: Designing with Paper and Pencil from the Terminal

Most design tools and most codebases describe the same product in two different languages. The canvas holds frames, layers, and styles; the repository holds components, props, and CSS. Neither artifact can read the other, so every move between them is a translation: export the frame, write the redline, re-implement the layout, screenshot the result, and explain in a comment why the spacing is different. The translation is slow the first time and painful every time after, because the two artifacts immediately start to drift.

Coding agents made the gap more visible, not smaller. An agent can build a competent component from a screenshot, but a screenshot is the least informative version of a design: it carries no token names, no layout intent, no component boundaries, and no record of which values were deliberate. The companion article on screenshot-to-implementation covers that failure mode in detail — the short version is that pixels in, plausible guesses out. What the agent actually needs is the design artifact itself, in a form it can parse and modify.

A small group of tools now builds for exactly that. Paper treats the canvas as HTML and CSS, so the design is already markup. Pencil keeps a vector design file inside your repository as readable JSON and exposes it to agents through the same protocol your coding agent already speaks. Figma, the incumbent, has moved in the same direction with its own MCP server. This article is about what changes when the canvas becomes something your agent can read and write directly — and what does not change, because taste, judgment, and review are still yours.

Prices, platforms, and tool names below were re-read from the vendors' pages on 9 October 2026. The round-trip walkthrough is still a reproduction against an older tool surface, and it is labeled that way.

A connected canvas is not a plugin or an exporter. It is a design surface that meets three conditions. First, the artifact is something an agent can natively manipulate — HTML and CSS in Paper's case, a JSON-based .pen file in Pencil's case — rather than a proprietary binary that needs an API translation before an agent can reason about it. Second, the surface exposes read and write access through the Model Context Protocol, so the same agent that edits your components can inspect a frame, take a screenshot of it, and push a change back. Third, the human and the agent see the same surface update: when the agent writes, the designer watches the canvas change, and when the designer drags a frame, the agent's next read reflects it.

Those three conditions produce the workflow this article teaches: the round trip. You design a section on the canvas with named layers and shared variables. The agent reads the structure, the variables, and a screenshot, then generates a component in your repository that maps the canvas variables to CSS custom properties. You edit the component the way you would edit any code — change a radius, rewrite a label — and the agent applies the same change back to the canvas, so the design file does not silently fall behind the implementation. A final render-versus-canvas check closes the loop.

The round trip matters more than the generation step. Plenty of tools can turn a design into a first draft of code. Far fewer can keep the design and the code describing the same thing a month later, after a dozen small changes have landed on whichever side was more convenient that day. The loop in the diagram below is the whole argument of this article in one picture.

One artifact, two readers. Paper connects with paper mcp. pen.dev writes through execute and has no published price. Older call names such as batch_design are not the current list.

Paper (paper.design) is a design canvas whose layers are HTML and CSS. The preferred agent path is now the Paper CLI command paper mcp, which speaks stdio to Claude Code, Codex, Copilot, VS Code, OpenCode, and Antigravity. Paper Desktop still serves the older HTTP endpoint at http://127.0.0.1:29979/mcp while a file is open. Desktop builds exist for macOS, Windows, and Linux. The free plan is $0, with unlimited editors and viewers and 100 MCP calls a week. Pro is $20 per editor per month, or $16 on yearly billing, with 1 million MCP calls a week and video export. Pro does not remove the cap. Organizations are quoted separately. This revision did not recount the tool list, so it does not repeat a tool count.

pen.dev, at pen.dev and pencil.dev, is the product this article used to call Pencil. The design file is still a .pen file in the repository. The MCP server still registers as pencil. The documented tools on 9 October 2026 are get_style, read_skill, get_app_state, and execute, plus browser tools in the desktop app and spawn_agents only when that flag is on. Older names such as batch_design, get_editor_state, and get_screenshot are not in that list. The pricing page says pen.dev is currently free and that paid plans may come later, disclosed before any charge. No dollar amount is published.

Figma recommends the remote MCP server. Read tools return design context. Write is use_figma, which entered open beta on 16 June 2026 and was still beta on 9 October 2026: free during the beta, usage-based pricing planned, a Full seat to write outside drafts, Dev seats read-only outside drafts. Code Connect maps a published component to code. Figma Make can open a GitHub pull request inside a closed beta. Make is evidence, not the production codebase. The distinction from Paper and pen.dev is still where the artifact lives: markup or a repo file on one side, a Figma cloud document on the other.

• Paper: paper mcp is the current connect path. Legacy HTTP stays at 127.0.0.1:29979 while a file is open. Free is 100 MCP calls a week. Pro is $20 monthly or $16 yearly, with 1 million calls a week.
• pen.dev: .pen file in the repo, MCP server name pencil, currently free, documented tools get_style, read_skill, get_app_state, and execute.
• Figma MCP: remote server preferred. use_figma writes and is still beta. Full seat to write outside drafts.
• Format details for .pen files are covered in the design-as-code article.

Paper and Pencil deliver the same promise — one artifact, shared by designer and agent — through opposite architectures, and the difference shapes how you work with each. Paper keeps the canvas in its cloud and gives the agent a local bridge to it: Paper Desktop runs the MCP server on your machine, the agent talks to localhost, and Paper synchronizes the result with the cloud document the rest of your team sees. Pencil keeps the canvas file in your repository and brings the editor to the code: the design opens inside VS Code or Cursor, the file is versioned with git, and the agent that edits your components is sitting in the same window as the canvas it is editing.

The tool surfaces diverge the same way. Paper exposes many narrow tools — one to fetch JSX for a selection, one for computed styles, one for a screenshot, one to write HTML, one to update styles, one to create an artboard, and so on. Prompts against Paper tend to read like a sequence of small, specific requests. Pencil exposes a handful of batch-style tools instead: one call that reads many nodes by pattern, one call that executes a script of insert, update, move, and delete operations, plus screenshots, layout snapshots, variable get and set, and node export. Prompts against Pencil tend to describe an outcome and let the agent compose the operation script.

Neither style is better in the abstract. The granular surface gives you predictable, auditable steps and is easier to permission tightly; the batch surface produces fewer round trips and suits larger edits. What matters for your choice is the artifact question underneath: if your deliverable is a marketing page or prototype that should ultimately ship as markup, Paper's HTML-native canvas removes a whole translation step. If your deliverable is product UI that lives and dies with a component library and code review, Pencil's repo-resident file means the design participates in the same pull requests as the code.

Setup is short for both tools, and it is worth doing properly once rather than improvising per project. For Paper, install Paper Desktop (macOS or Windows — the web app does not expose an MCP endpoint), open the file you want the agent to work on, and the local server starts with it. Then register the server with Claude Code, either through Paper's official plugin marketplace or by adding the local HTTP endpoint manually. The plugin route also installs Paper-specific commands; the manual route is one line and works everywhere Claude Code does.

For Pencil, install the extension in VS Code or Cursor and open or create a .pen file. The extension bundles the MCP server, so an agent running inside that editor — Claude Code in the integrated terminal, or the editor's own agent — discovers the Pencil tools without a separate server process. Check Pencil's agent-integration documentation for the current connection steps for terminal-only setups, because the wiring has changed during early access and may change again.

Whichever tool you connect, keep the registration at the project level rather than buried in a personal global config. A project-scoped .mcp.json (or the equivalent for your CLI) means every collaborator — and every agent session — gets the same canvas connection, the same way a shared AGENTS.md gives them the same instructions.

# Route A — Paper's official plugin marketplace
claude plugin marketplace add paper-design/agent-plugins
claude plugin install paper

# Route B — register the local MCP endpoint directly
# (Paper Desktop must be running with a file open)
claude mcp add paper --transport http http://127.0.0.1:29979/mcp

# Confirm the server is registered and reachable
claude mcp list

# Project-scoped alternative: commit .mcp.json so every session
# and every collaborator gets the same connection
# .mcp.json
{
  "mcpServers": {
    "paper": {
      "type": "http",
      "url": "http://127.0.0.1:29979/mcp"
    }
  }
}

The same canvas connects to other agent CLIs. The current path is paper mcp, which is stdio and does not need an HTTP bridge. Codex can declare an HTTP server with a url if you are still on the legacy endpoint. The canvas is not married to one agent.

Before doing any real work, run a connection test that is trivial to verify by eye. The classic is 'create a small red rectangle on the canvas and tell me its node id.' It costs one tool call, proves the write path works, and fails loudly when the desktop app is not running, the file is not open, or the editor extension lost its session. Delete the rectangle and start working.

Three failure modes still account for most setup trouble. The legacy HTTP server only exists while Paper Desktop is running with a file open — a connection refused on port 29979 means that. Desktop builds now include Linux. WSL still needs mirrored networking so localhost resolves to the Windows host. Sessions can drop after sleep or a restart. If reads come back empty, re-run the connection test before debugging the prompt.

# ~/.codex/config.toml
# Paper's MCP server is HTTP on localhost; mcp-remote bridges it
# to the stdio transport Codex expects.

[mcp_servers.paper]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:29979/mcp"]

# Connection test prompt (works in any connected CLI):
#   "Using the paper tools, create a 100x100 red rectangle on the
#    current artboard, tell me its node id, then delete it."

The rest of this article walks one small, complete round trip: a landing-page hero section designed on a canvas, turned into a JSX component, edited in code, and written back to the canvas, with a render-versus-canvas check at the end. One honesty note before the trace, because this site's editorial standard requires it: neither canvas tool could be driven from the environment this article was produced in — Paper requires its desktop app and an account, and the Pencil editor was not connected to this session — so the walkthrough below is a reproduction, written strictly against the officially documented tool surfaces of both products and the independent practitioner write-ups linked in the resources section, not a transcript of tool calls executed for this article. The prompts are the prompts you would run; the iteration counts describe the structure of the loop, not a measured benchmark. Where community write-ups report timings, they are attributed as such.

The scenario: a fictional hiking-log product needs a landing hero — a small badge, a serif headline, one paragraph of supporting copy, a primary and a secondary call to action. The design uses five shared variables on the canvas: a surface color, an ink color, a brand color, a control radius, and a section spacing value. The variables are the contract. They are what makes the round trip more than a one-off export, because both the component and the canvas will reference them rather than hardcoding values.

The trace below uses the older Pencil tool names (batch_get, get_variables, get_screenshot, batch_design, set_variables). It was not re-executed. pen.dev's documented tools on 9 October 2026 are get_style, read_skill, get_app_state, and execute. The prompts describe intent. Do not copy the old tool calls into a new config.

• Frame: landing/hero — badge, headline, supporting copy, primary and secondary CTA.
• Shared canvas variables: color/surface, color/ink, color/brand, radius/control, space/section.
• Deliverable: components/marketing/hero-section.tsx plus styles/canvas-tokens.css generated from the variables.
• Loop: read → generate → human edit → write back → render-vs-canvas check.
• Status: documentation-grounded reproduction, not an executed transcript — flagged here and in the research run's compliance notes.

The first prompt does three things in one pass: it tells the agent which frame is in scope, which tools to use to understand it, and what the output contract is. Naming the frame matters — 'the frame named landing/hero' is unambiguous, while 'the hero I just made' forces the agent to guess from a layout snapshot. Asking for the variables first matters even more, because the variables become the CSS custom properties that keep the component honest. The explicit instruction not to hardcode any value that exists as a variable is the single highest-leverage line in the prompt; without it, agents reliably inline the resolved values and the contract dissolves.

On the read side, the agent combines three views of the same frame. The variable definitions give it the named values and their meanings. The node structure gives it hierarchy, layout direction, gaps, and text content — the things a screenshot cannot carry. The screenshot gives it what neither of the others can: a check on its own reading, because an agent that has misparsed a layout usually produces a description that visibly disagrees with the image. Good agents are explicitly told to compare the two before writing code.

The generation step then has very little left to invent. Layout intent comes from the frame's layout containers, values come from the variables, copy comes from the text nodes, and the component's job is to express all of that in the project's conventions — Tailwind for layout, CSS custom properties for everything that came from a variable, and the project's own file layout for where things go. The next section shows the kind of output this produces.

# 1 — Design to code: read the frame, generate the component
Open designs/trailhead.pen and work on the frame named "landing/hero".
Use get_variables to read the shared variables, batch_get to read the frame's
node structure, and get_screenshot so you can see the rendered frame.
Generate two files:
  - styles/canvas-tokens.css: one CSS custom property per canvas variable
  - components/marketing/hero-section.tsx: a HeroSection component using
    Tailwind for layout and the custom properties for color, radius, and
    section spacing.
Do not hardcode any value that exists as a canvas variable.
Before writing code, state how the frame is laid out and flag anything in
the structure that disagrees with the screenshot.

# 2 — Code back to design: after the human edit
I edited hero-section.tsx: the control radius is now 12px and the secondary
button copy is "See a sample log". Apply the same change to the canvas:
update the radius/control variable (not the individual nodes) with
set_variables, update the button text in "landing/hero" with batch_design,
then return a fresh get_screenshot of the frame.

# 3 — Verify: render vs canvas
Render HeroSection at 1440px wide and screenshot it. Compare it with the
canvas screenshot. List every visible difference larger than ~2px and any
text mismatch, say which side you believe is wrong, and propose the smallest
change that brings them back in line.

The excerpt below is the shape of output this prompt produces — trimmed, but representative of what the documented workflow generates and what you should hold the agent to. Two things are worth reading for. First, the variable mapping: every color, the radius, and the section spacing reference a CSS custom property whose name traces directly back to a canvas variable. When the canvas variable changes, regenerating one small CSS file updates the component without touching the JSX. Second, the division of labor: Tailwind utilities carry layout — flex direction, gaps, max widths — while the custom properties carry the values that the design owns. That split is what keeps the component reviewable: a reviewer can see at a glance which decisions came from the canvas and which came from the code.

Resist the temptation to let the agent 'clean up' the custom properties into theme constants on the first pass. The verbosity is the point during the round-trip phase: it preserves the one-to-one mapping that makes write-back and drift-checking mechanical. Folding the values into your real token system is a deliberate later step — and if you already maintain a token pipeline, the canvas variables should map onto those tokens rather than spawning a parallel set, which is exactly the boundary where the design-as-code article picks up.

/* styles/canvas-tokens.css — generated from the canvas variables */
:root {
  --canvas-color-surface: #f6f2e9;   /* color/surface */
  --canvas-color-ink: #20222b;       /* color/ink */
  --canvas-color-brand: #3450c8;     /* color/brand */
  --canvas-radius-control: 8px;      /* radius/control */
  --canvas-space-section: 96px;      /* space/section */
}

// components/marketing/hero-section.tsx (excerpt)
export function HeroSection() {
  return (
    <section
      className="flex flex-col items-start gap-6 px-8 py-[var(--canvas-space-section)]"
      style={{
        backgroundColor: "var(--canvas-color-surface)",
        color: "var(--canvas-color-ink)",
      }}
    >
      <p
        className="rounded-full border-2 px-3 py-1 text-sm font-semibold"
        style={{ borderColor: "var(--canvas-color-ink)" }}
      >
        Field test 03 — open beta
      </p>
      <h1 className="max-w-2xl font-serif text-5xl leading-tight">
        Plan the route. Log the walk. Keep the notes.
      </h1>
      <p className="max-w-xl text-lg opacity-80">
        Trailhead keeps route plans, weather windows, and field notes together,
        so the next trip starts from the last one.
      </p>
      <div className="flex gap-3">
        <a
          href="/signup"
          className="px-5 py-3 font-semibold text-white"
          style={{
            backgroundColor: "var(--canvas-color-brand)",
            borderRadius: "var(--canvas-radius-control)",
          }}
        >
          Start a trip log
        </a>
        <a
          href="/example"
          className="px-5 py-3 font-semibold"
          style={{
            border: "2px solid var(--canvas-color-ink)",
            borderRadius: "var(--canvas-radius-control)",
          }}
        >
          See an example
        </a>
      </div>
    </section>
  )
}

The middle of the loop is the part most design-to-code tools skip: a person changes the code. In this scenario the edit is small and typical — the control radius goes from 8px to 12px after seeing the buttons in a real browser, and the secondary call to action is rewritten from 'See an example' to 'See a sample log' because the original was vague. In a disconnected workflow, those two changes are precisely the kind that never make it back to the design file. They are too small to justify opening the design tool, so the canvas quietly becomes a historical document.

With a connected canvas, the write-back is one prompt — the second prompt in the block above. Two details in it carry most of the value. Asking the agent to update the radius variable rather than the individual button nodes keeps the change systemic: every other control on the canvas that references radius/control picks it up, exactly as the CSS custom property did in code. And asking for a fresh screenshot after the write turns the change into something you can see and accept, rather than something you have to trust. In Pencil's tool surface this lands as a set_variables call plus a small batch_design script that updates the text node; in Paper, the same intent lands as a style update and a text-content update against the selected layers.

This is also where the canvas earns its place in review. The .pen file change shows up in the same pull request as the component change, so a reviewer sees the design and the code move together — or notices that one moved without the other, which is the drift the loop exists to prevent. Paper's cloud document does not give you a git diff, but the before-and-after screenshots serve the same review function in the conversation.

An honest version of this workflow includes its failure modes, and they are consistent across the practitioner write-ups this article draws on. The most common is the layout misread: a frame that looks like a tidy column but is actually a pile of absolutely positioned layers produces a component full of magic-number offsets, because the agent faithfully reproduced a structure that was never sound. The fix is on the canvas, not in the prompt — rebuild the frame with layout containers and let spacing come from gaps, then re-run the read. The second is the systemic-versus-local trap shown in the write-back step: an agent told to 'make the radius 12' will happily edit three button nodes and leave the variable untouched, so the canvas looks right while the contract is broken. Prompts that name the variable to change are the defense.

The verification pass catches a third class of problem: silent improvements. In the reproduced trace above, the rendered component wrapped the headline earlier than the canvas did, because the agent had narrowed a max-width 'for readability' without being asked. The render-versus-canvas comparison is what surfaces those — an agent asked to list visible differences larger than a couple of pixels will report its own embellishments, and you decide which side wins. Community write-ups describe the same practice with a literal overlay: a screenshot of the rendered code placed at half opacity over the canvas frame, which is the same visual-QA habit covered in this site's article on agent-assisted visual review.

The cost side: a loop like this is three to five agent passes for a section of this size. Paper's free plan allows 100 MCP calls a week. Pro allows 1 million a week at $20 per editor monthly, or $16 on yearly billing. The bigger cost is the discipline the loop demands. It only protects you if write-backs actually happen.

Connected canvases reward the same hygiene that good component code rewards, because the agent reads the canvas the way a compiler reads source: structure first, intentions never. The difference between a frame that round-trips cleanly and one that produces brittle output is rarely the prompt — it is how the frame was built and named before the agent arrived.

The table below collects the patterns that consistently separate clean round trips from messy ones. None of them are exotic; they are the canvas equivalent of writing functions a colleague can read.

The fair comparison is architectural. Figma can write, through use_figma, and that write path is still beta. What does not change with the beta is where the artifact lives. With Paper, the artifact is markup reached through paper mcp, with the old HTTP bridge still available. With pen.dev, it is a .pen file in the repository. With Figma, it is a cloud document. Each position has consequences for review, versioning, and how much fidelity survives the trip.

Figma remains the right call in clearly identifiable situations: an established team library and design system already living there, true multiplayer design with non-engineering stakeholders, the plugin and FigJam ecosystem, and organizational requirements around roles and audit. A connected canvas is the better fit when the deliverable is close to code, the people involved are comfortable in a repository, and the cost you most want to eliminate is the translation step between the design artifact and the shipped artifact. Plenty of teams will sensibly run both: Figma as the system of record for the design organization, a connected canvas as the working surface for the slice of the team that ships marketing pages or prototypes with an agent in the loop.

The table below was re-read on 9 October 2026. The June image is not shown, because it still prints the old prices and the old 'no Linux' line.

Platform and pricing limits first. Paper Desktop now includes Linux. WSL still needs mirrored networking. The free plan is 100 MCP calls a week, which an agent loop can spend. Pro is $20 per editor monthly or $16 yearly, and it raises the cap to 1 million calls a week rather than removing it. pen.dev is free, and the pricing page says paid plans may come later. Figma's MCP server is free during the beta, with usage-based pricing planned. Date-stamp those assumptions.

Capability limits next. Agents still misread complex layouts — overlapping layers, masked groups, intricate responsive behavior — and the more a frame relies on visual cleverness rather than structure, the more the generated component degrades into absolute positioning and guesswork. A connected canvas is also not a design system by itself: variables on a canvas are a contract for that file, not governance for a product. If the canvas variables and your real token pipeline disagree, the pipeline should win, and the canvas should be regenerated from it rather than the other way around. And the prototype-to-production boundary still exists — a hero section that round-trips beautifully is still a prototype until it has met accessibility checks, content review, and the rest of the production gate, which is its own article on this site.

Finally, the anti-patterns. Do not use a connected canvas as a one-way code generator and skip the write-back; you have rebuilt the handoff with extra steps, and the canvas will be stale within a sprint. Do not let the agent edit both sides in the same pass without a human between them — the loop's value is that a person reviews each direction, and an agent reconciling its own output on both surfaces can launder a mistake into both artifacts at once. Do not paste secrets or production data into canvas text layers that an agent will read and copy into code. And do not adopt either tool because the demo was impressive: adopt one because the artifact it produces — markup or a repo file — is the artifact your team actually wants to own.

• Paper Desktop ships for macOS, Windows, and Linux. Free is 100 MCP calls a week. Pro is $20 monthly or $16 yearly, with 1 million calls a week.
• pen.dev is currently free. Tool names have already changed once. Match the live list.
• Figma's Dev Mode MCP is in beta with usage-based pricing planned; re-verify capabilities before relying on them.
• Canvas variables are not a design system; your token pipeline remains the source of truth.
• Skipping the write-back, letting the agent close its own loop unreviewed, and tool choice by demo are the three habits that undo the benefit.

Everything above compresses into a workflow you can run the same day you connect a canvas. It assumes nothing about which canvas you chose — only that the agent can read structure, read variables, take screenshots, and write back.

Start smaller than feels necessary. One section, five variables, one component. The round trip is a habit before it is an architecture, and the habit is what keeps the two artifacts honest after the novelty wears off.

# Connected-canvas round trip — pre-flight

## Choose and connect
- [ ] Pick the canvas that matches the artifact you want to own:
      markup that ships (Paper) vs a design file in the repo (Pencil)
- [ ] Register the MCP server at project scope (.mcp.json / config.toml), not per machine
- [ ] Run the trivial write test (red rectangle in, node id back, delete it)

## Prepare the frame
- [ ] Layout containers and gaps, no absolute positioning unless intentional
- [ ] Semantic names for the frame and key layers (landing/hero, cta-primary)
- [ ] Shared variables for every value the code should treat as a token

## Run the loop on one section
- [ ] Read: variables + structure + screenshot, agent states the layout before coding
- [ ] Generate: variables become CSS custom properties; no hardcoded token values
- [ ] Edit: make the human change in code, as a normal review
- [ ] Write back: change variables (not nodes) where the change is systemic
- [ ] Verify: render-vs-canvas screenshot comparison; differences become the next pass

## Keep it honest
- [ ] Every accepted code change triggers a write-back in the same session
- [ ] Date-stamp pricing/capability assumptions; re-verify quarterly
- [ ] Canvas variables defer to the real token pipeline when they disagree

The links below are the primary pages this revision was checked against on 9 October 2026, plus earlier practitioner write-ups of the round trip. If you are reading this later, check the official pages first.