@render-harness/cap-figma

Figma capability pack for the Render Agent Harness. First pack with granular per-action OAuth scopes (post-Nov-2025 Figma platform update).

Tools cover files, projects/teams, and comments; the pack reads via accessMode: "read" or "read + post comments" via accessMode: "read_write_comments" (default).

Install

pnpm add @render-harness/cap-figma

Configure

capabilities:
  - pack: "@render-harness/cap-figma"
    config:
      accessMode: read_write_comments   # or "read"

Env vars on the harness service:

FIGMA_OAUTH_CLIENT_ID=...
FIGMA_OAUTH_CLIENT_SECRET=...
CONNECTIONS_ENCRYPTION_KEY=...

In the Figma Developer Apps page, create an OAuth app:

1. Redirect URL: ${RENDER_EXTERNAL_URL}/connections/figma/callback.
2. Scopes: cap-figma assembles them automatically based on accessMode. Make sure the corresponding granular scopes are enabled on the app (Figma's app config also lists them per app).
3. App type: for single-org deployments, choose private/internal to skip Figma's app-review process. Public OAuth apps require Figma review before non-development users can connect — recommend the private path for most cap-figma deployments.

End users connect via the operator UI's Connections tab. fetchAccountLabel pulls the user's email so the tab shows "Connected as [email protected]".

Tools

Always-on read (6):

| Tool | Description | |---|---| | figma.read_file | Read the document tree. Defaults to depth: 2 (pages → top-level frames). Pass ids: [...] for targeted reads. | | figma.read_file_nodes | Full subtree for specific node ids (max 200 per call). | | figma.read_file_metadata | Name, last_modified, role, thumbnail — cheap. | | figma.list_team_projects | Projects in a team. | | figma.list_project_files | Files in a project. | | figma.read_comments | List comments. Pass as_md: true for a markdown thread view. |

accessMode: read_write_comments (default) adds:

| Tool | Description | |---|---| | figma.post_comment | New comment OR reply (comment_id), optionally pinned via client_meta. |

Scopes (granular)

| accessMode | Scopes requested | |---|---| | read | file_content:read, file_metadata:read, file_comments:read, current_user:read | | read_write_comments (default) | read + file_comments:write |

cap-figma ships only the granular scope strings. The deprecated coarse files:read / file_read scopes stop working after Figma's Nov 2025 platform update.

If the connected user's grant doesn't match the pack's accessMode (e.g. user connected with read, pack later upgraded to read_write_comments), the pack surfaces a 403 → "Disconnect Figma in the operator UI and reconnect" error from each affected tool — pass through to the user.

Skills

| Skill | When to load | |---|---| | figma-files | Reading file structure, navigating from team → project → file, picking depth vs ids. | | figma-comments | Reading or posting comments — pin modes, reply threading. |

Loaded on demand via load_skill — not in every system prompt by default.

v1 limitations

• Components / styles library introspection — not exposed.
• Webhooks — Figma supports them, but cap-figma v1 doesn't subscribe. Defer until there's a "react to file changes" use case.
• File edits — Figma's REST API doesn't expose file-content writes (those go through the Plugin API, which runs in the Figma client). cap-figma can post comments but not change designs.
• Variables API — not exposed.
• Resolve / unresolve comments — Figma doesn't expose this via REST.

Versioning

First release at 0.6.0 matching the family minor. See docs/AGENTS.md for the family-wide versioning model.