@kody/figma

@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

When To Use

• 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

Auth

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

OAuth sends Authorization: Bearer …. Tokens send X-Figma-Token. Required API host: api.figma.com. Approve it in the account secrets UI.

Lane A — BYO OAuth

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, projects:read).
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%20projects%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 (commas also work at Figma).

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', which resolves to figma-work / figmaPat-work).

Scopes

If Figma returns 401/403 or an insufficient-scope error, helpers throw a message that names the missing scope and the next setup URL (reconnect OAuth with that scope, or save a token).

Multiple accounts

Every export accepts:

• integrationName / integration — exact saved OAuth name (figma-work)
• account — work → figma-work; figma-work used as-is; omitted → figma
• secretName — token secret override
• auth — 'oauth' or 'pat' when both exist

Do not hard-code a personal file key or team id.

Safety

Mutating helpers (./create-comment, ./delete-comment, and mutating ./request methods) require confirm: true. Pass dryRun: true to inspect the REST payload without calling Figma. ./request treats GET as read-only; POST / PUT / PATCH / DELETE need confirmation.

Exports

Smoke test

import smokeTest from 'kody:@kody/figma/smoke-test'

export default async function main() {
	return await smokeTest()
}

Without credentials this returns { ok: true, live: false } plus the connect and token URLs. After OAuth or a token is saved it reads /v1/me and returns { live: true, hasViewerId } without email.

Root import:

import figma from 'kody:@kody/figma'

export default async function main() {
	return await figma()
}

Preview a mutation without credentials:

import createComment from 'kody:@kody/figma/create-comment'

export default async function main() {
	return await createComment({
		fileKey: 'abc123',
		message: 'Ship the new empty state.',
		dryRun: true,
	})
}

Examples

import getFile from 'kody:@kody/figma/get-file'
import listComments from 'kody:@kody/figma/list-comments'

export default async function main() {
	const file = await getFile({
		fileKey: 'https://www.figma.com/design/abc123/Checkout',
	})
	return {
		file,
		comments: await listComments({ fileKey: file.fileKey }),
	}
}

import createComment from 'kody:@kody/figma/create-comment'

export default async function main() {
	const preview = await createComment({
		fileKey: 'abc123',
		message: 'Please bump the empty-state type to 16.',
		nodeId: '12:34',
		dryRun: true,
	})
	// After the user confirms the exact file and message:
	return await createComment({
		fileKey: 'abc123',
		message: 'Please bump the empty-state type to 16.',
		nodeId: '12:34',
		confirm: true,
	})
}

Unwrapped REST:

import request from 'kody:@kody/figma/request'

export default async function main() {
	return await request({
		path: '/v1/me',
	})
}

Notes

• REST base: https://api.figma.com
• fileKey accepts a raw key or a figma.com file/design/board/proto URL
• Node ids from Figma URLs (1-2) are normalized to API form (1:2)
• ./get-file projects a slim document (id/name/type/children) so agents do not pull full vector trees by default
• Use ./request for team projects, versions, webhooks, variables, or other unwrapped paths
• This package is not affiliated with or endorsed by Figma, Inc.

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.

Docs

• Figma REST API
• Authentication
• OAuth apps
• Scopes
• Personal access tokens