pencil-designlisted

# Pencil Design (general-purpose) Hard-won notes for working with `.pen` files via the Pencil MCP server (`mcp__pencil__*`) or the headless `pencil` npm CLI. This is the floor that applies everywhere: if a project-specific `pencil-design` skill exists (brand rules, component inventories, design-system paths), prefer it. Ordinary frontend / CSS design work belongs in `frontend-design` or `do-design-system`, not here. ## Reading .pen files - `.pen` files are encrypted JSON. **Never** use `Read`, `Grep`, or `cat` on them — you get binary garbage and waste a tool turn. - ALWAYS use `mcp__pencil__batch_get` to inspect node structure. - Use `mcp__pencil__get_screenshot` to visually verify the result. - `mcp__pencil__get_editor_state` lists open documents, available reusable components, and selection. ## Saving new .pen files (the gotcha that always bites) `mcp__pencil__open_document` on a non-existent path opens the file **in the desktop editor's memory only** — it does NOT create the file on disk. Existing files auto-save on edits, but **new files never touch disk until you Cmd+S**. The MCP has no save tool. Workaround — trigger Cmd+S via AppleScript after the first edit batch: ```bash osascript -e 'tell application "Pencil" to activate' osascript -e 'tell application "System Events" to keystroke "s" using command down' ``` After saving, verify with `ls` before committing — otherwise pre-commit fails with `no such file`. This bites worst when you `open_document` a fresh pa