Heuristics Agent - Figma Plugin

Project Status: 🚧 In Development (Alpha)

A Figma plugin that uses Large Language Models (LLMs) to analyze design comments and selections, providing UX feedback based on established frameworks (e.g., Nielsen Heuristics, Gestalt Principles).

---

🏗 Architecture

This project is a Monorepo managed by npm workspaces.

Structure

.
├── packages/
│   ├── plugin/      # Figma Plugin (Client)
│   │   ├── src/ui   # React UI (iframe)
│   │   └── src/code # Main thread logic verification
│   └── backend/     # API Service (Server)
│       ├── app/     # Next.js App Router
│       └── supabase/# Database Schema
└── package.json     # Root Manifest

Technology Stack

• Plugin: React 19, Vite (Single File Build), TypeScript.
• Backend: Next.js 15, Supabase (Postgres), Node.js.
• Authentication: Figma OAuth 2.0.
• Design System: Vanilla CSS (Plugin), Custom (Backend).

---

🚀 Getting Started

Prerequisites

• Node.js (v18+) and npm
• A Supabase project
• A Figma account

1. Installation

Clone the repo and install dependencies only at the root:

npm install

2. Environment Setup

Backend

Create a .env.local file in packages/backend/:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
# Add future keys here (FIGMA_CLIENT_ID, etc.)

Initialize your database by running the SQL found in packages/backend/supabase/schema.sql.

3. Running Locally

You can run both the plugin builder and the backend server from the root:

# Start Plugin Compiler (Watch Mode) + Backend Server
npm run dev

Alternatively, run them individually:

# Backend only (localhost:3000)
npm run dev --workspace=packages/backend

# Plugin only (Watch mode)
npm run dev --workspace=packages/plugin

4. Load in Figma

1. Open Figma Desktop App.
2. Go to Plugins > Development > Import plugin from manifest...
3. Select packages/plugin/manifest.json.
4. Run the plugin!

---

🛣 Roadmap & Next Steps

Phase 1: Foundation (Complete ✅)

• Monorepo Setup
• Plugin & Backend Scaffolding
• Database Schema Definition
• Implement Figma OAuth Handshake

Phase 2: Core Analysis (Current)

• Implement Comment Fetching (Figma REST API)
• Connect Plugin to Backend API (Analysis flow)
• Implement Parsing (Node -> Properties)
• Integrate LLM (Google Gemini)
• Next: Fine-tune UX analysis prompts and test with real designs

Phase 3: Monetization

• Implement RBAC (Free/Paid Tiers)
• Add Admin Dashboard
• Implement usage tracking and limits

---

📝 Commands Reference

Command	Description
npm run build	Build all packages for production.
npm run dev	Run dev servers for all packages.
npm run test	Run tests across the monorepo.