How to Extract Metadata from Figma and Sketch Design Files

Design files carry far more structured data than most teams realize. When a designer saves a Figma file or exports a Sketch document, the resulting artifact contains layers of metadata that describe the file's history, structure, and content.

Figma files store metadata on the server and expose it through a REST API. Each file tracks its name, last modified timestamp, editor type, thumbnail URL, current version string, and the full document tree. The components map links node IDs to component metadata like name, description, and containing frame. The styles map does the same for color styles, text styles, and effect styles. Version history records every named save point with timestamps and user attribution.

Sketch files take a different approach. A .sketch file is a ZIP archive containing JSON-encoded data alongside binary assets. Unzip one and you will find meta.json (document metadata including Sketch version, fonts, pages, and artboards), document.json (shared styles and page references), user.json (viewport settings, zoom levels, and Cloud sync status), a pages/ folder with one JSON file per page, an images/ folder with original-resolution bitmaps, and a previews/ folder with a rendered preview of the last edited page.

This distinction matters for extraction workflows. Figma metadata requires authenticated API calls. Sketch metadata requires file access and ZIP parsing. Both produce JSON, but the retrieval path is completely different.

For teams managing design assets at scale, extracting this metadata enables automatic cataloging, version tracking, component audits, and integration with digital asset management systems.

Figma exposes file metadata through its REST API. You need a personal access token (generated in your Figma account settings) and the file key, which is the alphanumeric string in any Figma file URL between /design/ and the file name.

Getting File Metadata

The primary endpoint is GET /v1/files/:key. Here is a Python example that retrieves the core metadata:

import requests

FIGMA_TOKEN = "your-personal-access-token"
FILE_KEY = "abc123XYZ"

headers = {"X-Figma-Token": FIGMA_TOKEN}
response = requests.get(
    f"https://api.figma.com/v1/files/{FILE_KEY}",
    headers=headers
)
data = response.json()

print(f"Name: {data['name']}")
print(f"Last modified: {data['lastModified']}")
print(f"Version: {data['version']}")
print(f"Editor type: {data['editorType']}")
print(f"Schema version: {data['schemaVersion']}")

The response includes the full document tree under data['document'], which can be large for complex files. Use the depth query parameter to limit traversal. Setting depth=1 returns only top-level pages without their children, which is enough for a file inventory.

Extracting Component Metadata

The components field maps node IDs to component metadata. This is how you build a component inventory:

components = data.get("components", {})
for node_id, meta in components.items():
    print(f"  {meta['name']} (ID: {node_id})")
    if meta.get("description"):
        print(f"    Description: {meta['description']}")
    print(f"    Containing frame: {meta.get('containing_frame', {}).get('name', 'N/A')}")

Component sets (variants) appear in the componentSets field with the same structure. Styles live in the styles map, where each entry includes the style name, type (FILL, TEXT, EFFECT, or GRID), and description.

Retrieving Version History

Figma tracks file versions over time. Use the versions endpoint to pull the full history:

versions_resp = requests.get(
    f"https://api.figma.com/v1/files/{FILE_KEY}/versions",
    headers=headers
)
for version in versions_resp.json()["versions"]:
    print(f"  {version['created_at']} - {version['label'] or '(unlabeled)'}")
    print(f"    By: {version['user']['handle']}")

Each version entry includes the creation timestamp, user who saved it, an optional label, and a version ID that you can pass back to the file endpoint to retrieve the document tree at that point in time.

Fetching Specific Nodes

If you only need metadata for certain frames or components, the GET /v1/files/:key/nodes endpoint accepts a comma-separated ids parameter. This is faster and returns less data than requesting the entire file.

Rate limits apply to all Figma API calls. File content endpoints are Tier 1, which means lower throughput. For batch extraction across many files, add delays between requests and cache responses locally.

Store and Query Your Design Metadata

Upload design files to Fast.io workspaces. Search file contents with AI, build Metadata Views for structured querying, and share results with your team. 50 GB free, no credit card required.

Sign Up Free

Sketch files are self-contained ZIP archives. You do not need the Sketch application to read their metadata, just a ZIP library and a JSON parser.

Extracting the Archive

In Python, the zipfile module handles extraction:

