Communitygithub.com

ZSeven-W/openpencil-skill

Skill de LLM para diseñar con OpenPencil mediante la CLI `op` y herramientas MCP

¿Qué es openpencil-skill?

Esta skill permite a agentes de IA, como Claude Code, Cursor o Codex, generar y manipular diseños vectoriales de calidad profesional utilizando OpenPencil. Aprovecha la CLI `op` y las herramientas del protocolo MCP (Model Context Protocol) para orquestar flujos de trabajo de diseño complejos. La skill admite tres enfoques principales: inserción individual de nodos con `op insert` (el más fiable y flexible), un DSL de diseño por lotes para estructuras planas, y un modo script que permite generar diseños dinámicos y basados en datos usando JavaScript real, ideal para patrones repetitivos como tablas o listas. Además, incluye herramientas para el post-procesado como `design:refine`, que resuelve iconos, valida el diseño y corrige problemas automáticamente. Está diseñada para funcionar tanto en la terminal como a través de servidores MCP, siendo útil para agentes que necesiten crear prototipos de UI rápidamente, modificar canvas existentes, o generar documentación visual de forma programática. La documentación detallada cubre el esquema completo de nodos PenNode con sus propiedades (frames, texto, iconos, imágenes), reglas estrictas de formato JSON para evitar errores de parseo, y ejemplos prácticos de código.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add ZSeven-W/openpencil-skill

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Diseño con OpenPencil

Genera diseños vectoriales de calidad profesional escribiendo árboles JSON de PenNode. Usa la CLI op o las herramientas MCP para crear, leer, actualizar y eliminar nodos en el lienzo de OpenPencil.

Cuándo Usarlo

  • Crear o modificar diseños de UI en archivos .op
  • Usar la CLI op para scriptear operaciones de diseño
  • Diseñar mediante herramientas MCP (batch_design, insert_node, design_skeleton)
  • Necesitar referencia sobre el esquema de PenNode, roles o reglas de layout

Referencia Rápida — CLI op

# Control de la aplicación
op start [--desktop|--web]           # Iniciar la app
op stop                              # Detener la instancia en ejecución
op status                            # Verificar si está en ejecución

# Documento
op open [file.op]                    # Abrir archivo o conectar al lienzo en vivo
op save <file.op>                    # Guardar el documento actual
op get [--depth N] [--pretty]        # Obtener el árbol del documento
op selection [--depth N]             # Obtener la selección actual del lienzo
op read-nodes [id...] [--depth N] [--vars]  # Leer subárbol(es) de nodos con resolución opcional de variables
op layout [--parent P] [--depth N]   # Instantánea del árbol de layout con posiciones calculadas
op find-space [--direction D] [--width N] [--height N]  # Encontrar espacio vacío en el lienzo

# Operaciones con nodos
op insert '<json>' [--parent P]     # Insertar nodo (--index N, --post-process)
op update <id> '<json>'              # Actualizar nodo
op delete <id>                       # Eliminar nodo
op move <id> <parent> [index]        # Mover nodo
op copy <id> <parent>                # Copiar nodo en profundidad
op replace <id> '<json>'             # Reemplazar nodo

# Diseño por lotes
op design '<dsl>'                    # DSL de diseño por lotes (inline, @file, o stdin) [--canvas-width N]
op design @ui.js                     # Script JS en sandbox: I(parent, obj) + bucles (.js/.mjs implica --script)
op design '<js>' --script            # Igual, inline/stdin (la bandera debe SEGUIR al payload)

# Flujo de trabajo por capas
op design:skeleton '<json>'          # Crear estructura de sección
op design:content <id> '<json>'      # Poblar contenido de la sección
op design:refine --root-id <id>      # Validar + corregir automáticamente (resuelve iconos) [--canvas-width N]

# Importación
op import:svg <file.svg> [--parent P]       # Importar SVG como nodos editables
op import:figma <file.fig> [--out out.op]   # Convertir archivo .fig de Figma a documento .op

