pencil-design

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 skill.

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

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)

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

Common Mistakes to Avoid

Resources

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