figmaclaw
Mirror Figma pages into local markdown so developers and agents can work against files, not slow UI/API loops.
Why Developers Care
figma/** becomes a grep-able design memory in your repo.- Figma structure and product code can evolve in the same PR.
- Design context is versioned in git history, not trapped in screenshots.
- Sync is incremental at file/page/frame levels to keep CI cost low.
Why This Is Great For Claude/Codex
Agent systems are strongest with local files. figmaclaw gives them structured frontmatter and prose context in markdown, so they can:
- search design context instantly with
rg
- reason over history via git instead of repeated remote calls
- update code and design documentation in one branch
Why It's Great For Design-System Evolution
Migrating a Figma file from one design system to another (or auditing one for token coverage, or verifying a DS rollout actually landed) is the kind of work where a one-shot agent pass looks right but produces silent corruption — invisible inheritance leaks, frozen literals on unbind, components that detach from their masters.
The audit-page / audit-pipeline / apply-tokens command family turns those passes into deterministic pipelines: every change is encoded as a manifest, linted against accumulated invariants (the FCLAW rule namespace), applied in atomic batches, and verified after each batch via REST. Round 1 of a real-world migration produced 365 silently-incorrect bindings; the rules and verifiers in this command family exist so round N doesn't.
The migration commands share a common --dry-run / --emit-only / --execute discipline and a use_figma batch-emission protocol (<prefix>-NNNN.{json,use_figma.js} + manifest.json). All emitted JS templates are F17/F22/F30 compliant — never .detach(), never throw on aggregate stats — so a single bad row never rolls back its successful sibling writes.
| Command | Purpose |
|---|
audit-page emit-clone-script | Clone a source page into an audit page (warns if the source looks inactive — archive, playground, prior audit clone, etc.). |
audit-page swap | Apply component-instance swaps from a typed manifest. Emits per-row try/catch JS, persists the SPD idMap so subsequent apply-tokens runs target NEW instances. |
audit-pipeline lint | Validate the component_migration_map.v3.json (nested + flat shapes); with --variants <taxonomy.json> enforces variant-axis names, values, and OLD-axis coverage. |
apply-tokens | Apply variable-binding fixes; legacy compact-row + versioned manifest accepted. Refusals list unrecognised + missing canonical fields, plus a did_you_mean_token_name hint when a <library>: prefix is detected. |
See docs/migration-pipeline.md for the full pipeline.
Setup Is Two Separate Steps
figmaclaw setup has two distinct scopes:
- Install the
figmaclaw CLI on your machine/CI runner.
- Initialize a target repository that will store your Figma mirror (
figma/**).
Installing the CLI does not create mirror workflows or tracked-file state. figmaclaw init does.
Step 1: Install The CLI
Quick install
curl -fsSL https://raw.githubusercontent.com/aviadr1/figmaclaw/main/install.sh | sh
Manual install
uv tool install git+https://github.com/aviadr1/figmaclaw
Upgrade
figmaclaw self update
Equivalent manual command:
uv tool install --force --reinstall --upgrade git+https://github.com/aviadr1/figmaclaw@main
Step 2: Initialize A Consumer Repo
Choose or create the repository that should hold your Figma markdown mirror:
mkdir -p /path/to/design-memory
cd /path/to/design-memory
git init
Then initialize:
figmaclaw init --repo-dir /path/to/design-memory
