Communitygithub.com

ZSeven-W/openpencil-skill

Habilidade LLM para design com OpenPencil via CLI op e ferramentas MCP

O que é openpencil-skill?

Esta habilidade permite que agentes de IA gerem designs vetoriais de qualidade de produção utilizando o OpenPencil, uma ferramenta de design centrada em JSON. Através da CLI `op` ou de ferramentas MCP (como `batch_design`, `insert_node` e `design_skeleton`), os agentes podem criar, ler, atualizar e manipular nós em uma tela de design, programaticamente. A habilidade é particularmente útil para desenvolvedores e designers que desejam automatizar fluxos de trabalho de UI, gerar interfaces a partir de dados ou integrar design em pipelines de CI/CD. Ela suporta três abordagens principais de construção de design: inserção de nós individuais com `op insert`, operações em lote via uma DSL simples, e um modo de script JavaScript para estruturas repetitivas e complexas. A documentação inclui referência completa para a CLI `op`, regras estritas de JSON PenNode, e um guia completo do schema dos nós, abrangendo propriedades comuns, containers, texto, ícones (com recomendação para `icon_font`), imagens e outros tipos de nó. O objetivo principal da habilidade é capacitar agentes de IA a atuarem como designers, construindo e refinando layouts completos diretamente através de código, com validação e correção automática disponíveis.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add ZSeven-W/openpencil-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 op para 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 children com objetos aninhados, ou múltiplos níveis de aninhamento de array). Mantenha cada chamada I() a um único nível de aninhamento. Para nós complexos com filhos, use chamadas I() separadas para pai e filhos, ou use 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"}] })
card2=C(card1, grid, { "name": "Card 2" })
M(sidebar, main, 0)
D(old_section)
R(old_btn, { "type": "rectangle", "role": "button" })
OpSintaxeAção
Inome=I(pai, { nó })Inserir
UU(ref, { atualizações })Atualizar
Cnome=C(origem, pai, { substituições })Copiar
Rnome=R(ref, { nó })Substituir
MM(ref, pai, índice?)Mover
DD(ref)Excluir
Gnome=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 children aninhados 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 chamadas I() 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 ": 50 ou : 50 sem 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 array fill: "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.
  • content para texto, NÃO text: {"type": "text", "content": "Olá"}.
  • iconFontName para ícones, NÃO iconName ou icon: {"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 use op 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á — prefira icon_font em 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]

Habilidades Relacionadas