zenit UI dev Skill
Claude Code 등 AI Agent를 위한 개발 매뉴얼입니다. 설치하면 Agent가 zenit UI를 작성할 때 기존 컴포넌트를 먼저 고르고, token과 recipe로 스타일을 지정하며, zenit의 생명주기에 맞춰 상태를 관리하고, 넘기기 전에 직접 빌드하고 스크린샷으로 확인합니다.
다운로드
압축 파일은 표준 Agent Skill 폴더입니다. 진입점인 SKILL.md는 짧게 규칙과 결정 표만 담고, 세부 내용은 references/에 나뉘어 있어 Agent가 필요할 때만 읽으므로 컨텍스트를 차지하지 않습니다.
설치
- 1Skill 폴더에 넣기
개인용이면
~/.claude/skills/에 두면 모든 프로젝트에 적용됩니다. 팀 공유라면 저장소의.claude/skills/에 커밋하면 클론하는 모두가 받게 됩니다. - 2Agent 세션 재시작
Claude Code는 세션 시작 시 Skill을 스캔합니다. 새 세션을 열고
/skills에zenit-ui-dev가 보이면 설치된 것입니다. - 3평소처럼 요청하기
zenit UI 관련 작업이면 자동으로 로드됩니다. “zenit-ui-dev skill을 사용해”라고 명시해도 됩니다.
다운로드한 뒤 사용자 폴더에 압축을 풉니다 (모든 프로젝트에 적용):
~/.claude/skills/
└── zenit-ui-dev/
├── SKILL.md
├── references/
└── tools/또는 프로젝트에 압축을 풀고 커밋합니다 (팀과 공유):
.claude/skills/
└── zenit-ui-dev/
├── SKILL.md
├── references/
└── tools/# Codex and other agents that read AGENTS.md: unpack into the repo and reference it
unzip -oq zenit-ui-dev.zip -d .agents/skills
echo '- zenit UI: read .agents/skills/zenit-ui-dev/SKILL.md before writing UI code' >> AGENTS.md구성 내용
SKILL.md진입점: 트리거 조건, 워크플로, 필수 규칙, 결정 표, 그리고 언제 어떤 reference를 읽을지references/app-architecture.md프로덕션 에디터를 예로 든 대규모 앱 계층: 상태, 뷰, 명령, 서비스references/components.mdui.widgets 카탈로그, 두 가지 mount 형태, “디자인 요소 → 컴포넌트” 선택 표references/macos-native.md메뉴, 단축키, 파일 대화상자, 클립보드, 드래그 앤 드롭, 멀티 창, IMEreferences/pencil-design.mdPencil (pen.dev) 디자인 재현: MCP로 수치 읽기, 필드 매핑, 스크린샷 수치 비교references/performance.md가상 리스트, dirty 레벨, 대용량 텍스트, 백그라운드 스레드와 메인 스레드 통신references/pitfalls.mdzenit과 프로덕션 앱 수정 기록에서 모은 “증상 → 원인 → 올바른 해결”references/project-setup.md새 프로젝트, build.zig / build.zig.zon, .app 패키징, 빌드 옵션 전달references/state-reactivity.mdbindState / cx.on, Signal / Memo / Effect, Scope 생명주기와 정리references/styling.mdToken → styles.zig → recipe 3계층, 테마, ui.arb 탈출구references/ui-tree-layout.md노드, Flex 레이아웃, 크기, 노드 업데이트, 표시 여부, 좌표references/verification.mdAgent 자체 검증 루프: 빌드, 스크린샷, E2E harness, DevTools, 로그tools/design_diff.ts디자인 PNG와 앱 스크린샷의 수치 비교, 실행 가능한 수정 힌트 출력tools/png.tsdesign_diff가 사용하는 무의존성 PNG 디코더tools/shot.ts파일 RPC로 모든 zenit 앱 스크린샷 (Retina)디자인의 각 요소를 ui.widgets의 기존 컴포넌트에 매핑해, Agent가 box로 Button을 다시 조립하지 않게 합니다.
bindState, pub deinit, Scope 정리, 페이지 전환 규칙으로 가장 흔한 누수, 이중 해제, 댕글링 포인터를 바로 해결합니다.
Agent가 빌드, 실행, 스크린샷 후 요청 사항과 대조하게 하며, “컴파일된다”에서 멈추지 않게 합니다.
실제 프로덕션 앱의 수정 기록에서 정리한 문제 목록으로, 각 항목에 원인과 올바른 해결 방법이 있습니다.
추천: Pencil로 디자인
Pencilpen.devPencil로 화면을 그리고, 이 Skill로 에이전트가 구현하게 하는 방식을 추천합니다. .pen 파일의 Flex 레이아웃, 간격, 모서리 반경, 글자 크기, lucide 아이콘은 zenit의 모델과 매우 가깝습니다. Skill에는 필드 매핑표와 design_diff 비교 도구가 들어 있어 에이전트가 감이 아닌 수치로 옮깁니다.
- 01.penPencil 디자인
- 02MCP에이전트가 정확한 수치를 읽음
- 03zigwidgets + token으로 zenit 코드
- 04diff디자인과 수치 비교
- 1Pencil MCP 연결
Agent에서 Pencil의 MCP server를 활성화하고 .pen 파일을 엽니다. Skill은 .pen을 MCP로만 읽습니다. MCP는 디자인 변수를 풀고 계산된 실제 크기를 제공하는데, 이 두 가지가 충실한 재현에 가장 필요합니다.
- 2픽셀이 아니라 수치 읽기
Agent는 먼저
Get(nodeId, { resolveVariables: true })로 gap, padding, 모서리 반경, 글자 크기, 색상을 가져온 뒤 매핑 표에 따라 zenit으로 옮깁니다:fill_container → .fill(),chevron-down → ui.icons.chevron_down. - 3일치할 때까지 수치 비교
디자인을 scale 2로 내보내고
tools/shot.ts로 실제 창을 캡처하면,tools/design_diff.ts가 위치 차이, 크기 차이, 히트맵, 색상 편차를 보고하고 Agent가 힌트대로 수정합니다. 한 라운드에 약 5초입니다.
SKILL=~/.claude/skills/zenit-ui-dev
bun $SKILL/tools/design_diff.ts --self-test
ZENIT_E2E_FILE_RPC_DIR=$RPCDIR bun $SKILL/tools/shot.ts /tmp/actual.png
bun $SKILL/tools/design_diff.ts /tmp/design/<nodeId>.png /tmp/actual.png사용법
특별한 문법은 필요 없습니다. 원하는 UI나 문제를 설명하면 됩니다. 효과가 좋은 프롬프트 몇 가지를 소개합니다:
Pencil MCP로 열려 있는 .pen의 "Settings" 프레임을 읽어 zenit으로 설정 창을 재현하고, design_diff 점수가 90을 넘으면 넘겨 주세요.
zenit으로 이 앱에 설정 창을 추가해 주세요. 왼쪽은 카테고리 목록, 오른쪽은 폼이고 변경 사항은 즉시 반영됩니다.
src/views/sidebar.zig에 직접 작성된 스타일을 styles.zig + recipe로 옮겨 주세요.
파일 트리가 5만 노드일 때 스크롤이 끊깁니다. 원인을 찾아 고치고, 수정 후 스크린샷을 보여 주세요.내용 출처
Skill의 규칙은 두 프로젝트에서 나왔습니다. zenit 프레임워크 자체(공개 API, 예제, 컴포넌트 카탈로그, 테스트 도구)와 zenit으로 만든 프로덕션 macOS 에디터(대규모 앱 계층화, 네이티브 통합, 수정 기록)입니다. 예제 코드는 가능한 한 두 저장소에서 컴파일되는 코드에서 가져왔으며 이 매뉴얼과 일치합니다.
소스는 사이트 저장소의 skill/zenit-ui-dev/에 있으며, 빌드 시 scripts/pack-skill.mjs로 패키징됩니다. SKILL.md를 직접 읽을 수도 있습니다.