pencil-design-skill

Design UIs in Pencil (.pen files) and generate production-ready code from them. Triggers on any task involving .pen files, UI prototyping, design system authoring, design-to-code conversion, or Pencil MCP tool usage.

Design production-quality UIs in Pencil and generate clean code. Two modes:

• Mode A — Direct file writing: write .pen JSON via write_to_file / replace_in_file. Always read references/pen-format.md before writing any .pen file.
• Mode B — MCP tool-based: when Pencil MCP is connected, use pencil_batch_design, pencil_batch_get, etc. See MCP tools below.

When to Use

• Creating/editing .pen files (UI screens, components, design systems)
• Converting Pencil designs to React/Vue/Svelte + Tailwind v4 + shadcn/ui code
• Syncing design tokens between Pencil variables and code (@theme blocks)

---

Critical Rules (MUST follow)

1. Read pen-format.md first before writing any .pen file (Mode A) — contains all node types, variables, layout rules, default templates.
2. Confirm style first — if user did not specify a style, ask via ask_followup_question using the menu in styles/style-picker.md. Never silently default to Shadcn Dark.
3. Enforce file split — count requested artboards before designing:
   • ≤ 3: proceed
   • 4: ask user (keep together vs split)
   • ≥ 5: MUST ask user for split strategy (1/file, 3/file, or 4/file). See File split policy.
4. Always use variables — never hardcode colors / radius / fonts. Use "$--background", not "#09090b". If a variable doesn't exist, create it.
5. Layout integrity is non-negotiable (HIGHEST PRIORITY) — applies to ALL outputs (PPT slides, web, mobile, components). No content may extend beyond its parent or the artboard. No overlaps. No crooked / misaligned elements. See references/layout-integrity.md + references/overflow-prevention.md. Summary:
   • Every top-level artboard MUST use "layout": "vertical" or "horizontal" (NOT "none") whenever it holds flowing content. Only use "none" for intentional absolute-positioned decoration (cover / hero slides), and in that case every child MUST stay within the artboard rect.
   • Every text node inside an auto-layout parent: "width": "fill_container" + "textGrowth": "fixed-width".
   • Every child frame whose content may grow: "width": "fill_container" and/or "height": "fit_content". Never fix a width larger than the parent's inner width (parent width − horizontal padding).
   • Artboards have fixed width + fixed height; sum of header + body (fill_container) + footer MUST equal artboard height. Body area content must never exceed its computed height.
   • Horizontal rows of cards: use gap + width: "fill_container" on each card. Never hand-pick fixed pixel widths that don't divide evenly.
   • Buttons / badges: use "fit_content" (padding [v,h]) + "justifyContent": "center" + "alignItems": "center". Never fix a width smaller than the label.
   • Absolutely no hand-computed x/y for content blocks inside an auto-layout parent.
6. Default UI language is Simplified Chinese — all user-facing text in .pen files uses 简体中文 unless user explicitly requests otherwise. Technical terms / brand names may stay English.
7. Multi-artboard layout — when ≥ 2 artboards exist in one file, default direction is HORIZONTAL (画板横向排列，x 递增，100 px gap). Each top-level frame needs x and y.
   • Default (horizontal): y = 0 for all; x = 0, W+100, 2(W+100), … Example for 1440×900: x = 0, 1540, 3080, 4620.
   • Vertical (only when user explicitly asks): x = 0 for all; y = 0, H+100, 2(H+100), … Example for 1440×900: y = 0, 1000, 2000, 3000. For PPT (1280×720): y = 0, 820, 1640, 2460.
   • Always ask the user before designing (in both English and Chinese), unless they have already specified a direction:

     Your request has N artboards. Arrange them: 您的请求包含 N 个画板，排列方向：

     1. Horizontal (default) / 横向排列（默认）
     2. Vertical / 竖向排列

