# figma-agent

Adopt this skill: https://proskills.md/skills/other/rasimme-figma-agent

Page: https://proskills.md/skills/other/rasimme-figma-agent
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 7440
upstream: https://github.com/rasimme/figma-agent/blob/HEAD/SKILL.md

````text
---
name: figma-agent
description: Figma MCP integration for OpenClaw. Use when the user wants to read Figma designs, inspect design tokens/variables, work with Code Connect, or create/edit Figma designs. Requires one-time bootstrap setup.
metadata:
  openclaw:
    requires:
      anyBins: ["node", "node18", "node20", "node22"]
    homepage: https://github.com/rasimme/figma-agent
---

# Figma Agent

Figma Remote MCP integration for OpenClaw. Reads designs via `figma__*` tools; creates and edits via CC sessions using `mcp__figma__*` tools.

## Route First

**Read/Inspect** → call `figma__*` tools directly. No CC session needed.  
**Write/Create/Edit** → requires CC session via `mcp__figma__*` tools.

Seeing or understanding a design? → Direct. Do not start a session.  
Changing or creating something? → Start a CC session. Follow the matching playbook below.

**Execution model:**
1. **Route & Brief** — choose the workflow, identify the real risks, and write a lean execution brief
2. **Execute** — perform the direct read or CC-based write flow
3. **Done Gate** — do not report success until the applicable structural and visual validation checks pass

## Workflow Routing

**First:** Determine the user's intent, then follow the matching path.

This is an abridged routing summary. For the full matrix and decision logic, see [references/workflow-selection.md](references/workflow-selection.md).

→ Full routing matrix: [references/workflow-selection.md](references/workflow-selection.md)

| Intent | Path | Route |
|--------|------|-------|
| Build a production screen | [Native Screen Generation](references/playbooks/native-screen-generation.md) | CC |
| Create next step / state variant from an existing screen | [Native Screen Generation](references/playbooks/native-screen-generation.md) | CC |
| Prototype from HTML/URL | [HTML-to-Figma Prototyping](references/playbooks/html-to-figma-prototyping.md) | CC |
| Read-only inspection | `get_design_context` / `get_screenshot` | Direct |
| Review + Edit a screen | [Screen Review Loop](references/playbooks/screen-review-loop.md) | CC |
| Apply design tokens | [Color Tokenization](references/playbooks/color-tokenization.md) | CC |
| Import + clean up Stitch export | [Stitch Import Cleanup](references/playbooks/stitch-import-cleanup.md) | CC |
| Discover variables/styles | [Variable Discovery](references/playbooks/variable-discovery.md) | Direct |
| Audit design system | [Design System Cleanup](references/playbooks/design-system-cleanup.md) | CC |
| Inspect finished design | [Design Audit Review](references/playbooks/design-audit-review.md) | Direct |

---

## Image Delivery (MANDATORY after every write)

Screenshots must reach the user as Telegram photo attachments — not as inline base64 text.

**Workflow:**

1. **Save to file** — use `--out <path>` flag so the PNG is written directly:

   ```bash
   node scripts/figma-mcp-cli.mjs get_screenshot \
     fileKey=<fileKey> nodeId=<nodeId> scale=2 \
     --out ~/workspace-dev-botti/screenshots/<name>.png
   ```

2. **Deliver to user** — put `MEDIA:<path>` on its own line in your reply:

   ```
   Hier ist der aktuelle Stand:
   MEDIA:screenshots/validate.png
   ```

   OpenClaw extracts every `MEDIA:` line and sends the file as a native Telegram photo.
   The path is workspace-relative (`screenshots/...`) or absolute.

**Two different tools — don't mix them up:**

| Tool | Purpose | Used for Image Delivery? |
|------|---------|--------------------------|
| `image` tool | Send to Vision model for analysis | ❌ No — analysis only |
| `MEDIA:<path>` in reply text | Send as Telegram attachment | ✅ Yes — actual delivery |

**Why `--out`?**
Without it, the Figma API returns base64-encoded JSON → renders as inline text in Telegram, not a photo. The `--out` flag decodes and writes a real PNG file that `MEDIA:` sends as an attachment.

**Screenshot directory:** `~/workspace-dev-botti/screenshots/` (create if missing)

**Validation pattern (every write operation):**

```bash
# After use_figma call — save screenshot → MEDIA: in reply
node scripts/figma-mcp-cli.mjs get_screenshot fileKey=<key> nodeId=<id> scale=2 \
  --out ~/workspace-dev-botti/screenshots/validate.png
# Reply with:
# MEDIA:screenshots/validate.png
```

**Stitch comparison:**
Stitch delivers via `MEDIA:<screenshotUrl>` (HTTP URL). Figma delivers via `MEDIA:<local-path>` (file). Mechanism identical — only the source differs.

---

## Hard Rules (Top 6)

These are non-negotiable. Full rule set: [references/core-rules.md](references/core-rules.md)

