\r \r

Pencil Design Skill\r

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

• 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.\r
• Mode B — MCP tool-based: when Pencil MCP is connected, use pencil_batch_design, pencil_batch_get, etc. See MCP tools below.\r \r

When to Use\r

\r

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

Critical Rules (MUST follow)\r

\r

1. Read pen-format.md first before writing any .pen file (Mode A) — contains all node types, variables, layout rules, default templates.\r
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.\r
3. Enforce file split — count requested artboards before designing:\r
   • ≤ 3: proceed\r
   • 4: ask user (keep together vs split)\r
   • ≥ 5: MUST ask user for split strategy (1/file, 3/file, or 4/file). See File split policy.\r
4. Always use variables — never hardcode colors / radius / fonts. Use "$--background", not "#09090b". If a variable doesn't exist, create it.\r
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:\r
   • 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.\r
   • Every text node inside an auto-layout parent: "width": "fill_container" + "textGrowth": "fixed-width".\r
   • 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).\r
   • 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.\r
   • Horizontal rows of cards: use gap + width: "fill_container" on each card. Never hand-pick fixed pixel widths that don't divide evenly.\r
   • Buttons / badges: use "fit_content" (padding [v,h]) + "justifyContent": "center" + "alignItems": "center". Never fix a width smaller than the label.\r
   • Absolutely no hand-computed x/y for content blocks inside an auto-layout parent.\r
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.\r
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.\r
   • Default (horizontal): y = 0 for all; x = 0, W+100, 2(W+100), … Example for 1440×900: x = 0, 1540, 3080, 4620.\r
   • 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.\r
   • Always ask the user before designing (in both English and Chinese), unless they have already specified a direction:\r

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

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

8. Icon font family — always "iconFontFamily": "lucide". No other families.\r
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.\r
10. Build section by section in Mode B — screenshot + layout-check after each section, fix issues before moving on. See mcp/screenshot-qa.md.\r
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.\r
12. Code generation requires frontend-design skill if available — load it for aesthetic direction.\r \r ---\r \r

File Split Policy\r

\r A single .pen file must NEVER contain more than 4 artboards (causes performance issues).\r \r When ≥ 4 artboards are requested, ask the user (in both English and Chinese):\r \r

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

1. One artboard per file / 每个画板一个文件\r
2. Max 3 artboards per file / 每个文件最多 3 个画板\r
3. Max 4 artboards per file / 每个文件最多 4 个画板\r
4. No split (not recommended) / 不拆分（不推荐）\r \r Naming: feature-01.pen, feature-02.pen, … or by logical groups (feature-onboarding.pen).\r \r ---\r \r

Quick Templates\r

\r

Single artboard (Shadcn Dark default)\r

\r

