IconAutomation

About this plugin

### **Comprehensive Guide to the IconAutomation Figma Plugin**

#### **Introduction**

**IconAutomation** is a powerful tool designed to streamline and automate the process of publishing icons within Figma. By integrating with GitLab CI, this plugin ensures your icon sets are always up-to-date and consistent across all platforms. Whether you're a designer working on a small project or part of a large team managing complex design systems, IconAutomation saves time and effort while eliminating manual workflows.

This plugin is primarily tailored for enterprise scenarios. Our company aims to build an internal icon library using Figma and GitLab as a replacement for Iconfont, which suffers from the following limitations:

- **Management Complexity**: Managing Iconfont requires multiple accounts and frequent importing/exporting between design files, Iconfont platforms, and code repositories.

- **Icon Accumulation**: Over time, unused icons accumulate and are loaded all at once in projects, preventing on-demand loading.

- **Font-Based Limitations**: Font-based icons may render blurry or pixelated on high-resolution screens.

- **Icon Conflicts**: Conflicts can arise when using multiple Iconfont libraries, leading to incorrect icon displays.

IconAutomation addresses these issues by leveraging SVGs to build a scalable internal icon library. Once configured, updating both the icon library and code repository can be done with a single click. Unlike font-based solutions, SVGs enable granular control over icon usage—only the icons actually used in a project are bundled, preventing unnecessary bloat.

#### **Core Features**

- **One-Click Publishing**: Publish icons directly from Figma with a single action.

- **GitLab Integration**: Seamlessly connect with GitLab CI/CD pipelines for automated workflows.

- **Version Control**: Automatically manage semantic versioning in `package.json`.

- **Diff Generation**: Compare current and historical icons to generate detailed change reports.

- **Branch Automation**: Create feature branches, submit merge requests (MRs), and clean up temporary branches automatically.

- **SVG Optimization**: Optimize icon assets for performance using industry-standard tools.

#### **Prerequisites**

- **GitLab Instance**: A deployed GitLab instance (cloud-based or self-hosted).

- **Template Repository**: Deploy the `react-icons` template repository to your GitLab instance.

- **Figma Client**: Install the IconAutomation plugin via Figma's Community portal.

- **Plugin Configuration**: Configure essential settings as outlined below.

#### **Configuration Guide**

##### **GitLab Settings**

- **Domain**: The URL of your GitLab instance (e.g., `https://gitlab.com`).

- **Project ID**: Found under your repository’s **Settings > General**.

- **Access Token**: Generate a token with `api`, `read_repository`, and `write_repository` scopes from GitLab’s **Profile > Access Tokens**.

##### **Figma Plugin Setup**

1. Install the plugin and grant necessary permissions.

2. Navigate to the plugin settings and input your GitLab domain, project ID, and access token.

3. Validate the connection to ensure seamless integration.

#### **Design Specifications**

##### **Page Naming Conventions**

- Pages intended for publishing **must** include the keyword "icon" (e.g., `product-icons`, `system-icons`).

- Only frames under these pages will be processed by the plugin.

##### **Frame Requirements**

- Frames must be named with one of the following suffixes:

- **Outlined**: For icons with stroke-based designs (e.g., `Navigation-Outlined`).

- **Filled**: For solid-filled icons (e.g., `Actions-Filled`).

- **Colored**: For multi-color icons, further categorized as:

- **Light**: Optimized for light backgrounds.

- **Dark**: Optimized for dark backgrounds.

##### **Icon Layer Rules**

- All icons **must** be Figma components (not frames or groups).

- Verify component status by selecting a layer—the top panel should display "Component."

##### **Naming Standards**

- Use **Upper Camel Case** (e.g., `AlertCircle`, `SettingsGear`).

- Append style suffixes (e.g., `AlertCircleOutlined`, `SettingsGearFilled`).

- Avoid special characters (`-`, `_`, spaces) and numeric suffixes unless intrinsic to the icon’s name (e.g., `Star1` is allowed; `Star 1` is invalid).

- Ensure uniqueness within each category to prevent conflicts.

#### **Automated Workflow**

1. **Repository Setup**: Configure GitLab details in the plugin settings.

2. **Local Validation**:

- The plugin checks for naming compliance, duplicates, and structural errors.

- Invalid icons are flagged with actionable feedback.

3. **Branch Management**:

- A temporary branch (e.g., `figma-update-20231001`) is created from `master`.

- Semantic versioning updates `package.json` (e.g., `1.2.0` → `1.3.0` for minor changes).

4. **Diff Analysis**:

- Compares current icons against the latest `master` commit.

- Generates a report detailing additions, modifications, and deletions.

5. **Asset Export**:

- Exports SVGs via Figma’s API and organizes them into folders (e.g., `/outlined`, `/filled`).

- Applies SVGO optimizations to reduce file size.

6. **Merge Request (MR)**:

- Submits an MR with a standardized title (e.g., `[Figma]: add icons`).

- Auto-merges after passing CI checks (linting, build tests).

#### **Best Practices**

- **Consistent Naming**: Adhere strictly to naming conventions to avoid validation failures.

- **Modular Design**: Build icons as reusable components with standardized dimensions (e.g., 24x24px).

- **Version Tracking**: Maintain a `CHANGELOG.md` to document icon updates and deprecations.

- **Performance Checks**: Audit SVG complexity to ensure optimal rendering (e.g., simplify paths for small icons).

#### **Example Scenarios**

##### **Scenario 1: Updating an Icon Set**

1. Add new icons to the `Actions-Filled` frame in Figma.

2. Run the plugin to validate and generate diffs.

3. Submit an MR to deploy changes to production.

##### **Scenario 2: Migrating Legacy Iconfont Icons**

1. Import existing Iconfont SVGs into a `Legacy-Outlined` frame.

2. Use the plugin to publish them as SVGs and update project imports.

#### **Troubleshooting**

| Issue | Solution |

| ------------------------ | ------------------------------------------------------------------------------ |

| **Naming Errors** | Check for invalid characters or duplicates using the plugin’s validation tool. |

| **Merge Conflicts** | Resolve conflicts manually in GitLab before re-running the plugin. |

| **API Timeouts** | Increase timeout thresholds in GitLab CI settings or split large icon sets. |

| **SVG Rendering Issues** | Convert strokes to outlines and simplify complex paths in Figma. |

#### **Future Roadmap**

- [ ] **GitHub Integration**: Support publishing to GitHub repositories.

- [ ] **Change Preview**: Display a summary of icon changes before publishing.

- [ ] **Enhanced Error Handling**: Provide contextual error messages with resolution steps.

- [ ] **Progress Tracking**: Add a visual progress bar for long-running tasks.

#### **Additional Resources**

- **Figma Documentation**: [Figma Help Center](https://help.figma.com)

- **GitLab CI/CD Guide**: [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)

- **Community Support**: Join discussions on Figma’s [Community Forum](https://forum.figma.com).