Design OpenPencil
Gere designs vetoriais de qualidade de produção escrevendo árvores JSON PenNode. Use a CLI op ou ferramentas MCP para criar, ler, atualizar e excluir nós na tela do OpenPencil.
Quando Usar
- Criando ou modificando designs de UI em arquivos
.op - Usando a CLI
oppara script de operações de design - Projetando via ferramentas MCP (
batch_design,insert_node,design_skeleton) - Precisa de referência para schema PenNode, papéis ou regras de layout
Referência Rápida — CLI op
# Controle do aplicativo
op start [--desktop|--web] # Iniciar aplicativo
op stop # Parar instância em execução
op status # Verificar se está em execução
# Documento
op open [arquivo.op] # Abrir arquivo ou conectar à tela ativa
op save <arquivo.op> # Salvar documento atual
op get [--depth N] [--pretty] # Obter árvore do documento
op selection [--depth N] # Obter seleção atual da tela
op read-nodes [id...] [--depth N] [--vars] # Ler subárvore(s) de nó com resolução opcional de variáveis
op layout [--parent P] [--depth N] # Capturar árvore de layout com posições calculadas
op find-space [--direction D] [--width N] [--height N] # Encontrar espaço vazio na tela
# Operações de nó
op insert '<json>' [--parent P] # Inserir nó (--index N, --post-process)
op update <id> '<json>' # Atualizar nó
op delete <id> # Excluir nó
op move <id> <pai> [índice] # Mover nó
op copy <id> <pai> # Copiar nó profundamente
op replace <id> '<json>' # Substituir nó
# Design em lote
op design '<dsl>' # DSL de design em lote (inline, @arquivo, ou stdin) [--canvas-width N]
op design @ui.js # Script JS em sandbox: I(pai, obj) + loops (.js/.mjs implica --script)
op design '<js>' --script # Mesmo, inline/stdin (flag DEVE SEGUIR o payload)
# Fluxo de trabalho em camadas
op design:skeleton '<json>' # Criar estrutura de seção
op design:content <id> '<json>' # Preencher conteúdo da seção
op design:refine --root-id <id> # Validar + corrigir automaticamente (resolve ícones) [--canvas-width N]
# Importação
op import:svg <arquivo.svg> [--parent P] # Importar SVG como nós editáveis
op import:figma <arquivo.fig> [--out saida.op] # Converter Figma .fig para documento .op
# Páginas
op page list # Listar todas as páginas
op page add [--name N] # Adicionar uma nova página
op page remove <id> # Remover uma página
op page rename <id> '<nome>' # Renomear uma página
op page reorder <id> <índice> # Mover página para posição
op page duplicate <id> # Clonar página com novos IDs
# Variáveis e Temas
op vars / op vars:set '<json>' # Variáveis (--replace para substituir todas)
op themes / op themes:set '<json>' # Temas (--replace para substituir todos)
op theme:save <arquivo.optheme> # Salvar tema atual como arquivo predefinido
op theme:load <arquivo.optheme> # Carregar um arquivo de tema predefinido
op theme:list <diretório> # Listar predefinições .optheme em um diretório
# Pipeline de geração de código
op codegen:plan '<json>' # Enviar plano de geração de código (framework, rootIds, opções)
op codegen:submit '<json>' # Enviar um bloco de código para um nó
op codegen:assemble [--framework F] # Montar todos os blocos enviados na saída final
op codegen:clean # Limpar estado da geração de código
Flags globais: --file <caminho>, --page <id>, --pretty. Entradas: string inline, @caminhodearquivo, ou - (stdin).
Construindo Designs — Três Abordagens
Abordagem 1: op insert (Recomendado)
A maneira mais confiável de construir designs. Use --parent para especificar o nó pai. Capture o nodeId retornado para referência posterior. Sempre finalize com design:refine para resolver ícones e validar o layout.
# Criar frame raiz, capturar seu 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'])")
# Inserir filhos usando --parent
op insert --parent "$ROOT" '{"type":"text","content":"Olá","fontSize":28,"fontWeight":700}'
# Pós-processamento: resolver ícones, validar layout
op design:refine --root-id "$ROOT"
Abordagem 2: DSL de Design em Lote
Uma operação por linha. Vincule resultados com nome= para referência posterior. Melhor para estruturas simples e planas.
Limitação: O analisador DSL não consegue lidar com JSON profundamente aninhado (por exemplo, arrays
childrencom objetos aninhados, ou múltiplos níveis de aninhamento de array). Mantenha cada chamadaI()a um único nível de aninhamento. Para nós complexos com filhos, use chamadasI()separadas para pai e filhos, ou useop 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"}] })
card2=C(card1, grid, { "name": "Card 2" })
M(sidebar, main, 0)
D(old_section)
R(old_btn, { "type": "rectangle", "role": "button" })
| Op | Sintaxe | Ação |
|---|---|---|
I | nome=I(pai, { nó }) | Inserir |
U | U(ref, { atualizações }) | Atualizar |
C | nome=C(origem, pai, { substituições }) | Copiar |
R | nome=R(ref, { nó }) | Substituir |
M | M(ref, pai, índice?) | Mover |
D | D(ref) | Excluir |
G | nome=G(pai, "pesquisa", "consulta") | Gerar imagem por pesquisa |
Padrão seguro DSL — sempre insira pai e filhos separadamente:
btn=I(form, {"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"}]})
Abordagem 3: Modo script (loops e direcionado por dados — RECOMENDADO para estruturas repetidas)
op design @ui.js # arquivo .js / .mjs implica modo script
op design '<código js>' --script # inline ou stdin; --script DEVE SEGUIR o payload
Via MCP: chame batch_design com o argumento script (exatamente UM de nodes_json | operations | script por chamada). Este é o MESMO protocolo que os agentes de design internos do OpenPencil usam; siga o mesmo contrato:
Escreva um programa JavaScript (sem prosa, sem cercas markdown) que construa o design chamando a função global I(pai, nó):
const id = I(pai, { ...nó... }); // insere nó, RETORNA seu id (uma string)
pai é null para um frame raiz, caso contrário, um id retornado por uma chamada ANTERIOR I(...). Um nó é filho de X apenas se você chamar I(X, {...}).
I(...) é a ÚNICA função disponível — não há console, e nenhum outro construtor. Não chame console.log ou qualquer auxiliar; apenas chame I(...). Modo script é somente inserção; use as operações DSL (Abordagem 2) para atualizar/mover/excluir.
USE JAVASCRIPT REAL — const/let, arrays de dados, e loops for...of / .forEach — para gerar estruturas repetidas (linhas de tabela, itens de navegação, cards, itens de lista) iterando sobre um array de dados. PREFIRA um loop a copiar e colar chamadas I(...) quase idênticas.
Cada objeto de nó começa com type ("frame"/"text"/"rectangle"/"ellipse"/"path"/"icon_font") e usa propriedades em camelCase (cornerRadius, fontSize, fontWeight, justifyContent, alignItems, clipContent). NÃO defina x/y em filhos dentro de frames de layout.
Exemplo:
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:"Alice Chen", status:"Ativo"}, {name:"Bob Ito", 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});
}
Gere CADA linha/card/item com valores realistas. Produza APENAS o programa JavaScript.
Notas CLI/MCP:
- Arrays
childrenaninhados são SEGUROS aqui — o motor serializa cada objeto para JSON perfeito de linha única, então a limitação de um único nível de aninhamento do DSL não se aplica. Prefira chamadasI()separadas de qualquer forma quando precisar da vinculação do pai. - Os ids dos nós são remapeados na inserção — não referencie um
"id"escrito após a chamada; apenas a vinculação retornada é significativa, e apenas dentro deste script. - Limites: 256 KiB de fonte, 4096 inserções, 8 MiB de saída gravada, 2 s de CPU, 64 MiB de memória. Um script truncado no meio de uma instrução é reparado com o melhor esforço (o prefixo completo ainda é executado).
Regras ESTRITAS de JSON
Ao emitir JSON PenNode (via op insert, op design, batch_design, insert_node), você DEVE produzir JSON estritamente válido. Erros comuns que quebram a análise:
- Cada propriedade DEVE ter uma chave e um valor. NUNCA emita
": 50ou: 50sem um nome de chave. Isso acontece frequentemente quando você trunca/reformata — verifique novamente. - Cada chave DEVE ser uma string não vazia entre aspas duplas.
fillé SEMPRE um array:"fill": [{"type": "solid", "color": "#hex"}]. A forma abreviada"fill": "#hex"funciona, mas a forma de array é a forma canônica.strokeé um objeto com um arrayfill:"stroke": {"thickness": 1, "fill": [{"type": "solid", "color": "#hex"}]}. NUNCA"stroke": {"thickness": 1, "color": "#hex"}ou"stroke": "#hex"(o analisador converte automaticamente estes, mas a forma correta é preferida).- NÃO coloque vírgulas finais antes de
}ou]. - NÃO coloque comentários dentro de JSON (
//ou/* */). - Use aspas duplas retas
", não aspas inteligentes/curvas. contentpara texto, NÃOtext:{"type": "text", "content": "Olá"}.iconFontNamepara ícones, NÃOiconNameouicon:{"type": "icon_font", "iconFontName": "lock"}.- Antes de finalizar o JSON, verifique mentalmente: cada chave tem um valor, cada valor tem uma chave, todos os colchetes se equilibram.
Schema PenNode
Propriedades Comuns
{
"type": "frame|rectangle|text|ellipse|line|polygon|path|image|icon_font|group|ref",
"name": "Nome de Exibição",
"role": "papel-semântico",
"x": 0, "y": 0,
"rotation": 0, "opacity": 1, "visible": true
}
Propriedades de Container (frame, rectangle, group, ellipse)
{
"width": 400, // number | "fill_container" | "fit_content"
"height": 300,
"layout": "vertical", // "none" | "vertical" | "horizontal"
"gap": 16,
"padding": [16, 24], // number | [v, h] | [topo, direita, fundo, esquerda]
"justifyContent": "center", // "start" | "center" | "end" | "space_between" | "space_around"
"alignItems": "center", // "start" | "center" | "end"
"clipContent": true,
"cornerRadius": 12, // number | [se, sd, ie, 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": "Olá", // string ou 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 rico: "content": [{ "text": "Negrito ", "fontWeight": "bold" }, { "text": "normal" }]
Ícones — Duas Opções
Opção A: icon_font (RECOMENDADO — renderiza diretamente, sem necessidade de pós-processamento)
{ "type": "icon_font", "name": "Ícone de Cadeado", "iconFontName": "lock",
"width": 20, "height": 20,
"fill": [{ "type": "solid", "color": "#6B7280" }] }
O campo é iconFontName (NÃO iconName, NÃO icon). Os valores são nomes Lucide em kebab-case minúsculo: 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 em TODOS os contextos: CLI, ferramentas MCP, ou arquivos .op diretos — nenhum design:refine necessário.
Opção B: path (requer pós-processamento)
{ "type": "path", "name": "HeartIcon", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
PascalCase + sufixo "Icon". Resolvido automaticamente do conjunto Lucide durante o pós-processamento.
Ícones path precisam de pós-processamento. Após inserir nós de path, execute
op design:refine --root-id <id>ou useop insert --post-process. Sem isso, ícones path não renderizarão visualmente. O servidor MCP autônomo (usado por agentes ACP) NÃO tem implementações de hook registradas, então ícones path NÃO serão resolvidos lá — prefiraicon_fontem contextos MCP.
Imagem
{ "type": "image", "src": "https://exemplo.com/foto.jpg", "width": 400, "height": 300,
"objectFit": "crop", "cornerRadius": 12 }
Placeholders de imagem IA (resolvidos por design:refine):
{ "type": "image", "width": 400, "height": 300,
"imagePrompt": "Um espaço de trabalho moderno com luz natural",
"imageSearchQuery": "espaço de trabalho moderno" }
Ajustes de imagem (todos -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" }] }
Fonte de Ícone
{ "type": "icon_font", "iconFontName": "lucide:home", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
Linha
{ "type": "line", "x2": 200, "y2": 0,
"stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }] } }
Tipos de Preenchimento
{ "type": "solid", "color": "#3B82F6" }
{ "type": "lin"
…
[truncado para tradução]