Paper Design

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  ''

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":"
Home
","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

| Command | Purpose | |---------|---------| | paper.sh get_basic_info | File name, page, artboards, fonts in use | | paper.sh get_selection | Currently selected nodes on canvas | | paper.sh get_node_info '{"nodeId":"ID"}' | Size, visibility, parent, children, text | | paper.sh get_children '{"nodeId":"ID"}' | Direct children with IDs and types | | paper.sh get_tree_summary '{"nodeId":"ID"}' | Compact hierarchy overview (cheap) | | paper.sh get_tree_summary '{"nodeId":"ID","depth":5}' | Deeper hierarchy | | paper.sh get_computed_styles '{"nodeIds":["ID1","ID2"]}' | CSS styles for nodes | | paper.sh get_jsx '{"nodeId":"ID"}' | JSX code (for dev handoff) | | paper.sh get_font_family_info '{"familyNames":["Inter","DM Sans"]}' | Font availability + weights |

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":"
content
","targetNodeId":"PARENT_ID","mode":"insert-children"}'
Replace an existing node
exec {baseDir}/paper.sh write_html '{"html":"
new content
","targetNodeId":"OLD_NODE_ID","mode":"replace"}'

HTML Rules (critical):

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:

Default Artboard Sizes

| Device | Width | Height | |--------|-------|--------| | Mobile (iPhone) | 390px | 844px | | Tablet (iPad) | 768px | 1024px | | Desktop | 1440px | 900px |

Troubleshooting

# 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":"
Home
","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