import zipfile
import json

with zipfile.ZipFile("design-system.sketch", "r") as zf:
    meta = json.loads(zf.read("meta.json"))
    document = json.loads(zf.read("document.json"))
    user = json.loads(zf.read("user.json"))

print(f"Sketch version: {meta['appVersion']}")
    print(f"Build: {meta['build']}")
    print(f"Pages: {len(meta['pagesAndArtboards'])}")

for page_id, page_info in meta["pagesAndArtboards"].items():
        print(f"  Page: {page_info['name']}")
        for artboard in page_info.get("artboards", {}).values():
            print(f"    Artboard: {artboard['name']}")

The meta.json file gives you a document overview without parsing the full page tree. It includes the list of fonts used, so you can audit font dependencies across files without opening each one in Sketch.

Deep Page Parsing

For layer-level metadata, read the individual page JSON files:

def extract_layers(layer, depth=0):
    info = {
        "name": layer["name"],
        "class": layer["_class"],
        "id": layer["do_objectID"],
        "visible": not layer.get("isVisible", True) is False,
    }
    if "frame" in layer:
        f = layer["frame"]
        info["dimensions"] = {
            "x": f["x"], "y": f["y"],
            "width": f["width"], "height": f["height"]
        }
    return info

with zipfile.ZipFile("design-system.sketch", "r") as zf:
    for name in zf.namelist():
        if name.startswith("pages/") and name.endswith(".json"):
            page = json.loads(zf.read(name))
            for layer in page.get("layers", []):
                print(extract_layers(layer))

Each layer object contains the class type (rectangle, text, group, symbolInstance, etc.), position and size in the frame field, style properties, and a unique do_objectID. Symbol instances reference their master symbol by ID, so you can trace which shared components are used across the file.

Using sketchtool CLI

If you have

Sketch installed on macOS, the bundled sketchtool command provides metadata extraction without writing code:

sketchtool metadata design-system.sketch

This outputs JSON with the app version, build number, compatibility version, font list, creation metadata, save history, and a complete mapping of pages to artboards. The output mirrors the raw meta.json content but is accessible from a single command without manual ZIP extraction.

For listing layers and artboards specifically:

sketchtool list artboards design-system.sketch
sketchtool list pages design-system.sketch

TypeScript Types

The sketch-file-format-ts npm package provides TypeScript definitions generated from the official Sketch JSON Schema. Use it to strongly type parsed Sketch data in Node.js projects:

import type { FileFormat } from "@sketch-hq/sketch-file-format-ts";

const meta: FileFormat.Meta = JSON.parse(metaJsonString);
console.log(meta.appVersion);

Individual file extraction is useful for one-off audits, but production workflows need a pipeline that handles both file formats, normalizes the output, and stores results for querying.

Normalizing Across Formats

Figma and Sketch metadata use different structures for the same concepts. A normalization layer maps both into a common schema:

def normalize_figma(api_data):
    return {
        "source": "figma",
        "file_name": api_data["name"],
        "last_modified": api_data["lastModified"],
        "version": api_data["version"],
        "components": [
            {"id": nid, "name": c["name"], "description": c.get("description", "")}
            for nid, c in api_data.get("components", {}).items()
        ],
        "styles": [
            {"id": sid, "name": s["name"], "type": s["styleType"]}
            for sid, s in api_data.get("styles", {}).items()
        ],
    }

def normalize_sketch(meta, document):
    return {
        "source": "sketch",
        "file_name": meta.get("appVersion", "unknown"),
        "last_modified": None,
        "version": str(meta.get("version", "")),
        "components": [],  # Requires page-level parsing for symbols
        "styles": [
            {"id": s["do_objectID"], "name": s["name"], "type": "shared"}
            for s in document.get("layerStyles", {}).get("objects", [])
        ],
    }

This normalized format gives you a consistent interface for downstream consumers like a DAM system, a component tracking dashboard, or an audit log.

Scheduling Extraction For Figma files, poll the API on a schedule. Comparing the lastModified timestamp against your stored value tells you whether a file has changed since the last extraction. Skip unchanged files to stay within rate limits.

