Pencil Design Skill

Design production-quality UIs in Pencil and generate clean, maintainable code from them. This skill enforces best practices for design system reuse, variable usage, layout correctness, visual verification, and design-to-code workflows.

When to Use This Skill

• Designing screens, pages, or components in a

  .pen

  file
• Generating code (React, Next.js, Vue, Svelte, HTML/CSS) from Pencil designs
• Building or extending a design system in Pencil
• Syncing design tokens between Pencil and code (Tailwind v4

  @theme

  , shadcn/ui tokens)
• Importing existing code into Pencil designs
• Working with any Pencil MCP tools (

  pencil_batch_design

  ,

  pencil_batch_get

  , etc.)

Critical Rules

These rules address the most common agent mistakes. Violating them produces designs that are inconsistent, hard to maintain, and generate poor code.

Rule 1: Always Reuse Design System Components

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

Before inserting any element, you MUST:

1. Call

   pencil_batch_get

   with

   patterns: [{ reusable: true }]

   to list all available reusable components
2. Search the results for a component that matches what you need (button, card, input, nav, etc.)
3. If a match exists, insert it as a

   ref

   instance using

   I(parent, { type: "ref", ref: "<componentId>" })

4. Customize the instance by updating its descendants with

   U(instanceId + "/childId", { ... })

5. 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:

1. Call

   pencil_get_variables

   to read all defined design tokens
2. Map your intended values to existing variables (e.g., use

   primary

   not

   #3b82f6

   , use

   radius-md

   not

   6

   )
3. Apply values using variable references, not raw values
4. 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:

1. Set appropriate text wrapping and truncation
2. Constrain widths to parent bounds, especially on mobile screens (typically 375px wide)
3. Use

   "fill_container"

   for width on text elements inside auto-layout frames
4. After inserting content, call

   pencil_snapshot_layout

   with

   problemsOnly: true

   to detect clipping/overflow
5. 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.):

1. Call

   pencil_get_screenshot

   on the section or full screen node
2. Analyze the screenshot for: alignment issues, spacing inconsistencies, text overflow, visual glitches, missing content
3. Call

   pencil_snapshot_layout

   with

   problemsOnly: true

   to catch clipping and overlap
4. Fix any issues found before moving to the next section
5. 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:

1. Call

   pencil_batch_get

   and search for existing image/logo nodes by name pattern (e.g.,

   patterns: [{ name: "logo|brand|icon" }]

   )
2. If a matching asset exists elsewhere in the document (another artboard/screen), copy it using the

   C()

   (Copy) operation
3. Only use the

   G()

   (Generate) operation for genuinely new images that don't exist anywhere in the document
4. 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

The

frontend-design

1. Load the

   frontend-design

   skill at the start of any Pencil design or code generation task
2. Follow its design thinking process: understand purpose, commit to a bold aesthetic direction, consider differentiation
3. Apply its guidelines on typography, color, motion, spatial composition, and visual details — both when designing in Pencil and when generating code from Pencil designs
4. 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.):

1. Plan - Identify which design system components to reuse
2. Build - Insert components as

   ref

   instances, apply variables for styles
3. Verify - Screenshot the section + check layout for problems
4. Fix - Address any overflow, alignment, or spacing issues
5. 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:

1. Load the

   frontend-design

   skill for aesthetic direction
2. Call

   pencil_get_guidelines

   with topic

   "code"

   and

   "tailwind"

3. Call

   pencil_get_variables

   to map design tokens to Tailwind

   @theme

   declarations
4. Read the design tree with

   pencil_batch_get

5. Map reusable Pencil components to shadcn/ui components (Button, Card, Input, etc.)
6. Generate code using semantic Tailwind classes (

   bg-primary

   ,

   rounded-md

   ), never arbitrary values
7. Apply

   frontend-design

   guidelines: distinctive typography, intentional color, motion, spatial composition
8. Use CVA for custom component variants,

   cn()

   for class merging, Lucide for icons

MCP Tool Quick Reference

pencil_get_editor_state

pencil_batch_get

reusable: true

pencil_batch_design

pencil_get_variables

pencil_set_variables

pencil_get_screenshot

pencil_snapshot_layout

pencil_get_guidelines

code

table

tailwind

landing-page

design-system

pencil_find_empty_space_on_canvas

pencil_get_style_guide_tags

pencil_get_style_guide

pencil_search_all_unique_properties

pencil_replace_all_matching_properties

pencil_open_document

Common Mistakes to Avoid

ref

fill: "#3b82f6"

primary

cornerRadius: 8

radius-md

bg-[#3b82f6]

bg-primary

text-[var(--primary)]

text-primary

rounded-[6px]

rounded-md

var(--primary)

bg-primary

text-primary

pencil_snapshot_layout(problemsOnly: true)

pencil_get_screenshot

C()

pencil_get_guidelines

tailwind.config.ts

@theme

<Search />

<ArrowRight />

frontend-design

frontend-design

Resources

• Pencil Docs
• Pencil Prompt Gallery
• Design as Code
• Variables
• Components
• Design to Code
• Styles and UI Kits