Pencil.dev — IDE 안에서 디자인하고, 코드로 착지하는 시대

디자인과 개발의 경계가 무너지고 있음. Figma에서 디자인하고, 개발자에게 넘기고, 스펙 문서 만들고, 다시 수정하고… 이 지루한 핸드오프 루프를 끊어버리는 도구가 등장함. 바로 Pencil.dev.

Pencil.dev가 뭔가

Pencil은 VS Code, Cursor 같은 IDE 안에 직접 들어가는 벡터 디자인 캔버스임. Figma처럼 무한 캔버스에서 UI를 그릴 수 있는데, 핵심 차이는 이게 코드 에디터 안에서 동작한다는 점.

디자인 파일 포맷은 .pen이라는 JSON 기반 파일. 이 파일이 프로젝트 소스코드와 나란히 존재하면서, AI 에이전트(Claude Code 등)가 MCP(Model Context Protocol)를 통해 디자인을 읽고 프로덕션 코드를 바로 생성함.

현재 얼리 액세스 기간으로 무료. 다만 AI 기능을 쓰려면 Claude Code 구독(월 $20~)이 필요함.

참고: 오픈소스 프로토타이핑 도구인 "Pencil Project"와는 완전히 다른 제품임.

---

설치 및 초기 설정

1단계: 확장 프로그램 설치

# VS Code / Cursor에서
Extensions (Cmd/Ctrl + Shift + X) → "Pencil" 검색 → Install

2단계: Claude Code 설치 및 인증

# Claude Code CLI 설치
npm install -g @anthropic-ai/claude-code-cli

# 또는 공식 설치 스크립트
curl https://claude.ai/cli/install.sh | sh

# 인증
claude
# 브라우저 인증 플로우 진행

3단계: 활성화

pencil.dev에서 가입 후 활성화 토큰을 받음. 이후 프로젝트에서 .pen 파일을 생성하면 Pencil 에디터가 자동으로 열림.

4단계: 첫 디자인 파일 생성

# 프로젝트 디렉토리에서
touch design.pen
code .  # IDE에서 열기

.pen 파일을 열면 무한 캔버스가 나타남. MCP 서버는 Pencil이 실행되면 자동으로 로컬에서 돌아감(클라우드 의존 없음).

---

지원하는 AI 어시스턴트

Claude Code만 되는 게 아님. MCP를 통해 다양한 도구와 연결 가능.

• Claude Code (CLI 및 IDE)
• Claude Desktop
• Cursor (AI IDE)
• Windsurf IDE (Codeium)
• Codex CLI (OpenAI)
• Antigravity IDE
• OpenCode CLI

---

VSCode 확장으로 쓸 때의 장점

Git 버전관리가 그대로 적용됨

Pencil의 가장 큰 강점. .pen 파일이 JSON 기반이라 Git으로 완벽하게 추적 가능함.

git add design.pen src/pages/landing.tsx
git commit -m "랜딩페이지 디자인 및 컴포넌트 추가"

브랜치 따서 디자인 실험하고, 머지하고, 롤백하는 게 전부 가능함. Figma에서 "v2_최종_진짜최종.fig" 같은 파일명 지옥을 경험해봤다면 이게 얼마나 혁명적인지 알 수 있음. 커밋을 롤백하면 디자인도 함께 롤백됨. 디자인과 코드 사이의 드리프트가 원천적으로 차단되는 구조.

개발 코드와의 통합 관리

프로젝트 구조를 보면 디자인 파일이 소스코드와 같은 레벨에 존재함.

my-project/
├── src/
│   ├── components/
│   └── styles/
├── design.pen    ← 디자인 파일
└── package.json

디자인이 별도 툴에 격리되지 않고 코드베이스의 일부가 됨. AI 에이전트가 .pen 파일과 소스코드를 동시에 볼 수 있어서, "이 디자인에 맞는 React 컴포넌트를 생성해줘"라고 하면 실제 프로젝트 컨텍스트를 반영한 코드가 나옴.

쉬운 코드 변환

MCP를 통한 양방향 워크플로우가 핵심.

• 디자인 → 코드: 캔버스에서 그린 UI를 React, HTML/CSS 컴포넌트로 즉시 변환
• 코드 → 디자인: 기존 코드베이스의 컴포넌트를 Pencil에서 시각적으로 재현

