PencilAutomator - Figma Plugin

📋 Overview

PencilAutomator is a powerful Figma plugin designed to automate the creation and management of product feature assets. It streamlines the workflow for creating ATF (Above The Fold), BTF (Below The Fold), and Banner variations by processing Excel spreadsheets and automatically generating or updating Figma instances with images, overlays, and proper naming conventions.

✨ Features

🚀 Core Functionality

• Excel-Driven Automation: Load product data from Excel spreadsheets (.xlsx, .xls, .csv)
• Batch Image Processing: Import entire folders of images and automatically match them to components
• Smart Component Creation: Automatically creates instances from templates based on Excel data
• Image Replacement Mode: Update existing assets without recreating the entire structure
• Bulk Export: Export all generated assets as PNG files in a single ZIP archive
• Intelligent Naming: Generates standardized filenames following the pattern:

  Cycle_CodeName_ProductName_Color_Variation_FeatureAssociation_ATF/BTF_Dimension.PNG
  

🎨 Asset Types Supported

1. Ports (2000x1000)
2. ATF (Above The Fold) - Multiple dimensions
3. BTF (Below The Fold) - Multiple dimensions
4. BTF_Banner - Thin (1464x250) and Wide (1464x600) variants

🎯 Template Support

• B (Balanced)
• LS (Left Screen)
• RS (Right Screen)
• LSC (Left Screen Centered)
• RSC (Right Screen Centered)
• LF (Left Fit)

📊 Excel Spreadsheet Format

Metadata Section (Rows 5-8)

The plugin reads metadata from the first 8 rows:

Row	Column A	Column B
5	Code Name	[Your Code Name]
6	Product Name	[Your Product Name]
7	Cycle	[Your Cycle]
8	Color	[Your Color]

Data Section (Row 12+)

Starting from row 12, the plugin expects the following columns:

Column	Name	Description
A	Feature Association	Feature number or identifier (e.g., "Ports", "Feature 1")
B	(unused)	Reserved
C	Variation	Optional variation identifier
D-E	(unused)	Reserved
F	ATF Trigger	Dimension for ATF asset (e.g., "1920x1080")
G	BTF Trigger	Dimension for BTF asset (e.g., "1920x1080")
H	BTF_Banner Trigger	Dimension for banner (e.g., "1464x250", "1464x600")
I	Image Filename	Name of the main image file
J	Screen Replacement	Name of the screen overlay image
K	Overlay Component	Name of the Figma component to use as overlay
L	Template	Template type (B, LS, RS, LSC, RSC, LF)

Example Data Row

Feature 1 | | Var1 | | | 1920x1080 | 1920x1080 | 1464x600 | hero.png | screen.png | IconOverlay | B

🛠️ Installation

Prerequisites

• Figma Desktop App (recommended) or Figma in browser
• Access to Figma plugin development mode

Steps

1. Clone or Download this repository:

   git clone git@bitbucket.org:zlalani/pencil_automator.git
   cd pencil_automator
   

2. Open Figma and navigate to:

   • Menu → Plugins → Development → Import plugin from manifest...

3. Select the manifest.json file from this repository

4. Run the Plugin:

   • Menu → Plugins → Development → PF_Automator

📖 Usage Guide

1️⃣ Prepare Your Figma File

Before running the plugin, ensure your Figma file contains the necessary component templates:

Required Components:

• PB3.0_Ports - For port diagrams
• ATF_B, ATF_LS, ATF_RS - ATF templates
• BTF_B, BTF_LS, BTF_RS - BTF templates
• BTFB_Thin, BTFB_B, BTFB_LS, BTFB_RS, BTFB_LSC, BTFB_RSC - Banner templates

Component Structure:

Each component should contain a layer named "Image" where the main image will be placed.

2️⃣ Prepare Your Assets

1. Excel File: Create your spreadsheet following the format above
2. Image Folder: Organize all your images in a single folder
   • Ensure filenames match those specified in columns I and J of your Excel

3️⃣ Run the Automation

1. Load Excel File:

   • Drag & drop your .xlsx file or click to browse
   • The plugin will display metadata and row count

2. Select Image Folder:

   • Click "Choose Folder" and select your image directory
   • The plugin will show the number of images loaded

3. Choose Operation:

   • Run Automation: Creates new instances from templates

     • Generates new assets on designated pages
     • Applies images, overlays, and naming
     • Positions assets vertically with spacing

   • Replace Images Only: Updates existing assets

     • Finds assets by name
     • Replaces images without recreating structure
     • Useful for updating visuals

   • Export ZIP: Exports all assets

     • Scans designated pages (Ports, ATF, BTF, BTF_Banner)
     • Exports each asset as PNG (2x scale)
     • Downloads as pf_automator_export.zip

4️⃣ Monitor Progress

The status window shows real-time logs:

• ✅ Success messages (green)
• ℹ️ Info messages (white)
• ⚠️ Warnings (yellow)
• ❌ Errors (red)

🎨 How It Works

Image Scaling Modes

• FIT: Used for RS and LF templates (maintains aspect ratio)
• FILL: Used for all other templates (fills the frame)

Overlay Logic

When an overlay component is specified:

1. The overlay is scaled to max 20% of instance width
2. Centered over the "Image" layer
3. Grouped with the main instance
4. Named using the standard naming convention

Screen Replacement

When a screen replacement image is provided:

1. A new layer named "ScreenReplacement" is created
2. Positioned on top of the main "Image" layer
3. Uses FIT scaling mode for proper display

Ports Special Handling

The "Ports" feature:

• Uses the existing PB3.0_Ports instance on the Ports page
• Renames it according to the naming convention
• Centers the image within the frame
• Dimension is always 2000x1000

📁 Project Structure

pencil_automator/
├── manifest.json       # Plugin configuration
├── code.js            # Main plugin logic
├── ui.html            # User interface
└── README.md          # This file

🔧 Technical Details

Dependencies

• XLSX.js (v0.18.5) - Excel file parsing
• JSZip (v3.10.1) - ZIP file generation

Figma API Usage

• Component creation and manipulation
• Image fills and paint properties
• Layer positioning and grouping
• Export functionality

Page Organization

The plugin creates/uses these pages:

• PB3.0_Ports: Port diagrams
• ATF: Above-the-fold assets
• BTF: Below-the-fold assets
• BTF_Banner: Banner assets

⚠️ Limitations & Known Issues

1. Component Search: The plugin searches for components locally in the current file. External library components may not be found.

2. Large Files: Processing hundreds of assets may take time. Monitor the status window for progress.

3. Memory: Loading many large images simultaneously may impact performance.

4. Naming Conflicts: If assets with identical names exist, the plugin may update the wrong asset in "Replace Images Only" mode.

🐛 Troubleshooting

"Component not found" Error

• Ensure all required template components exist in your Figma file
• Check component naming matches exactly (case-sensitive)

Images Not Loading

• Verify image filenames in Excel match actual files
• Ensure images are in supported formats (PNG, JPG, etc.)

Export Fails

• Check that assets exist on the designated pages
• Ensure assets are visible (not hidden)

Automation Stalls

• Check the status window for error messages
• Verify Excel data format matches specifications
• Ensure all required columns have data

🤝 Contributing

This is a private repository. For questions or issues, contact the repository owner.

📄 License

Proprietary - All rights reserved

👤 Author

Created for internal use at [Your Organization]

📞 Support

For support or questions:

• Create an issue in the Bitbucket repository
• Contact: [Your Contact Information]

---

Last Updated: January 2026
Version: 1.0.0
Figma API: 1.0.0