New Integration: Figma

[AggManik]

Description

Add Figma integration to sync design files, comments, and project activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - Similar webhook and event-based system
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference on comment/notification syncing

Required Files Structure

integrations/figma/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Figma API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Figma API Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code flow)
• Base URL: https://api.figma.com
• Required scopes:
  • file_content:read - Read access to file content (replaces deprecated files:read)
  • file_comments:read - Read access to file comments
  • file_comments:write - Write access to file comments
  • file_dev_resources:read - Read access to dev resources
  • webhooks:write - Manage webhooks for real-time updates

Key Endpoints

• GET /v1/files/:file_key - Get file data
• GET /v1/files/:file_key/comments - Get file comments
• GET /v1/files/:file_key/versions - Get file version history
• GET /v1/teams/:team_id/projects - List team projects
• GET /v1/projects/:project_id/files - List project files
• POST /v2/webhooks - Create webhooks for real-time events
• GET /v1/files/:file_key/images - Export images from files

Rate Limits

• Updated rate limits as of November 2025
• OpenAPI specification available at figma/rest-api-spec GitHub repository

Events to Track

1. File Activity - File created, updated, renamed, deleted
2. Comments - Comment created, replied to, resolved, deleted
3. Version History - New versions published
4. Team Activity - Files added/removed from projects
5. Component Updates - Components published or updated in libraries

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts (note: new OAuth app publishing requirements as of Nov 2025)
• Create API utilities in utils.ts with updated scopes (file_content:read instead of deprecated files:read)
• Implement sync logic in schedule.ts for files, comments, and versions
• Set up webhook handling for real-time file and comment events
• Convert Figma events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Figma REST API uses https://api.figma.com as the base URL
• Full OpenAPI spec available in the figma/rest-api-spec GitHub repository for type generation
• The files:read scope is deprecated; use specific scopes like file_content:read and file_comments:read
• Webhook support available for real-time event notifications
• PNG export quality bug was fixed on January 26, 2026

Resources

• Figma REST API Documentation
• Figma REST API Changelog
• Figma OpenAPI Spec (GitHub)
• Figma Rate Limits
• Figma Developer Docs

Labels

enhancement, integration, new-feature