Paper Design

Design UI screens in Paper — a professional design tool running locally on macOS. Create artboards, write HTML into designs, take screenshots, and iterate vi...

Security Scan

The skill appears to do what it claims (drive a local Paper app) and uses only curl/python3, but the runtime script reads/writes environment-configurable endpoints and session files (not declared in metadata), which could be misused or point to a remote endpoint if an environment variable is changed.

Purpose & Capability

Name/description match the implementation: the skill talks to Paper's local MCP server and exposes commands to read the canvas, write HTML, create artboards, and capture screenshots. Required binaries (curl, python3) are appropriate for the HTTP and JSON handling the script performs.

Instruction Scope

SKILL.md stays within the expected scope (telling the agent to call paper.sh with JSON args). However, the included paper.sh reads/writes local session files (/tmp/paper-mcp-session) and a screenshot directory (/tmp/paper-screenshots) and supports environment overrides for the MCP URL and paths. Those env vars are not documented in SKILL.md's public 'requires' list, which is a transparency gap the user should be aware of.

Install Mechanism

Instruction-only skill (no install spec). The included script is executed directly; nothing is downloaded or installed by the skill itself, which minimizes install-time risk.

Credentials

Registry metadata declares no required env vars, but paper.sh honors PAPER_MCP_URL, PAPER_SESSION, and PAPER_SCREENSHOT_DIR environment variables. In particular PAPER_MCP_URL defaults to a localhost address but can be overridden to any endpoint; if set to a remote URL, the skill would send design data and session initialization requests off-host. This is a configuration-based exfiltration risk and should have been declared and documented.

Persistence & Privilege

The skill does not request permanent platform privileges and is not always-enabled. It caches a session id and writes files under /tmp (its own state), which is expected for this kind of bridge. It does not modify other skills or system-wide settings.

What to consider before installing

This skill is coherent with its stated purpose and uses only local HTTP calls by default, but inspect and consider the following before installing: - Review paper.sh yourself. It will create a session file (default /tmp/paper-mcp-session) and save screenshots (default /tmp/paper-screenshots). - Be cautious about the PAPER_MCP_URL environment variable. Although it defaults to http://127.0.0.1:29979/mcp, if that variable is set to a remote host the script will forward MCP calls (and potentially design data) off your machine. Only run this skill in environments where you control env vars. - Confirm Paper is the official desktop app you expect and that the MCP endpoint is running locally. If you have strict data exfiltration requirements, consider running the script in a sandboxed account or reviewing network traffic to ensure MCP calls remain local. - The skill does not declare the optional env vars it supports; prefer explicit documentation or edit the script to harden PAPER_MCP_URL to localhost if you need to lock it down.

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

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

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

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