@directededges/specs-from-figma

Figma → spec. Core data transformation model for Specs design specification tools: transforms raw Figma design data into structured, deterministic component specs (YAML/JSON). Used across CLI, MCP, and plugin environments.

Overview

@directededges/specs-from-figma provides:

• Component Processing: Transform Figma design components into structured specifications
• Runtime Abstractions: Platform-agnostic data loading and node resolution
• Cross-Platform Support: Works in both Node.js (CLI/MCP) and Browser (Figma Plugin) environments

Installation

npm install @directededges/specs-from-figma

Usage

Plugin environment

import { Component } from '@directededges/specs-from-figma';

const component = await Component.fromPlugin(figmaNode, config);
console.log(component.yaml());

An optional coordinator and author can be passed as a third argument.

CLI / REST API environment

import { Component } from '@directededges/specs-from-figma';
import type { StylesMap, VariablesMap, CollectionsMap } from '@directededges/specs-from-figma';

const component = await Component.fromRestApi(
  libraryJson,   // raw REST API JSON
  componentId,   // component name or ID
  config,
  { styles, variables, collections }
);
console.log(component.yaml());

Both factory methods return a fully-processed Component. Call .yaml() for a YAML string or .json() for a plain object.

Public API

The public surface is intentionally minimal. All internal runtime and processing code is bundled and not re-exported.

Component

Main transformation class. Use the static factory methods — do not call new Component() directly.

| Method | Description | |--------|-------------| | Component.fromPlugin(node, config, options?) | Process a Figma Plugin API node | | Component.fromRestApi(json, id, config, options) | Process a component from REST API JSON | | component.yaml() | Returns a YAML string of the component specification | | component.json() | Returns a plain JavaScript object |

Foundations map types

Used as the options payload for fromRestApi:

• StylesMap — map of style IDs to style data
• VariablesMap — map of variable IDs to variable data
• CollectionsMap — map of collection IDs to collection data

Output schema types (e.g. Component from @directededges/specs-schema) are provided by the specs-schema package.

Development

Building

# Install dependencies
npm install

# Build the package
npm run build

# Build types only
npm run build:types

# Build JavaScript only
npm run build:js

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Version & Compatibility

• Pre-1.0 — breaking changes may occur in minor versions
• Node.js: 20+ required
• Target: ES2020
• Module Format: ESM only

License

PolyForm Internal Use License 1.0.0

Repository

https://github.com/DirectedEdges/specs-from-figma