paper-design

name paper-design description Design and prototype in Paper Design (app.paper.design) — read/write designs via MCP, convert to React/Tailwind code, import HTML/CSS, sync design tokens. Also covers Paper Shaders (@paper-design/shaders-react) — 30+ shader React components (mesh gradient, fluted glass, liquid metal, god rays, halftone, grain gradient, pulsing border). Pairs with minoan-frontend-design for creative direction. Triggers on Paper Design, paper.design, design-to-code, artboard, Paper Shaders, Paper MCP, prototype. argument-hint [artboard name, action, or 'health-check'] Read and write designs in Paper via MCP. Paper is a DOM-based design tool — designs are HTML/CSS structures that Claude reads and writes natively. Prerequisites Paper Desktop must be running before starting Claude Code. The app auto-starts an MCP server at http://127.0.0.1:29979/mcp . Run python3 ~/.claude/skills/paper-design/scripts/health-check.py to verify connection. If the MCP server is not registered, run bash ~/.claude/skills/paper-design/scripts/setup.sh . Paper vs Pencil Use Paper for design-to-code, code-to-design, and rapid prototyping (native DOM). Use Pencil for reusable design systems, existing .pen files, and presentations. Full comparison: references/paper-vs-pencil.md Paper Shaders Paper also ships a standalone React shader library — @paper-design/shaders-react — used independently of the MCP workflow. Install with npm i @paper-design/shaders-react and import named components like MeshGradient , FlutedGlass , LiquidMetal , HalftoneCMYK , GodRays . 30+ shaders across three categories (Image Filters, Logo Animations, Effects). Zero dependencies beyond React. Reach for Paper Shaders when the goal is to use a designer-tuned effect as a React component with named props. Reach for threejs-particle-canvas , grainient , or rocaille-shader when the goal is custom particle systems, grainient.supply-style page aesthetics, or pointer-reactive DOM distortion — those skills have different strengths. Shaders authored in Paper-the-tool export as the matching React component via get_jsx ; prop names map 1:1 onto the sliders in each shader panel. Full catalog, per-category tables, and integration notes: references/shaders.md . Workflow Every Paper interaction follows four phases: Orient, Create, Verify, Export. 1. Orient Read document state before making changes. Call get_basic_info for file name, page name, artboard list. Call get_tree_summary with an optional depth limit for structure overview. Call get_selection when the user says "this element" or "the selected thing." 2. Create Two paths depending on direction: Design from scratch: find_placement — find empty canvas space for new artboard create_artboard — common sizes: Desktop (1440x900), Tablet (768x1024), Mobile (375x812) start_working_on_nodes — lock the artboard (shows progress indicator to user) write_html — write semantic HTML with inline styles or Tailwind classes finish_working_on_nodes — release the lock Modify existing design: get_node_info or get_children — understand the target node's structure start_working_on_nodes — lock before modifying write_html (replace content), update_styles (targeted CSS changes), or set_text_content (text-only) finish_working_on_nodes — release the lock write_html replaces the entire content of the target node. To update part of a design, target a specific child node, not the artboard root. 3. Verify Call get_screenshot after every write operation to verify visual results. DOM correctness does not guarantee visual correctness. Scale options: 1x (default) or 2x for detail inspection. 4. Export Design to code: get_jsx exports a node as React + Tailwind JSX. Post-process if the project uses plain CSS. Combine with get_computed_styles to extract design tokens (colors, spacing, typography). Check get_font_family_info to verify font availability before shipping. In Paper itself, Alt T copies the selection as Tailwind JSX and Alt R copies it as React CSS — useful when the user is driving Paper manually and pasting directly into code without an MCP round trip. Responsive variants: duplicate_nodes to clone a desktop artboard, then resize and adjust layout for tablet/mobile breakpoints. Working Indicators start_working_on_nodes and finish_working_on_nodes are locks, not advisories. Starting prevents the user from editing those nodes simultaneously. Forgetting to call finish_working_on_nodes locks the user out. Always pair them. Call finish even if an error occurs mid-workflow. Integration When minoan-frontend-design is active, use it for creative direction (aesthetic, typography, color, spatial composition), then translate that direction into Paper artboards via write_html . The design lives in Paper; the code lives in the project. get_jsx bridges them. When shadcn is active, extract Paper design tokens via get_computed_styles and map them to shadcn's OKLCH CSS variables. Or reverse: read the project's shadcn theme, apply as Paper styles via update_styles . References Consult references/ on demand: tool-reference.md — All 21 MCP tools with usage patterns and gotchas. Read for any Paper MCP operation. workflow-patterns.md — 7 detailed workflow recipes. Read when starting a multi-step design task. paper-vs-pencil.md — Decision matrix across 10 dimensions. Read when choosing between design tools. shaders.md — Catalog of 30+ Paper Shaders ( @paper-design/shaders-react ) with categories, common props, and integration notes. Read when installing, selecting, or exporting a shader. Troubleshooting When MCP tools return connection errors or hallucinate parameters, the first fix is to restart the Claude Code session — long-running sessions are the most common failure mode, and Paper Desktop itself can stay running. Verify the local MCP endpoint with python3 scripts/health-check.py . Keep Paper Desktop current via About > Check for updates ; Mar 10, 2026 was the first shipping build, and prop names on shaders like FlutedGlass have changed between releases.