{\r
  "version": "2.8",\r
  "children": [\r
    {\r
      "type": "frame", "id": "scrn1", "name": "页面",\r
      "theme": { "Mode": "Dark" },\r
      "clip": true, "width": 1440, "height": 900,\r
      "fill": "$--background", "layout": "vertical",\r
      "children": [ ... ]\r
    }\r
  ],\r
  "themes": { "Mode": ["Light", "Dark"] },\r
  "variables": { ...copy from pen-format.md "Shadcn Dark Zinc Variables"... }\r
}\r
```\r
\r
### Multiple artboards — default HORIZONTAL (x 递增, 100 px gap)\r
\r
```json\r
{ "type": "frame", "id": "scrn1", "x": 0,    "y": 0, "width": 1440, "height": 900, ... },\r
{ "type": "frame", "id": "scrn2", "x": 1540, "y": 0, "width": 1440, "height": 900, ... },\r
{ "type": "frame", "id": "scrn3", "x": 3080, "y": 0, "width": 1440, "height": 900, ... }\r
```\r
\r
### Multiple artboards — VERTICAL (only when user picks it, y 递增, 100 px gap)\r
\r
```json\r
{ "type": "frame", "id": "scrn1", "x": 0, "y": 0,    "width": 1440, "height": 900, ... },\r
{ "type": "frame", "id": "scrn2", "x": 0, "y": 1000, "width": 1440, "height": 900, ... },\r
{ "type": "frame", "id": "scrn3", "x": 0, "y": 2000, "width": 1440, "height": 900, ... }\r
```\r
\r
Common screen sizes: Desktop `1440×900` / `1920×1080` · Tablet `768×1024` · Mobile `375×812` / `393×852`.\r
\r
---\r
\r
## Default Styles\r
\r
> Named style specs (Vercel / Linear / Stripe / Notion / Raycast / Supabase / Airtable / Apple) are distilled from \x3Chttps://getdesign.md/>.\r
\r
| Trigger | Style file | Notes |\r
|---|---|---|\r
| User chose a named style | `styles/style-\x3Cname>.md` | Read only the matching file (vercel / linear / stripe / notion / raycast / supabase / airtable / apple) |\r
| User skipped / chose "default" | Shadcn Dark Zinc | Variables block lives in `pen-format.md`. Dark surfaces `#09090b` / `#18181b`, light text `#fafafa`, subtle borders `#27272a`. |\r
| PPT / slide deck | [`ppt/presets-ppt.md`](ppt/presets-ppt.md) | 1280×720, blue gradient header, white body |\r
\r
---\r
\r
## Workflow Summary\r
\r
### Mode A — Direct file writing\r
```\r
1. Confirm style (Rule 2)         -> ask user OR read styles/style-\x3Cname>.md\r
2. Read pen-format.md             -> mandatory for first .pen task in session\r
3. Read layout-integrity.md       -> mandatory for EVERY .pen task (Rule 5, 11)\r
4. Plan layout & artboard count   -> apply file split policy if ≥ 4\r
   If ≥ 2 artboards, ask arrangement direction (Rule 7) — default HORIZONTAL\r
5. Write .pen with variables block and auto-layout (NEVER layout:"none" for content)\r
6. read_lints to validate JSON\r
7. Manual Layout Integrity Checklist pass (Rule 11) — fix before declaring done\r
```\r
\r
### Mode B — MCP tool-based\r
```\r
1. Confirm style + load frontend-design skill if available\r
2. pencil_get_editor_state        -> get .pen schema, current state\r
3. pencil_batch_get reusable=true -> discover existing components (REUSE > recreate)\r
4. pencil_get_variables           -> read tokens; pencil_set_variables to create new\r
5. pencil_find_empty_space        -> place new artboards\r
6. pencil_batch_design             -> build ONE section at a time\r
7. pencil_get_screenshot + pencil_snapshot_layout(problemsOnly:true) -> verify each section\r
8. Fix issues -> re-screenshot -> re-check (verify loop)\r
9. Final full-file layout audit (Rule 11) -> problemsOnly MUST be empty before declaring done\r
```\r
\r
---\r
\r
## MCP Tool Quick Reference\r
\r
See [`mcp/mcp-tools.md`](mcp/mcp-tools.md) for the full tool table and Mode B call order.\r
\r
---\r
\r
## Code Generation (Pencil → React + Tailwind v4 + shadcn/ui)\r
\r
**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.\r
\r
**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`).\r
\r
Detailed mapping: [`references/codegen-workflow.md`](references/codegen-workflow.md) + [`references/codegen-mapping.md`](references/codegen-mapping.md).\r
\r
---\r
\r
## Reference Files (read on demand)\r
\r
### Always-read (mandatory)\r
\r
| File | When |\r
|------|------|\r
| [`pen-format.md`](references/pen-format.md) | Before writing any `.pen` file |\r
| [`layout-integrity.md`](references/layout-integrity.md) | Before writing any `.pen` file — hard rules preventing overflow, misalignment, crooked layouts |\r
\r
### Style references (read 1, after style is selected)\r
\r
> Source for named style specs: \x3Chttps://getdesign.md/>\r
\r
| Style | File |\r
|-------|------|\r
| Style picker / menu | [`style-picker.md`](styles/style-picker.md) |\r
| Vercel | [`style-vercel.md`](styles/style-vercel.md) |\r
| Linear | [`style-linear.md`](styles/style-linear.md) |\r
| Stripe | [`style-stripe.md`](styles/style-stripe.md) |\r
| Notion | [`style-notion.md`](styles/style-notion.md) |\r
| Raycast | [`style-raycast.md`](styles/style-raycast.md) |\r
| Supabase | [`style-supabase.md`](styles/style-supabase.md) |\r
| Airtable | [`style-airtable.md`](styles/style-airtable.md) |\r
| Apple | [`style-apple.md`](styles/style-apple.md) |\r
| PPT preset | [`presets-ppt.md`](ppt/presets-ppt.md) |\r
\r
### Topic references (read on demand)\r
\r
| File | Topic |\r
|------|-------|\r
| [`layout-integrity.md`](references/layout-integrity.md) | **MUST-READ.** Hard rules for all UI / PPT — sizing, auto-layout, no-overflow, no-overlap, no-crooked-alignment, artboard budget math |\r
| [`overflow-prevention.md`](references/overflow-prevention.md) | Text `fill_container` rules, mobile constraints, fix patterns |\r
| [`design-tokens.md`](references/design-tokens.md) | Variable system, theming, Tailwind v4 mapping |\r
| [`component-reuse.md`](references/component-reuse.md) | `ref` instances, `descendants` overrides |\r
| [`image-reuse.md`](mcp/image-reuse.md) | Search-before-generate, copy vs regenerate |\r
| [`screenshot-qa.md`](mcp/screenshot-qa.md) | Section-by-section verification (Mode B) |\r
| [`responsive.md`](references/responsive.md) | Artboard sizes → Tailwind breakpoints |\r
| [`codegen-workflow.md`](references/codegen-workflow.md) | Full design-to-code workflow |\r
| [`codegen-mapping.md`](references/codegen-mapping.md) | Tailwind / shadcn quick mapping tables |\r
\r
> **Output rule**: user-facing design files must always be saved as `\x3Cname>.pen` (never `.pen.json` — that suffix is reserved for skill-internal storage).\r
\r
---\r
\r
## Common Mistakes\r
\r
| Mistake | Fix |\r
|---------|-----|\r
| Hardcoded `#3b82f6` in `.pen` | Use `"$--primary"` |\r
| Omitting `layout` on frame | Set `"layout": "vertical"` or `"horizontal"` (default is horizontal) |\r
| Using `"layout": "none"` on a content artboard | Switch to `"vertical"`; reserve `"none"` for intentional absolute decoration (cover backgrounds only) |\r
| Fixed-width text in auto-layout | Use `"width": "fill_container"` + `"textGrowth": "fixed-width"` |\r
| Card/content wider than parent inner width | Use `"width": "fill_container"` on every row child; size cards via `gap` on parent |\r
| Body height overflowing artboard (header + body > artboard) | Use `height: "fill_container"` on the body frame, fixed heights only for header/footer |\r
| Button with hardcoded width smaller than label | Use `"fit_content"` + `padding: [v, h]` + `justifyContent: "center"` |\r
| Hand-computed `x`/`y` inside auto-layout parent | Let auto-layout position children; use `gap`/`padding` instead |\r
| Text touching artboard edges | Apply horizontal padding (desktop 40–64px, tablet 24–32px, mobile 16–20px) |\r
| Long descriptive IDs | Use 5-char codes: `"btn01"`, `"crd1a"` |\r
| `bg-[#fff]` in code | Use `bg-background`, `text-foreground` |\r
| `tailwind.config.ts` | Use CSS `@theme` (Tailwind v4) |\r
| English UI text | Default to Simplified Chinese |\r
| Silently using Shadcn Dark | Always ask user for style first (Rule 2) |\r
| Cramming 5+ artboards in one file | Apply file split policy (Rule 3) |\r
| Skipping final layout audit | Run Layout Integrity Checklist before declaring done (Rule 11) |\r
\r