Figmalytics

Figma Plugin for Data Visualization in Figma.
Import CSV data exported from Firebase or Google Analytics and visualize it directly in your Figma file by mapping key values to design elements.

✨ Features

1. Click / Heatmap Verification: Map click and heatmap data directly to your design layers.
2. Before / After Comparison: Compare changes in metrics over time.
3. Funnel Analysis: Build step-by-step flows and check overall & per-step conversion rates.

🚀 Quick Start (Using the Prebuilt Plugin)

Prerequisite: A manifest.json file is provided.

1. Open Figma Desktop (not the browser version).
2. From the top menu: Plugins → Development → Import plugin from manifest…
3. Select the project’s manifest.json.
4. After import, open your Figma file → Plugins → Development → Figmalytics.
5. In the panel: Upload CSV → Map keys → Apply visualization.

Tip: If you update the code, refresh via Plugins → Development → Reload plugins.

📦 CSV Format Guide (Summary)

• Required columns (example):
  • node_key: Key to match Figma layers/components (layer name or plugin data key)
  • metric: Metric name (e.g., clicks, views, conversion)
  • value: Numeric value
  • timestamp (optional): YYYY-MM-DD or ISO 8601

node_key,metric,value,timestamp
btn_primary,clicks,123,2025-08-01
hero_banner,views,2045,2025-08-01
step_2,conversion,0.37,2025-08-01

• Key Matching Tips:
  • Match node_key with layer names or custom plugin keys.
  • If multiple layers share a key, the first match takes priority (you can remap inside the panel).

🏗 Architecture

System Flow (Overview)

flowchart LR
  subgraph External["External Data Sources"]
    GA["Google Analytics (CSV)"]
    FB["Firebase (CSV)"]
    CSV["Local CSV Files"]
  end

  subgraph Plugin["Figmalytics Plugin (Figma Desktop)"]
    subgraph UI["UI Thread"]
      UP["Upload Panel"]
      MAP["Key Mapping UI"]
      CTRL["Controls"]
      PREV["Preview & Apply"]
    end

    subgraph MAIN["Main Thread"]
      PARSER["CSV Parser"]
      MATCHER["Mapping Engine"]
      RENDER["Visualization Renderer"]
      STORE["Client Storage"]
    end

    DOC["Figma Document API"]
  end

  External --> UI
  UI <--> MAIN
  MAIN <--> DOC
  MAIN <--> STORE

Loading

Import → Map → Visualize (Sequence)

sequenceDiagram
  participant U as User
  participant UI as Plugin UI
  participant M as Main Thread
  participant F as Figma API
  participant S as Client Storage

  U->>UI: Select CSV file
  UI->>M: Send CSV data
  M->>M: Parse CSV rows
  M->>S: Save mapping & prefs
  M->>F: Query Figma nodes
  M->>M: Match node_key to layers
  UI->>M: Apply visualization
  M->>F: Render overlays & metrics
  M-->>UI: Send summary result
  UI-->>U: Display visualization

Loading

🧰 Local Development (For Developers)

Recommended: Node.js 18+ (LTS)

1. Clone the repository:

   git clone <your-repo-url>
   cd figmalytics

2. Register the plugin in Figma:
   • Plugins → Development → Import plugin from manifest…
   • Select the root manifest.json (make sure it points to the build output).
3. Modify & reload:
   • Keep npm run dev running for hot builds.
   • After edits, use Reload plugins in Figma.

🔐 Permissions (from manifest.json)

• permissions: Local file access (CSV), file read/write
• editorType: figma or figjam
• ui / main: Entry points for bundled files

Update the manifest if permissions or build outputs change, then reload the plugin.

🧯 Troubleshooting

• Import fails → Check manifest.json syntax (trailing commas, quotes).
• Plugin not visible → Only works in Figma Desktop, not in the browser.
• CSV encoding issues → Save as UTF-8, delimiter , (comma).
• Key mapping not working → Ensure consistent naming between CSV and layer keys.

📚 Links

• figmalytics

🤝 Contributing Guidelines

Contributions welcome! Please read the contributing guidelines.

📄 License

Copyright 2025 LY Corporation

LY Corporation licenses this file to you under the Apache License,
version 2.0 (the "License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at:

  https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.