Aile: Pencil Design (aile-pencil-design)

Overview

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."

Original Source Skill

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

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

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)

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)

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

Execution Process (MCP-first)

Step 0: Pencil MCP Executability Pre-check

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: Initialize Design Context

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: Batch Composition (Structure First)

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: Quality Gate for Each Batch (Mandatory)

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: Backfill Plan Document

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: Prepare G2 Review Materials

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 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)

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

aile-pencil-design

NPX Install

Tags

SKILL.md Content (Chinese)