8. Icon font family — always "iconFontFamily": "lucide". No other families.
9. Reuse assets — before generating images/logos, search existing nodes (Mode B uses pencil_batch_get). Copy & resize, do not regenerate. See mcp/image-reuse.md.
10. Build section by section in Mode B — screenshot + layout-check after each section, fix issues before moving on. See mcp/screenshot-qa.md.
11. Mandatory pre-completion layout audit — before declaring any .pen task done, run the Layout Integrity Checklist. In Mode B: pencil_snapshot_layout with problemsOnly: true for every artboard must return empty. In Mode A: manually verify each artboard against the checklist.
12. Code generation requires frontend-design skill if available — load it for aesthetic direction.

---

File Split Policy

A single .pen file must NEVER contain more than 4 artboards (causes performance issues).

When ≥ 4 artboards are requested, ask the user (in both English and Chinese):

Your request includes N artboards. Please choose a splitting strategy: 您的请求包含 N 个画板。请选择拆分方式：

1. One artboard per file / 每个画板一个文件
2. Max 3 artboards per file / 每个文件最多 3 个画板
3. Max 4 artboards per file / 每个文件最多 4 个画板
4. No split (not recommended) / 不拆分（不推荐）

Naming: feature-01.pen, feature-02.pen, … or by logical groups (feature-onboarding.pen).

---

Quick Templates

Single artboard (Shadcn Dark default)

json

{
  "version": "2.8",
  "children": [
    {
      "type": "frame", "id": "scrn1", "name": "页面",
      "theme": { "Mode": "Dark" },
      "clip": true, "width": 1440, "height": 900,
      "fill": "$--background", "layout": "vertical",
      "children": [ ... ]
    }
  ],
  "themes": { "Mode": ["Light", "Dark"] },
  "variables": { ...copy from pen-format.md "Shadcn Dark Zinc Variables"... }
}

Multiple artboards — default HORIZONTAL (x 递增, 100 px gap)

json

{ "type": "frame", "id": "scrn1", "x": 0,    "y": 0, "width": 1440, "height": 900, ... },
{ "type": "frame", "id": "scrn2", "x": 1540, "y": 0, "width": 1440, "height": 900, ... },
{ "type": "frame", "id": "scrn3", "x": 3080, "y": 0, "width": 1440, "height": 900, ... }

Multiple artboards — VERTICAL (only when user picks it, y 递增, 100 px gap)

json

{ "type": "frame", "id": "scrn1", "x": 0, "y": 0,    "width": 1440, "height": 900, ... },
{ "type": "frame", "id": "scrn2", "x": 0, "y": 1000, "width": 1440, "height": 900, ... },
{ "type": "frame", "id": "scrn3", "x": 0, "y": 2000, "width": 1440, "height": 900, ... }

Common screen sizes: Desktop 1440×900 / 1920×1080 · Tablet 768×1024 · Mobile 375×812 / 393×852.

---

Default Styles

Named style specs (Vercel / Linear / Stripe / Notion / Raycast / Supabase / Airtable / Apple) are distilled from https://getdesign.md/.

Trigger	Style file	Notes
User chose a named style	styles/style-<name>.md	Read only the matching file (vercel / linear / stripe / notion / raycast / supabase / airtable / apple)
User skipped / chose "default"	Shadcn Dark Zinc	Variables block lives in pen-format.md. Dark surfaces #09090b / #18181b, light text #fafafa, subtle borders #27272a.
PPT / slide deck	ppt/presets-ppt.md	1280×720, blue gradient header, white body

---

Workflow Summary

Mode A — Direct file writing

text

1. Confirm style (Rule 2)         -> ask user OR read styles/style-<name>.md
2. Read pen-format.md             -> mandatory for first .pen task in session
3. Read layout-integrity.md       -> mandatory for EVERY .pen task (Rule 5, 11)
4. Plan layout & artboard count   -> apply file split policy if ≥ 4
   If ≥ 2 artboards, ask arrangement direction (Rule 7) — default HORIZONTAL
5. Write .pen with variables block and auto-layout (NEVER layout:"none" for content)
6. read_lints to validate JSON
7. Manual Layout Integrity Checklist pass (Rule 11) — fix before declaring done

Mode B — MCP tool-based

text