일반적인 이미지-투-코드 도구가 스크린샷을 보고 "대충 20px 패딩인 것 같은데…"하고 추측하는 반면, Pencil은 벡터 노드의 정확한 JSON 데이터를 AI에게 직접 전달함. padding-left: 1rem → p-4(Tailwind) 같은 정밀한 변환이 가능한 이유.

컨텍스트 스위칭 제로

IDE 탭 하나로 디자인과 코드를 오감. Figma 열고, 브라우저 왔다 갔다 하고, 에셋 익스포트하고… 이런 과정이 전부 사라짐. Cmd+K 눌러서 "히어로 섹션 만들어줘" 하면 캔버스에 바로 그려지고, 이걸 즉시 코드로 변환 가능.

Figma 자산 재활용

Figma에서 프레임을 복사(Cmd+C)해서 Pencil에 바로 붙여넣기 가능. 레이어, 오토 레이아웃, 스타일이 그대로 유지됨. 기존 Figma 워크플로우를 완전히 버릴 필요 없이, 탐색은 Figma에서 하고 코드 착지는 Pencil에서 하는 전략이 가능.

내장 UI 킷 지원

Shadcn, Lunarus 같은 프리빌트 디자인 킷을 에셋 패널에서 바로 드래그해서 사용할 수 있음. 버튼, 카드, 모달 같은 공통 UI 패턴을 처음부터 그릴 필요 없음.

---

실전 사용법: 단계별 워크플로우

기본 플로우

# 1. .pen 파일 생성 후 IDE에서 열기
# 2. Cmd+K 눌러서 AI 프롬프트 패널 열기
# 3. 디자인 요청

User: "모던한 랜딩 페이지 히어로 섹션 만들어줘"
AI: [헤딩, 서브헤딩, CTA 버튼으로 히어로 생성]

User: "3컬럼 피처 섹션 추가해줘"
AI: [히어로 아래에 피처 섹션 추가]

User: "CTA 버튼에 primary color 변수 적용해줘"
AI: [버튼에 컬러 변수 적용]

User: "이 전체 페이지를 React 코드로 생성해줘"
AI: [Tailwind CSS 기반 React 컴포넌트로 내보내기]

# 4. 리뷰 및 수정
# 5. Git 커밋
git add design.pen src/pages/landing.tsx
git commit -m "랜딩 페이지 디자인 및 구현"

반복 수정 플로우

패딩이 맞지 않거나 색상을 바꾸고 싶을 때, 코드를 직접 수정하지 말 것. 이게 중요함.

1. Pencil 캔버스에서 시각적으로 간격/색상 조정
2. AI에게 "디자인 파일에서 버튼 간격을 수정했어. 코드를 디자인에 맞게 업데이트해줘" 요청
3. 코드가 새 디자인 값으로 재생성됨

디자인이 진실의 원천(Source of Truth)이고, 코드는 그걸 따라가는 구조. 이 흐름을 지켜야 일관성이 유지됨.

---

프로 팁: 픽셀 퍼펙트를 위한 디자인 규칙

레이어 이름은 시맨틱하게

Frame 42 같은 기본 이름을 쓰면 AI가 .frame-42라는 무의미한 클래스명을 생성함. pricing-card-container처럼 의미 있는 이름을 붙여야 시맨틱한 코드가 나옴.

관련 요소는 반드시 그룹핑

아이콘과 텍스트가 나란히 있으면 Cmd+G로 그룹핑해야 함. 이게 AI에게 "이건 flex-row야"라는 신호를 줌. 그룹핑 안 하면 AI가 관계를 파악하지 못해서 레이아웃이 깨짐.

Auto Layout 활용

버튼을 박스 한가운데 떠있게 놓지 말고, 컨테이너에 Auto Layout(정렬 제약조건)을 적용해야 함. 그래야 AI가 절대 위치(position: absolute) 대신 안정적인 컨테이너 기반 코드를 생성함.

그리드 스냅 필수

"Snap to Grid"를 항상 활성화하고, 간격 값은 4 또는 8의 배수로 맞출 것. 10.43px 같은 소수점 값이 들어가면 브라우저에서 흐릿하게 렌더링됨.

아이콘은 SVG로

