penpot-bridge

Penpot 设计↔代码桥 (penpot-bridge)

能力边界

• 能做: 读 Penpot 组件结构/样式/Token 实值；Token 双向同步（ui-spec ↔ Penpot ↔ tokens.css）；从 Penpot 设计生成组件代码骨架；设计↔代码视觉一致性校验
• 不做: 需求/架构/页面信息设计（由 ui-design 负责）；业务逻辑/状态管理/API 对接（由 TDD GREEN 负责）；修改 ui-spec 语义契约

权威划分（语义 vs 视觉实值）见 ui-spec 模板「权威源约定」。

前置条件（所有操作共用）

• {INSTRUCTION_FILE} 设计工具 字段为 penpot
• Penpot MCP 可用（见 §Penpot MCP 接入）；不可用时返回 blocked，不静默 success

输入规范

• read: UC-{NNN} 或 Penpot 组件名
• sync: ui-spec#§1 设计系统 Token + sync-direction ∈ {emit, mirror, ingest}
• generate: ui-spec#§2 UC-{NNN}（Props/变体/交互——语义）+ arch#§1.4 技术栈 + Penpot 组件设计数据（视觉，经 read）
• verify: Penpot 组件设计数据（视觉权威源，经 read）+ 已实现组件代码路径 + ui-spec#§2 UC-{NNN}（语义参照）

输出规范

• read: 组件层级结构 / CSS 属性 / Token 实值 + 组件导出图像（供其他操作复用）
• sync: src/styles/tokens.css（W3C Design Tokens 格式）+ 同步差异报告
• generate: 组件骨架文件（按 arch 技术栈）+ 样式文件（引 tokens.css 变量）
• verify: 设计一致性审查报告 docs/reviews/design/DESIGN-REVIEW-{component_id}-r{N}.md（差异列表 + 修复建议）

Penpot MCP 接入

具体 MCP 工具名以平台 MCP 配置为准（Claude: .mcp.json / .claude/settings.json；Cursor: .cursor/mcp.json；OpenCode: opencode.json），运行时按可用工具列表自动发现。典型操作：读项目信息、读组件结构/样式/SVG、读写设计 Token、导出组件图像（export_shape）。工具列表中无 Penpot 工具时先 cataforge penpot ensure（若未部署则 cataforge penpot deploy），仍不可用返回 blocked。

Plugin API 已知限制

程序化操作 Penpot 时以下限制不可绕过：

1. 跨页移动/克隆无效 — appendChild / insertChild 跨页静默 no-op（不抛错、返回成功但 shape 仍在原页），clone() 对非激活页 shape 返回 null，parent 只读；已有 board 无法编程搬到另一页，只能人工在 UI 剪切粘贴
2. shape 变更仅对激活页生效 — 对非当前激活页 board 的属性赋值静默 no-op；页面切换跨执行异步（同一次执行内 currentPage 不切换），程序化建 board / 排版必须「openPage 目标页 → 下一次执行再变更」两段式
3. 无删页 API — 空页/误建页无法编程删除，仅能人工在 UI 删或改名复用；建页前先确定页数清单，宁可复用/回收，不误建

Penpot 文件组织约定（一规格一页）

design_tool=penpot 时视觉稿 authoring 按 ui-spec 结构一规格一页建页：设计系统 / 各页面规格 P-NNN / 组件库分别落独立 Penpot 页面，board 创作期即落对页。Plugin API 无法事后无损重组（§Plugin API 已知限制），页面骨架必须在创作期先建好；退化路径（generateMarkup → SVG 重建）丢失 flex 布局、设计 Token、组件实例链接与文本可编辑性，不可作为重组手段。

操作指令

read

读 Penpot 设计数据，供 sync/generate/verify 复用或独立做视觉 grounding。

1. 经 MCP 读取组件层级结构（容器/子元素/文本/图标）
2. 提取 CSS 属性（尺寸/颜色/字体/间距/边框）与 Token 实值
3. 映射到 tokens.css 设计变量（优先变量而非硬编码值）
4. 经 MCP export_shape 导出目标组件图像，供调用方做视觉自检（设计决策 / 还原度核对）