Skip to Content
Core Concepts

Core Concepts

Understanding these fundamental concepts will help you work effectively with Pencil.

.pen Files

What are .pen files?

.pen files are Pencil’s design file format:

  • JSON-based - Structured, readable data format
  • Encrypted - Content is encrypted for security
  • Version-control friendly - Works with Git like any code file
  • Portable - Share files across teams and platforms

Working with .pen files

Creating:

  • In IDE: Create a new file with .pen extension
  • In Desktop: File → New or Cmd/Ctrl + N

Opening:

  • Double-click .pen files
  • Open in IDE like any other file
  • Pencil activates automatically

Saving:

  • Cmd/Ctrl + S to save
  • Note: Auto-save is not yet available - save frequently!
  • Use Git commits for version history

Best Practices:

  • Save frequently (no auto-save yet)
  • Commit to Git regularly for version history
  • Keep .pen files in your project workspace alongside code
  • Use descriptive names: dashboard.pen, components.pen

Components

Component Types

Regular Elements:

  • Standard design elements (frames, shapes, text)
  • Blue bounding box when selected
  • Can be converted to reusable components

Reusable Components:

  • Component symbols that can be reused
  • Purple/magenta bounding box when selected
  • Changes to the main component update all instances
  • Similar to Figma components or React components

Creating Reusable Components

Convert an element:

  1. Select the element
  2. Press Cmd/Ctrl + Option/Alt + K
  3. Deselect and reselect to see the purple highlight

Why use components:

  • Maintain consistency across designs
  • Update all instances by editing one
  • Build design systems
  • Sync with code components

Design Systems

Pencil includes pre-built design kits:

  • Shadcn UI - Popular React component library
  • Halo - Modern design system
  • Lunaris - Design system
  • Nitro - Design system

These provide ready-to-use components for common UI patterns.

Layers & Navigation

Layers Panel

Pencil includes a layers panel similar to Figma:

  • View your design hierarchy
  • Navigate complex nested structures
  • Select elements by name
  • Organize your canvas

Keyboard Navigation

Navigate without the layers panel using shortcuts:

Direct Selection:

  • Cmd/Ctrl + Click - Select deepest element under cursor
  • Bypasses parent containers

Parent Selection:

  • Shift + Enter - Select parent of current selection
  • Cmd/Ctrl + Enter - Alternate shortcut for parent selection

Moving through hierarchy:

  • Use these shortcuts to quickly navigate nested elements
  • Combine with layer panel for complex designs

Variables & Design Tokens

What are Variables?

Variables in Pencil are like CSS custom properties or design tokens:

  • Define colors, spacing, typography once
  • Use throughout your design
  • Change the variable to update everywhere
  • Sync with code (CSS variables, Tailwind config)

Creating Variables

From CSS:

  • Ask the AI agent to create variables from your globals.css
  • Automatically extracts colors, spacing, fonts

From Figma:

  • Copy/paste tokens from Figma
  • Or paste screenshots of token tables
  • Ask the agent to create variables from them

Manual:

  • Define variables directly in Pencil
  • Set values for different themes

Using Variables

Apply to elements:

  • Instead of hardcoded values, reference variables
  • Changes propagate automatically

Sync with code:

  • Update variables in Pencil → sync to CSS
  • Update CSS → import back to Pencil
  • Enables two-way design ↔ code workflow

Theming:

  • Define different values per theme (light/dark mode)
  • Switch themes to see designs adapt

Selection & Highlighting

Selection Colors

Blue bounding box:

  • Regular element selection
  • Standard frames, shapes, text

Purple/magenta bounding box:

  • Reusable component / symbol
  • Indicates this element is a component instance

Selection Shortcuts

  • Click - Select element
  • Cmd/Ctrl + Click - Direct select (deepest element)
  • Shift + Click - Add to selection
  • Cmd/Ctrl + A - Select all

Canvas & Workspace

Infinite Canvas

  • Unlimited workspace for your designs
  • Pan by dragging (spacebar + drag)
  • Zoom with trackpad or Cmd/Ctrl + scroll
  • Spacebar + Drag - Pan canvas
  • Shift + Scroll - Horizontal pan
  • Cmd/Ctrl + 0 - Zoom to fit
  • Cmd/Ctrl + 1 - Zoom to 100%

Frames

Frames are containers for your designs:

  • Group related elements
  • Define screen boundaries
  • Create component variants
  • Cmd/Ctrl + Option/Alt + G - Create frame from selection

Import & Export

Importing

Images:

  • Drag and drop - Works reliably on all platforms
  • File menu - May have issues on macOS, use drag-drop instead
  • Supported: PNG, JPEG, SVG

From Figma:

  • Copy elements from Figma
  • Paste in Pencil
  • Note: Images don’t copy from Figma, use SVG or re-import

Icons:

  • Built-in: Material Icons library
  • Custom: SVG paths supported
  • For code generation: Specify icon library in prompts (Lucide, Heroicons)

Exporting

To Code:

  • Use AI agent to export designs to React/code
  • Press Cmd/Ctrl + K and ask to generate code

Images:

  • Export frames as PNG/SVG
  • Right-click frame → Export

Collaboration & Version Control

Git Integration

  • Commit .pen files like code files
  • View diffs in Git (text-based format)
  • Branch and merge designs with code

Best Practices:

  • Frequent commits
  • Descriptive commit messages
  • Keep designs in sync with code branches

Real-time Collaboration

  • Not currently available
  • Collaboration via Git only
  • Use Git workflow: pull, edit, commit, push, PR

Undo / Redo

Current Limitations

  • Undo/redo may be more limited than standard code editors
  • Recommendation: Save frequently and use Git commits

Workarounds:

  • Commit to Git before major changes
  • Save often (Cmd/Ctrl + S)
  • Use Git history to revert if needed

Next Steps

Now that you understand core concepts:

Last updated on
InstallationAuthentication