PNG로 가져온 아이콘은 코드 변환 시 흐릿해짐. 반드시 SVG를 사용하거나, AI에게 lucide-react이나 Heroicons 같은 아이콘 라이브러리로 대체하도록 지시할 것.

---

효과적인 AI 프롬프팅 가이드

나쁜 프롬프트 vs 좋은 프롬프트

❌ "이거 좀 만들어줘"
✅ "dashboard.pen에서 선택된 프레임을 확인하고, 
   Tailwind CSS를 사용한 React 컴포넌트로 생성해줘.
   - 벡터 노드에서 정확한 패딩/마진 값을 읽어서 적용
   - 타이포그래피: 디자인에 정의된 font-weight와 line-height를 정확히 매칭
   - 반응형: Hero Container는 모바일에서 flex-col, 데스크톱에서 flex-row
   - 아이콘: 벡터 아이콘을 lucide-react 컴포넌트로 교체"

디자인 토큰 강제하기

세션 시작 시 AI에게 이렇게 선언하면 일관성이 유지됨:

"나는 Pencil MCP를 사용 중임. 
생성되는 모든 코드는 tokens.md에 정의된 디자인 토큰을 엄격히 따라야 함. 
임의의 px 값(예: 13px)은 사용하지 말고, 
가장 가까운 Tailwind 클래스로 스냅할 것."

단계별 접근이 핵심

1. 넓게 시작: "대시보드 레이아웃 만들어줘"
2. 구체화: "사이드바에 네비게이션 아이템 추가해줘"
3. 디테일: "네비 아이템에 hover 스타일 적용해줘"
4. 마무리: "전체 간격을 8px 그리드에 맞춰줘"

유용한 프롬프트 모음

디자인 생성:

• "사이드바와 메인 콘텐츠 영역이 있는 대시보드 디자인해줘"
• "3단 프라이싱 테이블 만들어줘"
• "헤딩과 CTA 버튼이 있는 히어로 섹션 추가해줘"

디자인 수정:

• "모든 primary 버튼을 파란색으로 변경해줘"
• "사이드바를 더 좁게 만들어줘"
• "이 요소들 사이에 간격을 추가해줘"

디자인 시스템:

• "variant가 있는 버튼 컴포넌트 만들어줘"
• "#3b82f6 기반으로 컬러 팔레트 생성해줘"
• "타이포그래피 스케일 구축해줘"

코드 연동:

• "이 컴포넌트의 React 코드 생성해줘"
• "코드베이스의 Header 컴포넌트를 임포트해줘"
• "이 변수들로 Tailwind config 만들어줘"

배치 작업:

• "이 버튼 컴포넌트의 변형 5개 만들어줘"
• "모든 input 타입이 포함된 폼 생성해줘"
• "히어로, 피처, 프라이싱, 푸터가 있는 전체 랜딩 페이지 디자인해줘"

기존 코드베이스 임포트:

• "src/components의 모든 컴포넌트를 Pencil에서 재현해줘"
• "Tailwind config에서 디자인 시스템을 임포트해줘"
• "코드베이스를 분석하고 매칭되는 디자인을 만들어줘"

---

디자인 토큰 관리

Pencil에서 디자인 토큰은 Variables라는 개념으로 관리됨. CSS 커스텀 프로퍼티와 동일한 구조.

변수 생성 방법 3가지

방법 1: CSS 파일에서 자동 생성

AI에게: "globals.css에서 Pencil 변수를 만들어줘"
→ 색상, 간격, 폰트가 자동 추출되어 변수화됨

방법 2: Figma에서 가져오기

Figma의 토큰 테이블을 복사/붙여넣기하거나, 스크린샷을 캔버스에 붙이고 AI에게 변수 생성을 요청.

방법 3: 수동 정의

Pencil에서 직접 변수를 정의하고, 테마별(라이트/다크) 다른 값을 설정.

CSS 변수와의 양방향 동기화

이게 킬러 기능임. 기존 CSS 변수 파일과 양방향 동기화가 가능함.

CSS → Pencil 방향:

/* globals.css */
:root {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --spacing-base: 1rem;
}

AI에게 "globals.css에서 Pencil 변수를 만들어줘"라고 지시하면 디자인 캔버스에 토큰이 자동 생성됨.

