# Pencil Design

> 使用 Pencil MCP 创建/编辑 .pen 设计文件，或导出为 React 代码。 Use when: 设计 UI、编辑 .pen 文件、从设计稿生成代码。 Not for: 纯代码实现（无设计稿）、非 Pencil 工具的设计工作。 Output: .pen 设计文件 或 React/Tailwind 组件代码。

- Skill: `zts212653/pencil-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zts212653/pencil-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zts212653/pencil-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: zts212653 (https://skillmd.com/u/zts212653)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zts212653/pencil-design

---


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

## 核心知识

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

配置要求：当前 Antigravity IDE 的 MCP 参数是 `--app antigravity_ide`；
VS Code 是 `--app visual_studio_code`。不要沿用旧的 `antigravity` / `vscode`
socket 标识；Clowder AI 的 resolver 会按扩展安装目录自动生成正确参数。

## SOP 位置

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

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

**可观测性 / 状态 / 失败相关 UI 必读**：动手画之前先过 Design Gate 的 **现场可感知性自检**（`../.cat-cafe-shared-refs/in-context-observability-checklist.md`）。Clowder AI 的可观测性哲学是"明厨亮灶"——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: 判断设计类型

| 类型 | 做法 | 例子 |
|------|------|------|
| **扩展现有产品** | 必须复用现有风格，作为现有界面的自然延伸 | 给 Mission Hub 加 Tab |
| **全新独立产品** | 可以用 `get_style_guide_tags` + `get_style_guide` 探索新风格 | 新的独立工具 |
| **重新设计** | 先对比旧设计和新方向，operator确认后再动手 | 产品改版 |

### Step 3: 风格验证

设计完成后，`get_screenshot` 截图，然后**和现有 UI 截图并排对比**：
- 配色一致？
- 布局语言一致（Tab/列表/详情面板）？
- 不会让用户觉得"换了个产品"？

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

## 两种模式

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

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

| 工具 | 用途 |
|------|------|
| `get_editor_state` | 查看当前画布状态（首先调用） |
| `open_document` | 打开已有 .pen 文件（`"new"` 不落盘，需用户手动 Cmd+S） |
| `batch_get` | 批量读取 layer/component 属性 |
| `batch_design` | 批量创建/修改设计元素（**每次最多 25 ops**） |
| `get_screenshot` | 获取当前画布截图（验证设计结果） |
| `get_guidelines` | 获取布局参考线 |
| `get_style_guide` | 获取项目色系/字体规范 |

**关键限制**：
- `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

| 错误 | 后果 | 修复 |
|------|------|------|
| **🔴 不看现有 UI 就设计** | 风格断裂，被否决重做 | 先截图分析现有风格 |
| **🔴 做独立 dashboard 而不是集成扩展** | 和产品割裂 | 问清楚是"扩展"还是"全新" |
| 用 Read/Grep 读 .pen 文件 | 乱码，无法解析 | 只用 Pencil MCP 工具 |
| batch_design 超过 25 ops | 工具报错 | 拆成多次调用 |
| MCP 使用旧 `--app antigravity` / `vscode` 标识 | 找得到扩展却连不上当前 IDE socket | 让 resolver 生成 `antigravity_ide` / `visual_studio_code`，新 invocation 生效 |
| 跨调用复用 binding | binding 失效 | 每次调用重新声明 |
| `open_document("new")` 后忘记保存 | 内容丢失 | 告诉operator完整路径，请求 Cmd+S |
| `get_style_guide` 的 tags 传字符串 | 参数格式错误 | 必须传 JSON 数组 |
| **🔴 在别人的 .pen 上修改** | 覆盖其他猫的设计 | 永远 `open_document("new")` 新建 |
| **🔴 保存路径硬编码** | 项目搬家后路径失效 | 用 `git rev-parse --show-toplevel` |
| **🔴 保存后不 commit push** | 其他猫看不到设计稿 | 请operator保存后 commit push 到 main |

## 和其他 Skill 的区别

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

## 下一步

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