pen.dev × Claude Code
最佳实践全景指南

为什么是 pen.dev + Claude Code

它解决的核心问题:设计-代码鸿沟

传统流程里,设计师在 Figma 精雕细琢,开发者对着标注重写一遍——间距差一点、字重不对、hover 态没文档,最终上线的东西「像设计稿的表亲」。这不是谁的错,而是设计与开发两套工具链、两个事实来源的结构性问题。

通用 AI 编码工具也没能根治:它们看不到你的设计系统、品牌色和间距阶梯,只能基于全网见过的模式生成「看起来还行」但不属于你产品的组件。

能力版图

来源:Pencil.dev + Claude Code Workflow · 官方 AI Integration 文档 · Geeky Gadgets

环境搭建标准流程

综合官方文档与 DevelopersIO 实测教程,这是社区验证过的最稳妥路径(以 VS Code 为例,Cursor 同理):

1. 安装 Claude Code 并认证:官方首推 native 安装器 curl -fsSL https://claude.ai/install.sh | bash(Windows 用 irm https://claude.ai/install.ps1 | iex);运行 claude 走浏览器登录。装不上/登不上查环境急救手册。
2. 安装 pen.dev 扩展:VS Code 扩展面板搜索 "pen.dev",认准发布者标识 highagency.pencildev。
3. 启动 pen.dev:点击状态栏左下角的 pen.dev 铅笔图标(不出现就重启 VS Code)。
4. 邮箱激活:首次启动输入邮箱 → 收验证码 → 填码登录。
5. 验证 MCP 连接:启动 Claude Code,执行 /mcp,确认 pencil 显示为 connected。MCP 配置在安装时已自动写好,无需手工配置。
6. 创建 design.pen:放在项目工作区根目录,与代码同仓库——这是后续一切「AI 同时看到设计与代码」玩法的前提。

自动写入 .claude.json 的 MCP 配置长这样(路径因平台而异):

"mcpServers": {
  "pencil": {
    "command": ".../highagency.pencildev-x.y.z/out/mcp-server-darwin-arm64",
    "args": ["--app", "visual_studio_code"],
    "type": "stdio"
  }
}

来源:DevelopersIO 实测教程 · 官方 Installation · 官方 Troubleshooting

四种核心工作流

社区实践收敛出四种可复用的工作流范式,可按项目阶段自由组合:

Workflow A 的实测效果

DevelopersIO 用「三要素提示词」各生成一次、零手工修改的直出结果:

以上图片来源:DevelopersIO 实测文章

给既有项目改版的完整链路(实测)

DevelopersIO 演示了对现有项目「设置页」改版的两步法:

1. 生成设计:向 Claude Code 描述页面要求(用 pen.dev MCP 设计当前项目的 Settings 页:白色卡片表单、AI 分析设置分区、模型单选按钮、每个模型下方灰色小字说明……)——先产出 .pen 设计稿。
2. 应用设计:确认设计后一句 请应用这个设计,AI 把设计落到项目的 CSS/组件代码上。

来源:DevelopersIO · 官方 Design ↔ Code · daily.dev: Vibe Design with Pencil and Claude Code

Workflow D 深挖:.pen 的 diff 长什么样、冲突怎么办

本指南 hero 统计条把 .pen = JSON,可 Git 版本化、可 diff、可合并 立成第二大卖点,但「能 diff」不等于「diff 可读」,「能合并」也不等于「冲突好解决」。这三个问题拆开说清楚。

1. .pen 的 diff 实际长什么样

官方没有公开过完整的真实 .pen 导出文件(格式本身在 《pen.dev 文档中文版 · .pen 文件格式》一节有详细 schema),下面这段 diff 是按该 schema 手工构造的示意结构,不是真实文件导出,用来展示「文本 diff」大致的可读程度——一次按钮位置下移 + 文案改动 + 颜色变量切换:

