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](references/html-to-pencil-mapping.md)** — 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](references/tailwind-to-pencil-styles.md)** — 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](references/uview-to-pencil-styles.md), [uviewpro](references/uviewpro-to-pencil-styles.md), [element](references/element-to-pencil-styles.md), [bootstrap](references/bootstrap-to-pencil-styles.md), [layui](references/layui-to-pencil-styles.md), [vant](references/vant-to-pencil-styles.md). Cross-framework mapping and "refs vs primitives": [tailwind-to-pencil-styles.md](references/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](references/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](references/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](references/tailwind-to-pencil-styles.md) section 16. 2. **Apply styles** (see [tailwind-to-pencil-styles.md](references/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 | Phase | Description | Typical batch | Parent ref | |-------|-------------|---------------|------------| | 0 | Canvas prep (optional) | — | — | | 1 | Document + root + header + main placeholder | Batch 1 | document → root, main | | 2 | Header content (back, title, actions) | Batch 2 | header | | 3 | Tabs bar (if present) | Batch 3 | root | | 4 | Section 1 (card + title + body placeholder) | Batch 4 | main | | 5 | Section 1 body (form rows, inputs, buttons) | Batch 5 | card1Body | | 6 | Section 2 (card + …) | Batch 6 | main | | 7 | Section 2 body | Batch 7 | card2Body | | … | One batch per section body if large | … | … | | N | Footer or final dividers | Batch N | main | 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](references/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) | Batch | Ops | Content | |-------|-----|---------| | 1 | 3 | root, header, main | | 2 | 2 | backIcon, titleText under header | | 3 | 6 | card1, card1Header, card1Title, card1Body | | 4 | 5 | row1, label1, input1; row2, label2, input2 under card1Body | 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](https://stitch.withgoogle.com/docs/mcp/guide/) - [Pencil MCP tools](https://github.com/google-labs-code/pencil-skills) / pencil-skills [stitch-html-to-pencil-batch.md](https://github.com/full-stack-skills/pencil-skills/blob/main/docs/stitch-html-to-pencil-batch.md) - [HTML → Pencil mapping](references/html-to-pencil-mapping.md) - [Tailwind → Pencil styles](references/tailwind-to-pencil-styles.md) (includes §15–16 framework mapping and refs vs primitives)