For Sketch files, watch a shared directory or cloud storage bucket for new uploads. When a .sketch file lands, trigger extraction. Since Sketch files are local artifacts (not cloud-native like Figma), the trigger mechanism depends on your infrastructure: a file watcher daemon, a webhook from your storage provider, or a CI pipeline step.

Storing and Querying Results

Once extracted, metadata is most useful in a queryable format. A database table per entity (files, components, styles, versions) lets you answer questions like:

• Which components appear across the most files?
• When was this design token last modified?
• Which files still reference a deprecated style?
• How many artboards exist across all files in a project?

These queries drive design system governance. When a team deprecates a color token, a metadata query instantly shows which files still use it.

Extracting metadata is the first step. The harder problem is keeping that metadata organized, searchable, and accessible to the people and tools that need it.

Local scripts produce JSON files or database rows, but those outputs sit on one machine. Design teams, developers, and project managers all need access to the extracted data, and they need it without running scripts themselves.

Cloud storage with built-in intelligence changes the workflow. Instead of dumping extraction results into a shared drive and hoping people find them, platforms like Fast.io let you upload extracted metadata files into shared workspaces where the content is automatically indexed for search and AI-powered querying.

Fast.io's Metadata Views go a step further. Rather than writing custom parsing scripts for every file type, you describe the fields you want extracted in natural language, and the platform's AI designs a typed schema and populates a sortable, filterable spreadsheet. This works with the exported JSON, CSV, or even the original design files themselves. Need to extract component counts, font lists, and last-modified dates from a batch of Sketch files? Define those columns in a Metadata View and let the platform handle the rest.

For teams already using the Figma API or Sketch parsing scripts, the extracted output (JSON, CSV, or structured YAML) can be uploaded to a Fast.io workspace via the API or MCP server. Agents can automate the entire flow: extract metadata from Figma, normalize it, upload the results, and trigger a Metadata View update. The free agent plan includes 50 GB of storage and 5,000 credits per month with no credit card required.

Alternatives like Google Drive or Dropbox can store the extracted files, but they treat them as opaque blobs. You can search file names, not file contents. S3 gives you programmatic access but no built-in querying layer. A dedicated workspace platform bridges the gap between raw storage and structured data access.

Where this matters most is handoff. A design ops team extracts and catalogs metadata weekly. Product managers query it to understand component coverage. Developers reference it to check style token usage. The extraction pipeline produces the data. The workspace makes it usable.

Design System Audits

Component metadata extraction powers design system health checks. By pulling the component list from every Figma file in a team project, you can identify unused components, track adoption of new additions, and flag files still using detached instances. The Figma API's componentSets field distinguishes between base components and variant sets, so your audit can differentiate between a button component and its individual size/state variants.

Font and Asset Licensing

Sketch's meta.json includes a font list for the entire document. Extracting fonts across all Sketch files in a repository produces a complete font inventory for license compliance. Figma exposes font information at the node level within the document tree, requiring a recursive traversal of text nodes to collect the full font list.

Migration Between Tools

When migrating from Sketch to Figma (or vice versa), metadata extraction tells you what you are working with before you start. Pull page counts, artboard dimensions, symbol usage, and style definitions from the source files. Compare those against the target format's capabilities to identify what will carry over cleanly and what needs manual attention.

Handling Edge Cases

Large Figma files can produce responses exceeding 100 MB. Use the depth parameter to limit the document tree, or request specific nodes with the /nodes endpoint. Pagination is not available on the file endpoint, so large files require selective extraction.

Password-protected Sketch files cannot be unzipped without the password. The sketchtool CLI will prompt for credentials, but automated pipelines need the password passed programmatically or the file decrypted beforehand.

Figma branches are separate entities. The main file endpoint returns branch metadata (key, name, thumbnail, last modified), but extracting a branch's full content requires a separate API call using the branch key as the file key.

Sketch plugins store custom data in the userInfo field on documents and layers. This data uses reverse-domain namespacing (like com.example.plugin.data). If your extraction pipeline needs plugin metadata, include userInfo parsing in your layer traversal.

Deleted components in Figma still appear in instances that reference them. The component metadata will be missing from the components map, but instance nodes will retain their componentId. Your pipeline should handle these orphaned references gracefully.