diff --git a/design/settings.pen b/design/settings.pen
index 8a1f3c2..44e9b7a 100644
--- a/design/settings.pen
+++ b/design/settings.pen
@@ -18,11 +18,11 @@
     {
       "id": "save-button",
       "type": "ref",
       "ref": "primary-button",
-      "x": 24, "y": 480,
+      "x": 24, "y": 512,
       "descendants": {
         "label": {
-          "text": "Save",
-          "fill": "$color.text-secondary"
+          "text": "Save changes",
+          "fill": "$color.text-primary"
         }
       }
     },

结论是「介于两者之间」:比 Figma 的二进制/云端格式确实可读得多——审阅者能看出「按钮往下挪了、文案变了、颜色变量换了」;但比一段代码 diff噪音更大——组件实例的 id/ref/descendants 路径会占掉不少行,读起来更接近 review 一份 package-lock.json 而不是一段函数改动。「PR 里能看懂设计变了什么」成立,但「一眼看懂改得好不好」仍然做不到——这正是下方 高级玩法 · 接入 CI/CD 里「CI 自动出截图」要补的缺口。

2. 两人同时改一个 .pen,冲突怎么解

• 官方原话(乐观的一面):「可分支合并——设计跟着功能分支走,一起合并、一起回滚」(Design as Code);「没有实时协作:目前通过 Git 协作——分支并行、pull → 编辑 → commit → push → PR」(Troubleshooting)。
• 官方原话(矛盾的一面):「官方明确:不要手动编辑 .pen,走编辑器或 MCP 工具」(见下方避坑清单)。
• 缺口:.pen 是单棵 JSON 对象树,一旦两个分支都改了同一个 id 的节点,Git 的三方合并会在 JSON 文本中间插入 <<<<<<</=======/>>>>>>> 冲突标记——这和代码冲突的形态完全一样,但解决它需要手工编辑 JSON 文本,而这恰恰是官方明确劝阻的操作。截至本文核对(2026-07-28),docs.pencil.dev 与 Jerad Bitner、Tao An、Xinran Ma 等三篇被本站引用的社区文章均未提及这个场景的处理办法。

在没有官方指引的情况下,以下是本文作者基于上述两条已发布规则反推出的可行规避思路,不是官方教程:

1. 优先靠流程规避,而不是靠合并技术解决:Troubleshooting 页给的协作方式本质是「分支并行 + PR 评审」,没有说「放心并发改同一文件」。同一个 Frame/页面同一时间只给一个人改,是目前唯一被官方认可的路径。
2. 用 imports 拆分文件,缩小冲突面:.pen 格式支持文档级 imports 字段(键为别名、值为相对路径,见 .pen 文件格式),可以把大设计拆成多个按页面/组件划分的 .pen 文件、在根文件里 import——和代码里拆模块减少合并冲突是同一个思路,只是官方文档没有把这一点明确写成「防冲突手段」,这是本文的推断用法。
3. 真出现冲突标记,别手改 JSON,改「二选一 + 重做」:git checkout --ours/--theirs 整体选一侧,再让对方回到编辑器/MCP 工具里把自己那部分改动重新做一遍——这样冲突解决过程始终没有绕开「只用编辑器或 MCP 工具改 .pen」这条官方红线,代价是重做一遍改动。

3. 变量双向同步跑完,两边各自长什么样

「Create pen.dev variables from my globals.css」执行前后,CSS 和 pen.dev 变量面板的对应关系(命名规则依据官方 Variables 与 .pen 文件格式两篇文档描述整理,非真实截图——官方文档也没有给出这条命令的实际运行截图):

