让 AI 在 Penpot 里画一个移动端登录页，最常见的结局是：颜色随机挑、间距靠蒙、画完它自己也不知道对不对。问题不在模型不会调 API，在于从来没人告诉它什么叫”对”。设计决策里那些隐性的判断力，才是人和代码猴子之间的分水岭。
penpot-uiux-design 这个 Skill 给的解法很直接。它不是又一份 MCP 工具清单，而是一份把”一个合格设计师进场前该做的动作”编码成硬流程的约束文档。它挂在 Smithery 上，ID 是 github/penpot-uiux-design，目标读者是已经接好 Penpot MCP 的 AI 客户端。
抓它最核心的架构思想，一句话就能说清：先探查再创建，先问设计系统再落像素，画完必须自己看一眼。这三拍顺序错一处，输出质量就塌一半。它卖的不是创意，是纪律。
但有个前提必须先摆出来。它依赖的 penpot/penpot-mcp 仓库在 2026 年 2 月 3 日已经归档，代码整体迁进了 Penpot 主仓库的 develop/mcp 目录，连插件 UI 都在归档后加了弃用提示。这件事不只是历史 footnote，它会直接影响你现在怎么装、装到的是不是冻结版，后面专门展开。
架构解析
工具面铺开看只有 4 个，文档也是一行一个这么列的，很容易让人以为它们分量相当：
-
execute_code：在插件上下文执行任意 JavaScript，直接调 Plugin API -
export_shape：把 shape 导出成 PNG 或 SVG，让模型能”看见”结果 -
import_image：把图标、照片、logo 等素材导入设计 -
penpot_api_info：按需取回 Penpot 的 API 文档，让 agent 现查现用
读完整份 SKILL.md 我才反应过来，execute_code 一个就够干完其他三个的活。它在 Penpot 插件上下文里执行任意 JavaScript，直接调 Plugin API，把创建修改查询全包了。剩下三个更像配套件：import_image 补素材缺口，penpot_api_info 让 agent 能现查文档，export_shape 是这个设计里最关键也最容易被低估的一环。换句话说，真正稀缺的不是工具数量，而是”先探查再创建、画完自验”这套顺序纪律，以及文档替你踩过的那些坑。这里有个判断值得记下来：execute_code 是发动机，那三个配套件只是油箱和仪表盘。
说它关键，是因为 export_shape 把渲染结果导成 PNG 或 SVG 回灌给模型。等于给一个盲画的 agent 装回了眼睛。没有这一步，前面所有创建动作都是无反馈的开环，模型永远在猜自己到底画成了什么样。
链路拓扑长这样，外层的客户端和内层的插件之间隔了一道桥。
这个三段式桥接的理由很明确。MCP Server 自己不直接碰设计文件，一切的增删改都经插件之手。好处是权限边界清清楚楚，代价是必须有人肉在浏览器里点一次”Connect”，而且插件 UI 全程不能关，一关连接就断。4403 那个 REPL 端口不进生产链路，是留给开发者手动发指令调通的。配置写进 VS Code 的 settings.json 即可。
{
"mcp": {
"servers": {
"penpot": {
"url": "http://localhost:4401/sse"
}
}
}
}
工作流分析
六步工作流串起来是：先确认设计系统，再用 shapeStructure 看层级，用 findShapes 定位元素，然后创建或修改，套 addFlexLayout 做响应式，最后 export_shape 自验。这条链最反直觉的地方在第一步。
第一步不是动手创建，而是先开口问。文档要求 agent 先问用户有没有 design system，没有的话得主动去当前文件里”挖”：扫所有 shape 的 fills 拿颜色集合，扫 text 节点拿字号字重，查 library.local.components 拿组件数量。这段 JS 值得单独贴出来看。
const allShapes = penpotUtils.findShapes(() => true, penpot.root);
const colors = new Set();
allShapes.forEach(s => {
if (s.fills) s.fills.forEach(f => colors.add(f.fillColor));
});
const textStyles = allShapes
.filter(s => s.type === 'text')
.map(s => ({ fontSize: s.fontSize, fontWeight: s.fontWeight }));
const componentCount = penpot.library.local.components.length;
这一步的意义比它看起来大得多。多数 AI 生成设计的翻车点从来不是技法，而是它根本不知道你团队已经攒了一套东西。强制先做发现，等于把默认行为从”从零发明”改成”先对齐再增量”，出来的东西才接得住现有体系。
到了创建阶段，文档给的 5 条 API gotchas 才是真正值钱的部分。这些不是 API 文档能推出来的，全是撞过墙才有的经验。
- width / height 是只读属性，改尺寸只能用 shape.resize(w, h)
- parentX / parentY 只读，移动位置要用 penpotUtils.setParentXY
- z 轴排序用 insertChild(index, shape)，不是 appendChild
- flex 子节点数组在 dir 为 column 或 row 时顺序是反的
- text.resize 之后必须把 growType 重置回 auto-width 或 auto-height
还有个容易被忽略的工程细节：新建 board 之前必须先扫一遍已有 board，算出下一个 x 坐标，否则新画布会叠在旧的上面。相关流程留 100px 间距，不同流程要 200px 以上。整条流程走下来是这样。
使用场景
最值得用的场景一，是已经有设计系统的团队把 AI 接进来。这种情况下 agent 只是在既有 token 上做排布，翻车概率最低，产出也最贴团队规范。它在这里更像一个听话的执行层，而不是创意来源。
从零起步的场景二，要靠文档给的默认 token 表兜底。这张表是它给”无设计系统”用户的最大善意，几个维度都给了明确取值：
-
间距：走 8px 基线，从 4 到 48px 六档递增 -
字号：12 标题、16 正文、20 以上分级、48 以上展示 -
颜色：只给成功、警告、错误三档语义色，主色留给品牌
它甚至把移动端 375×812 与桌面端 1440×900 两套画布骨架，连同状态栏、导航、底栏的像素分配都标了出来，agent 不用自己拍脑袋定布局。
| 类别 | 取值 | 用途 |
|---|---|---|
| 间距 | 4 / 8 / 16 / 24 / 32 / 48px | 紧凑到页面级递增 |
| 字号 | 12 标题 16 正文 20-28 各级 48-64 展示 | 单屏信息层级 |
| 主色 | 品牌色（用户指定） | CTA 与重点 |
| 语义色 | 绿 #22C55E / 橙 #F59E0B / 红 #EF4444 | 成功 / 警告 / 错误 |
一轮完整交互的调用链长这样，从客户端发指令到插件回灌截图，中间跨了三次协议转换。
边界条件得说清楚。它只覆盖”在 Penpot 里把界面画出来”这一段，不做用户研究，替代不了可用性测试。产物是可编辑的矢量结构，不是直接能上线的代码，虽然 penpot.generateStyle 确实能把设计导成 CSS。
顺带把文档里的验收清单也值得提一句，它给组件和无障碍都列了硬指标，agent 照着做就能把可用性下限拉起来：
-
按钮：最小触摸目标 44×44px，与背景对比 3:1 以上，必须带 hover / active / disabled / loading 四态 -
表单：标签永远在输入框上方，必填项要有标记 -
导航：同级项控制在 7±2 个 -
无障碍：正文对比度 4.5:1，大字号 3:1，焦点状态可见，图片有替代文本
这些不是创意，是 agent 照着做就能把可用性下限拉起来的硬指标。
penpot.generateStyle(selection, { type: 'css', includeChildren: true });
洞察与反思
整份文档里最精彩的部分，其实不是那段设计原则。Golden Rules 是一组常识，视觉层级五要素也一样：
-
尺寸：越大越重要 -
对比：高对比更吸睛 -
位置：左上角最先被看到 -
留白：孤立即强调 -
字重：加粗即突出
它们的真正价值在于给 agent 一个可执行的优先级，风格冲突时知道该让谁。
真正稀缺的是那些”踩坑记录”。width/height 只读、flex 子节点数组顺序反转、text.resize 之后要重置 growType，这几条没有一条能从语法规范里推出来，只能靠人实打实地撞过。Skill 把这些写进来，等于把前人的学费变成了后人的默认值。
最现实的一个局限，还是归档。文档里那句 git clone 指向的是只读归档仓库，插件 UI 在 2026 年 2 月 18 日就加了弃用警告。它能装能跑，但你拿到的是冻结版本，后续修复和远程多用户模式的新代码都在 penpot/penpot 的 develop/mcp 里，不在你 clone 下来的这棵树上。
另外两个局限更隐蔽。四份 reference 文件全部托管在 Smithery 站点路径下，不在仓库里：
-
setup-troubleshooting：安装与排错 -
component-patterns：按钮、表单、导航规范 -
accessibility：对比度与触摸目标 -
platform-guidelines：各端尺寸规范
Skill 本身不是自包含的，站点改路径或下线引用就断。默认色板也只给了语义色 hex，主色和辅色只写”品牌色”，对没有设计系统的用户其实留了个需要自己填的坑。
资源地址
| 资源 | 链接 |
|---|---|
| Smithery 技能页 | https://smithery.ai/skills/github/penpot-uiux-design |
| Penpot MCP 仓库（已归档） | https://github.com/penpot/penpot-mcp |
| Penpot 主仓库 MCP 目录 | https://github.com/penpot/penpot/tree/develop/mcp |
| Penpot 官网 | https://penpot.app |
| Penpot 插件 API 文档 | https://help.penpot.app/technical-guide/ |
总结
penpot-uiux-design 抓的痛点很准：AI 不缺画界面的能力，缺的是知道”什么算画对了”的判断力。它把这种判断力拆成了前置提问、先探查后创建、画完自验三段纪律，塞进了 MCP 工具链的调用顺序里。对比那些只甩给你一份 API 文档的教程，它的差别不在知识量，在于把知识变成了 agent 绕不过去的顺序。
它不适合当成设计思想课来读。Golden Rules 那段是给 agent 的排序提示，不是给人的新知。真正该被工程团队盯住的，是那 5 条 API gotchas 和 board 定位算法，那是这种 Skill 拉开差距的地方，也是市面上多数”教 AI 用工具”的文档懒得写的部分。你完全可以照着它的骨架，把 token 和组件规范换成自己团队的真实东西，一份内部变体很快就能落地。
最后留个判断：归档这件事决定了它的定位。短期它依然可用，长期你得把安装源切到 Penpot 主仓库的 develop/mcp，否则停在一个不再更新的版本上。把它当一份”设计约束清单”用最划算，别把它当会自我演进的活文档，那是它现在给不了的东西。