understand-figma

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/understand-figma

Analyzes a Figma file and produces an interactive design knowledge graph in the existing dashboard.

分析Figma文件并在现有仪表盘中生成交互式设计知识图谱。

Prerequisites

前置条件

FIGMA_TOKEN
environment variable — a Figma personal access token (create one at https://www.figma.com/settings). If it is missing, STOP and tell the user:
Set a Figma token first: create one at figma.com/settings, then
```
export FIGMA_TOKEN=<token>
```
.
Node ≥ 22, pnpm ≥ 10.

Security: the token is read only from the environment and travels only in the
X-Figma-Token
request header. Never write it to the graph,
meta.json
, logs, or intermediate files. This skill makes outbound calls to
api.figma.com
— unlike
/understand
, it is not fully offline. Tell the user this once.

FIGMA_TOKEN
环境变量 —— Figma个人访问令牌（可在https://www.figma.com/settings创建）。如果缺失，请停止操作并告知用户：
请先设置Figma令牌：在figma.com/settings创建令牌，然后执行
```
export FIGMA_TOKEN=<token>
```
。
Node ≥ 22，pnpm ≥ 10.

安全说明：令牌仅从环境变量读取，且仅通过
X-Figma-Token
请求头传输。切勿将其写入图谱、
meta.json
、日志或中间文件。该技能会向
api.figma.com
发起外部请求 —— 与
/understand
不同，它并非完全离线。请告知用户这一点。

Phase 0 — Pre-flight

阶段0 —— 预检

Parse
```
$ARGUMENTS
```
for a Figma URL or bare file key (the non-flag token) and an optional
```
--language <lang>
```
.
Resolve
```
PROJECT_ROOT
```
to the current working directory. Resolve the data directory
$UA_DIR
once and reuse it for every read and write below:
```
UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"
```
— the legacy
```
.understand-anything/
```
when it already exists, otherwise the new
```
.ua/
```
. Because each phase may run in a fresh shell, carry
```
$UA_DIR
```
forward like
```
$PROJECT_ROOT
```
, re-resolving it with the same line if a later command block needs it.

Resolve

PLUGIN_ROOT

and ensure core is built (same logic as

/understand

Phase 0.1.5). If

packages/core/dist/figma/index.js

is missing, run:

bash

cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build

```
mkdir -p $UA_DIR/intermediate
```
.

解析
```
$ARGUMENTS
```
以获取Figma URL或裸文件密钥（非标志令牌），以及可选的
```
--language <lang>
```
参数。
将
```
PROJECT_ROOT
```
解析为当前工作目录。**解析数据目录
```
$UA_DIR
```
**一次，并在后续所有读写操作中复用：
```
UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"
```
—— 如果已存在旧版
```
.understand-anything/
```
目录则使用它，否则使用新的
```
.ua/
```
目录。由于每个阶段可能在新的shell中运行，请像传递
```
$PROJECT_ROOT
```
一样传递
```
$UA_DIR
```
，如果后续命令块需要，用相同的行重新解析它。

解析

PLUGIN_ROOT

并确保核心已构建（与

/understand

阶段0.1.5的逻辑相同）。如果

packages/core/dist/figma/index.js

缺失，运行：

bash

cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build

```
mkdir -p $UA_DIR/intermediate
```
.

Phase 1 — FETCH & PARSE (deterministic)

阶段1 —— 抓取与解析（确定性）

Run the bundled scan script (

<SKILL_DIR>

is this skill's directory):

bash

FIGMA_TOKEN="$FIGMA_TOKEN" node <SKILL_DIR>/figma-scan.mjs "$PROJECT_ROOT" "<url-or-key>"

It writes

$UA_DIR/intermediate/scan-manifest.json

and prints the node counts. Relay the counts to the user. If it exits non-zero, relay stderr and STOP.

If the scan prints
UP_TO_DATE
, report "Design graph is already up to date for this Figma file version" and STOP. To force a full rebuild, re-run with
UNDERSTAND_FIGMA_FORCE=1
set in the environment.

运行捆绑的扫描脚本（

<SKILL_DIR>

为该技能的目录）：

bash

FIGMA_TOKEN="$FIGMA_TOKEN" node <SKILL_DIR>/figma-scan.mjs "$PROJECT_ROOT" "<url-or-key>"

它会写入

$UA_DIR/intermediate/scan-manifest.json

并打印节点数量。将数量告知用户。如果脚本非零退出，传递错误信息并停止操作。

如果扫描输出
UP_TO_DATE
，则报告“此Figma文件版本的设计图谱已为最新”并停止操作。如需强制完全重建，请在环境中设置
UNDERSTAND_FIGMA_FORCE=1
后重新运行。

Phase 2 — ANALYZE (LLM enrichment)

阶段2 —— 分析（LLM增强）

Read
```
scan-manifest.json
```
. Group nodes into batches of ~15, grouped by page when possible.
For each batch, dispatch a subagent using the
```
design-analyzer
```
agent definition (
```
agents/design-analyzer.md
```
). Pass:
- the batch of nodes (
```
id
```
  ,
```
type
```
  ,
```
name
```
  ,
```
figmaMeta
```
  , child names, token usage),
- the full list of existing node IDs,
- ```
$INTERMEDIATE_DIR = $UA_DIR/intermediate
```
  ,
- the batch number for output naming. The agent writes
```
analysis-batch-<N>.json
```
  . Append
```
$LANGUAGE_DIRECTIVE
```
  if
```
--language
```
  was provided (reuse
```
/understand
```
  's directive text).
Run up to 5 batches concurrently. If a batch fails, log a warning and continue — the manifest is a solid base.

读取
```
scan-manifest.json
```
。将节点分组为约15个一批的批次，尽可能按页面分组。
对每个批次，使用
```
design-analyzer
```
代理定义（
```
agents/design-analyzer.md
```
）调度子代理。传递：
- 节点批次（包含
```
id
```
  、
```
type
```
  、
```
name
```
  、
```
figmaMeta
```
  、子节点名称、令牌使用情况），
- 现有节点ID的完整列表，
- ```
$INTERMEDIATE_DIR = $UA_DIR/intermediate
```
  ，
- 批次编号用于输出命名。代理会写入
```
analysis-batch-<N>.json
```
  。如果提供了
```
--language
```
  参数，追加
```
$LANGUAGE_DIRECTIVE
```
  （复用
```
/understand
```
  的指令文本）。
最多同时运行5个批次。如果某个批次失败，记录警告并继续操作 —— 扫描清单是可靠的基础。

Phase 3 — MERGE

阶段3 —— 合并

bash

node <SKILL_DIR>/figma-merge.mjs "$PROJECT_ROOT"

It combines

scan-manifest.json

analysis-batch-*.json

, runs

mergeDesignGraph

(validates, re-attaches

kind:"design"

), and writes

knowledge-graph.json

meta.json

. Relay the printed stats and any non-

auto-corrected

issues.

bash

node <SKILL_DIR>/figma-merge.mjs "$PROJECT_ROOT"

它会合并

scan-manifest.json

analysis-batch-*.json

，运行

mergeDesignGraph

（验证并重新附加

kind:"design"

），并写入

knowledge-graph.json

meta.json

。传递打印的统计信息以及所有非

auto-corrected

的问题。

Phase 4 — SAVE & LAUNCH

阶段4 —— 保存与启动

Clean up intermediate files except

scan-manifest.json

bash

INTER="$UA_DIR/intermediate"
find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-manifest.json' -exec rm -rf {} +

Report a summary: project name, counts by node type, edges by type, layers, tour steps, and the path
```
$UA_DIR/knowledge-graph.json
```
.
Auto-launch the dashboard by invoking the
```
/understand-dashboard
```
skill.

清理中间文件除了

scan-manifest.json

：

bash

INTER="$UA_DIR/intermediate"
find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-manifest.json' -exec rm -rf {} +

报告摘要：项目名称、按节点类型统计的数量、按类型统计的边数、图层、引导步骤，以及路径
```
$UA_DIR/knowledge-graph.json
```
。
通过调用
```
/understand-dashboard
```
技能自动启动仪表盘。