CSS 一侧不会有任何变化——AI 只读取 globals.css,把每条 --自定义属性 映射成 pen.dev 变量面板里的一条新记录(命名把 -- 前缀去掉、连字符按语义拆成点号分段,这是 .pen 格式变量键名惯用的 色板.用途 写法,而不是逐字保留 CSS 变量名)。画布上的元素这时还没有自动引用这些新变量——同步命令只负责「把 CSS 里已有的值搬进变量面板」,要让画布元素用上它们,得再来一句类似「所有按钮改用 $color.primary」的指令,或手动在属性面板里把硬编码值换成变量引用。反向的「Update globals.css with these pen.dev variables」同理:只搬运值,不会自动重构还在用旧硬编码值的 CSS 规则。

实战提示词范例集

以下范例来自社区实测与官方文档,可直接改造使用。经验规律:「页面类型 + 内容清单 + 配色气质」三要素的提示词,一次成型率最高。

整页生成(三要素模板)

DevelopersIO 用该模式实测五种页面全部一次可用,例如:

设计 → 代码(指定技术栈)

代码 → 设计

变量与设计令牌

设计系统一致性

来源:DevelopersIO · 官方 Design ↔ Code · 官方 AI Integration

设计系统工程化

单页生成只是起点;社区里最成熟的打法,是把 pen.dev + Claude Code 当成设计系统的生产与消费流水线。

五阶段方法论(社区 Claude Code Skill)

社区流传较广的 /create-design-system 技能把「从想法到设计系统」拆成五个必须逐一确认的阶段,核心思想是每个阶段边界都停下来给人确认,绝不一口气冲到底:

企业级案例:Lullabot 品牌库

Lullabot 工程师 Jerad Bitner 的做法展示了「库文件」的正确姿势:把整个品牌系统装进一个可导入的设计库——56 个颜色变量、Circular + IBM Plex Mono 的字体令牌、4px 网格的间距阶梯、16 个可复用组件(按钮、卡片、表单输入、导航链接、徽章、标签、引用块)。

• 公司内部工具 OpptyNet 导入它,Upstraker 导入它,下一个新工具还导入它——第二个项目起,视觉语言就不用从零搭。
• 他的原话概括:「有了共享设计库,你不再纠结用哪种蓝,而开始思考界面真正要做什么。」

来源:TobyScr / create-design-system skill · Jerad Bitner: Designing with Pencil and Claude Code · 官方 Design Libraries

高效提示词模式

具体性法则

迭代金字塔(官方推荐节奏)

1. 先框架 — "创建仪表盘布局"
2. 再细化 — "加带导航项的侧边栏"
3. 后打磨 — "导航项加 hover 态"
4. 终收尾 — "间距对齐 8px 网格"

社区共识与此一致:抵制「一个巨型提示词生成完整应用」的诱惑。小块设计 → 生成 → 审查 → 精修 → 下一块,质量远高于一次性梭哈。

上下文注入技巧

• 引用既有资产:"用我们现有的按钮组件"、"遵循变量里的间距阶梯"、"和 Header 组件风格保持一致"——让 AI 复用而不是重造。
• 点名设计系统:"按 Material Design 原则"、"用 shadcn/ui 风格"、"遵循 design-system.pen 里的规范"。
• 画布选区即上下文:在画布上选中的元素会自动进入 AI 上下文;话题切换时点 "New Agent" 清空上下文重开。
• 要求先解释再动手:对大改动,让 AI 先说明打算怎么改,确认后再执行,配合 Claude Code 的计划模式(Plan Mode)效果更佳——计划错了一句话就能纠正,改完了才发现错,代价是几百行 diff。

验证闭环

1. 画布上目视检查;
2. 图层面板核对结构;
3. 让 AI 调 get_screenshot 截图自检复杂布局;
4. 用 get_app_state(旧版工具名 snapshot_layout)排查重叠与错位。

来源:官方 AI Integration / Best Practices · Pencil.dev + Claude Code Workflow · DEV: Claude Code Workflow Best Practices

高级玩法

pen.dev CLI:无头设计与批量生产

# 一句话生成设计文件
pen --out login.pen --prompt "Create a modern login page with email, password, social login"

