Getting Started with Pencil

This guide will help you set up Pencil and create your first design.

Prerequisites

Before starting, make sure you have:

• Pencil installed (Installation Guide)
• Claude Code CLI installed and authenticated
• A code editor (VS Code or Cursor) or the Pencil desktop app

Recommended First-Time Setup Flow

1. Authenticate Claude Code

Pencil requires Claude Code to be logged in for AI integration.

# Login to Claude Code
claude

Follow the authentication prompts in your browser.

2. Create Your First .pen File

In VS Code/Cursor:

1. Create a new file in your project: design.pen
2. Open the file - Pencil should activate automatically
3. If you don’t see the Pencil icon in the top right, open Command Palette (Cmd/Ctrl + Shift + P) and search for “Pencil”

In Desktop App:

1. Launch Pencil
2. Create a new file or open an existing .pen file
3. Right-click on the canvas and choose Open Welcome File to see examples

3. Explore the Welcome File

The welcome file contains:

• Example components and layouts
• Design system samples
• Quick tutorial on basic features

If you didn’t get the welcome file automatically:

• Right-click anywhere on the canvas
• Choose Open Welcome File
• It may open in a separate window

Working with Pencil and Claude Code

The recommended workflow combines Pencil’s visual canvas with Claude Code’s AI capabilities:

Basic Workflow

1. Save your .pen file into your project directory
2. Open a terminal in that directory
3. Run claude to start Claude Code
4. Return to Pencil and use Cmd/Ctrl + K to open the prompt panel
5. Ask Claude to help with your design

Example prompts:

• “Create a login form with email and password fields”
• “Design a dashboard with a sidebar and cards”
• “Add a button component to my design system”

Best Practices for New Projects

Adding Pencil to a Cursor Project

1. Create a new file like design.pen in your project workspace
2. Open it in Cursor
3. Activate Pencil (should happen automatically)
4. Keep the .pen file in the same workspace as your code so the AI agent can see both

File Organization

• Keep .pen files in your project repository
• Commit them to Git like any other source file
• Use descriptive names: dashboard.pen, components.pen, landing-page.pen

Next Steps

• Learn about Core Concepts - components, variables, and layers
• Explore Keyboard Shortcuts to speed up your workflow
• Set up Design to Code sync for your project
• Check the AI Integration guide for advanced AI workflows

Common First-Time Issues

Pencil says Claude Code isn’t connected:

• Make sure you’re logged in using claude CLI
• Check that Claude Code is running in your project directory

Don’t see the Pencil icon in VS Code/Cursor:

• Create and open a .pen file first
• Check the extension is installed and enabled
• Use Command Palette to search for Pencil commands

Activation code email not received:

• Check spam/junk folder
• Try a different email address
• Reinstall the extension if activation gets stuck

See the Troubleshooting guide for more help.