aile-pencil-design

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 artifacts:

• docs/plans/{Story-Key}/design.pen(Recommended)
• In docs/plans/{Story-Key}/analysis.md backfill the UI design section and evidence
• If not producing .pen, you must explicitly write "This Story has no UI design" and the reason

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

Source original Skill

• Source: superpowers original requirements analysis and planning capability (migrated to aile-only)
• Strategy: Keep the original Skill as the baseline and fallback path; this Skill copies, rewrites, and strengthens the Pencil MCP execution specification.

When to use / when to skip

Use cases

• Story adds new pages, modals, or key interaction flows
• Existing page layout, state display, or interaction feedback changes
• Requirements explicitly require providing design mockups/canvas/prototypes

Skip cases

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

When skipping, you must in analysis.md write:This Story has no UI design, and provide the reason.

Input contract (define before drawing)

Before starting MCP operations, first solidify the following inputs:

1. Page/module boundaries: which pages or overlays this change affects
2. State matrix: normal / empty / loading / error (add permission state when necessary)
3. Interaction paths: entry, main flow, failure loop, return path
4. Reuse strategy: prioritize reusing existing components; add new ones only when missing

Output contract (must be followed)

• Artifact directory:docs/plans/{Story-Key}/
• Design file:design.pen(required when there are UI changes)
• analysis.md The UI section of
  • Page structure
  • Core interaction flows
  • State design (normal/empty/loading/error)
  • Comparison notes with PM UI mockups
  • Key screenshots and layout inspection conclusions

Execution flow (MCP-first)

Step 0: Pencil MCP executability pre-check

Before execution, you must confirm:

1. Pencil has been started (desktop app or editor extension)
2. MCP is connected and tools are available
3. The target file is located in the project workspace
4. A save strategy has been agreed upon (manual save after key batches)

If the pre-check fails:

• In analysis.md mark UI 设计阻塞
• Record the blocking reason, impact scope, and recovery conditions
• Output the minimal wireframe description and state list, and complete design.pen

Step 1: Initialize the design context

Call the minimal toolchain in order:

1. open_document
2. get_editor_state
3. get_guidelines(select by scenario)
4. batch_get(one-time retrieval of reusable components)
5. get_variables(if missing, then set_variables fill in the minimal token)

Step 2: Batch composition (structure first)

• Each time batch_design Control in <=25 actions
• Skeleton before details: layout framework → component instances → copy and states → visual fine-tuning
• Recommended batches:
  • Batch A: Discovery and reuse
  • Batch B: Skeleton setup
  • Batch C: Core states (normal/empty/loading/error)
  • Batch D: Failure loop and return path

Step 3: Quality gate for each batch (mandatory)

Each batch must complete the following checks before moving to the next batch:

1. snapshot_layout（problemsOnly=true) Check overlap/clipping/out-of-bounds
2. snapshot_layout(routine) Review structure
3. get_screenshot Sample screenshots of key nodes (at least main flow + exception states)

If not passed, fix immediately; do not allow issues to carry over into the next batch.

Step 4: Backfill the planning document

In analysis.md backfill the UI subsection:

• .pen file path
• State coverage checklist (normal/empty/loading/error)
• Interaction path coverage (entry, main flow, failure loop, return path)
• Residual 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)
• docs-templates/g2-design-review-checklist.md corresponding self-check results

Failure fallback and recovery strategy

1. MCP unavailable: mark as blocked and downgrade to a wireframe description; do not skip the UI section
2. Permission/connection exception: first check whether Pencil is running, whether MCP is visible, and whether workspace permissions are correct
3. Save risk: after key batches, save manually immediately and commit to Git version

UI Definition of Done（DoD）

Only allowed to enter the development phase if the following conditions are met:

• Produced and saved design.pen, or explicitly state "this Story has no UI design"
• The state matrix covers at least the four states: normal/empty/loading/error
• Both the main flow and failure loop have visible feedback
• snapshot_layout and get_screenshot acceptance passed
• analysis.md 's UI section has been fully backfilled