Paper Design — MCP Bridge Skill

Paper is a professional design tool (like Figma) that runs locally on macOS. This skill connects to Paper's MCP server via HTTP, giving you full design capabilities.

Prerequisite: Paper must be open with a design file loaded. If Paper is not running, tell the user to open it first.

How to Use Paper

All Paper operations go through the paper.sh script in this skill's directory:

exec {baseDir}/paper.sh <tool_name> '<json_arguments>'

Important: Always quote JSON arguments with single quotes to prevent shell expansion.

Quick Start

# 1. Check what's on the canvas
exec {baseDir}/paper.sh get_basic_info

# 2. Create a new mobile artboard
exec {baseDir}/paper.sh create_artboard '{"name":"Home Screen","styles":{"width":"390px","height":"844px","display":"flex","flexDirection":"column","backgroundColor":"#FAFAFA"}}'

# 3. Add content (one visual group at a time)
exec {baseDir}/paper.sh write_html '{"html":"<div layer-name=\"Header\" style=\"display:flex;padding:60px 20px 20px;align-items:center\"><span style=\"font-family:Inter Tight;font-size:28px;font-weight:700;color:#1A1A1A\">Home</span></div>","targetNodeId":"ARTBOARD_ID","mode":"insert-children"}'

# 4. Take a screenshot to review
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID"}'
# → saves to /tmp/paper-screenshots/screenshot-TIMESTAMP.jpg

# 5. View the screenshot
image /tmp/paper-screenshots/screenshot-TIMESTAMP.jpg

# 6. When done, release the working indicator
exec {baseDir}/paper.sh finish_working_on_nodes

Tool Reference

Reading the Canvas

Visual Review

# Screenshot an artboard or node
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID"}'

# Higher resolution (for reading small text)
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID","scale":2}'

# Save to specific path
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID"}' --save /tmp/my-review.jpg

# Then view the screenshot with the image tool
image /tmp/paper-screenshots/screenshot-TIMESTAMP.jpg

Creating Designs

# Create artboard (mobile)
exec {baseDir}/paper.sh create_artboard '{"name":"Screen Name","styles":{"width":"390px","height":"844px","display":"flex","flexDirection":"column","backgroundColor":"#FFFFFF"}}'

# Create artboard (desktop)
exec {baseDir}/paper.sh create_artboard '{"name":"Dashboard","styles":{"width":"1440px","height":"900px","display":"flex","flexDirection":"column","backgroundColor":"#F5F5F5"}}'

# Create related artboard (positioned next to existing)
exec {baseDir}/paper.sh create_artboard '{"name":"Screen V2","relatedNodeId":"EXISTING_ID","styles":{"width":"390px","height":"844px"}}'

Writing HTML into Designs

# Add elements as children of a node
exec {baseDir}/paper.sh write_html '{"html":"<div style=\"...\">content</div>","targetNodeId":"PARENT_ID","mode":"insert-children"}'

# Replace an existing node
exec {baseDir}/paper.sh write_html '{"html":"<div style=\"...\">new content</div>","targetNodeId":"OLD_NODE_ID","mode":"replace"}'

HTML Rules (critical):

• Always use inline styles (style="...")
• Use display: flex for ALL layouts — no grid, no inline, no tables
• Use padding and gap for spacing — NO margins
• No emojis as icons — use SVG paths
• Set layer-name="Semantic Name" on key elements
• Google Fonts available via font-family: "Font Name"
• Font sizes MUST use px units
• Use border-box sizing assumptions

Modifying Existing Designs

# Update styles on nodes
exec {baseDir}/paper.sh update_styles '{"updates":[{"nodeIds":["ID1","ID2"],"styles":{"backgroundColor":"#FF0000","padding":"20px"}}]}'

# Change text content
exec {baseDir}/paper.sh set_text_content '{"updates":[{"nodeId":"TEXT_ID","textContent":"New text here"}]}'

# Duplicate nodes (efficient for repeated elements)
exec {baseDir}/paper.sh duplicate_nodes '{"nodes":[{"id":"SOURCE_ID"}]}'
# With specific parent:
exec {baseDir}/paper.sh duplicate_nodes '{"nodes":[{"id":"SOURCE_ID","parentId":"TARGET_PARENT"}]}'

# Delete nodes
exec {baseDir}/paper.sh delete_nodes '{"nodeIds":["ID1","ID2"]}'

# Rename layers
exec {baseDir}/paper.sh rename_nodes '{"updates":[{"nodeId":"ID","name":"Header"}]}'

Finishing Up

# ALWAYS call when done with an artboard — releases the working indicator
exec {baseDir}/paper.sh finish_working_on_nodes

Design Workflow (Mandatory)

1. Start — get_basic_info to see what's on the canvas
2. Check fonts — get_font_family_info before writing any typography
3. Design brief — Before writing HTML, decide: color palette (5-6 hex), type choices, spacing rhythm, visual direction
4. Build incrementally — ONE visual group per write_html call (header, row, button group — not an entire screen)
5. Review every 2-3 changes — get_screenshot → image → critique spacing, typography, contrast, alignment, clipping
6. Fix issues before moving on
7. Finish — finish_working_on_nodes when done

Review Checkpoints (every 2-3 modifications)

After a screenshot, evaluate:

• Spacing — Uneven gaps? Cramped? Clear rhythm?
• Typography — Readable? Strong hierarchy?
• Contrast — Low contrast text? Elements blending?
• Alignment — Consistent vertical/horizontal lanes?
• Clipping — Content cut off at edges?

Default Artboard Sizes

Troubleshooting

• "Paper is not running" — Open the Paper app on macOS first
• "Failed to initialize MCP session" — Paper needs a design file open (not just the app)
• Empty response — The node ID may be wrong; use get_basic_info to find valid IDs
• Session expired — The script auto-retries with a fresh session; if persistent, delete /tmp/paper-mcp-session