pp-figma

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/figma/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Figma — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `figma-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install figma --cli-only
   ```
2. Verify: `figma-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/productivity/figma/cmd/figma-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use figma-pp-cli when an agent or engineer needs to reason about a Figma file as data — not pixels. It shines for codegen prompt context (`frame extract`, `dev-mode dump`), design-system ops (`orphans`, `tokens diff`, `fingerprint`), comment hygiene (`comments-audit`), and webhook iteration (`webhooks test`). For interactive design work, the Figma desktop app is fine — figma-pp-cli covers everything Figma's REST API exposes and adds the cross-file analytical commands the dashboard hides.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Agent-native plumbing
- **`frame extract`** — Extract a single frame as a compact codegen-ready payload that fuses simplified node tree, in-scope variables, dev resources, and Code Connect mappings.

  _First call when an AI agent needs Figma frame context for code generation — returns a compact payload that fits in the context window instead of the raw 10MB file response._

  ```bash
  figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json
  ```
- **`dev-mode dump`** — Emit a portable Markdown bundle that fuses dev-resource links, variables in scope, render permalink, and Code Connect mapping for one node.

  _Use when an agent or engineer needs the full Dev Mode context for one frame as a single Markdown blob — no Desktop pairing required._

  ```bash
  figma-pp-cli dev-mode dump abc123 --node 1234-5678 --format md
  ```
- **`webhooks test`** — Pull Figma's webhook request log and replay stored payloads (with original headers and HMAC) against an arbitrary target URL.

  _Use when iterating on a new webhook handler — replay yesterday's failed deliveries against your local server without re-triggering upstream events._

  ```bash
  figma-pp-cli webhooks test wh_abc --replay-failed --target-url https://localhost:3000/figma
  ```

### Local state that compounds
- **`comments-audit`** — Aggregate unresolved comments across every synced team file with age and group-by filters.

  _Run this on Monday morning before design review — surfaces every stale unresolved thread across the team._

  ```bash
  figma-pp-cli comments-audit --older-than 14d --group-by file,author --json
  ```
- **`orphans`** — Find published library entities (components, styles, variables) with zero usage over a window by joining team-library publish list with library-analytics usage data.

  _First command for the quarterly design-system cleanup — returns the list of entities safe to deprecate._

  ```bash
  figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json
  ```
- **`tokens diff`** — Diff Figma variables across two file versions with mode-awareness; emits a Markdown or JSON change set.

  _Run before merging a design-tokens PR to see what actually changed in Figma since the last release._

  ```bash
  figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md
  ```
- **`fingerprint`** — Stable hash of a Figma file's token + component + style surface; exits non-zero if --expect doesn't match.

  _Wire this into CI to fail builds when the upstream Figma file's design-system surface drifts from the committed snapshot._

  ```bash
  figma-pp-cli fingerprint abc123 --expect sha256:a1b2c3...
  ```
- **`variables explain`** — Flat list of every node and component that references a given variable across a file.

  _First call when planning a variable rename or deprecation — shows the blast radius before you touch anything._

  ```bash
  figma-pp-cli variables explain abc123 --variable color/brand/primary --json
  ```

## Command Reference

**activity-logs** — Get activity logs as an organization admin.

- `figma-pp-cli activity-logs` — Returns a list of activity log events

**component-sets** — Get information about published component sets.

- `figma-pp-cli component-sets <key>` — Get metadata on a published component set by key.

**components** — Get information about published components.

- `figma-pp-cli components <key>` — Get metadata on a component by key.

**dev-resources** — Interact with dev resources in Figma Dev Mode.

- `figma-pp-cli dev-resources post` — Bulk create dev resources across multiple files. Dev resources that are successfully created will show up in the...
- `figma-pp-cli dev-resources put` — Bulk update dev resources across multiple files. Ids for dev resources that are successfully updated will show up in...

**developer-logs** — Get developer logs for REST API and MCP server requests in an organization.

- `figma-pp-cli developer-logs` — Returns a list of developer log entries for REST API and MCP server requests made within the organization. This...

**figma-analytics** — Manage figma analytics

- `figma-pp-cli figma-analytics get-library-component-actions` — Returns a list of library analytics component actions data broken down by the requested dimension.
- `figma-pp-cli figma-analytics get-library-component-usages` — Returns a list of library analytics component usage data broken down by the requested dimension.
- `figma-pp-cli figma-analytics get-library-style-actions` — Returns a list of library analytics style actions data broken down by the requested dimension.
- `figma-pp-cli figma-analytics get-library-style-usages` — Returns a list of library analytics style usage data broken down by the requested dimension.
- `figma-pp-cli figma-analytics get-library-variable-actions` — Returns a list of library analytics variable actions data broken down by the requested dimension.
- `figma-pp-cli figma-analytics get-library-variable-usages` — Returns a list of library analytics variable usage data broken down by the requested dimension.

**files** — Get file JSON, images, and other file-related content.

- `figma-pp-cli files <file_key>` — Returns the document identified by `file_key` as a JSON object. The file key can be parsed from any Figma file url:...

**images** — Manage images

- `figma-pp-cli images <file_key>` — Renders images from a file. If no error occurs, `'images'` will be populated with a map from node IDs to URLs of the...

**me** — Manage me

- `figma-pp-cli me` — Returns the user information for the currently authenticated user.

**oembed** — Get oEmbed data for Figma files and published Makes.

- `figma-pp-cli oembed` — Returns oEmbed data for a Figma file or published Make site URL, following the [oEmbed...

**payments** — Get purchase information for your Community resources.

- `figma-pp-cli payments` — There are two methods to query for a user's payment information on a plugin