Pencil Design From Stitch HTML

Stitch HTML / URL to Pencil design (pencil-design-from-stitch-html)

Constraint: Use this skill when the user wants to turn a Stitch screen (HTML or Stitch URL/IDs) into a Pencil .pen design that matches the page layout and style (100% precise correspondence). Combines Stitch MCP (get_screen, htmlCode) when input is URL with Pencil MCP (open_document, batch_design, find_empty_space_on_canvas, get_screenshot).

This skill belongs to pencil-skills. When input is a Stitch URL or projectId/screenId, Stitch MCP (get_screen) is used to obtain HTML; Stitch skills are responsible for PRD→prototype only, and this skill is responsible for prototype→.pen design.

You are a design conversion specialist: Stitch exports Tailwind-based HTML; Pencil uses a node tree and batch_design (I/U/R/M/D/C/G). This skill defines HTML element → Pencil node mapping rules, strict execution order, and Tailwind → .pen style mapping (background, color, size, margin, padding, shadow, border-radius) so the drawn artboard is a precise visual match.

Prerequisites

• Stitch MCP Server (https://stitch.withgoogle.com/docs/mcp/guide/) when user provides Stitch URL or projectId/screenId
• Pencil MCP (batch_design, batch_get, open_document, find_empty_space_on_canvas, get_screenshot)
• Stitch projectId and screenId (from URL or list_projects / list_screens), or user-pasted HTML
• Optional: existing .pen file with design system (pencil-ui-design-system-*); otherwise use primitive nodes (frame, text, icon_font)

Core References (must follow)

• HTML → Pencil mapping — Which HTML element/semantic block maps to which Pencil node type and batch_design operation (frame, text, ref, icon_font).
• Execution order and batch split — Defined in the section below: strict phase order, ≤25 ops per batch_design; canvas prep → root → header → main → sections/cards → forms → footer.
• Tailwind → Pencil styles — Background, color, size, margin, padding, shadow, border-radius, typography: Tailwind class → .pen property value (fill, padding, gap, stroke, cornerRadius, fontSize, fontWeight, textColor).
• Per-framework style docs — When a target framework is set, use that framework’s *-to-pencil-styles.md (sections 0, 12, 14, 15) for component styles, tokens, and design-system refs/constraints: uview, uviewpro, element, bootstrap, layui, vant. Cross-framework mapping and "refs vs primitives": tailwind-to-pencil-styles.md sections 15–16.

Optional Target Framework

• Agnostic (default): No target → use primitive nodes (frame, text, icon_font) and tailwind-to-pencil-styles.md for maximum layout/style fidelity without design-system dependency.
• Target set: User or config specifies one of: uView 2, uView Pro, Bootstrap, Element Plus, Layui, Vant → (1) use the corresponding *-to-pencil-styles.md for full style mapping and section 15 for design-system refs and batch_design conventions; (2) ensure .pen has the corresponding pencil-ui-design-system-* initialized so the .pen aligns with the stitch-*-components skills.

Retrieval and HTML

1. Resolve screen: From Stitch design URL parse projectId/screenId, or use list_projects → list_screens → pick screen. If user provides pasted HTML, skip to Parse.
2. get_screen: Call Stitch MCP get_screen with projectId and screenId; obtain htmlCode.downloadUrl, screenshot.downloadUrl, width, height, title.
3. Download HTML: Fetch HTML from htmlCode.downloadUrl (Bash script or web_fetch); save to e.g. temp/source.html. If fetch fails, ask user to paste HTML.
4. Parse: Extract DOM tree and per-node class list (Tailwind). Preserve element semantics: header, main, section, form, input, button, label, etc.

Conversion Pipeline

1. Apply mapping (see html-to-pencil-mapping.md): For each HTML element, determine Pencil node type (frame / text / ref / icon_font), parent binding, and default layout/size. If target framework is set, prefer design-system refs per that framework's *-to-pencil-styles.md section 15 and tailwind-to-pencil-styles.md section 16.
2. Apply styles (see tailwind-to-pencil-styles.md): For each node, resolve Tailwind classes to .pen properties; when target framework is set, prefer that framework's tokens (section 12 of its *-to-pencil-styles.md) and refs (section 15).
3. Build execution plan (see Execution order and batch split below): Split operations into ordered batches (Batch 1: document + root + header + main placeholder; Batch 2: header content; Batch 3–N: per section/card; etc.). Each batch ≤25 ops. When target framework is set, use refs for section/card/hint/divider per that framework's *-to-pencil-styles.md section 15.
4. Run Pencil: Open document (open_document('new') or path); optionally find_empty_space_on_canvas for root frame position; then call batch_design once per batch in order. After each batch (or at end), call get_screenshot on root frame to verify.

Execution Steps

1. Stitch (if URL/IDs): Get projectId/screenId → get_screen → download HTML (and optionally screenshot for reference). Else use user-pasted HTML.
2. Parse HTML: Build DOM tree + class list per node; identify semantic regions (header, main, sections, forms).
3. Plan batches: From the execution order phases below, produce N batch_design payloads (filePath + operations string). Use unique binding names per batch; parent refs from previous batch (e.g. main from Batch 1 used as parent in Batch 3).
4. Pencil: open_document → find_empty_space_on_canvas (if needed) → batch_design(Batch 1) → batch_design(Batch 2) → … → get_screenshot(root) for verification.
5. Verify: Compare screenshot with Stitch screenshot; note any layout or style gaps for next iteration.

Execution order and batch split

Strict execution order for converting Stitch HTML into Pencil batch_design calls: parents must exist before children; each batch at most 25 operations (Pencil recommendation).

1. Phase overview

Parents created in an earlier batch are referenced by binding name in later batches (e.g. I(main, ...), I(card1Body, ...)). Binding names are unique per batch; do not reuse the same name across batches for different nodes.

When a target framework is set, use that framework's refs for section/card, hints, divider, button, input, tabs per that framework's *-to-pencil-styles.md section 15 and tailwind-to-pencil-styles.md section 16.

2. Phase 0: Canvas prep (optional)

• When: Before any batch_design, if the artboard must be placed at a specific position on the canvas.
• Actions: Call find_empty_space_on_canvas with desired width/height (e.g. screen width × height from Stitch get_screen). Use returned position when creating the root frame in Phase 1 (x, y on document). No batch_design in this phase.

3. Phase 1: Root and main structure (Batch 1)

Goal: Create the root frame, header frame, and main content placeholder so all later content has a parent.

Order of operations (≤25): (1) Insert root frame under document: layout vertical, width from screen (e.g. 390), height a fixed value (844 or 884) so the canvas is not blank—avoid root fit_content when children use fill_container. Fill = page background. (2) Insert header frame under root: layout horizontal, height 56 or 64, width fill_container, padding, fill #fff, optional stroke bottom. (3) Insert main frame under root: layout vertical, width fill_container, height fit_content(800), padding 16, gap 16, placeholder true.

Binding names for later batches: root, header, main. Style: root fill from <body> or wrapper class (bg-*); header/main padding and gap from Tailwind (p-4, space-y-4 → 16).

4. Phase 2: Header content (Batch 2)

Goal: Fill the header with back icon, title text, and optional right actions. Parent: header. Insert backIcon (icon_font arrow_back), titleText (content = page title), and optionally headerRight frame with actions. Binding names: backIcon, titleText, headerRight.

5. Phase 3: Tabs bar (Batch 3, if present)

Goal: Create the tab row. Parent: root. Insert tabsWrap frame under root (horizontal, height 48), then tab1/tab1Text, tab2/tab2Text, tab3/tab3Text under tabsWrap. If more than 3 tabs, split into Batch 3a/3b or keep under 25 ops total.

6. Phase 4–5: First section / card (Batch 4 + 5)

Batch 4 — Parent: main. Insert card1 frame (vertical, fill_container, padding 24, gap 16, fill #fff, cornerRadius 12, stroke 1px); card1Header under card1; card1Title under card1Header; optional card1Right; card1Body under card1 (vertical, placeholder true).

Batch 5 — Parent: card1Body. For each form row: insert row frame, label text, input frame (or ref). If more than ~8 rows, split into Batch 5a, 5b. Binding names: card1, card1Header, card1Title, card1Body.

7. Phase 6–7: Second section (Batch 6 + 7)

Same pattern: Batch 6 — card2, card2Header, card2Title, card2Body under main. Batch 7 — card2Body children. Repeat for Section 3, 4, … (Batch 8, 9, …). If one section has very many rows, use multiple batches with same parent (e.g. card3Body).

8. Phase N: Footer and final elements

Insert any footer frame under main, or final divider lines. Keep under 25 ops; if many small elements, group into one batch.

9. Batch size and naming rules

• Max 25 operations per batch_design call. Split large section bodies (e.g. 15 form rows → Batch 5 first 7, Batch 5b next 8).
• Binding names: Unique per batch; use descriptive names (card1, card1Body, inputRow1, labelName). In the next batch, reference parents by the binding name from the previous batch.
• Placeholder: Use placeholder: true on frames that will receive many children in the next batch (main, card1Body).

10. Execution order checklist

Before running Pencil: [ ] Phase 0 optional find_empty_space_on_canvas; [ ] Phase 1 Batch 1 — root, header, main; [ ] Phase 2 Batch 2 — header content; [ ] Phase 3 Batch 3 — tabs if any; [ ] Phase 4–5 Batch 4–5 — card1 + card1Body + body children; [ ] Phase 6–7 Batch 6–7 — card2 + card2Body; [ ] … repeat for remaining sections; [ ] Phase N footer/final; [ ] After all batches: get_screenshot(root) to verify.

11. Example: Minimal page (header + 1 card + 2 rows)

Total: 4 batches, 16 operations. Order is fixed: 1 → 2 → 3 → 4.

Integration

• Stitch screens: Same pattern as stitch-remotion / stitch-uviewpro-components: list_projects, list_screens, get_screen, download URLs (when user provides Stitch URL/IDs).
• Pencil: Same pattern as pencil-ui-designer / pencil-mcp-batch-design: open_document, batch_design (≤25 ops per call), get_screenshot for visual check.
• Design system: If .pen has a design system (e.g. uView Pro), prefer refs for Card, Button, Input, Tabs; otherwise use primitive frame + text + icon_font for 100% control over size/margin/shadow.

File Structure

skills/pencil-design-from-stitch-html/
├── SKILL.md
├── LICENSE.txt
├── references/
│   ├── html-to-pencil-mapping.md   # Element → node + op rule
│   ├── tailwind-to-pencil-styles.md # Generic Tailwind → Pencil; §15–16 framework mapping + refs vs primitives
│   ├── uview-to-pencil-styles.md   # uView 2 → Pencil (full style table + §15 refs/constraints)
│   ├── uviewpro-to-pencil-styles.md
│   ├── element-to-pencil-styles.md
│   ├── bootstrap-to-pencil-styles.md
│   ├── layui-to-pencil-styles.md
│   └── vant-to-pencil-styles.md
└── examples/
    ├── usage.md                    # When to use, steps, MCP flow, example prompts
    ├── sample-batch-ops.md         # Minimal page → one batch_design (≤25 ops)
    ├── sample-multi-batch.md       # Header + card + form rows → four batches
    ├── sample-with-framework-refs.md # Same page with target framework (refs + tokens)
    └── sample-simple-create-product.md # Simplified Create Product (1–2 batches) for quick validation

Keywords

English: Stitch, Pencil, batch_design, .pen, HTML to design, Tailwind, layout, fidelity.
中文关键词： Stitch、Pencil、绘图、HTML 转设计稿、批动作。

References

• Stitch MCP
• Pencil MCP tools / pencil-skills stitch-html-to-pencil-batch.md
• HTML → Pencil mapping
• Tailwind → Pencil styles (includes §15–16 framework mapping and refs vs primitives)
• Per-framework style tables (incl. refs/constraints §15): uview, uviewpro, element, bootstrap, layui, vant
• Examples: usage, single batch, multi-batch, with framework refs, simplified Create Product

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。