tokyo-megacorp/snapshot-all

Bulk Snapshot All Frames

1. Parse the URL

Extract fileKey from the Figma URL (https://www.figma.com/design/<fileKey>/...). No node-id parameter needed.

2. Check prerequisites

• Verify a Figma token is loadable: bash scripts/auth.sh status (if it fails, tell the user to run bash scripts/auth.sh set and stop)
• Always refresh the index first (re-run the index workflow: fetch tree, walk, write index.json) to catch new frames added since last run
• After indexing, if the frames array in index.json is empty, stop and tell the user the file has no indexable frames

2.5. Orchestration

Create tasks for each phase. Dispatch haiku subagents per phase — raw output stays forked.

TaskCreate("Fetch file tree",       activeForm: "Fetching <fileName> from Figma API...")
TaskCreate("Split frame snapshots", activeForm: "Extracting <N> frame subtrees...")
TaskCreate("Export frame PNGs",     activeForm: "Exporting <N> screenshots in batches...")
TaskCreate("Generate frame docs",   activeForm: "Extracting text, colors, buttons, layout...")
TaskCreate("Update search index",   activeForm: "Indexing frames for semantic search...")
TaskCreate("Store Figma comments",  activeForm: "Downloading comment threads...")

Task lifecycle:

1. Create ALL tasks upfront (pending)
2. Before each phase: TaskUpdate(taskId, status: "in_progress")
3. Dispatch Agent(model: "haiku") — agent reports only counts, never raw output
4. After agent returns: TaskUpdate(taskId, status: "completed")
5. After ALL phases: verify no tasks left in_progress — every task must be completed or deleted before the final summary

Data discipline

• NEVER keep raw API responses, JSON trees, or large frame content in the conversation context
• ALWAYS write intermediate data to disk (temp files or ~/.figma-differ/)
• Subagent prompts MUST include: "Write results to <path>. Report only counts and file paths."
• Final summary to user: counts, paths, and actionable next steps only

3. Fetch the full file tree (1 API call)

Pipe directly to a temp file (do NOT store in shell variable — file trees can be 10-30MB):

TREE_FILE="/tmp/figma-tree-<fileKey>-$$.json"
bash $CLAUDE_PLUGIN_ROOT/scripts/figma-api.sh fetch_file_tree <fileKey> > "$TREE_FILE"

Extract fileName from the response: jq -r '.name' "$TREE_FILE".

3.5. Extract screen flows

Extract connector lines and prototype transitions from the tree:

node $CLAUDE_PLUGIN_ROOT/scripts/extract-flows.js <fileKey> "$TREE_FILE"

4. Split into per-frame node.json files

For each frame in the index, extract its subtree from the tree file using jq.

IMPORTANT: Do NOT use jq recursive descent (..) — it hangs on large trees. Use explicit path traversal to find each frame by ID:

jq --arg id "<nodeId>" '
  [.document.children[].children[]? | recurse(.children[]?) | select(.id == $id)] | first
' "$TREE_FILE"

Store each frame's JSON at:

~/.figma-differ/<fileKey>/<nodeId_safe>/<timestamp>/node.json

Use the same timestamp for all frames in this snapshot (atomic file-level snapshot).

5. Batch export PNGs

Collect all frame IDs from the index. Call:

BATCH_DIR="/tmp/figma-batch-<fileKey>-$$"
mkdir -p "$BATCH_DIR"
bash $CLAUDE_PLUGIN_ROOT/scripts/figma-api.sh fetch_batch_images <fileKey> "id1,id2,..." "$BATCH_DIR"

Move each downloaded PNG to its frame's snapshot directory and clean up:

~/.figma-differ/<fileKey>/<nodeId_safe>/<timestamp>/screenshot.png

After all PNGs are moved: rm -rf "$BATCH_DIR" "$TREE_FILE"

5.5. Generate frame.md documents (for QMD search)

If QMD is available, generate searchable markdown for each frame:

node $CLAUDE_PLUGIN_ROOT/scripts/generate-frame-md.js <fileKey>
source $CLAUDE_PLUGIN_ROOT/scripts/lib/qmd.sh
qmd_reindex

This is best-effort — if QMD is not installed, skip silently. The frame.md files are still useful as human-readable summaries even without QMD.

6. Store comments

Pipe directly to file (do NOT store in shell variable — large comment payloads will exceed argument limits):

COMMENT_DIR="$HOME/.figma-differ/<fileKey>/comments"
mkdir -p "$COMMENT_DIR"
bash $CLAUDE_PLUGIN_ROOT/scripts/figma-api.sh fetch_comments <fileKey> > "$COMMENT_DIR/<timestamp>.json"

7. Create Slack parent threads (if configured)

Check if ~/.figma-differ/config.json exists and has a slack_channel_id. If so:

1. Read ~/.figma-differ/<fileKey>/slack-threads.json (create { "channel_id": "<channel_id>", "threads": {} } if missing)

2. For each frame in the index that is NOT already in the threads registry, create a parent message:

   Infer a semantic emoji from the frame name:

   • 🔐 :lock: — login, sign in, auth
   • ⚙️ :gear: — settings, preferences, config
   • 👤 :bust_in_silhouette: — profile, account, user
   • 📥 :inbox_tray: — inbox, notifications, messages
   • 💰 :moneybag: — net worth, balance, portfolio, finance
   • 🎁 :gift: — gift, rewards, offers, promotions
   • 📄 :page_facing_up: — statements, documents, history
   • 🛡️ :shield: — security, privacy, verification
   • 🏠 :house: — home, dashboard, overview
   • 🔍 :mag: — search, explore, discover
   • 💳 :credit_card: — payments, cards, transactions
   • 📊 :bar_chart: — analytics, reports, charts
   • 📱 :iphone: — default/fallback for any screen

   Build Figma deep-link: https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId with : replaced by ->

   Post via mcp__claude_ai_Slack__slack_send_message:

   • channel_id: from config
   • message: <emoji> *<Frame Name>* · <<figma-deep-link>|Figma> · _<Page Name>_

   Save the returned message_ts to the registry:

   { "ts": "<message_ts>", "name": "<Frame Name>", "page": "<Page Name>" }
   

3. Write the updated slack-threads.json after all parent messages are created.

Rate limit note: If there are many new frames (e.g. first run with 50+ frames), post parent messages sequentially with no artificial delay — the Slack MCP handles rate limiting. Log progress: Creating Slack thread for "<Frame Name>"... (M/N)

8. Confirm

Snapshot complete — <fileName>
  Frames: N snapshots stored
  PNGs: M exported (K failed)
  Comments: C total (U unresolved)
  Slack threads: T created (S already existed)
  Timestamp: <timestamp>
  Storage: ~/.figma-differ/<fileKey>/

Run /figma-differ:diff-all <url> to check for changes later.

API call budget

• 1 call: fetch_file_tree
• ceil(N/10) calls: batch image export (e.g. 200 frames = 20 calls)
• 1 call: fetch_comments
• N Slack calls: parent thread creation (first run only; subsequent runs = 0)
• Total for 200 frames: ~22 Figma API calls + up to 200 Slack messages on first run