Communitygithub.com

OpenPencil 디자인 스킬

op CLI 및 MCP 도구를 통해 OpenPencil을 사용하여 디자인하는 LLM 스킬입니다.

OpenPencil 디자인 스킬란 무엇인가요?

이 스킬은 LLM 에이전트(Claude Code, Cursor, Codex 등)가 OpenPencil 플랫폼에서 생산 품질의 벡터 디자인을 생성, 수정 및 관리할 수 있도록 설계되었습니다. `op` 커맨드라인 인터페이스와 MCP 도구(`batch_design`, `insert_node`, `design_skeleton`)를 모두 지원하여, UI 디자인을 `.op` 파일로 스크립팅하거나 실시간 캔버스와 상호작용할 수 있습니다. 에이전트는 PenNode JSON 트리를 사용하여 프레임, 텍스트, 아이콘, 이미지 등 다양한 노드 타입을 삽입하고, 배치 디자인 DSL 및 JavaScript 스크립트 모드를 통해 복잡한 구조를 효율적으로 생성할 수 있습니다. 특히 중첩된 구조나 반복적인 요소(테이블 행, 탐색 항목 등)는 JavaScript 루프를 사용하여 생성하는 스크립트 모드가 권장됩니다. 최종 디자인 검증과 아이콘 해결을 위해 `design:refine` 명령어를 실행하는 것이 중요하며, `icon_font` 타입 아이콘을 사용하면 별도의 후처리 없이 즉시 렌더링됩니다. 이 스킬은 개발자와 AI 에이전트 사용자가 코드 기반 UI 디자인 워크플로우를 자동화하고, 생산성을 극대화하는 데 핵심적인 역할을 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add ZSeven-W/openpencil-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

OpenPencil 디자인

PenNode JSON 트리를 작성하여 생산 품질의 벡터 디자인을 생성합니다. op CLI 또는 MCP 도구를 사용하여 OpenPencil 캔버스에서 노드를 생성, 읽기, 업데이트, 삭제합니다.

사용 시기

  • .op 파일에서 UI 디자인을 생성하거나 수정할 때
  • op CLI를 사용하여 디자인 작업을 스크립팅할 때
  • 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" })
작업구문작업
Iname=I(parent, { node })삽입
UU(ref, { updates })업데이트
Cname=C(source, parent, { overrides })복사
Rname=R(ref, { node })교체
MM(ref, parent, index?)이동
DD(ref)삭제
Gname=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

관련 스킬