# Páginas
op page list                         # Listar todas las páginas
op page add [--name N]               # Añadir una nueva página
op page remove <id>                  # Eliminar una página
op page rename <id> '<name>'         # Renombrar una página
op page reorder <id> <index>         # Mover página a una posición
op page duplicate <id>               # Clonar página con nuevos IDs

# Variables y Temas
op vars / op vars:set '<json>'       # Variables (--replace para reemplazar todas)
op themes / op themes:set '<json>'   # Temas (--replace para reemplazar todos)
op theme:save <file.optheme>         # Guardar el tema actual como archivo de preajuste
op theme:load <file.optheme>         # Cargar un archivo de preajuste de tema
op theme:list <directory>            # Listar preajustes .optheme en un directorio

# Pipeline de generación de código
op codegen:plan '<json>'             # Enviar plan de generación de código (framework, rootIds, opciones)
op codegen:submit '<json>'           # Enviar un fragmento de código para un nodo
op codegen:assemble [--framework F]  # Ensamblar todos los fragmentos enviados en la salida final
op codegen:clean                     # Limpiar el estado de generación de código

Indicadores globales: --file <ruta>, --page <id>, --pretty. Entradas: cadena inline, @ruta-de-archivo, o - (stdin).

Construir Diseños — Tres Enfoques

Enfoque 1: op insert (Recomendado)

La forma más fiable de construir diseños. Usa --parent para especificar el nodo padre. Captura el nodeId devuelto para referenciarlo después. Termina siempre con design:refine para resolver iconos y validar el layout.