# 修改既有设计并导出 2 倍图
pen --in dashboard.pen --out dashboard-v2.pen --prompt "Add a sidebar navigation"
pen --in design.pen --export hero.png --export-scale 2

# 批量任务(每个任务独立编辑器实例,顺序执行)
pen --tasks batch.json

# 简单任务换便宜模型,控制成本
pen --out simple.pen --model claude-haiku-4-5 --prompt "Create a simple 404 page"

接入 CI/CD

在组织设置的 Developer Keys 里创建 CLI Key,流水线中即可自动跑设计任务:

export PEN_CLI_KEY=pen_cli_...
export ANTHROPIC_API_KEY=sk-ant-...
pen --out onboarding.pen --prompt "Create a 3-step onboarding flow"

配合 pen interactive 交互 shell,还能在脚本里直接调 MCP 工具做精细操作(execute 建节点 → get_screenshot 出图 → save() 落盘;旧版工具名是 batch_design)。

CI 里跑设计,到底解决什么问题

不是「让 AI 在流水线里自动画设计」这种花活——最有说服力的用途是补上 Workflow D 深挖里提到的那个缺口:.pen 的文本 diff 能看出「改了什么节点」,但看不出「改完长什么样、好不好看」。让 CI 在每个改动 .pen 文件的 PR 里自动渲染一版截图,评审者不用装 pen.dev、不用切出 IDE,PR 页面里直接肉眼判断这版改动是否可接受——这是「设计变更能像代码一样被 review」这句话里,文本 diff 单独做不到、必须靠出图来补的那一半。

# .github/workflows/design.yml
name: pen.dev 设计预览

on:
  pull_request:
    paths:
      - '**/*.pen'

jobs:
  design-preview:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: 检出代码(需要能 diff 出改动的 .pen 文件)
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # CLI 要求 Node.js 18+,见官方 Installation
      - name: 安装 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: 安装 pen.dev CLI
        run: npm install -g @pen.dev/cli

      - name: 导出本次 PR 改动的 .pen 文件为 PNG
        env:
          PEN_CLI_KEY: ${{ secrets.PEN_CLI_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          mkdir -p design-previews
          git fetch origin "${{ github.base_ref }}"
          for f in $(git diff --name-only "origin/${{ github.base_ref }}"...HEAD -- '*.pen'); do
            [ -f "$f" ] || continue
            name=$(echo "$f" | tr '/' '_' | sed 's/\.pen$//')
            pen --in "$f" --export "design-previews/${name}.png" --export-scale 2
          done

      - name: 上传设计预览 artifact
        uses: actions/upload-artifact@v4
        with:
          name: design-previews
          path: design-previews/
          if-no-files-found: ignore

      - name: 在 PR 里留言,附本次运行的预览链接
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `本次 PR 改动的 .pen 设计已渲染,预览图见[本次 workflow 运行的 Artifacts](${runUrl})。`
            });

要点对照官方参数:pen --in <path> --export <path> 不加 --out 也合法(--out 仅在不使用 --export 时必填);--export-scale 2 出 2 倍图便于在小屏幕上看清细节;PEN_CLI_KEY 走 CI Key 而不是交互登录,优先于本机已存的会话令牌,这也是它能在无人值守的 runner 上工作的原因。

Script 节点:数据驱动的设计

对图表、网格、纹样这类「手搭很痛苦」的结构,用 Script 节点让代码生成图层:声明 @input 参数即可在属性面板获得可视化旋钮;把输入绑到变量(如 $primary)还能自动响应主题切换。官方示例仓库 highagency/pencil-scripts 提供现成的图表/网格/纹样脚本。

与 Claude Code 生态组合

• Skills(技能):把重复流程固化成技能,如社区的 /create-design-system(五阶段设计系统)和 pencil-to-code(.pen → React 组件的规范化转换)。
• Plan Mode:大功能先规划后动手;规划阶段只读不写,方向错了一句话就能掉头。
• 设计令牌文件:让 Claude Code 维护一份 design-tokens.ts / design-tokens.css,作为设计与代码共同的单一事实源,项目演进时一处更新、两边生效。
• 版本控制兜底:代理式修改多文件时偶尔会弄坏东西——频繁 commit 给自己留检查点;.pen 的撤销/重做有限,Git 就是你的后悔药。

