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
oppara 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
childrencon objetos anidados, o múltiples niveles de anidamiento de arrays). Mantén cada llamadaI()a un solo nivel de anidamiento. Para nodos complejos con hijos, usa llamadasI()separadas para padre e hijos, o usaop 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" })
| Op | Sintaxis | Acción |
|---|---|---|
I | nombre=I(padre, { nodo }) | Insertar |
U | U(ref, { actualizaciones }) | Actualizar |
C | nombre=C(origen, padre, { sobrescrituras }) | Copiar |
R | nombre=R(ref, { nodo }) | Reemplazar |
M | M(ref, padre, índice?) | Mover |
D | D(ref) | Eliminar |
G | nombre=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
childrenanidados 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 llamadasI()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
": 50o: 50sin 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.
filles SIEMPRE un array:"fill": [{"type": "solid", "color": "#hex"}]. La forma abreviada"fill": "#hex"funciona, pero la forma de array es la canónica.strokees un objeto con un arrayfill:"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. contentpara texto, NOtext:{"type": "text", "content": "Hola"}.iconFontNamepara iconos, NOiconNameniicon:{"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 usaop 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í — prefiereicon_fonten 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.
| layout | Comportamiento |
|---|---|
none | Posicionamiento absoluto (se requiere x/y) |
vertical | Los hijos se apilan verticalmente. justifyContent controla el espaciado vertical. alignItems controla la alineación horizontal. |
horizontal | Los 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).
| Rol | Uso |
|---|---|
hero | Sección principal del encabezado |
navbar, sidebar | Navegación |
card, card-header, card-content, card-footer | Tarjetas |
modal, modal-content | Diálogos superpuestos |
form, form-field, form-label, form-input, form-textarea, form-select, form-checkbox, form-radio, form-switch, form-button, form-error | Elementos de formulario |
button, button-primary, button-secondary, button-outline, button-ghost, button-danger | Botones |
badge, badge-success, badge-warning, badge-error | Insignias / etiquetas |
table, table-row, table-header, table-cell | Tablas y cuadrículas de datos |
avatar | Avatares de usuario |
tabs, tab | Navegación por pestañas |
accordion, accordion-item, accordion-trigger, accordion-content | Acordeones |
alert, alert-title, alert-description | Alertas |
icon-wrapper | Contenedor de iconos |
section, divider, spacer, tooltip, drawer | Utilidades 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
typedeben ser cadenas:"type": "frame", no"type": frame. - Los arrays de colores deben ser válidos: Los colores hexadecimales necesitan
"#"y 6 dígitos. fontWeightpermite cadenas y números: Ambos400y"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
--scripto 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
opestán disponibles en la interfaz de línea de comandos. - MCP (Model Context Protocol): Las herramientas
batch_design,insert_node,design_skeletonestá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
- Planifica la estructura del diseño (secciones, roles, jerarquía).
- Crea el esqueleto con
op design:skeletono inserta manualmente los frames raíz. - Agrega contenido con
op insertindividual o con el DSL de diseño por lotes para estructuras planas. - Para estructuras repetitivas (tablas, listas, cuadrículas), usa el modo script con bucles JavaScript.
- Post-procesa siempre con
op design:refinepara resolver iconos y validar el layout. - Itera según sea necesario: actualiza, mueve o elimina nodos con los comandos correspondientes.
Consejos y Prácticas Recomendadas
- Prefiere
icon_fontsobrepathpara 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 --parento 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.