OpenPencil 디자인
PenNode JSON 트리를 작성하여 생산 품질의 벡터 디자인을 생성합니다. op CLI 또는 MCP 도구를 사용하여 OpenPencil 캔버스에서 노드를 생성, 읽기, 업데이트, 삭제합니다.
사용 시기
.op파일에서 UI 디자인을 생성하거나 수정할 때opCLI를 사용하여 디자인 작업을 스크립팅할 때- MCP 도구(
batch_design,insert_node,design_skeleton)를 통해 디자인할 때 - PenNode 스키마, 역할 또는 레이아웃 규칙에 대한 참조가 필요할 때
빠른 참조 — op CLI
# 앱 제어
op start [--desktop|--web] # 앱 실행
op stop # 실행 중인 인스턴스 중지
op status # 실행 중인지 확인
# 문서
op open [file.op] # 파일 열기 또는 라이브 캔버스에 연결
op save <file.op> # 현재 문서 저장
op get [--depth N] [--pretty] # 문서 트리 가져오기
op selection [--depth N] # 현재 캔버스 선택 항목 가져오기
op read-nodes [id...] [--depth N] [--vars] # 노드 하위 트리 읽기 (선택적 변수 해석)
op layout [--parent P] [--depth N] # 계산된 위치가 포함된 레이아웃 트리 스냅샷
op find-space [--direction D] [--width N] [--height N] # 캔버스에서 빈 공간 찾기
# 노드 작업
op insert '<json>' [--parent P] # 노드 삽입 (--index N, --post-process)
op update <id> '<json>' # 노드 업데이트
op delete <id> # 노드 삭제
op move <id> <parent> [index] # 노드 이동
op copy <id> <parent> # 노드 깊은 복사
op replace <id> '<json>' # 노드 교체
# 배치 디자인
op design '<dsl>' # 배치 디자인 DSL (인라인, @file, 또는 stdin) [--canvas-width N]
op design @ui.js # 샌드박스 처리된 JS 스크립트: I(parent, obj) + 루프 (.js/.mjs는 --script를 의미)
op design '<js>' --script # 동일, 인라인/stdin (플래그는 페이로드 뒤에 와야 함)
# 계층형 워크플로우
op design:skeleton '<json>' # 섹션 구조 생성
op design:content <id> '<json>' # 섹션 콘텐츠 채우기
op design:refine --root-id <id> # 검증 + 자동 수정 (아이콘 해결) [--canvas-width N]
# 가져오기
op import:svg <file.svg> [--parent P] # 편집 가능한 노드로 SVG 가져오기
op import:figma <file.fig> [--out out.op] # Figma .fig를 .op 문서로 변환
# 페이지
op page list # 모든 페이지 나열
op page add [--name N] # 새 페이지 추가
op page remove <id> # 페이지 제거
op page rename <id> '<name>' # 페이지 이름 바꾸기
op page reorder <id> <index> # 페이지 위치 이동
op page duplicate <id> # 새 ID로 페이지 복제
# 변수 및 테마
op vars / op vars:set '<json>' # 변수 (--replace로 모두 교체)
op themes / op themes:set '<json>' # 테마 (--replace로 모두 교체)
op theme:save <file.optheme> # 현재 테마를 프리셋 파일로 저장
op theme:load <file.optheme> # 테마 프리셋 파일 로드
op theme:list <directory> # 디렉토리에서 .optheme 프리셋 나열
# 코드 생성 파이프라인
op codegen:plan '<json>' # 코드 생성 계획 제출 (프레임워크, rootIds, 옵션)
op codegen:submit '<json>' # 노드에 대한 코드 청크 제출
op codegen:assemble [--framework F] # 제출된 모든 청크를 최종 출력으로 조합
op codegen:clean # 코드 생성 상태 지우기
전역 플래그: --file <path>, --page <id>, --pretty. 입력: 인라인 문자열, @filepath, 또는 - (stdin).
디자인 구축 — 세 가지 접근 방식
접근 방식 1: op insert (권장)
디자인을 구축하는 가장 안정적인 방법입니다. --parent를 사용하여 상위 노드를 지정합니다. 반환된 nodeId를 캡처하여 나중에 참조합니다. 항상 design:refine으로 마무리하여 아이콘을 해결하고 레이아웃을 검증하세요.
# 루트 프레임 생성, ID 캡처
ROOT=$(op insert '{"type":"frame","name":"Page","width":375,"height":812,"layout":"vertical"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")
# --parent를 사용하여 자식 삽입
op insert --parent "$ROOT" '{"type":"text","content":"Hello","fontSize":28,"fontWeight":700}'
# 후처리: 아이콘 해결, 레이아웃 검증
op design:refine --root-id "$ROOT"
접근 방식 2: 배치 디자인 DSL
한 줄에 하나의 작업. name=으로 결과를 바인딩하여 나중에 참조합니다. 간단하고 평평한 구조에 가장 적합합니다.
제한 사항: DSL 파서는 깊이 중첩된 JSON(예: 중첩 객체가 있는
children배열, 또는 여러 수준의 배열 중첩)을 처리할 수 없습니다. 각I()호출을 단일 중첩 수준으로 유지하세요. 자식이 있는 복잡한 노드의 경우 상위 및 자식에 대해 별도의I()호출을 사용하거나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" })
| 작업 | 구문 | 작업 |
|---|---|---|
I | name=I(parent, { node }) | 삽입 |
U | U(ref, { updates }) | 업데이트 |
C | name=C(source, parent, { overrides }) | 복사 |
R | name=R(ref, { node }) | 교체 |
M | M(ref, parent, index?) | 이동 |
D | D(ref) | 삭제 |
G | name=G(parent, "search", "query") | 검색을 통해 이미지 생성 |
DSL 안전 패턴 — 항상 상위와 자식을 별도로 삽입:
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":"Submit","fontSize":16,"fontWeight":600,"fill":[{"type":"solid","color":"#FFFFFF"}]})
접근 방식 3: 스크립트 모드 (루프 및 데이터 중심 — 반복 구조에 권장)
op design @ui.js # .js / .mjs 파일은 스크립트 모드를 의미
op design '<js code>' --script # 인라인 또는 stdin; --script는 페이로드 뒤에 와야 함
MCP를 통해: batch_design을 script 인수로 호출합니다(호출당 nodes_json | operations | script 중 정확히 하나). 이는 OpenPencil의 내부 디자인 에이전트가 사용하는 것과 동일한 프로토콜입니다. 동일한 계약을 따르세요:
디자인을 구축하는 JavaScript 프로그램을 작성합니다(산문 없음, 마크다운 펜스 없음). 프로그램은 전역 함수 I(parent, node)를 호출합니다:
const id = I(parent, { ...node... }); // 노드 삽입, 해당 id(문자열)를 반환
parent는 루트 프레임의 경우 null이고, 그렇지 않으면 이전 I(...) 호출에서 반환된 id입니다. 노드는 I(X, {...})를 호출한 경우에만 X의 자식입니다.
I(...)는 사용 가능한 유일한 함수입니다 — console이나 다른 빌더는 없습니다. console.log나 어떤 헬퍼도 호출하지 마세요. 그냥 I(...)를 호출하세요. 스크립트 모드는 삽입 전용입니다. 업데이트/이동/삭제에는 DSL 작업(접근 방식 2)을 사용하세요.
실제 JavaScript 사용 — const/let, 데이터 배열, for...of / .forEach 루프를 사용하여 데이터 배열을 반복함으로써 반복 구조(테이블 행, 탐색 항목, 카드, 목록 항목)를 생성합니다. 거의 동일한 I(...) 호출을 복사-붙여넣기하는 것보다 루프를 선호하세요.
각 노드 객체는 type("frame"/"text"/"rectangle"/"ellipse"/"path"/"icon_font")으로 시작하고 camelCase 속성(cornerRadius, fontSize, fontWeight, justifyContent, alignItems, clipContent)을 사용합니다. 레이아웃 프레임 내의 자식에는 x/y를 설정하지 마세요.
예:
const sec = I(null, {type:"frame", name:"Clients", layout:"vertical", width:"fill_container", gap:0});
const tbl = I(sec, {type:"frame", layout:"vertical", width:"fill_container"});
const rows = [{name:"Alice Chen", status:"Active"}, {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});
}
모든 행/카드/항목을 실제 값으로 생성합니다. JavaScript 프로그램만 출력하세요.
CLI/MCP 참고 사항:
- 중첩된
children배열은 여기서 안전합니다 — 엔진이 각 객체를 완벽한 한 줄 JSON으로 직렬화하므로 DSL의 단일 중첩 수준 제한이 적용되지 않습니다. 그래도 상위 바인딩이 필요할 때는 별도의I()호출을 선호하세요. - 노드 ID는 삽입 시 다시 매핑됩니다 — 호출 후에 작성된
"id"를 참조하지 마세요. 반환된 바인딩만 의미가 있으며, 이 스크립트 내에서만 유효합니다. - 제한 사항: 256KiB 소스, 4096개 삽입, 8MiB 기록된 출력, 2초 CPU, 64MiB 메모리. 문 중간에 잘린 스크립트는 최선을 다해 복구됩니다(완전한 접두사는 여전히 실행됨).
엄격한 JSON 규칙
PenNode JSON을 내보낼 때(op insert, op design, batch_design, insert_node를 통해) 엄격하게 유효한 JSON을 생성해야 합니다. 구문 분석을 깨뜨리는 일반적인 실수:
- 모든 속성에는 키와 값이 모두 있어야 합니다. 키 이름 없이
": 50또는: 50을 내보내지 마세요. 이는 잘라내기/재포맷 시 자주 발생합니다 — 다시 확인하세요. - 모든 키는 큰따옴표로 묶인 비어 있지 않은 문자열이어야 합니다.
fill은 항상 배열입니다:"fill": [{"type": "solid", "color": "#hex"}]."fill": "#hex"와 같은 약식도 작동하지만 배열 형식이 표준 형태입니다.stroke는fill배열이 있는 객체입니다:"stroke": {"thickness": 1, "fill": [{"type": "solid", "color": "#hex"}]}. 절대"stroke": {"thickness": 1, "color": "#hex"}또는"stroke": "#hex"를 사용하지 마세요(파서가 자동 변환하지만 올바른 형태가 선호됩니다).}또는]앞에 후행 쉼표 없음.- JSON 내부에 주석 없음(
//또는/* */). - 곧은 큰따옴표
"를 사용하고, 스마트/곱슬 따옴표를 사용하지 마세요. - 텍스트에는
text가 아닌content:{"type": "text", "content": "Hello"}. - 아이콘에는
iconName또는icon이 아닌iconFontName:{"type": "icon_font", "iconFontName": "lock"}. - JSON을 마무리하기 전에 정신적으로 확인하세요: 모든 키에 값이 있고, 모든 값에 키가 있으며, 모든 대괄호가 균형을 이루고 있습니다.
PenNode 스키마
공통 속성
{
"type": "frame|rectangle|text|ellipse|line|polygon|path|image|icon_font|group|ref",
"name": "표시 이름",
"role": "semantic-role",
"x": 0, "y": 0,
"rotation": 0, "opacity": 1, "visible": true
}
컨테이너 속성 (frame, rectangle, group, ellipse)
{
"width": 400, // 숫자 | "fill_container" | "fit_content"
"height": 300,
"layout": "vertical", // "none" | "vertical" | "horizontal"
"gap": 16,
"padding": [16, 24], // 숫자 | [v, h] | [top, right, bottom, left]
"justifyContent": "center", // "start" | "center" | "end" | "space_between" | "space_around"
"alignItems": "center", // "start" | "center" | "end"
"clipContent": true,
"cornerRadius": 12, // 숫자 | [tl, tr, br, bl]
"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": []
}
텍스트
{
"type": "text",
"content": "Hello", // 문자열 또는 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" }]
}
서식 있는 텍스트: "content": [{ "text": "Bold ", "fontWeight": "bold" }, { "text": "normal" }]
아이콘 — 두 가지 옵션
옵션 A: icon_font (권장 — 직접 렌더링, 후처리 불필요)
{ "type": "icon_font", "name": "Lock Icon", "iconFontName": "lock",
"width": 20, "height": 20,
"fill": [{ "type": "solid", "color": "#6B7280" }] }
필드는 iconFontName입니다(iconName이 아님, icon이 아님). 값은 소문자 케밥 케이스 Lucide 이름입니다: 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.
모든 컨텍스트에서 작동: CLI, MCP 도구 또는 직접 .op 파일 — design:refine이 필요하지 않습니다.
옵션 B: path (후처리 필요)
{ "type": "path", "name": "HeartIcon", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
PascalCase + "Icon" 접미사. 후처리 중 Lucide 세트에서 자동 해결됩니다.
경로 아이콘은 후처리가 필요합니다. 경로 노드를 삽입한 후
op design:refine --root-id <id>를 실행하거나op insert --post-process를 사용하세요. 이렇게 하지 않으면 경로 아이콘이 시각적으로 렌더링되지 않습니다. 독립 실행형 MCP 서버(ACP 에이전트에서 사용)에는 후크 구현이 등록되어 있지 않으므로 경로 아이콘이 해결되지 않습니다 — MCP 컨텍스트에서는icon_font를 선호하세요.
이미지
{ "type": "image", "src": "https://example.com/photo.jpg", "width": 400, "height": 300,
"objectFit": "crop", "cornerRadius": 12 }
AI 이미지 자리 표시자(design:refine에 의해 해결됨):
{ "type": "image", "width": 400, "height": 300,
"imagePrompt": "자연 채광이 들어오는 현대적인 사무실 공간",
"imageSearchQuery": "modern office workspace" }
이미지 조정(모두 -100 ~ 100): exposure, contrast, saturation, temperature, tint, highlights, shadows.
다각형
{ "type": "polygon", "polygonCount": 6, "width": 80, "height": 80, "cornerRadius": 4,
"fill": [{ "type": "solid", "color": "#6366F1" }] }
아이콘 폰트
{ "type": "icon_font", "iconFontName": "lucide:home", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
선
{ "type": "line", "x2": 200, "y2": 0,
"stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }] } }
채우기 유형
{ "type": "solid", "color": "#3B82F6" }
{ "type": "lin