来源:官方 pen.dev CLI · 官方 Code on Canvas · Pencil.dev + Claude Code Workflow

避坑清单

方法论层面

操作层面

认知层面

• AI 产出质量 ∝ 你给的上下文质量——这是全部实践浓缩成的一句话。模糊提示 + 无上下文 = 通用模板;具体提示 + 画布/风格/仓库上下文 = 属于你产品的代码。
• pen.dev 不是 Figma 替代品(至少现在不是):功能没有 Figma 全,强项是内部工具、快速原型与设计-代码一体化场景;重协作、重高保真交付的团队仍需权衡。
• 工具迭代快:菜单位置、命令语法都可能变;掌握原理(上下文经由结构化协议流向代码代理)比记住界面更长久。

来源:Jerad Bitner · Best Practices and Pro Tips · 官方 Troubleshooting

真实案例研究

案例一:OpptyNet — 七个版本,三小时,一条对话线

Lullabot 内部的政府招标(RFP)筛选工具,全程用 pen.dev + Claude Code 对话式设计:

以上图片来源:Jerad Bitner 博客

作者的三点收获:① 方法论先于像素——缺筛选器这种坑,七轮像素迭代也发现不了;② 对话式迭代快得惊人——「统计压成一行」一句话就是一轮;③ 设计与代码同环境,从一开始就共享上下文。

案例二:Upstraker — 库复用的复利

第二个内部工具直接导入第一个项目沉淀的 Lullabot 设计库(56 色彩变量 + 16 组件),概念成型明显更快;亮暗双主题同出于一套库令牌。设计库的价值在第二个项目开始兑现,并随项目数量复利增长。

图片来源:Jerad Bitner 博客

案例三:多人并行改同一设计——这套流程在这里会更慢

前两个案例都是「一个人 + 一条对话线」的场景,这也是 pen.dev + Claude Code 打法目前最擅长的形态。反过来,多人需要同时对着同一屏设计动手的场景,是它相对 Figma 更慢的地方——这不是一次具体项目翻车的复盘故事(没找到这样的公开案例),而是一条能在官方文档里找到出处、并被独立第三方评测反复印证的能力边界。

• 官方自己的定性:Troubleshooting 页原话——「没有实时协作:目前通过 Git 协作——分支并行、pull → 编辑 → commit → push → PR」。这不是「暂时的 bug」,而是架构选择:.pen 的协作模型是「分支 + PR」,不是「光标可见的多人同屏」。
• 独立评测的印证:Tao An 在复盘 pen.dev 的 Git-first 主张时写道,「there's no real-time collaboration, which is a notable gap for teams used to Figma's multiplayer editing」,并把两者的取舍概括为「Figma optimizes for designers collaborating on design. Pencil optimizes for design integrating with development」——言下之意是多人协同设计的场景,pen.dev 天然不是主场。
• 叠加效应:Xinran Ma 2026-04-19 的实测还提到一个放大因素——暂无自动保存,「it's relatively common to hit a crash」且「if it goes down mid-session, you lose work with no recovery option」。在单人场景下这只是「勤按 Cmd/Ctrl+S」的习惯问题;但换到多人并行、需要频繁交接同一文件的场景,一次意外崩溃加上前一节讨论过的「.pen 冲突官方没有给出解法」,代价会被放大。

来源:官方 Troubleshooting · Tao An: Design Files Don't Belong in Git. Pencil.dev Says We're All Wrong. · Xinran Ma: Exploring Pencil.dev — Walkthrough and Impressions(2026-04-19)

资源与来源索引

官方资源

本文引用的社区实践(按主题)