Add comprehensive README documentation
This commit is contained in:
DJP
parent
4591e5ee05
commit
8b98ff6cf6
1 changed files with 269 additions and 0 deletions
269
README.md
Normal file
269
README.md
Normal file
|
|
@ -0,0 +1,269 @@
|
|||
# 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:
|
||||
```bash
|
||||
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
|
||||
Loading…
Add table
Reference in a new issue