Paper Design 是一个基于 DOM 的设计工具，设计稿本质上是 HTML/CSS 结构，因此 Claude 可以原生地读取和写入。该技能通过 MCP（Model Context Protocol）与 Paper 交互，实现设计稿的读写、代码转换与令牌同步。
用途
该技能适用于三类场景：设计转代码（design-to-code）、代码转设计（code-to-design）以及快速原型制作。由于 Paper 采用原生 DOM 结构，Claude 可以直接操作设计内容。若需要可复用设计系统、已有 .pen 文件或演示文稿，则应使用 Pencil 工具，完整对比见 references/paper-vs-pencil.md。
前置条件
启动 Claude Code 之前，必须先运行 Paper Desktop。该应用会自动在 http://127.0.0.1:29979/mcp 启动 MCP 服务器。可运行 python3 ~/.claude/skills/paper-design/scripts/health-check.py 验证连接。若 MCP 服务器未注册，运行 bash ~/.claude/skills/paper-design/scripts/setup.sh。
工作流
每次 Paper 交互遵循四个阶段：Orient（定位）、Create（创建）、Verify（验证）、Export（导出）。
1. Orient
在做出更改前先读取文档状态。调用 get_basic_info 获取文件名、页面名、画板列表；调用 get_tree_summary（可带深度限制）获取结构概览；当用户说“这个元素”或“选中的东西”时，调用 get_selection。
2. Create
根据方向有两条路径：
从零开始设计：
- find_placement — 为新画板寻找空白画布空间
- create_artboard — 常用尺寸：Desktop (1440x900)、Tablet (768x1024)、Mobile (375x812)
- start_working_on_nodes — 锁定画板（向用户显示进度指示）
- write_html — 写入带内联样式或 Tailwind 类的语义化 HTML
- finish_working_on_nodes — 释放锁定
修改现有设计：
- get_node_info 或 get_children — 了解目标节点结构
- start_working_on_nodes — 修改前锁定
- write_html（替换内容）、update_styles（针对性 CSS 更改）或 set_text_content（仅文本）
- finish_working_on_nodes — 释放锁定
注意：write_html 会替换目标节点的全部内容。若要更新设计的一部分，应针对特定子节点，而非画板根节点。
3. Verify
每次写入操作后调用 get_screenshot 验证视觉效果。DOM 正确并不保证视觉正确。缩放选项：1x（默认）或 2x（细节检查）。
4. Export
设计转代码：get_jsx 将节点导出为 React + Tailwind JSX。若项目使用纯 CSS，需后处理。结合 get_computed_styles 提取设计令牌（颜色、间距、字体）。发布前检查 get_font_family_info 验证字体可用性。在 Paper 本身中，Alt T 将选中内容复制为 Tailwind JSX，Alt R 复制为 React CSS——当用户手动操作 Paper 并直接粘贴到代码中、无需 MCP 往返时很有用。
响应式变体：duplicate_nodes 克隆桌面画板，然后调整尺寸和布局以适应平板/移动断点。
工作指示器
start_working_on_nodes 和 finish_working_on_nodes 是锁定，而非建议。开始会阻止用户同时编辑这些节点。忘记调用 finish_working_on_nodes 会将用户锁在外面。务必成对调用。即使工作流中途出错，也要调用 finish。
集成
当 minoan-frontend-design 激活时，用它进行创意方向（美学、排版、颜色、空间构图），然后通过 write_html 将该方向转化为 Paper 画板。设计存在于 Paper 中，代码存在于项目中，get_jsx 是两者之间的桥梁。
当 shadcn 激活时，通过 get_computed_styles 提取 Paper 设计令牌，并映射到 shadcn 的 OKLCH CSS 变量。或者反向操作：读取项目的 shadcn 主题，通过 update_styles 应用为 Paper 样式。
Paper Shaders
Paper 还附带一个独立的 React 着色器库——@paper-design/shaders-react——独立于 MCP 工作流使用。安装命令：npm i @paper-design/shaders-react，然后导入命名组件，如 MeshGradient、FlutedGlass、LiquidMetal、HalftoneCMYK、GodRays。共有 30 多个着色器，分为三类（图像滤镜、Logo 动画、效果）。除 React 外零依赖。
当目标是将设计师调校的效果作为带命名 props 的 React 组件使用时，选择 Paper Shaders。当目标是自定义粒子系统、grainient.supply 风格页面美学或指针反应式 DOM 扭曲时，选择 threejs-particle-canvas、grainient 或 rocaille-shader——这些技能各有不同优势。在 Paper 工具中创作的着色器通过 get_jsx 导出为匹配的 React 组件；prop 名称与每个着色器面板中的滑块一一对应。
完整目录、分类表格和集成说明见 references/shaders.md。
参考资料
按需查阅 references/ 目录：
- tool-reference.md — 全部 21 个 MCP 工具及使用模式和注意事项。任何 Paper MCP 操作前阅读。
- workflow-patterns.md — 7 个详细工作流配方。开始多步骤设计任务时阅读。
- paper-vs-pencil.md — 跨 10 个维度的决策矩阵。在选择设计工具时阅读。
- shaders.md — 30 多个 Paper Shaders（@paper-design/shaders-react）的目录，含分类、常用 props 和集成说明。安装、选择或导出着色器时阅读。
故障排除
当 MCP 工具返回连接错误或幻觉参数时，第一个修复方法是重启 Claude Code 会话——长时间运行的会话是最常见的失败模式，而 Paper Desktop 本身可以保持运行。用 python3 scripts/health-check.py 验证本地 MCP 端点。通过 About > Check for updates 保持 Paper Desktop 最新；2026 年 3 月 10 日是首个发布构建，FlutedGlass 等着色器的 prop 名称在版本之间已发生变化。