Pencil Design — .pen 文件设计与代码导出

核心知识

Pencil 是装在 Antigravity IDE 上的设计扩展。 .pen 文件是加密格式，只能通过 Pencil MCP 工具读写，Read/Grep/cat 无法解析。

配置要求：MCP 配置必须加 --app antigravity（不是默认 IDE）。

SOP 位置

feat-lifecycle → Design Gate → **pencil-design** → writing-plans → worktree → tdd

pencil-design 在 spec 确认后、写代码前。先把 UX 做对，再动手写代码。

可观测性 / 状态 / 失败相关 UI 必读：动手画之前先过 Design Gate 的 现场可感知性自检（cat-cafe-skills/refs/in-context-observability-checklist.md）。Cat Café 的可观测性哲学是"明厨亮灶"——in-context 富块 + entity 自带状态点优先于 dashboard。否则容易画成上个世纪的 stats card 被打回（F174 D2b 教训）。

🔴 风格一致性门禁（Style Consistency Gate）

这是最重要的规则。 在创建任何新设计之前，必须完成以下步骤：

Step 1: 分析现有 UI

如果要设计的功能是已有产品的扩展（如给 Mission Hub 加新 Tab）：

1. 截图现有 UI — 用 Read 工具查看产品截图，或在浏览器中截图
2. 提取风格特征 — 记录以下 token：
   • 配色方案（背景色、主色、强调色）
   • 布局模式（列表/卡片/详情面板、Tab 结构）
   • 间距和圆角
   • 字体层级
3. 写入设计约束 — 在 batch_design 前明确："延续 X 风格"

Step 2: 判断设计类型

Step 3: 风格验证

设计完成后，get_screenshot 截图，然后和现有 UI 截图并排对比：

• 配色一致？
• 布局语言一致（Tab/列表/详情面板）？
• 不会让用户觉得"换了个产品"？

踩坑教训 (F076)：给 Mission Hub 做面板时用了深色 command-center 风格，和现有暖色调 Mission Hub 完全不搭，operator experience"不能说一模一样，只能说毫不相关"。被否决后全部重做。

两种模式

Mode A：Design — 创建/编辑 .pen 文件

用 Pencil MCP 工具操作设计画布：

关键限制：

• batch_design 每次最多 25 ops，超出必须分批调用
• Binding（绑定引用）不能跨 batch_design 调用复用
• MCP 配置改动需等下次调用才生效（无头模式）

🔴 .pen 文件管理规则：

• 每个 feat 一个 .pen 文件 — 用 open_document("new") 新建，不要在其他 feat 的 .pen 文件上修改
• 不能修改其他猫/feat 的设计稿 — 只读参考可以（batch_get + get_screenshot），但不要 batch_design/Update/Delete 别人的节点
• 保存需要operator — open_document("new") 创建的文件不落盘，猫猫无法自行保存。设计完成后：
  1. 告诉operator完整保存路径：{项目根目录}/designs/{文件名}.pen
  2. 路径用 git rev-parse --show-toplevel 动态获取项目根目录，不要硬编码绝对路径
  3. 文件命名规范：{feat-id}-{描述}.pen（如 F096-interactive-rich-blocks-ux.pen）
  4. operator保存后，需要 commit + push 到 main（设计稿是共享状态文件）
• 保存后验证 — operator确认保存后，用 open_document("{完整路径}") 打开验证内容完整

Mode B：Code Export — 从 .pen 设计稿生成代码

1. 用 get_editor_state + batch_get 读取设计属性
2. 用 get_style_guide 获取设计 token（颜色、字体、间距）
3. 生成 React + Tailwind 组件代码
4. 截图对比：get_screenshot → 目视验证还原度

工作流

设计任务
  ↓
现有 UI 截图分析（扩展型设计必须！）
  ↓
get_editor_state（了解画布现状）
  ↓
get_style_guide_tags + get_style_guide（仅全新设计）
  ↓
Mode A: batch_design（分批，≤25 ops/次）
Mode B: batch_get → 生成 React/Tailwind
  ↓
get_screenshot（验证）
  ↓
和现有 UI 对比 → 风格一致？
  ├─ 不一致 → 修正配色/布局后重新 batch_design
  └─ 一致 → 请operator保存
       ↓
       告诉operator完整路径（git rev-parse --show-toplevel + /designs/Fxxx-xxx.pen）
       operator Cmd+S 保存 → commit push 到 main
       ↓
       operator/设计负责人 review 设计截图
       ├─ 否决 → 记录反馈 → 回到 batch_design 修正
       └─ 通过 → 如需实现 → worktree → tdd

Common Mistakes

和其他 Skill 的区别

• tdd / worktree：代码实现阶段 — pencil-design 是设计阶段，先于代码
• quality-gate：检查代码合规 — pencil-design 输出的是设计文件或组件代码

下一步

• Mode A 完成设计 → 告知operator完整保存路径 → operator Cmd+S 保存 + commit push → 设计 review → 如需实现 → worktree → tdd
• Mode B 导出代码 → 进入 tdd 编写测试 + 集成