Skip to content

Figma Spec Tools

Salman Ashraf edited this page Oct 9, 2026 · 1 revision

Portable Figma spec helpers

Install into your app/game repository with:

npx mobile-ai-agents figma tools init

Existing files are preserved. Helpers ship inside the npm package, so this command needs no separate GitHub download and does not modify MCP configuration. Python 3.10+ is required. Install optional dependencies in your project's environment:

python3 -m pip install -r tools/figma-spec/requirements.txt

JSON syntax in .yml files works without PyYAML; ordinary YAML requires PyYAML. Screenshot comparison requires Pillow and numpy. These helpers never authenticate or call MCP themselves.

Extraction

page_index.js, text_dump.js, and node_dump.js are templates for an available use_figma tool. Load the vendor's prerequisite skill first. Replace __PAGE_ID__, __NODE_IDS__, and __MAX_DEPTH__ with JSON literals, then pass the script as the tool's code. Do not execute these in Node: they depend on Figma's Plugin API. A page switch changes the active UI context but does not edit design nodes. Run page-scoped reads sequentially when they share an active page.

  • Index pages, then inspect the requested scope; do not skip pages by naming convention.
  • Dump requirements/copy including instance descendants. Text-root extraction is supported.
  • Dump component values with sufficient depth. Numeric source values retain precision; human-readable hex accompanies source RGBA values. Mixed styles and depth-limited children remain incomplete, requiring further inspection.
  • Variable bindings/IDs and explicit modes are retained. Resolve actual mode values with available variable tools; bindings alone are not resolved tokens.
  • These scripts are not complete exports of every Plugin API property. Asset inventory does not export SVG/bitmap bytes. Record unsupported properties and obtain actual exports separately.
  • Without use_figma, use standard design-context/metadata/variable/screenshot tools or supplied structured exports. Do not fabricate a compatible raw dump from generated CSS; record extraction limitations.

Local commands

python3 tools/figma-spec/dump_to_yaml.py raw.json docs/design-spec/checkout/components --page Checkout --block C1 --url 'https://www.figma.com/design/your-file/Checkout'
python3 tools/figma-spec/crosscheck.py docs/design-spec/checkout fresh.json --write
python3 tools/figma-spec/validate_spec.py docs/design-spec/checkout --strict
python3 tools/figma-spec/compare_screens.py reference.png rendered.png --out diff.png --threshold 2 --tolerance 16 --json

Use fresh dumps covering every component; merge bounded batches into one nodes array (with unique IDs and capture timestamp). Cross-check fails on missing components, zero checks, changed frame sizes or nested positions. Top-level canvas placement is deliberately excluded; relative child placement is checked. A fresh dump with the same depth cannot prove omitted descendants were inspected. Strict validation rejects depth truncation, mixed text styles, unknown verification, incomplete scope and blocking questions.

Conversion emits JSON-compatible YAML, quotes ambiguous strings, uses safe filename slugs, and marks prior implementation evidence stale when the design fingerprint changes. Implementation tracking uses files and tests, independent of framework.

Image comparison checks RGBA differences. Sizes must match by default; --resize is an explicit opt-in only for a documented export-scale difference with matching aspect ratios. --crop x,y,w,h crops the candidate only and must remain inside its bounds. Keep raw references alongside the diff. Record threshold, tolerance, crop/resampling, theme, viewport, content and font setup. A low pixel-difference percentage is a numerical result, not proof of behavior or accessibility. No universal threshold guarantees design fidelity.

Contract shape

Alongside generated components/*.yml and actual screenshots/*.png, write:

# index.yml
schema_version: 1
figma:
  file_key: your-file-key
coverage: complete
pages:
  - file: pages/checkout.yml
# pages/checkout.yml
sections:
  - blocks:
      - code: C1
        node_id: '1:2'
        title: Checkout
# acceptance_criteria.yml
acceptance_criteria:
  - id: C1-AC1
    block: C1
    text: Submit remains disabled while saving.
    source: verbatim
    source_node_id: '1:3'
    source_text: Submit remains disabled while saving.
    components: [components/submit--1-2.yml]
    verify_by: native-ui-test
# questions.yml
questions: []

Set each component's verification.screenshot_capture to pass only after capturing its real reference. crosscheck.py --write records the value check and capture timestamp. --strict verifies contract readiness; non-strict mode checks structural errors and prints pending verification warnings. Neither proves the implementation passed runtime checks. Keep tokens, strings, raw dumps and overall verification/drift reports per the harvest skill.

Adapted from the seller-app's Figma tools. Tested with local synthetic captures and mock Plugin API responses; live Figma reads and platform builds remain unverified.

Clone this wiki locally