Pencil → CSS 방향:

디자인에서 색상을 #2563eb로 변경한 후 "이 변수를 globals.css에 반영해줘"라고 하면:

/* globals.css - 업데이트됨 */
:root {
  --color-primary: #2563eb;  /* 변경 반영! */
  --color-secondary: #64748b;
  --spacing-base: 1rem;
}

tokens.md 파일 활용 팁

프로젝트 루트에 tokens.md 파일을 만들어 핵심 토큰을 문서화해두면 AI가 이걸 참조해서 일관된 코드를 생성함.

## Colors
- Primary: #3b82f6
- Secondary: #64748b
- Destructive: #ef4444
- Muted: #f1f5f9

## Spacing
- 1rem = 16px, 0.5rem = 8px

## Border Radius
- sm: 4px, md: 8px, lg: 12px

디자인 시스템 일관성 강제

AI 프롬프트를 통해 시스템 전체의 일관성을 강제할 수 있음.

• "모든 버튼에 primary color 변수를 적용해줘"
• "모든 제목에 타이포그래피 스케일을 적용해줘"
• "8px 간격 그리드를 전체 요소에 적용해줘"

하드코딩된 hex 값이나 임의의 px 값 대신, 항상 정의된 변수를 참조하도록 강제하는 워크플로우. Tailwind v4의 시맨틱 유틸리티 클래스(bg-primary, text-foreground 등)로의 매핑도 자연스러움.

테마 지원

라이트/다크 모드 같은 테마를 변수별로 다른 값을 설정해서 관리 가능. 테마를 전환하면 디자인이 자동으로 적응하는 걸 확인할 수 있음.

---

반응형 디자인 처리법

픽셀 퍼펙트한 데스크톱 레이아웃이 모바일에서 깨지는 건 흔한 문제. Pencil에서는 멀티 프레임 전략으로 해결함.

듀얼 프레임 접근법

.pen 파일 안에 두 개의 프레임을 그림:

• 모바일 프레임: 390px 너비
• 데스크톱 프레임: 1440px 너비

동일한 컴포넌트를 각 화면 크기에 맞게 디자인한 후, AI에게 이렇게 요청:

"모바일 프레임은 기본(mobile-first) 상태로, 
데스크톱 프레임은 md 브레이크포인트 상태로 간주해서 
두 디자인을 하나의 반응형 Tailwind 컴포넌트로 합쳐줘."

이렇게 하면 AI가 데스크톱 내비바가 모바일에서 어떻게 축소되어야 하는지 추측할 필요가 없음. 양쪽 상태를 명시적으로 보여줬기 때문.

---

시각적 검증 방법

AI가 생성한 코드가 디자인과 정확히 일치하는지 확인하는 과정이 필수.

오버레이 트릭

프로 유저들이 쓰는 방법: 렌더링된 코드의 스크린샷을 찍어서 Pencil 캔버스에 다시 붙여넣고, 원본 디자인 위에 50% 투명도로 겹쳐보는 것. 미세한 차이를 한눈에 발견할 수 있음.

AI 스크린샷 검증

AI에게 직접 스크린샷을 요청해서 복잡한 레이아웃을 검증할 수도 있음. Pencil MCP에는 get_screenshot과 snapshot_layout 같은 분석 도구가 내장되어 있음.

수정 시 주의사항

차이를 발견했으면 코드를 직접 고치지 말고, Pencil 캔버스에서 디자인을 수정한 후 AI에게 코드 업데이트를 요청할 것. 이 원칙을 지켜야 디자인-코드 동기화가 깨지지 않음.

---

자주 발생하는 문제와 해결법

문제	원인	해결
폰트 크기가 미세하게 다름	브라우저와 캔버스의 렌더링 엔진 차이	Tailwind 표준 클래스(text-sm, text-lg)로 매핑하도록 프롬프트에 명시
리사이즈하면 레이아웃 깨짐	디자인에서 고정 위치를 사용함	Auto Layout(스택)을 사용하고 절대 위치 지양
색상이 안 맞음	RGB/HSL 변환 불일치	AI가 hex 추측하지 않도록 CSS 변수(bg-primary) 사용 강제
아이콘이 흐릿함	PNG로 임포트됨	SVG로 전환하거나 아이콘 라이브러리(Lucide, Heroicons) 사용 지시
MCP 서버 연결 안 됨	Pencil이 실행되지 않았거나 인증 문제	Pencil 실행 확인 → claude 명령으로 재인증 → IDE 재시작
Cursor에서 프롬프트 패널 안 보임	활성화/로그인 상태 문제	Settings → Tools & MCP에서 연결 확인 → Cursor 재시작

