`open-pencil eval` — API de Plugin compatible con Figma para scripting headless

Visión general

bun open-pencil eval <file> --code '<js>' ejecuta JavaScript contra un archivo .fig con un objeto global figma compatible con Figma. Esto permite scripting headless, operaciones por lotes, ejecución de herramientas IA y pruebas — todo sin interfaz gráfica.

El objeto figma refleja la superficie de la API de Plugin de Figma lo más fielmente posible, por lo que el conocimiento existente sobre plugins de Figma y los fragmentos de código son directamente transferibles.

# Crear un marco, configurar auto-layout, añadir hijos
bun open-pencil eval design.fig --code '
  const frame = figma.createFrame()
  frame.name = "Card"
  frame.resize(300, 200)
  frame.layoutMode = "VERTICAL"
  frame.itemSpacing = 12
  frame.fills = [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }]
  return { id: frame.id, name: frame.name }
'

# Consultar nodos
bun open-pencil eval design.fig --code '
  const buttons = figma.currentPage.findAll(n => n.name.includes("Button"))
  return buttons.map(b => ({ id: b.id, name: b.name }))
'

# Escribir los cambios
bun open-pencil eval design.fig --code '...' --write

Arquitectura

CLI: open-pencil eval <file> --code '...'
  → loadDocument(file) → SceneGraph
  → FigmaAPI(sceneGraph) → proxy `figma`
  → AsyncFunction('figma', code)(figmaProxy)
  → imprimir resultado / guardar con --write

Clases principales

Clase	Ubicación	Rol
`FigmaAPI`	`packages/core/src/figma-api.ts`	Objeto proxy que implementa métodos `figma.*`
`FigmaNode`	`packages/core/src/figma-api.ts`	Proxy que envuelve `SceneNode` con acceso a propiedades estilo Figma
Comando `eval`	`packages/cli/src/commands/eval.ts`	Carga documento, crea API, ejecuta código

¿Por qué en `@open-pencil/core`?

La clase FigmaAPI vive en core porque: las herramientas IA la reutilizan, los tests la usan y no tiene dependencias DOM.

Comando CLI

bun open-pencil eval <file> [opciones]

Argumentos:
  file            Archivo .fig sobre el que operar

Opciones:
  --code, -c      Código JavaScript a ejecutar
  --stdin         Leer código desde stdin
  --write, -w     Escribir cambios en el archivo de entrada
  -o, --output    Escribir en un archivo diferente
  --json          Salida como JSON
  --quiet, -q     Suprimir la salida

Implementación por fases

Fase 1: Core — creación de nodos, propiedades, operaciones de árbol, auto-layout, texto (~80% de scripts reales)
Fase 2: Componentes e Instancias — createComponent, createInstance, detachInstance
Fase 3: Variables — getLocalVariables, createVariable, setBoundVariable
Fase 4: Estilos y Avanzado — estilos paint/texto/efectos, operaciones booleanas

Referencia API completa en inglés

2.8 KiB Raw Blame History

open-pencil eval — API de Plugin compatible con Figma para scripting headless