pencil on claude：让设计师和程序员少吵架的一种可能

1. 设计稿到代码之间到底卡在哪一步如果你同时待过设计评审和代码评审大概率见过同一个页面被两拨人来回拉扯设计师说“这个间距不对视觉重心偏了”程序员说“稿子里没标我按 8px 栅格猜的”。问题往往不在谁不专业而在于设计意图和代码实现之间隔着一层“人工翻译”——Figma 里是图层、约束、自动布局代码里是 flex、grid、token中间靠截图、标注、口头描述来传递信息每过一手就掉一层。pencil on claude 想解决的正是这个断层。pencil 可以理解成一个“给 AI 代理用的无限设计画布”它把设计文件直接放进代码库让 claude code、opencode、Cursor 这类编码代理能读写同一份设计上下文。你不再需要“先在 Figma 画完再导出标注再让 AI 照着写”而是让设计稿和代码骨架在同一个工作区里互相引用。适合谁适合那些已经在用 claude code 写前端、但每次改 UI 都要和设计师对半天的开发者也适合想把自己设计意图直接变成可讨论代码骨架的设计师。我试过把这套流程跑通一次最大的感受是吵架点被前移了。以前吵“你到底想要什么效果”现在吵“这个 token 该不该抽出来”——后者至少是可验证、可回滚的。2. 前置准备TaoToken 与 pencil 的接入位置在讲配置之前先把“模型从哪来”这件事说清楚。claude code 本身是一个编码代理它需要调用模型能力pencil 则是挂在代理旁边的设计画布扩展。你要做的是让 claude code 能稳定拿到模型响应同时让 pencil 的文件被代理识别。TaoToken 在这里扮演的是模型接入层。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。你需要先去控制台生成一个 API Key然后把它写进 claude code 的配置里。注意TaoToken 不是编辑器也不替代 claude code它只负责把请求转发到模型侧真正的编码和画布交互还是在你的 IDE 里完成。pencil 的安装方式取决于你用的 IDE。以 VS Code 系为例在扩展市场搜索 “Pencil Dev”安装后用邮箱登录登录后你会看到 pencil 文件通常是.pen后缀出现在工作区。pencil 支持多种 UI 包比如 Lunaris、Halo 设计系统、Swiss Clean 样式这些包决定了你画布上组件的默认视觉语言。装好之后claude code 就能通过文件引用和 pencil 画布协作。这里有个容易忽略的点pencil 的画布是“代理可读”的不是纯图片。也就是说claude code 读到的不是一张截图而是带图层、样式、布局信息的结构化数据。这是它能生成“不像 AI 粗糙作品”的前提。3. 可复制的 settings.json 配置片段下面这段配置是我实测能跑通的 claude code settings.json 片段。你需要把YOUR_TAOTOKEN_API_KEY替换成自己在控制台生成的 Key。如果你用的是 opencode 或 Cursor字段名可能略有差异但核心是baseURL和apiKey两项。{ claude: { apiKey: YOUR_TAOTOKEN_API_KEY, baseURL: https://taotoken.net/api, model: claude-sonnet-4-20250514, maxTokens: 8192, temperature: 0.2 }, pencil: { enabled: true, workspace: ./design, defaultPackage: Lunaris, stylePreset: Swiss Clean, syncToCode: true }, projectRules: { framework: next, styling: tailwind, tokenFile: ./design/tokens.json } }几个参数说明一下。baseURL指向 TaoToken 的 API 地址不要写成官网首页。temperature设 0.2 是因为设计到代码的转换需要稳定输出太高会随机改布局。pencil.workspace指向你放.pen文件的目录claude code 会从这里读取设计上下文。syncToCode打开后画布上的改动会触发代理重新生成对应组件骨架。如果你用的是 Cursor可以在 Cursor 的模型设置里把 OpenAI 兼容的 base URL 填成https://taotoken.net/apiKey 填同一把。opencode 则在它的 config 文件里对应providers字段。配置完记得重启 IDE否则扩展可能读不到新的环境变量。注意不要把 API Key 提交到公开仓库。建议用环境变量TAOTOKEN_API_KEY注入settings.json 里写apiKey: ${TAOTOKEN_API_KEY}。4. 端到端验证从一句提示到可讨论的代码骨架配置写完后做一次最小验证。打开你的 IDE确保 pencil 画布已经加载了一个.pen文件然后在 claude code 的对话窗口里输入这样一段提示参考当前 pencil 画布中的 Lunaris UI 包和 Swiss Clean 样式 创建一个 SaaS 着陆页骨架包含顶部导航、hero 区、三个功能卡片、 底部 CTA。使用 Next.js Tailwind间距用 8px 栅格 颜色引用 design/tokens.json 中的 token。发送后claude code 会读取 pencil 画布的结构化数据结合你 settings.json 里的projectRules生成对应的组件文件。实测下来一次运行通常能产出app/page.tsx、components/Hero.tsx、components/FeatureCard.tsx这几个文件Tailwind 类名里会带上gap-2、p-4这类栅格值颜色则是bg-[var(--color-primary)]这种 token 引用。验证成功的标志有三个第一生成的组件能直接npm run dev跑起来不报未定义变量第二画布上改一个卡片的圆角重新触发代理对应组件的rounded-*类会跟着变第三设计师能在画布上直接拖动图层调整对齐代理读到的布局信息同步更新。如果这三点都成立说明设计意图到代码骨架的链路是通的。这时候再和设计师讨论话题就从“你想要的间距是多少”变成了“这个 token 要不要单独抽出来”。前者靠猜后者靠看代码。5. 本篇常见错排查报错一401 Unauthorized或invalid api key。先检查 settings.json 里的 Key 有没有多余空格再确认baseURL是不是写成了https://taotoken.net/api而不是官网首页。如果用的是环境变量注入确认 IDE 重启后环境变量已加载。可以到控制台的 API Keys 页面重新生成一把排除 Key 被误删的情况。报错二pencil 画布加载了但 claude code 读不到.pen文件。检查pencil.workspace路径是否相对于项目根目录。如果.pen文件在./design下配置就写./design不要写绝对路径。另外确认 pencil 扩展已登录未登录状态下画布是只读的代理拿不到完整结构。报错三生成的代码里 Tailwind 类名全是硬编码颜色没走 token。这通常是tokenFile路径不对或者tokens.json格式不符合预期。token 文件建议用扁平结构比如{color-primary: #3b82f6, spacing-base: 8px}代理解析起来更稳。如果还是不行在提示里显式写“颜色必须引用 tokens.json 中的 key”强制它走 token。报错四画布改动后代理没重新生成。先确认syncToCode是true然后看 IDE 的输出面板里 pencil 扩展有没有报错。有些情况下需要手动触发一次“重新读取工作区”或者把.pen文件保存一下再发提示。如果用的是 Cursor注意它的文件监听有时会延迟等两秒再操作。报错五模型响应截断组件只生成了一半。把maxTokens调大比如从 8192 提到 16384。设计到代码的转换输出比较长尤其是带完整 Tailwind 类名的时候。如果还是截断把任务拆小先只生成 hero 区再生成卡片区分步验证。6. 把吵架点前移到配置和输出上这套流程跑顺之后你会发现设计和开发之间的交接环节被压缩了。设计师在 pencil 画布上调整代理读到的就是最新结构程序员在代码里改 token画布上的样式引用也会跟着变。双方讨论的对象从“感觉”变成了具体的配置项和生成结果。如果你主要是在排障和接入阶段建议先把 API Keys 和接入文档过一遍确认 base URL 和 Key 的写法没问题API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先验证模型对话效果可以直接用模型对话页面试一句提示https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你打算长期用 claude code 做编码和 Agent 任务Coding Plan 会更适合https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实用技巧把design/tokens.json纳入版本管理每次设计评审前先 diff 这个文件。token 变了代码里的引用会自动跟着变评审时直接看 diff 就能判断影响范围。这比截图对比靠谱得多。