# Crear frame raíz, capturar su ID
ROOT=$(op insert '{"type":"frame","name":"Página","width":375,"height":812,"layout":"vertical"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

# Insertar hijos usando --parent
op insert --parent "$ROOT" '{"type":"text","content":"Hola","fontSize":28,"fontWeight":700}'

# Post-procesado: resolver iconos, validar layout
op design:refine --root-id "$ROOT"

Enfoque 2: DSL de Diseño por Lotes

Una operación por línea. Vincula resultados con nombre= para referenciarlos después. Ideal para estructuras simples y planas.

Limitación: El analizador del DSL no puede manejar JSON profundamente anidado (p. ej., arrays children con objetos anidados, o múltiples niveles de anidamiento de arrays). Mantén cada llamada I() a un solo nivel de anidamiento. Para nodos complejos con hijos, usa llamadas I() separadas para padre e hijos, o usa op insert --parent.

root=I(null, { "type": "frame", "width": 1200, "layout": "vertical" })
nav=I(root, { "type": "frame", "role": "navbar", "height": 72 })
U(nav, { "fill": [{"type": "solid", "color": "#FFFFFF"}] })
tarjeta2=C(tarjeta1, grid, { "name": "Tarjeta 2" })
M(sidebar, main, 0)
D(seccion_vieja)
R(boton_viejo, { "type": "rectangle", "role": "button" })
OpSintaxisAcción
Inombre=I(padre, { nodo })Insertar
UU(ref, { actualizaciones })Actualizar
Cnombre=C(origen, padre, { sobrescrituras })Copiar
Rnombre=R(ref, { nodo })Reemplazar
MM(ref, padre, índice?)Mover
DD(ref)Eliminar
Gnombre=G(padre, "buscar", "consulta")Generar imagen mediante búsqueda

Patrón seguro para DSL — inserta siempre padre e hijos por separado:

btn=I(formulario, {"type":"rectangle","role":"button","width":"fill_container","height":50,"cornerRadius":12,"fill":[{"type":"solid","color":"#111111"}],"layout":"horizontal","justifyContent":"center","alignItems":"center"})
I(btn, {"type":"text","content":"Enviar","fontSize":16,"fontWeight":600,"fill":[{"type":"solid","color":"#FFFFFF"}]})

Enfoque 3: Modo Script (bucles y basado en datos — RECOMENDADO para estructuras repetitivas)

op design @ui.js                 # El archivo .js / .mjs implica modo script
op design '<código js>' --script   # inline o stdin; --script debe SEGUIR al payload

A través de MCP: llama a batch_design con el argumento script (exactamente UNO de nodes_json | operations | script por llamada). Este es EL MISMO protocolo que usan los agentes de diseño internos de OpenPencil; sigue el mismo contrato:

Escribe un programa en JavaScript (sin prosa, sin delimitadores de markdown) que construya el diseño llamando a la función global I(parent, node):

const id = I(parent, { ...node... });   // inserta un nodo, DEVUELVE su id (una cadena)

parent es null para un frame raíz, de otro modo es un id devuelto por una llamada ANTERIOR a I(...). Un nodo es hijo de X solo si llamas a I(X, {...}).

I(...) es la ÚNICA función disponible — no hay console, ni ningún otro constructor. No llames a console.log ni a ninguna función auxiliar; solo llama a I(...). El modo script es solo de inserción; usa las operaciones del DSL (Enfoque 2) para actualizar/mover/eliminar.

USA JAVASCRIPT REAL — const/let, arrays de datos, y bucles for...of / .forEach — para generar estructura repetitiva (filas de tabla, elementos de navegación, tarjetas, elementos de lista) iterando sobre un array de datos. PREFIERE un bucle en lugar de copiar y pegar llamadas casi idénticas a I(...).

Cada objeto de nodo comienza con type ("frame"/"text"/"rectangle"/"ellipse"/"path"/"icon_font") y usa propiedades en camelCase (cornerRadius, fontSize, fontWeight, justifyContent, alignItems, clipContent). NO establezcas x/y en hijos dentro de frames con layout.

Ejemplo:

const sec = I(null, {type:"frame", name:"Clientes", layout:"vertical", width:"fill_container", gap:0});
const tbl = I(sec, {type:"frame", layout:"vertical", width:"fill_container"});
const rows = [{name:"Ana García", status:"Activo"}, {name:"Carlos López", status:"VIP"}];
for (const r of rows) {
  const row = I(tbl, {type:"frame", layout:"horizontal", width:"fill_container", padding:[12,16]});
  const c1 = I(row, {type:"frame", width:"fill_container"}); I(c1, {type:"text", content:r.name});
  const c2 = I(row, {type:"frame", width:"fill_container"}); I(c2, {type:"text", content:r.status});
}

Genera CADA fila/tarjeta/elemento con valores realistas. Genera SOLO el programa JavaScript.

Notas CLI/MCP:

  • Los arrays children anidados son SEGUROS aquí — el motor serializa cada objeto a JSON perfecto de una sola línea, por lo que la limitación de un solo nivel de anidamiento del DSL no aplica. Prefiere llamadas I() separadas de todos modos cuando necesites la vinculación del padre.
  • Los ids de los nodos se reasignan al insertar — no referencies un "id" creado después de la llamada; solo la vinculación devuelta es significativa, y solo dentro de este script.
  • Límites: 256 KiB de fuente, 4096 inserciones, 8 MiB de salida registrada, 2 s de CPU, 64 MiB de memoria. Un script truncado a mitad de una declaración se repara con el mejor esfuerzo (el prefijo completo aún se ejecuta).

Reglas JSON Estrictas

Al emitir JSON de PenNode (mediante op insert, op design, batch_design, insert_node), DEBES producir JSON estrictamente válido. Errores comunes que rompen el análisis:

  • Cada propiedad DEBE tener tanto una clave como un valor. NUNCA emitas ": 50 o : 50 sin un nombre de clave. Esto sucede a menudo cuando truncas/reformateas — verifica dos veces.
  • Cada clave DEBE ser una cadena no vacía entre comillas dobles.
  • fill es SIEMPRE un array: "fill": [{"type": "solid", "color": "#hex"}]. La forma abreviada "fill": "#hex" funciona, pero la forma de array es la canónica.
  • stroke es un objeto con un array fill: "stroke": {"thickness": 1, "fill": [{"type": "solid", "color": "#hex"}]}. NUNCA "stroke": {"thickness": 1, "color": "#hex"} o "stroke": "#hex" (el analizador convierte automáticamente estos, pero la forma correcta es preferida).
  • SIN comas finales antes de } o ].
  • SIN comentarios dentro de JSON (// o /* */).
  • Usa comillas dobles rectas ", no comillas inteligentes/curvas.
  • content para texto, NO text: {"type": "text", "content": "Hola"}.
  • iconFontName para iconos, NO iconName ni icon: {"type": "icon_font", "iconFontName": "lock"}.
  • Antes de finalizar el JSON, verifica mentalmente: cada clave tiene un valor, cada valor tiene una clave, todos los corchetes están balanceados.

Esquema de PenNode

Propiedades Comunes

{
  "type": "frame|rectangle|text|ellipse|line|polygon|path|image|icon_font|group|ref",
  "name": "Nombre para Mostrar",
  "role": "rol-semántico",
  "x": 0, "y": 0,
  "rotation": 0, "opacity": 1, "visible": true
}

Propiedades de Contenedor (frame, rectangle, group, ellipse)

{
  "width": 400,              // número | "fill_container" | "fit_content"
  "height": 300,
  "layout": "vertical",      // "none" | "vertical" | "horizontal"
  "gap": 16,
  "padding": [16, 24],       // número | [v, h] | [superior, derecho, inferior, izquierdo]
  "justifyContent": "center", // "start" | "center" | "end" | "space_between" | "space_around"
  "alignItems": "center",    // "start" | "center" | "end"
  "clipContent": true,
  "cornerRadius": 12,        // número | [si, sd, ii, id]
  "fill": [{ "type": "solid", "color": "#FFFFFF" }],
  "stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }], "align": "inside", "dashPattern": [5, 3] },
  "effects": [{ "type": "shadow", "offsetX": 0, "offsetY": 4, "blur": 12, "spread": 0, "color": "rgba(0,0,0,0.08)" }],
  "children": []
}

Texto

{
  "type": "text",
  "content": "Hola",          // cadena o StyledTextSegment[]
  "fontSize": 16, "fontFamily": "Inter", "fontWeight": 600,
  "textAlign": "center",       // "left" | "center" | "right"
  "textGrowth": "fixed-width", // "auto" | "fixed-width" | "fixed-width-height"
  "lineHeight": 1.5, "letterSpacing": 0,
  "fill": [{ "type": "solid", "color": "#111111" }]
}

Texto enriquecido: "content": [{ "text": "Negrita ", "fontWeight": "bold" }, { "text": "normal" }]

Iconos — Dos Opciones

Opción A: icon_font (RECOMENDADO — se renderiza directamente, sin necesidad de post-procesado)

{ "type": "icon_font", "name": "Icono de Candado", "iconFontName": "lock",
  "width": 20, "height": 20,
  "fill": [{ "type": "solid", "color": "#6B7280" }] }

El campo es iconFontName (NO iconName, NO icon). Los valores son nombres Lucide en kebab-case minúsculas: mail, lock, eye, eye-off, chrome, apple, message-circle, x, arrow-right, search, heart, star, check, plus, bell, home, user, settings, chevron-right, download, globe, layers, zap, shield, play.

Funciona en TODOS los contextos: CLI, herramientas MCP, o archivos .op directos — no requiere design:refine.

Opción B: path (requiere post-procesado)

{ "type": "path", "name": "HeartIcon", "width": 24, "height": 24,
  "fill": [{ "type": "solid", "color": "#111111" }] }

PascalCase + sufijo "Icon". Se resuelve automáticamente desde el conjunto de Lucide durante el post-procesado.

Los iconos de tipo path necesitan post-procesado. Después de insertar nodos path, ejecuta op design:refine --root-id <id> o usa op insert --post-process. Sin esto, los iconos path no se renderizarán visualmente. El servidor MCP independiente (usado por agentes ACP) NO tiene implementaciones de hooks registradas, por lo que los iconos path NO se resolverán allí — prefiere icon_font en contextos MCP.

Imagen

{ "type": "image", "src": "https://ejemplo.com/foto.jpg", "width": 400, "height": 300,
  "objectFit": "crop", "cornerRadius": 12 }

Marcadores de posición de imagen por IA (resueltos por design:refine):

{ "type": "image", "width": 400, "height": 300,
  "imagePrompt": "Un espacio de oficina moderno con luz natural",
  "imageSearchQuery": "espacio de oficina moderno" }

Ajustes de imagen (todos de -100 a 100): exposure, contrast, saturation, temperature, tint, highlights, shadows.

Polígono

{ "type": "polygon", "polygonCount": 6, "width": 80, "height": 80, "cornerRadius": 4,
  "fill": [{ "type": "solid", "color": "#6366F1" }] }

Fuente de Icono

{ "type": "icon_font", "iconFontName": "lucide:home", "width": 24, "height": 24,
  "fill": [{ "type": "solid", "color": "#111111" }] }

Línea

{ "type": "line", "x2": 200, "y2": 0,
  "stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }] } }

Tipos de Relleno

{ "type": "solid", "color": "#3B82F6" }
{ "type": "gradient", "gradientType": "linear", "startX": 0, "startY": 0, "endX": 1, "endY": 0, "stops": [{ "position": 0, "color": "#3B82F6" }, { "position": 1, "color": "#8B5CF6" }] }
{ "type": "image", "src": "https://..." }

Sombras / Efectos

{ "type": "shadow", "offsetX": 0, "offsetY": 4, "blur": 12, "spread": 0, "color": "rgba(0,0,0,0.08)" }
{ "type": "blur", "blurType": "layer", "radius": 8 }

Propiedades de Layout

Los contenedores con layout distribuyen automáticamente a sus hijos. No establezcas x/y en hijos dentro de un frame con layout.

layoutComportamiento
nonePosicionamiento absoluto (se requiere x/y)
verticalLos hijos se apilan verticalmente. justifyContent controla el espaciado vertical. alignItems controla la alineación horizontal.
horizontalLos hijos se apilan horizontalmente. justifyContent controla el espaciado horizontal. alignItems controla la alineación vertical.

Modos de tamaño:

  • número (p. ej., 400): tamaño fijo en píxeles
  • "fill_container": estirar para llenar el espacio disponible del contenedor
  • "fit_content": reducir al contenido (solo contenedores)

Sombra de cuadro vs. Efecto de sombra: No hay una propiedad boxShadow. Usa effects: [{ type: "shadow", ... }].

Roles Semánticos

Los roles ayudan a organizar y estilizar los diseños. Aplica para alinear con librerías de componentes (p. ej., Shadcn/ui).

RolUso
heroSección principal del encabezado
navbar, sidebarNavegación
card, card-header, card-content, card-footerTarjetas
modal, modal-contentDiálogos superpuestos
form, form-field, form-label, form-input, form-textarea, form-select, form-checkbox, form-radio, form-switch, form-button, form-errorElementos de formulario
button, button-primary, button-secondary, button-outline, button-ghost, button-dangerBotones
badge, badge-success, badge-warning, badge-errorInsignias / etiquetas
table, table-row, table-header, table-cellTablas y cuadrículas de datos
avatarAvatares de usuario
tabs, tabNavegación por pestañas
accordion, accordion-item, accordion-trigger, accordion-contentAcordeones
alert, alert-title, alert-descriptionAlertas
icon-wrapperContenedor de iconos
section, divider, spacer, tooltip, drawerUtilidades de layout

Ejemplos de Referencia de Diseño

Estos ejemplos producen diseños completos y detallados que pueden ser verificados visualmente. Sigue el estilo y nivel de detalle.

Ejemplo 1: Página de Lista de Clientes (modo script)

const page = I(null, {type:"frame", name:"CRM Dashboard", layout:"vertical", width:960, fill:[{type:"solid",color:"#F9FAFB"}]});
const header = I(page, {type:"frame", layout:"horizontal", width:"fill_container", padding:[24,32], alignItems:"center", justifyContent:"space_between", fill:[{type:"solid",color:"#FFFFFF"}], effects:[{type:"shadow",offsetY:1,blur:3,color:"rgba(0,0,0,0.05)"}]});
I(header, {type:"text",content:"Clientes",fontSize:24,fontWeight:700,fill:[{type:"solid",color:"#111827"}]});
const addBtn = I(header, {type:"frame", role:"button-primary", layout:"horizontal", padding:[12,20], cornerRadius:8, gap:8, alignItems:"center", fill:[{type:"solid",color:"#3B82F6"}]});
I(addBtn, {type:"icon_font",iconFontName:"plus",width:16,height:16,fill:[{type:"solid",color:"#FFFFFF"}]});
I(addBtn, {type:"text",content:"Añadir Cliente",fontSize:14,fontWeight:600,fill:[{type:"solid",color:"#FFFFFF"}]});
const table = I(page, {type:"frame", role:"table", layout:"vertical", width:"fill_container", margin:[24,32,0,32], fill:[{type:"solid",color:"#FFFFFF"}], cornerRadius:12, effects:[{type:"shadow",offsetY:1,blur:4,color:"rgba(0,0,0,0.04)"}]});
const headerRow = I(table, {type:"frame", role:"table-header", layout:"horizontal", width:"fill_container", padding:[16,20], fill:[{type:"solid",color:"#F9FAFB"}]});
I(headerRow, {type:"text",content:"Nombre",fontSize:12,fontWeight:600,width:200,fill:[{type:"solid",color:"#6B7280"}]});
I(headerRow, {type:"text",content:"Email",fontSize:12,fontWeight:600,width:280,fill:[{type:"solid",color:"#6B7280"}]});
I(headerRow, {type:"text",content:"Estado",fontSize:12,fontWeight:600,width:120,fill:[{type:"solid",color:"#6B7280"}]});
I(headerRow, {type:"text",content:"Plan",fontSize:12,fontWeight:600,width:120,fill:[{type:"solid",color:"#6B7280"}]});
I(headerRow, {type:"text",content:"Acción",fontSize:12,fontWeight:600,width:80,fill:[{type:"solid",color:"#6B7280"}]});
const rows = [
  {name:"Ana García",email:"[email protected]",status:"Activo",plan:"Pro"},
  {name:"Carlos López",email:"[email protected]",status:"VIP",plan:"Enterprise"},
  {name:"María Rodríguez",email:"[email protected]",status:"Inactivo",plan:"Básico"}
];
for (const r of rows) {
  const row = I(table, {type:"frame", role:"table-row", layout:"horizontal", width:"fill_container", padding:[16,20], fill:[{type:"solid",color:"#FFFFFF"}]});
  I(row, {type:"text",content:r.name,fontSize:14,fontWeight:500,width:200,fill:[{type:"solid",color:"#111827"}]});
  I(row, {type:"text",content:r.email,fontSize:14,width:280,fill:[{type:"solid",color:"#6B7280"}]});
  const statusColor = r.status === "Activo" ? "#10B981" : r.status === "VIP" ? "#8B5CF6" : "#EF4444";
  const badge = I(row, {type:"frame", role:"badge", layout:"horizontal", width:100, padding:[4,12], cornerRadius:100, alignItems:"center", justifyContent:"center", fill:[{type:"solid",color:statusColor+"20"}]});
  I(badge, {type:"text",content:r.status,fontSize:12,fontWeight:600,fill:[{type:"solid",color:statusColor}]});
  I(row, {type:"text",content:r.plan,fontSize:14,width:120,fill:[{type:"solid",color:"#374151"}]});
  I(row, {type:"icon_font",iconFontName:"more-horizontal",width:20,height:20,fill:[{type:"solid",color:"#9CA3AF"}]});
}
const summary = I(page, {type:"frame", layout:"horizontal", width:"fill_container", padding:[24,32], alignItems:"center", justifyContent:"space_between"});
I(summary, {type:"text",content:"Mostrando 3 de 24 clientes",fontSize:14,fill:[{type:"solid",color:"#6B7280"}]});
const pagination = I(summary, {type:"frame", layout:"horizontal", gap:8});
I(pagination, {type:"rectangle", width:32, height:32, cornerRadius:6, fill:[{type:"solid",color:"#3B82F6"}]});
for (const n of [2,3,4]) { I(pagination, {type:"rectangle", width:32, height:32, cornerRadius:6, fill:[{type:"solid",color:"#F3F4F6"}]}); }

Ejemplo 2: Tarjeta de Producto (enfoque op insert)

# Frame del producto
PRODUCT=$(op insert '{"type":"frame","name":"Tarjeta de Producto","role":"card","width":320,"layout":"vertical","cornerRadius":16,"fill":[{"type":"solid","color":"#FFFFFF"}],"effects":[{"type":"shadow","offsetY":4,"blur":20,"color":"rgba(0,0,0,0.08)"}]}' | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

# Imagen del producto
IMAGE=$(op insert --parent "$PRODUCT" '{"type":"image","width":"fill_container","height":200,"cornerRadius":[16,16,0,0],"objectFit":"crop","imagePrompt":"Zapatillas deportivas modernas con diseño elegante"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

# Contenido
CONTENT=$(op insert --parent "$PRODUCT" '{"type":"frame","layout":"vertical","width":"fill_container","padding":[20,20,24,20],"gap":12}' | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

# Nombre del producto
op insert --parent "$CONTENT" '{"type":"text","content":"UltraBoost Pro X3","fontSize":20,"fontWeight":700,"fill":[{"type":"solid","color":"#111827"}]}'

# Descripción
op insert --parent "$CONTENT" '{"type":"text","content":"Diseñadas para el máximo rendimiento con tecnología de amortiguación adaptativa.","fontSize":14,"fill":[{"type":"solid","color":"#6B7280"}]}'

# Fila de precio
PRICE_ROW=$(op insert --parent "$CONTENT" '{"type":"frame","layout":"horizontal","width":"fill_container","alignItems":"center","justifyContent":"space_between","padding":[0,0,0,0]}' | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

op insert --parent "$PRICE_ROW" '{"type":"text","content":"$149.99","fontSize":24,"fontWeight":800,"fill":[{"type":"solid","color":"#059669"}]}'

RATING=$(op insert --parent "$PRICE_ROW" '{"type":"frame","layout":"horizontal","gap":4,"alignItems":"center"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

op insert --parent "$RATING" '{"type":"icon_font","iconFontName":"star","width":16,"height":16,"fill":[{"type":"solid","color":"#F59E0B"}]}'
op insert --parent "$RATING" '{"type":"text","content":"4.9","fontSize":14,"fontWeight":600,"fill":[{"type":"solid","color":"#111827"}]}'

# Botón
ADD_BTN=$(op insert --parent "$CONTENT" '{"type":"frame","role":"button","layout":"horizontal","justifyContent":"center","alignItems":"center","width":"fill_container","height":48,"cornerRadius":12,"gap":8,"fill":[{"type":"solid","color":"#111827"}]}' | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")
op insert --parent "$ADD_BTN" '{"type":"icon_font","iconFontName":"shopping-cart","width":18,"height":18,"fill":[{"type":"solid","color":"#FFFFFF"}]}'
op insert --parent "$ADD_BTN" '{"type":"text","content":"Añadir al Carrito","fontSize":16,"fontWeight":600,"fill":[{"type":"solid","color":"#FFFFFF"}]}'

op design:refine --root-id "$PRODUCT"

Solución de Problemas

Errores Comunes de JSON

  • Token inesperado: A menudo causado por comillas curvas o caracteres escapados incorrectamente. Verifica que todas las comillas sean dobles rectas (") y que las barras invertidas sean correctas.
  • Coma perdida o adicional: Verifica que cada propiedad excepto la última tenga una coma después del valor. Las comas finales (antes de } o ]) son inválidas.
  • Los objetos type deben ser cadenas: "type": "frame", no "type": frame.
  • Los arrays de colores deben ser válidos: Los colores hexadecimales necesitan "#" y 6 dígitos.
  • fontWeight permite cadenas y números: Ambos 400 y "bold" funcionan.

Errores de Diseño por Lotes (DSL)

  • "parent node not found": La referencia nombre= debe ocurrir antes de su uso en una operación posterior. Verifica el orden.
  • "invalid operation": Verifica que el operador (I, U, C, R, M, D, G) esté escrito en mayúsculas y tenga los argumentos correctos.
  • "JSON parse error": Cada argumento JSON debe estar encerrado entre llaves {} y ser estrictamente válido.

Errores de Modo Script

  • I no está definido: Las funciones solo están disponibles en modo script. Usa --script o un archivo .js/.mjs.
  • ID de nodo no encontrado: La ID devuelta por I() solo es válida dentro de la ejecución del mismo script (los ids se reasignan). No pases ids codificados de una ejecución a otra.
  • Programa demasiado grande: Máximo 256 KiB de fuente. Extrae datos a un archivo separado o acorta la lógica de generación.
  • Se excedió el límite de inserciones: Máximo 4096 inserciones por script. Divide el diseño en múltiples scripts si es necesario.

Plataformas Soportadas

  • Terminal / CLI: Todos los comandos op están disponibles en la interfaz de línea de comandos.
  • MCP (Model Context Protocol): Las herramientas batch_design, insert_node, design_skeleton están disponibles a través de servidores MCP, permitiendo que agentes de IA (Claude Code, Cursor, Codex) interactúen con OpenPencil.
  • Servidor MCP independiente: Usado por agentes ACP. Nota: el post-procesado de iconos path no está disponible aquí; prefiere icon_font.

Flujo de Trabajo Recomendado

  1. Planifica la estructura del diseño (secciones, roles, jerarquía).
  2. Crea el esqueleto con op design:skeleton o inserta manualmente los frames raíz.
  3. Agrega contenido con op insert individual o con el DSL de diseño por lotes para estructuras planas.
  4. Para estructuras repetitivas (tablas, listas, cuadrículas), usa el modo script con bucles JavaScript.
  5. Post-procesa siempre con op design:refine para resolver iconos y validar el layout.
  6. Itera según sea necesario: actualiza, mueve o elimina nodos con los comandos correspondientes.

Consejos y Prácticas Recomendadas

  • Prefiere icon_font sobre path para iconos, especialmente en contextos MCP. Ahorra un paso de post-procesado y funciona en todas partes.
  • Usa roles semánticos (role: "card", role: "button-primary") para alinear con librerías de componentes como Shadcn/ui. Esto permite que OpenPencil aplique estilos inteligentes.
  • Mantén las estructuras JSON planas en el DSL de diseño por lotes. Para nodos anidados, usa op insert --parent o el modo script.
  • Captura los IDs de los nodos cuando crees estructuras que se referenciarán después (como frames contenedores o elementos de navegación).
  • Verifica el balance de corchetes antes de ejecutar. Un error de JSON detendrá todo el comando.
  • Para diseños complejos, considera dividir la generación en múltiples scripts o comandos MCP para evitar límites de inserción o de tamaño.

Skills relacionados