aile-pencil-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Aile：Pencil 设计（aile-pencil-design）

Aile: Pencil Design (aile-pencil-design)

概述

Overview

当 Story 涉及 UI/交互变更时，本技能用于阶段 2 产出可审查、可执行、可回溯的设计产物：

```
docs/plans/{Story-Key}/design.pen
```
（推荐）
在
```
docs/plans/{Story-Key}/analysis.md
```
回填 UI 设计章节与证据
若不产出
```
.pen
```
，必须明确写出“本 Story 无 UI 设计”及原因

本技能采用 MCP-first 方式，核心目标是把“设计描述”升级为“设计执行规范 + 证据化门禁”。

When a Story involves UI/interaction changes, this skill is used in Phase 2 to produce reviewable, executable, and traceable design deliverables:

```
docs/plans/{Story-Key}/design.pen
```
(recommended)
Backfill the UI design section and evidence in
```
docs/plans/{Story-Key}/analysis.md
```
If no
```
.pen
```
is produced, you must clearly state "No UI design for this Story" and the reason

This skill adopts an MCP-first approach, with the core goal of upgrading "design description" to "design execution specifications + evidence-based gates."

来源原 Skill

Original Source Skill

来源：

skills/brainstorming/SKILL.md

skills/writing-plans/SKILL.md

策略：保留原 Skill 作为基线与回退路径，本 Skill 复制改写并强化 Pencil MCP 执行规范。

Source:

skills/brainstorming/SKILL.md

skills/writing-plans/SKILL.md

Strategy: Retain the original Skill as the baseline and fallback path, while this Skill is copied, rewritten, and enhanced with Pencil MCP execution specifications.

何时使用 / 何时跳过

When to Use / When to Skip

使用场景

Usage Scenarios

Story 新增页面、弹窗、关键交互流程
现有页面布局、状态展示、交互反馈发生变化
需求明确要求提供设计稿/画布/原型

New pages, pop-ups, or critical interaction flows are added to a Story
Existing page layouts, state displays, or interaction feedback change
Requirements explicitly require design drafts/canvases/prototypes

跳过场景

Skip Scenarios

纯后端、数据处理、脚本、配置调整且无可见 UI 变化

跳过时必须在
analysis.md
写明：本 Story 无 UI 设计，并给出理由。

Pure backend, data processing, scripts, configuration adjustments with no visible UI changes

When skipping, you must state clearly in
analysis.md
: No UI design for this Story, and provide the reason.

输入契约（先定义再作图）

Input Contract (Define Before Designing)

在开始 MCP 操作前，先固化以下输入：

页面/模块边界：本次改动影响哪些页面或弹层
状态矩阵：正常 / 空 / 加载 / 异常（必要时加权限态）
交互路径：入口、主流程、失败回路、返回路径
复用策略：优先复用现有组件，缺失时再新增

Before starting MCP operations, first solidify the following inputs:

Page/module boundaries: Which pages or layers are affected by this change
State matrix: Normal / Empty / Loading / Exception (add permission states if necessary)
Interaction paths: Entry point, main flow, failure loop, return path
Reuse strategy: Prioritize reusing existing components, then add new ones if missing

输出契约（必须遵守）

Output Contract (Must Comply)

产物目录：
```
docs/plans/{Story-Key}/
```
设计文件：
```
design.pen
```
（有 UI 变更时必需）
```
analysis.md
```
的 UI 章节必须包含：
- 页面结构
- 核心交互流程
- 状态设计（正常/空/加载/异常）
- 与 PM UI 示意对照说明
- 关键截图与布局检查结论

Deliverable directory:
```
docs/plans/{Story-Key}/
```
Design file:
```
design.pen
```
(required when there are UI changes)
The UI section of
```
analysis.md
```
must include:
- Page structure
- Core interaction flows
- State design (normal/empty/loading/exception)
- Comparison and explanation with PM UI sketches
- Key screenshots and layout inspection conclusions

执行流程（MCP-first）

Execution Process (MCP-first)

Step 0：Pencil MCP 可执行性预检

Step 0: Pencil MCP Executability Pre-check

执行前必须确认：

Pencil 已启动（桌面端或编辑器扩展）
MCP 已连接且工具可用
目标文件位于项目工作区
已约定保存策略（关键批次后手动保存）

若预检失败：

在
```
analysis.md
```
标记
```
UI 设计阻塞
```
记录阻塞原因、影响范围、恢复条件
输出最小线框说明和状态清单，待 MCP 恢复后补齐
```
design.pen
```

Before execution, you must confirm:

Pencil is running (desktop version or editor extension)
MCP is connected and tools are available
The target file is located in the project workspace
Save strategy is agreed upon (manual save after key batches)

If pre-check fails:

