Pencil.dev / .pen file import

# Pencil.dev Sync for Figma> ⚠️ **Alpha Release** — This plugin was built through vibe coding by Martin Dubois from [QuatreCentQuatre](https://quatrecentquatre.com) to explore and test workflows between [Pencil](https://pencil.dev) and Figma. Depending on reception and usage, this project may be maintained long-term or evolve from prototype to production-ready status.A Figma plugin to import and export `.pen` files from [pencil.dev](https://pencil.dev), enabling bidirectional sync between your Pencil designs and Figma projects.## ✨ Features- **📥 Import** `.pen` files into Figma with full structure preservation- **🖼️ Local images** support via folder upload- **🧩 Components** support with instances and overrides- **🌍 Multilingual** UI (English / French, auto-detected)- **📍 Positioning** — Choose where to place imports on your canvasupcoming:- **📤 Export** Figma elements back to `.pen` format (for now use Pencil's paste from Figma feature)- **🔄 Bidirectional sync** via `pencilId` metadata stored in Figma nodes## 🚀 Installation### Manual Installation (Development)1. **Download or clone this repository**2. **Import into Figma**:- Open Figma Desktop- Go to **Plugins** → **Development** → **Import plugin from manifest...**- Select the `manifest.json` file from this folder3. **Run the plugin**:- **Plugins** → **Development** → **Pencil.dev Sync**## 📖 Usage### Importing a .pen file1. Open the plugin2. Stay on the **📥 Import** tab3. Drag & drop your `.pen` file or click to select4. If your design has local images, click **Select images folder** and choose the folder containing your images5. Click **Next →**6. Navigate to where you want the import on your Figma canvas7. Click **📍 Place here**### Exporting to .pen1. Open the plugin2. Switch to the **📤 Export** tab3. Choose export mode:- **Export selection** — Only selected elements- **Export synced elements** — All elements previously imported from a `.pen` file4. Click **📤 Export**5. A `.pen` file will be downloaded## 🎨 Supported Elements| Pencil Type | Figma Conversion ||-------------|------------------|| `frame` | Frame (or Component if `reusable: true`) || `ref` | Component Instance || `text` | Text with styles || `rectangle` | Rectangle || `ellipse` / `circle` | Ellipse || `image` | Frame with image fill || `group` | Group || `line` | Line || `vector` / `path` | Vector |### Supported Properties- **Layout**: `vertical`, `horizontal`, `none` (auto-layout)- **Dimensions**: Fixed, `fill_container`, `hug_contents`- **Flexbox**: `justifyContent`, `alignItems`, `gap`- **Padding**: Number, `[vertical, horizontal]`, or `[top, right, bottom, left]`- **Color variables**: `$red`, `$white`, etc. (via `variables` object)- **Fills**: Hex, rgb, rgba, and color tokens- **Strokes**: `{ thickness: 1, fill: "$black" }`- **Corner radius**: Number or array of 4 values- **Text**: `content`, `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `textAlign`- **Components**: `reusable: true` creates Figma Components- **Instances**: `type: "ref"` with `ref: ""` and `descendants` overrides## 🔄 Sync MechanismWhen importing, each element stores its Pencil ID as invisible metadata:```javascriptfigmaNode.setPluginData('pencilId', 'xvJuI');figmaNode.setPluginData('pencilSync', 'true');```This enables:- Finding elements by their original Pencil ID- Re-exporting with preserved IDs for Pencil to match- Tracking which elements are part of the sync## 📁 .pen File FormatThe plugin supports the native pencil.dev format:```json{"version": "2.6","variables": {"white": { "type": "color", "value": "#FFFFFF" },"red": { "type": "color", "value": "#FF5046" }},"children": [{"type": "frame","id": "header1","name": "Header","reusable": true,"width": "fill_container","height": 80,"fill": "$white","layout": "horizontal","padding": [0, 80],"justifyContent": "space_between","alignItems": "center","children": [...]},{"type": "ref","id": "headerInstance1","ref": "header1","name": "Header Instance","descendants": {"titleText": { "content": "New Title" }}}]}```## 🐛 Known Limitations- **Images**: Local images require manual folder selection; URLs must be absolute- **Fonts**: Falls back to Inter if a font is not available- **Complex vectors**: May lose some path data in conversion- **Nested components**: Deep nesting may have edge cases## 🔧 Development### Project Structure```figma-pencil-importer/├── manifest.json # Plugin configuration├── code.js # Main logic├── ui.html # User interface├── example.pen # Example file└── README.md # This file```### Testing Changes1. Edit the source files2. In Figma, right-click the plugin → **Run Last Plugin** or relaunch from the menu## 📝 Changelog### v0.1.1-alpha- Improved handling of nested components### v0.1.0-alpha- Initial alpha release- Import/Export functionality- Component and instance support- Local image upload- Bidirectional sync via pluginData- English/French localization- Canvas positioning for imports## 👨‍💻 Author**Martin Dubois** — [QuatreCentQuatre](https://quatrecentquatre.com)Built with Claude (Anthropic) through vibe coding sessions.## 📄 LicenseMIT License — See LICENSE file for details.## 🔗 Links- [Pencil.dev](https://pencil.dev) — The design tool for IDEs- [QuatreCentQuatre](https://quatrecentquatre.com) — Digital agency- [Figma Plugin API](https://www.figma.com/plugin-docs/)