pencil-design

$29

NEVER recreate a component from scratch when one already exists in the design file.

Before inserting any element, you MUST:

• Call pencil_batch_get with patterns: [{ reusable: true }] to list all available reusable components

• Search the results for a component that matches what you need (button, card, input, nav, etc.)

• If a match exists, insert it as a ref instance using I(parent, { type: "ref", ref: "<componentId>" })

• Customize the instance by updating its descendants with U(instanceId + "/childId", { ... })

• Only create a new component from scratch if no suitable reusable component exists

See references/design-system-components.md for detailed workflow.

Rule 2: Always Use Variables Instead of Hardcoded Values

NEVER hardcode colors, border radius, spacing, or typography values when variables exist.

Before applying any style value, you MUST:

• Call pencil_get_variables to read all defined design tokens

• Map your intended values to existing variables (e.g., use primary not #3b82f6, use radius-md not 6)

• Apply values using variable references, not raw values

• When generating code, use Tailwind v4 semantic utility classes (e.g., bg-primary, text-foreground, rounded-md). NEVER use arbitrary value syntax (bg-[#3b82f6], text-[var(--primary)], rounded-[6px])

See references/variables-and-tokens.md for detailed workflow.

Rule 3: Prevent Text and Content Overflow

NEVER allow text or child elements to overflow their parent or the artboard.

For every text element and container:

• Set appropriate text wrapping and truncation

• Constrain widths to parent bounds, especially on mobile screens (typically 375px wide)

• Use "fill_container" for width on text elements inside auto-layout frames

• After inserting content, call pencil_snapshot_layout with problemsOnly: true to detect clipping/overflow

• Fix any reported issues before proceeding

See references/layout-and-text-overflow.md for detailed workflow.

Rule 4: Visually Verify Every Section

NEVER skip visual verification after building a section or screen.

After completing each logical section (header, hero, sidebar, form, card grid, etc.):

• Call pencil_get_screenshot on the section or full screen node

• Analyze the screenshot for: alignment issues, spacing inconsistencies, text overflow, visual glitches, missing content

• Call pencil_snapshot_layout with problemsOnly: true to catch clipping and overlap

• Fix any issues found before moving to the next section

• Take a final full-screen screenshot when the entire design is complete

See references/visual-verification.md for detailed workflow.

Rule 5: Reuse Existing Assets (Logos, Icons, Images)

NEVER generate a new logo or duplicate asset when one already exists in the document.

Before generating any image or logo:

• Call pencil_batch_get and search for existing image/logo nodes by name pattern (e.g., patterns: [{ name: "logo|brand|icon" }])

• If a matching asset exists elsewhere in the document (another artboard/screen), copy it using the C() (Copy) operation

• Only use the G() (Generate) operation for genuinely new images that don't exist anywhere in the document

• For logos specifically: always copy from an existing instance, never regenerate

See references/asset-reuse.md for detailed workflow.

Rule 6: Always Load the frontend-design Skill

**NEVER design in Pencil or generate code from Pencil without first loading the frontend-design skill.**

The frontend-design skill provides the aesthetic direction and design quality standards that prevent generic, cookie-cutter UI. You MUST:

• Load the frontend-design skill at the start of any Pencil design or code generation task

• Follow its design thinking process: understand purpose, commit to a bold aesthetic direction, consider differentiation

• Apply its guidelines on typography, color, motion, spatial composition, and visual details — both when designing in Pencil and when generating code from Pencil designs

• Never produce generic AI aesthetics (overused fonts, cliched color schemes, predictable layouts)

This applies to both directions:

• Pencil design tasks: Use the skill's aesthetic guidelines to inform layout, typography, color, and composition choices in the .pen file

• Code generation from Pencil: Use the skill's guidelines to ensure the generated code includes distinctive typography, intentional color themes, motion/animations, and polished visual details — not just a mechanical translation of the design tree

Design Workflow

Starting a New Design

0. Load `frontend-design` skill   -> Get aesthetic direction and design quality standards

1. pencil_get_editor_state        -> Understand file state, get schema

2. pencil_batch_get (reusable)    -> Discover design system components

3. pencil_get_variables           -> Read design tokens

4. pencil_get_guidelines          -> Get relevant design rules

5. pencil_get_style_guide_tags    -> (optional) Get style inspiration

6. pencil_get_style_guide         -> (optional) Apply style direction

7. pencil_find_empty_space_on_canvas -> Find space for new screen

8. pencil_batch_design            -> Build the design (section by section)

9. pencil_get_screenshot          -> Verify each section visually

10. pencil_snapshot_layout        -> Check for layout problems

Building Section by Section

For each section of a screen (header, content area, footer, sidebar, etc.):

• Plan - Identify which design system components to reuse

• Build - Insert components as ref instances, apply variables for styles

• Verify - Screenshot the section + check layout for problems

• Fix - Address any overflow, alignment, or spacing issues

• Proceed - Move to the next section only after verification passes

Design-to-Code Workflow

See references/design-to-code-workflow.md for the complete workflow.

See references/tailwind-shadcn-mapping.md for the full Pencil-to-Tailwind mapping table.

See references/responsive-breakpoints.md for multi-artboard responsive code generation.

Summary:

• Load the frontend-design skill for aesthetic direction

• Call pencil_get_guidelines with topic "code" and "tailwind"

• Call pencil_get_variables to map design tokens to Tailwind @theme declarations

• Read the design tree with pencil_batch_get

• Map reusable Pencil components to shadcn/ui components (Button, Card, Input, etc.)

• Generate code using semantic Tailwind classes (bg-primary, rounded-md), never arbitrary values

• Apply frontend-design guidelines: distinctive typography, intentional color, motion, spatial composition

• Use CVA for custom component variants, cn() for class merging, Lucide for icons

MCP Tool Quick Reference

Tool

When to Use

pencil_get_editor_state

First call - understand file state and get .pen schema

pencil_batch_get

Read nodes, search for components (reusable: true), inspect structure

pencil_batch_design

Insert, copy, update, replace, move, delete elements; generate images

pencil_get_variables

Read design tokens (colors, radius, spacing, fonts)

pencil_set_variables

Create or update design tokens

pencil_get_screenshot

Visual verification of any node

pencil_snapshot_layout

Detect clipping, overflow, overlapping elements

pencil_get_guidelines

Get design rules for: code, table, tailwind, landing-page, design-system

pencil_find_empty_space_on_canvas

Find space for new screens/frames

pencil_get_style_guide_tags

Browse available style directions

pencil_get_style_guide

Get specific style inspiration

pencil_search_all_unique_properties

Audit property values across the document

pencil_replace_all_matching_properties

Bulk update properties (e.g., swap colors)

pencil_open_document

Open a .pen file or create a new document

Common Mistakes to Avoid

Mistake

Correct Approach

Creating a button from scratch

Search for existing button component, insert as ref

Using fill: "#3b82f6"

Use the variable: reference primary or the corresponding variable

Using cornerRadius: 8

Use the variable: reference radius-md or the corresponding variable

Generating bg-[#3b82f6] in code

Use semantic Tailwind class: bg-primary

Generating text-[var(--primary)] in code

Use semantic Tailwind class: text-primary

Generating rounded-[6px] in code

Use semantic Tailwind class: rounded-md

Using var(--primary) in className

Use semantic Tailwind class: bg-primary or text-primary

Not checking for overflow

Call pencil_snapshot_layout(problemsOnly: true) after every section

Skipping screenshots

Call pencil_get_screenshot after every section

Generating a new logo

Copy existing logo from another artboard with C()

Building entire screen, then checking

Build and verify section by section

Ignoring pencil_get_guidelines

Always call it for the relevant topic before starting

Using tailwind.config.ts

Use CSS @theme block (Tailwind v4)

Using Material Icons in code

Map to Lucide icons (<Search />, <ArrowRight />, etc.)

Skipping frontend-design skill

Always load it before designing in Pencil or generating code

Generic AI aesthetics (Inter font, purple gradients)

Follow frontend-design guidelines for distinctive, intentional design

Resources

• Pencil Docs

• Pencil Prompt Gallery

• Design as Code

• Variables

• Components

• Design to Code

• Styles and UI Kits