| name | pencil-design |
| description | Work with Pencil .pen design files via the Pencil MCP (batch_design, variables, guidelines). Use when creating or editing .pen files, exploring UI layouts in Pencil, generating wireframes for EduHub, or when the user mentions Pencil, .pen, or the highagency Pencil extension. |
Pencil design files (.pen)
Rules
- Do not read
.pen files with the Read or Grep tools — they are encrypted/binary; use Pencil MCP tools only.
- Read tool schemas before calling — tool descriptors live under the workspace MCP folder (e.g.
batch_design.json); parameters must match exactly.
- Prefer a repo path for persistence — e.g.
/home/steffen/git/eduhub/design/<name>.pen. Open with open_document using that path or "new", then save from Pencil if the file should live in git.
Workflow
get_editor_state — see active document and top-level node IDs.
open_document — pass an absolute .pen path or "new" if nothing is open.
get_guidelines — list guides/styles; load Web App, Design System, Table, etc. as needed for the task.
get_variables — if {} or missing keys, tokens like $--background resolve to black (#000000) in the canvas.
batch_design — insert/update frames and content; max ~25 operations per call; every I/C/R needs a binding name; follow property rules in the tool description (e.g. alignItems only start/center/end, no invalid node props).
batch_get — inspect nodes; use resolveVariables: true to see resolved colors (when variables are defined).
set_variables — define colors/strings/numbers before or after designs; variable names without $ (e.g. --background); reference in nodes as $--background. For theme-aware colors, use the { value, theme } array form from set_variables docs.
replace_all_matching_properties — bulk fix baked colors (e.g. replace #000000 fills) under chosen parent node IDs.
get_screenshot — verify layout after substantive changes when needed.
Avoid “all black” canvases
On a new or empty-variable document, $--* fills and text often resolve to black. Before or right after building screens:
- Run
set_variables with at least --background, --foreground, --muted-foreground, --card, --border, --primary, --secondary (and --radius-m / --radius-pill if used in cornerRadius), or
- Use explicit hex in
batch_design U(...) / I(...) (e.g. fill: "#EBEBEB") for wireframes that must always read clearly.
If nodes already show black, use replace_all_matching_properties (fillColor, textColor, strokeColor) from #000000 to intended values under the screen parent IDs, then fine-tune with U(...).
EduHub alignment
When designing screens that will be implemented in the app, cross-check frontend-nx/apps/edu-hub/.cursor/rules/theme-and-styling.mdc for semantic tokens (e.g. brand green, label/fill/border roles). Pencil variables can mirror those roles even if hex values are approximations for the design file.
MCP server
Use the Pencil MCP server enabled in Cursor (e.g. user-highagency.pencildev-extension-pencil). Tool names include: get_editor_state, open_document, get_guidelines, get_variables, set_variables, batch_get, batch_design, snapshot_layout, get_screenshot, find_empty_space_on_canvas, search_all_unique_properties, replace_all_matching_properties, export_nodes.