# @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

5. Paste the Figma client id and client secret into the Kody wizard (never into
   chat). Approve host `api.figma.com`.
6. 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](https://developers.figma.com/docs/rest-api/personal-access-tokens/))
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`](./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

- [Figma REST API](https://developers.figma.com/docs/rest-api/)
- [Authentication](https://developers.figma.com/docs/rest-api/authentication/)
- [OAuth apps](https://developers.figma.com/docs/rest-api/oauth-apps/)
- [Scopes](https://developers.figma.com/docs/rest-api/scopes/)
- [Personal access tokens](https://developers.figma.com/docs/rest-api/personal-access-tokens/)