Skip to content

README.md

97 lines · 4.4 KB · Markdown

@kody/figma

Intent

Provide reusable, account-agnostic Figma REST helpers so Kody agents can read files, nodes, comments, components, styles, and images through a saved figma / figma-* OAuth integration or a personal/plan access token — without hand-rolling REST. Comment and other write mutations are previewable with dryRun: true and only run live after confirm: true.

This listing is meant to be forked. After you fork, connect your Figma account. Do not treat the live @kody/figma package storage as yours.

Share this listing as https://kody.codes/@kody/figma

What it does

  • Inspect a Figma file, specific nodes, or file metadata
  • List, preview, or (after confirmation) create/delete comments
  • List published components and styles
  • Render node images or list image-fill download URLs
  • Call an unwrapped Figma REST path through ./request
  • Connect more than one Figma account via integrationName / account

Prerequisites / setup

Figma has no built-in Kody OAuth app. Choose one lane:

Lane A — BYO OAuth (recommended)
  1. Create an OAuth app at https://www.figma.com/developers/apps
  2. Set the redirect URI exactly to https://kody.codes/connect/oauth
  3. Enable the scopes this package uses (current_user:read, file_content:read, file_metadata:read, file_comments:read, file_comments:write, file_versions:read, library_content:read, library_assets:read, folders:read). Enable exactly those scopes on the Figma OAuth app. Figma returns HTTP 400 Invalid scopes when authorize asks for anything else: a scope the app does not offer, a deprecated scope, or an enterprise-only extra.
  4. Connect while signed in to Kody:

https://kody.codes/connect/oauth?provider=figma&authorizeUrl=https%3A%2F%2Fwww.figma.com%2Foauth&tokenUrl=https%3A%2F%2Fapi.figma.com%2Fv1%2Foauth%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.figma.com&scopes=current_user%3Aread%20file_content%3Aread%20file_metadata%3Aread%20file_comments%3Aread%20file_comments%3Awrite%20file_versions%3Aread%20library_content%3Aread%20library_assets%3Aread%20folders%3Aread&flow=confidential&pkce=true&allowedHosts=api.figma.com&dashboardUrl=https%3A%2F%2Fwww.figma.com%2Fdevelopers%2Fapps

  1. Paste the Figma client id and client secret into the Kody wizard (never into chat). Approve host api.figma.com.
  2. Reconnect later with https://kody.codes/connect/oauth?provider=figma

OAuth authorize URL: https://www.figma.com/oauth. Token URL: https://api.figma.com/v1/oauth/token. Flow: confidential (client secret) plus S256 PKCE. Figma scopes are space-separated.

To connect a second account, change provider (for example provider=figma-work) and pass integrationName: 'figma-work' on every call.

Lane B — Personal or plan access token
  1. Create a personal access token from Figma Settings → Security, or a plan token at https://www.figma.com/developers/tokens (PAT docs)
  2. Save it (do not paste the value in chat):

https://kody.codes/account/secrets/new?name=figmaPat&description=Figma%20personal%20or%20plan%20access%20token&allowedHosts=api.figma.com&scope=user

For a second account/token, use a distinct secret name such as figmaPat-work and pass secretName: 'figmaPat-work' (or account: 'work').

Hosts
  • api.figma.com — all REST calls (required)

Agents: import paths, smoke checks, and mutation snippets live in AGENTS.md.

Done when

  • figma OAuth is connected or figmaPat is saved; api.figma.com is approved
  • Smoke test returns { ok: true, live: true, … } (or { live: false } with setup URLs when credentials are missing)
  • Comment mutations preview with dryRun: true and only run live with confirm: true after you approve the target

Branding

The community icon is Figma's official five-shape logomark (red, orange, purple, blue, green). Paths are unmodified from the official mark. Figma® is a trademark of Figma, Inc. This package is not affiliated with or endorsed by Figma, Inc.

Docs