Paper.design 最佳实践:从网页画布到代码,兼谈 Figma 与 Pencil
Paper Docs · Paper Roadmap · Paper vs Figma · Paper vs Pencil
AI 参与说明(Agent:Codex)。依据三家官方文档、发布记录和团队原文整理,Paper 功能与示例核对至 2026-11-19,Figma 与 Pencil 对比补充于 2026-11-20。工作流与案例是本文建议。Paper 画布内的导入、Agent 写入及交付流程供读者按步骤复现。
如果要重做一个已经上线的网页区块,Paper 最值得尝试的地方是可以从实际网页取样,在画布上并排比较方案,再把选中的设计交给 Agent 和工程师实现。HTML/CSS 画布让布局、字体与颜色的表达更靠近 Web。团队仍要决定解决什么问题,并在真实浏览器中验证交互。已有共享组件库、多角色评审和可点击原型的团队,可以继续用 Figma 承担这些工作。希望设计文件随功能代码进入同一个 Git PR 的团队,则更适合考察 Pencil(现名 pen.dev)。
| 英文术语 | 中文名称 | 简要解释 |
|---|---|---|
| Canvas | 画布 | 并排摆放方案、状态和说明的工作区 |
| Paper Snapshot | 网页捕获扩展 | 将浏览器里看到的网页区域转成 Paper 中的可编辑图层 |
| Design Token | 设计令牌 | 为颜色、间距等设计决策命名,供多个位置引用 |
| MCP | 模型上下文协议 | 让 Agent 调用工具来读取设计上下文或修改画布 |
| Handoff | 设计交付 | 把选定方案、状态和行为规则交给实现者 |
Paper 的设计哲学
先保留选择,再决定实现
Paper 团队的 Agu Seguí 把画布视作思考和协作的空间。Agent 能快速生成方案,设计师仍要同时看见几个方向,判断各自适合什么情境。改版时可以把线上版本、两个候选方案和取舍理由放在一起。让 Agent 扩充内容或整理图层,再由设计师判断哪一个方案能让访客更快理解、薄弱环节在哪里。这个方法也适用于手工设计,MCP 减少的是重复操作。 Paper 团队原文
让画布采用 Web 的表达方式
Paper uses HTML and CSS as its rendering foundation. 例如订阅卡片用 Flexbox 的容器方向、gap 和 padding 表达结构,开发者可以沿用这些布局关系,Agent 也能从节点读取样式。Paper 还强调 CSS 原生颜色表达与视觉效果,例如在画布中使用 oklch()、Display P3 与 CSS filters。用于品牌页面时,可以先选定色彩和材质方向,再回应用检查目标浏览器与显示设备上的实际效果。 Paper 团队对渲染选型的说明 · Paper 对比 Figma
画布里排得下的按钮,部署后还要支持键盘焦点、长文案、提交中和失败重试。Paper 可以让视觉结构更容易传递,应用组件、断点规则与运行时状态依然由代码表达。把画布当作评审视觉意图和布局的地方,把代码仓库当作生产行为与共享组件的依据。
同一项改版,三种工作方式
假设订阅区块已经上线。这次要让窄屏的邮箱和提交按钮纵排,并让提交失败的访客能保留邮箱、直接重试。三款工具都能画出结果,区别在于团队拿什么来评审。
| 要先解决的问题 | 更合适的起点 | 评审时打开什么 |
|---|---|---|
| 线上区块在窄屏挤在一起,想快速比较两种排法 | Paper。用 Snapshot 保留线上基线,在同一张 HTML/CSS 画布上做两个变体 | Paper 链接里的基线和候选 Frame,随后检查应用里的实现 |
| 想让产品经理亲自走一次失败与重试,还要遵循公司的表单组件规范 | Figma Design。用已有的组件实例与状态做可点击原型 | Figma 原型和在 Dev Mode 中标明可开发的定稿 |
| 想让设计稿跟着代码一起分支、审核和回溯 | Pencil(pen.dev)。把 newsletter.pen、表单组件和测试纳入同一个 PR | 对应 Git 提交里的 .pen 与代码。外部评审者可以看桌面端分享的快照 |
Paper 与 Figma:改线上界面,还是用组件库推演流程
Paper 从浏览器里已经渲染出来的界面开始。 用 Snapshot 捕获现有区块后,在旁边摆出两个窄屏 Frame。一版把按钮排在邮箱下方,另一版把错误提示移到邮箱和按钮之间。评审时可以拿相同的长文案和测试邮箱比较两版。Paper 的 HTML/CSS 画布让设计和前端都能用 Flexbox、gap 和 padding 讨论布局。导出的视觉结构可以给实现者参考,字段语义、校验、焦点和真实请求仍由应用里的组件负责。 Paper Snapshot · Paper MCP
Figma Design 的长处是让共享组件和用户流程一起接受评审。 从发布的 Library 取出团队的输入框与按钮,画出默认、提交中、失败、成功四个状态,再用 Prototype 连成可点击路径。让评审者点击提交、看到模拟失败、再点重试。通过标准很具体:评审者能看出哪里出错、原邮箱是否还在、下一步点哪里。确认后把区块标记为 Ready for dev,工程师可以在 Dev Mode 查看规格和组件。团队已经配置 Code Connect 时,Figma MCP 还可以把设计组件对应的代码用法交给 Agent,例如指出该用项目里的哪个按钮、如何传入状态。 Figma Library · Prototyping · Dev Mode · Code Connect
Figma 的 Remote MCP 也支持 Write to canvas(Beta),有兼容客户端、编辑权限和相应访问资格时,可以用现有组件和变量写入原生图层。Figma 把运行中的网页带进来时,可以先获得外观图层,再用库中的原生组件重建要交付的部分。如果团队本来就在 Figma 发布组件,先挑一个 Frame 试迁:将现有订阅区块复制到 Paper,检查输入框实例与变量。Paper 的粘贴文档明确说明会解除这两类关联。只想讨论一个网页改动,保留外观可能就够了。后续还要跟着共享库更新时,保留 Figma 中的组件稿能省去重复维护。 Figma Write to canvas · Paper 的 Figma 导入说明
Paper 与 Pencil:共享画布怎么评审,设计文件怎么回溯
Paper 把这次视觉评审留在共享文件里。 设计师把「线上版」「纵排版」「失败重试版」并排放好,发同一个 Paper 链接。在有编辑权限的团队成员之间,可以在同一个文件里一起看和改。定稿后,把具体 Frame 的链接附到实现 PR。一个月后查历史时,代码 Git 提交能告诉你实际改了什么,Paper 链接可用来找当时评审的画布。需要让评审指向某个版本时,可保留该次定稿并在 PR 里写清对应的 Frame。 Paper Build Log · Paper 对比 Pencil
Pencil 把可编辑设计放到工程文件旁边。 例如把 design/newsletter.pen、它引用的图标或 .lib.pen,以及订阅表单的实现和测试一起提交。评审者打开 PR 分支,可以在 Pencil 查看这一版稿,也可以在应用里模拟提交失败。以后切回该提交,稿件和实现就能按同一版本一起打开。这个好处也带来 Git 协作成本:两个分支同时改一份 .pen 时,官方建议保存两份版本,选一个作底稿,再在编辑器把另一边的修改补进去并检查受影响的 Frame。共享资源也要保持正确的相对路径。 pen.dev 的 .pen 文件与 Git · .pen 文件格式
Pencil 也有 Web 入口。若团队采用本地 .pen 工作流,桌面端可把稿件和依赖作为快照发给外部评审者,并按权限开放评论或下载。改完本地稿后,文件所有者需要点 Update snapshot,评审者刷新原链接才能看到新版。比如 PR 已把错误提示换了位置,评审链接还是旧版,此时要更新快照,并在 PR 标明它对应哪个提交。 pen.dev 官网 · 快照分享与更新
两款工具都可以接 Agent,也都可以从网页开始。Paper 以 HTML/CSS 渲染画布,Pencil 将可编辑结构保存为有公开 Schema 的 .pen 节点。Pencil 可以导出 HTML/CSS 或 HTML/Tailwind,它的 Design ↔ Code 工作流由人发起具体的更新请求。例如让 Agent 从选中的 Frame 读出纵排和错误提示位置,再复用工程中的表单组件。选型时可以直接跑一次评审:如果参与者需要用浏览器一起推敲多个候选,试 Paper 的共享画布。如果交付标准是从任一 Git 提交都能打开对应稿件,试 Pencil 的同仓版本管理。 Paper 的渲染选型 · pen.dev Design ↔ Code
三家都能复用设计值,团队推广方式各有成本。Figma 的 Library 可以发布组件、样式和变量,使用方可评审并接受更新。Pencil 的 .lib.pen 支持组件与变量,已有 slots 和多维主题,依赖文件重新打开时读取保存的库版本。Paper 当前的 Design Tokens 可在文件内同步,跨文件复制后要另行更新各文件。多个团队共同改一套表单时,可以先做一次「修改错误色 → 让两个页面消费新值」的演练,再决定哪套方式更适合现有发布周期。 Figma Library 发布指南 · pen.dev Design Libraries · pen.dev Slots · pen.dev Variables · Paper Tokens
用 Paper 完成一次网页改版
下面以一个邮件订阅区块为例。假设现有 Web 应用已经有表单组件和 CSS Design Tokens。希望在桌面保留紧凑的并排布局,在窄屏把输入和按钮按阅读顺序排开。最终交付包含一张设计评审链接和一个可运行的代码 PR。
1. 从一块有真实内容的界面开始
在浏览器打开自己的页面或测试环境,用 Paper Snapshot 捕获订阅区块,粘贴进 Paper。把结果命名为 Newsletter / Baseline,旁边建两个候选 Frame,并记录来源页面、捕获时的宽度和所处的状态。先核对字体、图片、溢出与图层嵌套,再开始改。用测试数据复现长标题、错误提示和窄屏。遇到本地图片缺失,按 Snapshot 文档检查资源 URL 和开发服务器的 CORS 配置。 Paper Snapshot 说明 · 本地图片排查
如果手里已有 Figma 稿,先复制单个代表性 Frame 到 Paper。官方导入说明指出,粘贴时组件实例和变量会解除关联,图片也可能需要连接有访问权限的 Figma 账号。逐项检查图层结构、图片和样式,再决定是否迁移更多页面。若已有一段自写 HTML,可按官方指南提供带 inline styles 的片段,HTML Paste 会忽略 class 和由选择器应用的样式。 Paste from Figma · Paste from HTML
没有现成页面时,可以把下面的 HTML 保存为 newsletter.html,在该文件所在目录运行 python3 -m http.server 8000 --bind 127.0.0.1,打开 http://127.0.0.1:8000/newsletter.html 后通过 Snapshot 选取订阅区块。这个无依赖样本在窄屏时会把字段与按钮换行,按钮只用于展示版式。导入后,在 Paper 里尝试分别选中标题、字段与按钮,再改长标题。如果粘贴后得到一整张图片,回到浏览器扩展重新捕获可编辑图层。
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>邮件订阅区块</title>
<section style="max-width: 640px; padding: 24px; background: #eff6ff; color: #172554">
<h1>订阅产品设计简报</h1>
<p>每月一封,分享值得读的实践。</p>
<div style="display: flex; flex-wrap: wrap; gap: 12px">
<input aria-label="邮箱地址" placeholder="name@example.com" type="email"
style="box-sizing: border-box; flex: 1 1 260px; min-width: 0; padding: 12px">
<button type="button" style="padding: 12px 24px">订阅简报</button>
</div>
</section>
</html>
2. 用容器和 Design Tokens 表达约束
把标题与说明放在一个容器,把字段与按钮放在另一个容器。使用 Flexbox 的方向和 gap 表达布局,让长文案能改变内容占用的空间。画出 390 px 与 1024 px 的参考 Frame,并写清中间宽度的规则,例如表单容器够宽时字段和按钮并排,空间不足时换成上下排列。参考 Frame 是两个观察点,真正的切换条件要在浏览器里检查。 Paper MCP 的布局与交付指南
在 Theme 面板中绑定来自仓库的语义化 Design Tokens,例如 --color-surface、--color-text 和 --space-form-gap。先只同步这个区块用到的几个值,改一个间距值,确认引用它的候选方案一起更新。Paper 文档说明跨文件复制的是值与定义,之后单个文件中的更新不会传播到其他文件。团队可把 CSS 文件定为每次同步的依据,记录来源提交,并在设计确定后审阅涉及 token 的代码差异。 Paper Tokens
3. 让 Agent 先确认目标,再改一组节点
在本机使用 Paper Desktop,打开目标文件后,从编辑器的 MCP 面板连接所用 Agent。新配置以 Paper CLI 的 stdio 接入为主,旧 HTTP 配置按官方迁移指引处理。需要从云端操作时,官方另有 Remote MCP Early Access,连接时需登录 Paper。先让 Agent 报告它看到的文件和选区,确认后再修改画布。 Paper MCP 安装与连接
选中 Newsletter / Baseline,将下面的提示词交给已连接 Paper 的 Agent。若需要并排比较视觉方向,可以先做一个变体并评审,再用同样的样本约束第二个变体。
先读取当前选区并报告文件、页面与 Frame 名。确认它是 Newsletter / Baseline 后,复制到同一页,命名为 Newsletter / Stacked。保留 Baseline。
只调整副本的订阅字段与提交按钮容器,使用 Flexbox 和已有 Design Tokens。用 390 px 参考宽度检查标题换成「每月收到产品设计与前端实践精选」后的换行。
在副本旁画出提交中、已提交、失败可重试三个状态。失败状态保留原邮箱。完成后返回可用于评审的 Frame 名,并检查画布截图是否有裁切。
评审时打开基线和副本,核对基线和其他图层是否保持原样,字段和提示能否一起换行,以及各状态下用户是否看得出下一步。视觉判断通过后,交给工程师选定 Frame 及其状态说明。需要评估外部协作时,使用评审者的实际身份打开链接,确认其可见范围和权限。
4. 在应用里验收交互,再回画布比对
让实现 Agent 读取选定 Frame,与仓库现有表单组件和 token 对照后再改代码。Paper 可以复制 React CSS 或 Tailwind 代码作为交付输入。工程侧沿用现有字段、验证和提交逻辑,根据 PR diff 确认没有引入另一套表单或重复定义 token。若最终浏览器效果有偏差,可以用 Snapshot 把实现结果放到候选稿旁边,逐项核对。 Paper Build Log · Paper 的设计转网站示例
| 验收项 | 操作 | 通过条件 |
|---|---|---|
| 响应式 | 打开本地应用,在 390 px、两种布局的交界和 1024 px 更换长短文案 | 字段与按钮按约定换行,页面无横向溢出,提示信息保持可见 |
| 键盘 | 用 Tab 从输入框走到提交按钮,再提交表单 | 焦点可见,顺序符合阅读顺序,字段有可访问名称 |
| 提交状态 | 在测试环境模拟慢响应、成功和失败 | 提交中避免重复请求,成功有反馈,失败保留已输入邮箱并允许重试 |
| 设计一致性 | 比较 Paper 中的选定 Frame、应用截图和 PR | 版式取舍一致,新增样式复用已有语义 token,代码评审能定位选定方案 |
如果要试用一周,可以让同一个团队用同一个真实区块完成以上流程。记录评审后发生了几次视觉返工、实现时复用了哪些现有组件,以及有多少状态需要口头补充。这三项足以检验 Paper 有没有减少当前工作流里的交接成本。
怎样读 Paper 的路线图
Roadmap 展示 Paper 希望减少哪些交接工作。判断能否用于本周的项目时,优先看专项文档、Build Log 和实际文件权限。比如九月的 Build Log 曾把 Remote MCP 列为即将推出,现行 MCP 文档已经给出 Early Access 接入步骤。HTML Paste 的文字说明仍有旧的 Rich Text 限制,十月的 Build Log 已记录 Rich Text Editing 上线。涉及导入保真度时,仍应拿自己的一段混合样式文案实测。 Paper Roadmap · Paper Build Log · Paper MCP · Paste from HTML
| 官方资料中的状态 | 对当前项目的影响 |
|---|---|
| Snapshot、本地 MCP 和文件内 Design Tokens 有公开使用指南 | 可以先用它们试点一个已有网页区块 |
| Roadmap 将直接使用项目代码组件、Native Tailwind CSS integration 列为进行中 | 现有 Copy as code 可用于生成起点。仍由工程师在仓库里匹配组件并审阅代码 |
| Components with slots 标为即将推出,CSS Grid 标为计划 | 采用 Flexbox 完成本例。项目若依赖 slots 或 CSS Grid 编辑能力,先在所用版本验证 |
| Tokens 已可在文件内使用,Theme Modes 和共享库仍是专项文档中的后续方向 | 有跨团队发布依赖的项目,先保留现有库的发布方式,用代码管理产品主题的最终值 |