Figma
Hierarch connects with Figma to embed design files as first-class artifacts, sync Figma URLs to Linear issues as attachments, access file metadata and design tokens, and link Hierarch tasks as dev resources inside Figma.
Capabilities
- Figma URL validation against
figma.com/(file|design|proto|board)/ - oEmbed thumbnail generation for file previews
- Dedicated "Figma" artifact type with URL field and preview rendering
- Automatic attachment sync to Linear issues (create, update, delete)
- File metadata access (name, last modified, version, thumbnail)
- Recent files list for quick access
- Design token and variable access via the Variables API
- Dev resource linking (Hierarch tasks linked to Figma nodes)
- Comments on specific design nodes referencing task phase and status
Authentication
The Figma integration uses OAuth 2.0. When registering Hierarch as a Figma OAuth application:
| Application Name | Hierarch |
| Redirect URI (prod) | https://hierarch.vercel.app/api/auth/callback/figma |
| Redirect URI (dev) | http://localhost:3000/api/auth/callback/figma |
| OAuth 2.0 Grant Type | Authorization Code |
Required OAuth Scopes
| files:read | Read file metadata, nodes, images, and comments |
| file_dev_resources:read | Read dev resources and design tokens |
| file_dev_resources:write | Create and update dev resource links back to Hierarch tasks |
Data Hierarch Reads
- File metadata (name, last modified, version, thumbnail) via oEmbed and REST API
- User's recently accessed files
- File components and styles
- Design tokens (via Variables API)
- Comments on specific file nodes
Data Hierarch Writes
- Dev resource links (linking Hierarch tasks to Figma nodes)
- Comments on specific design nodes referencing task status
- Figma URL attachments synced to Linear issues (see the Linear integration docs for details on attachment sync)
URL Validation
Hierarch validates Figma URLs against this pattern before accepting them:
figma.com/(file|design|proto|board)/[fileKey]
Valid examples:
https://www.figma.com/file/abc123/My-Design https://www.figma.com/design/abc123/My-Design https://www.figma.com/proto/abc123/My-Prototype https://www.figma.com/board/abc123/My-Board
oEmbed Endpoint
Hierarch fetches Figma file metadata using the oEmbed protocol:
GET https://www.figma.com/api/oembed ?url=https://www.figma.com/file/[fileKey]/[fileName] &format=json
The response includes a thumbnail URL, file title, and dimensions. This endpoint works for files with link sharing enabled.
REST API Endpoints
Hierarch uses these Figma REST API endpoints:
| Endpoint | Method | Purpose |
|---|---|---|
| /v1/files/:key | GET | File metadata and node tree |
| /v1/files/:key/comments | GET | Comments on a file |
| /v1/files/:key/comments | POST | Post a comment (phase/status updates) |
| /v1/me | GET | Authenticated user profile |
| /v1/me/files/recent | GET | User's recently accessed files |
| /v1/files/:key/variables/local | GET | Design tokens and variables |
Artifact Storage
Figma artifacts are stored as part of the Hierarch artifact system. Each Figma artifact includes:
{
id: string,
title: string,
text: string, // rich text notes about the file
type: "figma",
url: string, // validated Figma URL
projectId?: string,
taskId?: string,
timestamp: string, // ISO 8601
updatedAt: string // ISO 8601
}