Mark
```
UI design blocked
```
in
```
analysis.md
```
Record the blocking reason, impact scope, and recovery conditions
Output minimal wireframe description and state list, then complete
```
design.pen
```
after MCP is restored

Step 1：初始化设计上下文

Step 1: Initialize Design Context

按顺序调用最小工具链：

```
open_document
```
```
get_editor_state
```
```
get_guidelines
```
（按场景选择）
```
batch_get
```
（一次性检索可复用组件）
```
get_variables
```
（缺失时再
```
set_variables
```
补齐最小 token）

Call the minimal toolchain in order:

```
open_document
```
```
get_editor_state
```
```
get_guidelines
```
(select by scenario)
```
batch_get
```
(retrieval reusable components in one go)
```
get_variables
```
(use
```
set_variables
```
to fill in minimal tokens if missing)

Step 2：分批构图（结构优先）

Step 2: Batch Composition (Structure First)

每次
```
batch_design
```
控制在
```
<=25
```
操作
先骨架后细节：布局框架 → 组件实例 → 文案与状态 → 视觉微调
推荐批次：
- 批次 A：发现与复用
- 批次 B：骨架搭建
- 批次 C：核心状态（正常/空/加载/异常）
- 批次 D：失败回路与返回路径

Control each
```
batch_design
```
operation to
```
<=25
```
actions
Skeleton first, then details: Layout framework → Component instances → Copy and states → Visual fine-tuning
Recommended batches:
- Batch A: Discovery and reuse
- Batch B: Skeleton construction
- Batch C: Core states (normal/empty/loading/exception)
- Batch D: Failure loops and return paths

Step 3：每批质量门禁（硬性）

Step 3: Quality Gate for Each Batch (Mandatory)

每一批都必须完成以下检查后再进入下一批：

```
snapshot_layout
```
（
```
problemsOnly=true
```
）检查重叠/裁剪/越界
```
snapshot_layout
```
（常规）复核结构
```
get_screenshot
```
抽样关键节点截图（至少主流程 + 异常态）

未通过则立即修正，不允许带问题进入下一批。

Complete the following checks before proceeding to the next batch:

```
snapshot_layout
```
(
```
problemsOnly=true
```
) to check overlap/clipping/out-of-bounds
```
snapshot_layout
```
(regular) to review structure
```
get_screenshot
```
to sample key node screenshots (at least main flow + exception state)

If not passed, correct immediately; do not proceed with unresolved issues.

Step 4：回填计划文档

Step 4: Backfill Plan Document

在

analysis.md

的 UI 小节回填：

```
.pen
```
文件路径
状态覆盖清单（正常/空/加载/异常）
交互路径覆盖（入口、主流程、失败回路、返回路径）
遗留风险与后续动作

Backfill the UI section of

analysis.md

with:

```
.pen
```
file path
State coverage list (normal/empty/loading/exception)
Interaction path coverage (entry point, main flow, failure loop, return path)
Remaining risks and follow-up actions

Step 5：准备 G2 审查材料

Step 5: Prepare G2 Review Materials

PR 中至少包含：

```
analysis.md
```
```
design.pen
```
（如有 UI 变更）

docs/templates/g2-design-review-checklist.md

对应自检结果

The PR must include at least:

```
analysis.md
```
```
design.pen
```
(if there are UI changes)

Self-inspection results corresponding to

docs/templates/g2-design-review-checklist.md

失败兜底与恢复策略

Failure Fallback and Recovery Strategy

MCP 不可用：标记阻塞并降级为线框说明，不得跳过 UI 章节
权限/连接异常：先检查 Pencil 是否运行、MCP 是否可见、工作区权限是否正确
保存风险：关键批次后立刻手动保存并落 Git 版本

MCP unavailable: Mark as blocked and downgrade to wireframe description; do not skip the UI section
Permission/connection exception: First check if Pencil is running, MCP is visible, and workspace permissions are correct
Save risk: Manually save immediately after key batches and commit to Git version

UI Definition of Done（DoD）

UI Definition of Done (DoD)

满足以下条件才允许进入开发阶段：

已产出并保存
```
design.pen
```
，或明确“本 Story 无 UI 设计”
状态矩阵至少覆盖正常/空/加载/异常四态
主流程与失败回路均有可见反馈
```
snapshot_layout
```
与
```
get_screenshot
```
验收通过
```
analysis.md
```
的 UI 章节已完整回填

The following conditions must be met before proceeding to the development phase:

```
design.pen
```
has been produced and saved, or "No UI design for this Story" is clearly stated
The state matrix covers at least the four states: normal/empty/loading/exception
Both main flow and failure loop have visible feedback
```
snapshot_layout
```
and
```
get_screenshot
```
acceptance passed
The UI section of
```
analysis.md
```
has been fully backfilled