@directededges/specs-from-figma

@directededges/specs-from-figma

Core data transformation model for Specs design specification tools. This package extracts the Model and Runtime layers from specs-plugin, enabling independent development and reusability 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

From GitHub Packages

# Configure npm to use GitHub Packages for @directededges scope
npm config set @directededges:registry https://npm.pkg.github.com

# Install the package
npm install @directededges/specs-from-figma

Authentication Required: You must configure a GitHub Personal Access Token with read:packages scope:

# Add to ~/.npmrc
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

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

Publishing

# Publish to GitHub Packages (runs build + test automatically)
npm publish

See CONTRIBUTING.md for contribution guidelines.

Architecture

See ARCHITECTURE.md for a system diagram, component hierarchy, runtime model, and design principles.

Version & Compatibility

• Version: 0.17.0 (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