Claude-code-minoan paper-design

install

source · Clone the upstream repo

git clone https://github.com/tdimino/claude-code-minoan

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/tdimino/claude-code-minoan "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/design-media/paper-design" ~/.claude/skills/tdimino-claude-code-minoan-paper-design && rm -rf "$T"

manifest: skills/design-media/paper-design/SKILL.md

source content

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.