---

알아두면 좋은 주요 단축키

단축키	기능
Cmd/Ctrl + K	AI 프롬프트 패널 열기
Cmd/Ctrl + Click	가장 깊은 요소 직접 선택
Shift + Enter	부모 요소 선택
Cmd/Ctrl + G	요소 그룹핑
Cmd/Ctrl + Option/Alt + K	재사용 가능한 컴포넌트로 변환
F	프레임 도구

컴포넌트로 변환 후 보라색/마젠타 하이라이트가 나타나야 정상. 안 보이면 선택 해제 후 다시 선택.

---

Pencil MCP가 제공하는 주요 도구들

AI가 Pencil에 연결되면 다음 도구들을 사용할 수 있음:

• batch_design: 디자인 요소 생성, 수정, 삭제, 이동, 이미지 배치
• batch_get: 디자인 컴포넌트 구조 읽기, 패턴 검색
• get_screenshot: 디자인 프리뷰 렌더링, 전후 비교 검증
• snapshot_layout: 레이아웃 구조 분석, 위치 문제 감지, 겹침 요소 탐지
• get_editor_state: 현재 에디터 컨텍스트, 선택 정보, 활성 파일
• get_variables / set_variables: 디자인 토큰 읽기/쓰기, CSS 동기화

사용 가능한 전체 도구 목록은 Cursor의 경우 Settings → Tools & MCP, Codex CLI의 경우 /mcp 명령으로 확인 가능.

---

현재 한계와 주의점

아직 얼리 액세스 제품이라 몇 가지 제약이 존재함.

• Claude Code 의존성: AI 기능이 Claude Code에 강하게 최적화되어 있음. 다른 LLM을 쓰는 팀은 기능 제한이 있을 수 있음
• 브라우저 버전 없음: 로컬에 CLI를 설치해야 하므로 순수 디자이너에게는 진입장벽이 있음
• Windows 안정성: macOS/Linux 대비 Windows에서 간헐적 버그가 보고됨
• 복잡한 레이아웃의 정밀도: 3컬럼 반응형 같은 복잡한 레이아웃에서 4~8px 정도의 정렬 오차가 발생할 수 있음
• Auto Layout 변환: 복잡한 Auto Layout 구조를 변환할 때 가끔 버그가 있음
• 문서/튜토리얼 부족: 성숙한 도구 대비 학습 자료가 아직 적음
• 무료 가격 정책의 지속 가능성: 현재 무료지만 유료 전환은 시간문제
• Codex CLI 주의: Pencil이 config.toml을 수정하거나 중복시키는 이슈가 보고됨. 첫 사용 전 config 백업 권장

---

시작 전 체크리스트

• 레이어에 시맨틱한 이름을 붙였는가?
• AI에게 hex 코드 대신 CSS 변수를 우선 사용하도록 지시했는가?
• 모든 간격 값이 4 또는 8의 배수인가?
• Auto Layout을 사용해서 flex 관계를 명시했는가?
• 아이콘이 SVG인가?
• tokens.md 또는 globals.css에 디자인 토큰을 정의했는가?

---

정리

Pencil.dev는 "디자인 파일도 코드처럼 다루자"는 철학을 실현한 도구. Git 버전관리, 코드베이스 통합, 디자인 토큰 동기화, AI 기반 코드 변환까지 — 디자인과 개발의 핸드오프를 근본적으로 없애는 방향으로 움직이고 있음.

특히 풀스택 개발자나 1인 개발팀, 바이브 코딩 워크플로우를 적극 활용하는 팀에게 강력 추천. 얼리 액세스 중이니 무료일 때 경험해보는 게 이득.

시작하기:

• 다운로드 → pencil.dev
• 공식 문서 → docs.pencil.dev
• 기존 프로젝트의 작은 컴포넌트 하나를 .pen 파일로 변환해보는 것부터 시작 추천