1. Confirm style + load frontend-design skill if available
2. pencil_get_editor_state        -> get .pen schema, current state
3. pencil_batch_get reusable=true -> discover existing components (REUSE > recreate)
4. pencil_get_variables           -> read tokens; pencil_set_variables to create new
5. pencil_find_empty_space        -> place new artboards
6. pencil_batch_design             -> build ONE section at a time
7. pencil_get_screenshot + pencil_snapshot_layout(problemsOnly:true) -> verify each section
8. Fix issues -> re-screenshot -> re-check (verify loop)
9. Final full-file layout audit (Rule 11) -> problemsOnly MUST be empty before declaring done

---

MCP Tool Quick Reference

See mcp/mcp-tools.md for the full tool table and Mode B call order.

---

Code Generation (Pencil → React + Tailwind v4 + shadcn/ui)

Always do: TypeScript · React 19 (ref as prop, no forwardRef) · semantic Tailwind classes (bg-primary, never bg-[#3b82f6]) · @theme { --color-* / --radius-* } blocks · Lucide icons · CVA + cn() for variants · OKLCH in tokens.

Never do: arbitrary values (bg-[#fff], rounded-[6px], p-[24px]) · tailwind.config.ts (v4 uses CSS) · forwardRef · hardcoded artboard widths in components (use w-full max-w-7xl).

Detailed mapping: references/codegen-workflow.md + references/codegen-mapping.md.

---

Reference Files (read on demand)

Always-read (mandatory)

File	When
pen-format.md	Before writing any .pen file
layout-integrity.md	Before writing any .pen file — hard rules preventing overflow, misalignment, crooked layouts

Style references (read 1, after style is selected)

Source for named style specs: https://getdesign.md/

Style	File
Style picker / menu	style-picker.md
Vercel	style-vercel.md
Linear	style-linear.md
Stripe	style-stripe.md
Notion	style-notion.md
Raycast	style-raycast.md
Supabase	style-supabase.md
Airtable	style-airtable.md
Apple	style-apple.md
PPT preset	presets-ppt.md

Topic references (read on demand)

File	Topic
layout-integrity.md	MUST-READ. Hard rules for all UI / PPT — sizing, auto-layout, no-overflow, no-overlap, no-crooked-alignment, artboard budget math
overflow-prevention.md	Text fill_container rules, mobile constraints, fix patterns
design-tokens.md	Variable system, theming, Tailwind v4 mapping
component-reuse.md	ref instances, descendants overrides
image-reuse.md	Search-before-generate, copy vs regenerate
screenshot-qa.md	Section-by-section verification (Mode B)
responsive.md	Artboard sizes → Tailwind breakpoints
codegen-workflow.md	Full design-to-code workflow
codegen-mapping.md	Tailwind / shadcn quick mapping tables

Output rule: user-facing design files must always be saved as <name>.pen (never .pen.json — that suffix is reserved for skill-internal storage).

---

Common Mistakes

Mistake	Fix
Hardcoded #3b82f6 in .pen	Use "$--primary"
Omitting layout on frame	Set "layout": "vertical" or "horizontal" (default is horizontal)
Using "layout": "none" on a content artboard	Switch to "vertical"; reserve "none" for intentional absolute decoration (cover backgrounds only)
Fixed-width text in auto-layout	Use "width": "fill_container" + "textGrowth": "fixed-width"
Card/content wider than parent inner width	Use "width": "fill_container" on every row child; size cards via gap on parent
Body height overflowing artboard (header + body > artboard)	Use height: "fill_container" on the body frame, fixed heights only for header/footer
Button with hardcoded width smaller than label	Use "fit_content" + padding: [v, h] + justifyContent: "center"
Hand-computed x/y inside auto-layout parent	Let auto-layout position children; use gap/padding instead
Text touching artboard edges	Apply horizontal padding (desktop 40–64px, tablet 24–32px, mobile 16–20px)
Long descriptive IDs	Use 5-char codes: "btn01", "crd1a"
bg-[#fff] in code	Use bg-background, text-foreground
tailwind.config.ts	Use CSS @theme (Tailwind v4)
English UI text	Default to Simplified Chinese
Silently using Shadcn Dark	Always ask user for style first (Rule 2)
Cramming 5+ artboards in one file	Apply file split policy (Rule 3)
Skipping final layout audit	Run Layout Integrity Checklist before declaring done (Rule 11)