1. **Validate after every write** — `get_screenshot` or `get_metadata` after each `use_figma` call. Never assume success.
2. **Read → Understand → Fix → Retry** — never blindly retry failed code, never rebuild as first response.
3. **Explicit over implicit** — name exact variables, components, layout modes. Leave nothing to inference.
4. **Design-system-first** — check local variables, styles, Code Connect, then libraries before creating anything raw.
5. **Component-instance-first** — if a suitable existing design-system component exists, instantiate it instead of recreating it with local frames.
6. **Section-by-section** — one logical section per `use_figma` call, validate between sections.

---

## Known Gotchas

Before writing any `use_figma` code, know these failure modes:

→ Full reference: [references/plugin-api-gotchas.md](references/plugin-api-gotchas.md)

- **Paint binding:** `setBoundVariableForPaint` returns a new paint — reassign the fills/strokes array ([#paint-binding](references/plugin-api-gotchas.md#paint-binding))
- **Opacity reset:** Paint binding resets opacity to 1.0 — save and restore explicitly ([#opacity](references/plugin-api-gotchas.md#opacity))
- **Page context:** Always set page explicitly — `figma.currentPage` may reset between calls ([#page-context](references/plugin-api-gotchas.md#page-context))
- **FILL sizing:** appendChild to auto-layout parent before setting `layoutSizingHorizontal: "FILL"` ([#append-before-fill](references/plugin-api-gotchas.md#append-before-fill))
- **Async:** Always `await` async operations — `loadFontAsync`, `importComponentByKeyAsync`, etc. ([#promises](references/plugin-api-gotchas.md#promises))

---

## Prompting Guidance

→ Full patterns: [references/prompting-patterns.md](references/prompting-patterns.md)

Key patterns: variable-first code structure, section-by-section execution, explicit design-system usage, validation loops, error recovery framing.

---

## Install / Setup

If dependencies are missing, install them from the skill repo root:

```bash
npm install
```

Then run one-time bootstrap:

## Setup (One-Time Bootstrap)

```bash
node ~/.openclaw/skills/figma-agent/scripts/auth.mjs
```

Reads CC OAuth token from `~/.claude/.credentials.json`, writes it into `~/.openclaw/openclaw.json`. Then restart the OpenClaw gateway.

**Token check:** `node ~/.openclaw/skills/figma-agent/scripts/auth.mjs --check`

**On 401 errors:** Open CC → use any Figma tool (auto-refreshes token) → re-run bootstrap script.

---

## URL Parsing

```
figma.com/design/:fileKey/:name?node-id=:nodeId
```
Convert `-` to `:` in nodeId (e.g. `123-456` → `123:456`). For FigJam: `figma.com/board/:fileKey/:name` → use `get_figjam`.

---

## Tool & Rate-Limit Reference

→ [references/figma-api.md](references/figma-api.md)
````

## File: README.md
upstream: https://github.com/rasimme/figma-agent/blob/HEAD/README.md

````text
<h1 align="center">Figma Agent</h1>

<p align="center">
  <strong>Workflow-driven Figma skill for OpenClaw — inspect designs directly, then create, review, and edit screens through structured Figma workflows.</strong><br>
  Built on the official <a href="https://help.figma.com/hc/en-us/articles/32132100833559">Figma Remote MCP server</a>.
</p>

<p align="center">
  <a href="https://github.com/rasimme/figma-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></a>
  <a href="https://github.com/rasimme/figma-agent/blob/main/CHANGELOG.md"><img src="https://img.shields.io/badge/version-v0.3.0-blue.svg" alt="Version"></a>
  <a href="https://clawhub.ai"><img src="https://img.shields.io/badge/ClawHub-skill-purple.svg" alt="ClawHub"></a>
</p>

<p align="center">
  <a href="#what-this-skill-does">What this skill does</a> •
  <a href="#core-architecture">Core architecture</a> •
  <a href="#supported-workflows">Supported workflows</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#image-delivery">Image Delivery</a> •
  <a href="#limitations">Limitations</a>
</p>

---

## What this skill does

Figma Agent is not just a raw MCP wrapper. It is a structured OpenClaw skill for working with Figma in two modes:

- **Direct read / inspect** for screenshots, metadata, design context, variables, and Code Connect inspection
- **Structured write / edit workflows** for building screens, reviewing existing work, applying tokens, and iterating on designs through ACP coding sessions

Typical use cases:

- "Show me this screen and tell me what is off"
- "Build the next step based on this existing screen"
- "Replace hardcoded colors with design-system tokens"
- "Inspect local variables and Code Connect mappings"
- "Create a production-ready screen using existing components"

---

## Core architecture

The skill is intentionally split into four layers:

1. **`SKILL.md`** — routing surface for deciding direct read vs ACP write/edit
2. **`references/workflow-selection.md`** — workflow and strategy selection
3. **`references/core-rules.md`** — global execution rules and constraints
4. **`references/prompting-patterns.md` + playbooks** — prompt structure and step-by-step execution

### Runtime model

- **Read / inspect** goes directly to Figma MCP
- **Write / create / edit** goes through an ACP coding session with Figma MCP available

This hybrid model keeps inspection fast while preserving a stronger execution path for canvas changes.

### Execution model

The controller should operate in three phases:

1. **Route & Brief** — choose the workflow, identify the actual risks, and produce a lean execution brief
2. **Execute** — perform the direct read or ACP write/edit task
3. **Done Gate** — require structural checks first and screenshot confirmation second before reporting success

---

## Supported workflows

### Read / Inspect

- **Read-only inspection** — screenshots, metadata, design context, variables, Code Connect context
- **Variable Discovery** — inspect local tokens and styles before searching externally
- **Design Audit Review** — review a finished design and identify issues or cleanup opportunities

### Create / Edit

- **Native Screen Generation** — production-ready, design-system-aligned screen creation
- **Screen Review Loop** — screenshot, isolate issues, apply targeted fixes, validate
- **Color Tokenization** — replace hardcoded values with variable bindings
- **HTML-to-Figma Prototyping** — rapid exploration from HTML/CSS, then cleanup
- **Stitch Import Cleanup** — fix imported Stitch output for native Figma quality
- **State Variants / Next Steps** — prefer **Copy + Edit** over rebuild when most of the screen already exists

### Execution principles

- **Design-system-first** — use local variables, styles, components, and Code Connect before creating anything raw
- **Component-instance-first** — if a suitable component exists, instantiate it instead of rebuilding it visually
- **Section-by-section** — build in small validated steps, not giant write calls
- **Validate after every write** — structural checks first, screenshots second

---

## Quick Start

### Prerequisites

- [OpenClaw](https://github.com/openclaw/openclaw) installed
- [Node.js](https://nodejs.org) available
- Figma account connected to a supported MCP client
- **Full Seat** in Figma for write operations (`use_figma`)

### Install

**Via ClawHub (recommended):**

```bash
clawhub install figma-agent
```

**Manual install:**

```bash
cd ~/.openclaw/skills
git clone https://github.com/rasimme/figma-agent.git
cd figma-agent
npm install
```

### Bootstrap authentication

```bash
node ~/.openclaw/skills/figma-agent/scripts/bootstrap-token.mjs
```

The bootstrap script extracts or refreshes the Figma MCP token from a supported MCP client and writes the Figma server config into your OpenClaw config.

Then restart OpenClaw:

```bash
openclaw gateway restart
```

### Verify

Check that Figma MCP is configured in `~/.openclaw/openclaw.json` under `mcp.servers.figma`, then try a simple read action such as `get_screenshot` or `get_metadata`.

---

## Image Delivery

For chat delivery, screenshots should be sent as actual image attachments, not inline base64 blobs.

### Recommended pattern

1. Save the screenshot to disk with `--out`
2. Reply with `MEDIA:<path>`

Example:

```bash
node scripts/figma-mcp-cli.mjs get_screenshot \
  fileKey=<fileKey> nodeId=<nodeId> scale=2 \
  --out ~/workspace-dev-botti/screenshots/validate.png
```

Then in chat:

```text
MEDIA:screenshots/validate.png
```

### Important distinction

- `image` tool = image analysis / vision input
- `MEDIA:<path>` = actual chat attachment delivery

This matters especially on Telegram, where inline base64 is not the same as a native image attachment.

---

## Tool coverage

The skill supports the official Figma Remote MCP toolset for inspection and canvas operations. Commonly used tools include:

- `get_design_context`
- `get_screenshot`
- `get_metadata`
- `get_variable_defs`
- `search_design_system`
- `get_code_connect_map`
- `get_figjam`
- `whoami`
- `use_figma`
- `create_new_file`
- `generate_figma_design`
- `generate_diagram`
- Code Connect mapping helpers

For full tool-level details, see [`references/figma-api.md`](references/figma-api.md).

---

## Limitations

Current known constraints:

- **Write operations require a Full Seat** in Figma
- **Large write calls are fragile** — split work into smaller sections
- **Remote MCP write behavior still has edge cases** — validate after each change
- **Some Plugin API behavior differs in Remote MCP** — see [`references/plugin-api-gotchas.md`](references/plugin-api-gotchas.md)
- **Image delivery works best through local file output + `MEDIA:`**
- **State variants should usually duplicate and edit existing screens rather than rebuild from scratch**
- **Playbooks guide the agent, not ACP automatically** — critical execution constraints must still be injected into ACP prompts when relevant

---

## Project structure

```text
figma-agent/
├── SKILL.md
├── README.md
├── CHANGELOG.md
├── LICENSE
├── package.json
├── references/
│   ├── core-rules.md
│   ├── figma-api.md
│   ├── plugin-api-gotchas.md
│   ├── prompting-patterns.md
│   └── workflow-selection.md
└── scripts/
    ├── bootstrap-token.mjs
    ├── figma-mcp-cli.mjs
    ├── figma-mcp.mjs
    └── token-scanner.mjs
```

---

## License

MIT — see [LICENSE](LICENSE).
````
