오픈 디자인 입문: 오픈 소스 Claude Design을 올바르게 여는 방법

프로젝트 소개

Open Design은 Claude Design의 오픈 소스 대안이며, nexu-io/open-design이 개발하고 유지보수합니다.

핵심 아이디어는 아주 간단합니다: 바퀴를 다시 만들지 않는다. 여러분의 컴퓨터에 이미 설치된 코딩 에이전트(Claude Code, Codex, Cursor Agent 등 16종 CLI)가 그대로 디자인 엔진이 됩니다. 여기에 31종의 조합 가능한 디자인 스킬과 72개의 브랜드급 디자인 시스템을 함께 사용해, 로컬에서 전체 디자인 과정을 완성합니다.

주요 기능 한눈에 보기:

---

목표 독자

• 프론트엔드/풀스택 개발자: AI로 디자인 시안을 만들고 싶지만 Figma의 복잡한 조작은 배우고 싶지 않다
• 개인 개발자: 랜딩 페이지, 모바일용 프로토타입, 제품 데모를 빠르게 만들어야 한다
• 디자인 팀: 로컬 우선, 클라우드 의존이 적은 디자인 자동화 솔루션을 원한다
• AI 도구 애호가: 이미 있는 코딩 에이전트가 디자인 분야에서 갖는 잠재력을 탐구하고 싶다

---

핵심 의존 요소와 환경

Node.js ~24
pnpm 10.33.x (Corepack으로 관리)
운영체제: macOS / Windows / Linux

Open Design은 PATH에 설치된 코딩 에이전트를 자동으로 스캔합니다. 만약 어떤 CLI도 설치되어 있지 않다면, BYOK 모드 설정을 안내해 줍니다(이때 API Key가 필요합니다).

---

전체 프로젝트 구조 트리

open-design/
├── apps/
│   ├── daemon/                 # 로컬 서비스(Express + SQLite)
│   │   └── src/
│   │       ├── agents.ts       # 코딩 에이전트 탐지 및 어댑터
│   │       ├── skills.ts       # 스킬 로더
│   │       └── server.ts       # API 라우트
│   └── web/                    # Next.js 16 프론트엔드
│       └── src/
│           ├── prompts/        # 프롬프트 템플릿
│           ├── artifacts/      # 산출물 파싱
│           └── components/     # UI 컴포넌트
├── skills/                     # 31종 디자인 스킬
│   ├── web-prototype/          # 웹 프로토타입
│   ├── mobile-app/             # 모바일 앱
│   ├── dashboard/              # 대시보드
│   ├── guizang-ppt/            # 프레젠테이션
│   └── ...
├── design-systems/             # 72개 디자인 시스템
│   ├── linear-app/
│   ├── vercel/
│   ├── anthropic/
│   └── ...
├── assets/frames/              # 기기 프레임(iPhone, Pixel, iPad, MacBook)
└── .od/                        # 런타임 데이터(SQLite, 프로젝트 파일)

---

단계별 진행

1) 저장소를 클론하고 의존성 설치

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
pnpm install

corepack enable은 package.json에 고정된 pnpm 버전(10.33.x)을 자동으로 읽어 팀 환경이 동일하게 동작하도록 보장합니다.

2) 로컬 개발 서버 시작

pnpm tools-dev run web

성공적으로 시작되면 두 개의 URL이 출력됩니다:

✅ Daemon running at http://localhost:17456
✅ Web running at http://localhost:17573

브라우저에서 Web URL을 열면 바로 사용할 수 있습니다.

3) 코딩 에이전트 선택

웹 UI를 처음 열면 Open Design이 PATH에 있는 코딩 에이전트를 자동으로 감지합니다.

지원되는 16종 CLI:

화면 오른쪽 상단의 모델 선택기에는 감지된 에이전트가 표시됩니다. 어떤 CLI도 없다면, BYOK 모드를 선택하고 자신의 API Key로 OpenAI/Anthropic/Azure/Gemini 인터페이스를 통해 실행하세요.

4) 디자인 스킬 선택

진입 페이지에는 31종 스킬이 목록으로 제공되며, 상황별로 그룹화되어 있습니다:

• Design: web-prototype(기본값), mobile-app, mobile-onboarding, gamified-app, wireframe-sketch, critique, tweaks
• Marketing: saas-landing, pricing-page, blog-post, email-marketing, social-carousel, magazine-poster, motion-frames, sprite-animation
• Operation/Engineering/Product: dashboard, docs-page, pm-spec, team-okrs, meeting-notes, kanban-board, eng-runbook, finance-report, invoice, hr-onboarding
• Deck(프레젠테이션): guizang-ppt(기본값), simple-deck, replit-deck, weekly-update

필요에 따라 해당 스킬을 클릭하세요. 예를 들어 mobile-app을 선택하면 모바일용 프로토타입을 생성합니다.

5) 디자인 시스템 선택

스킬을 선택하면 디자인 시스템 패널이 표시됩니다. 기본으로 제공되는 시작 시스템은 default(Neutral Modern)와 warm-editorial(Warm Editorial) 두 가지입니다.

전체 라이브러리에는 72개의 브랜드 디자인 시스템이 포함되어 있습니다:

• AI & LLM: claude, cohere, mistral-ai, ollama, x-ai…
• 개발 도구: cursor, vercel, linear-app, supabase, posthog, sentry…
• 제품: notion, figma, airtable, intercom, raycast…
• 이커머스: shopify, airbnb, uber, nike, starbucks…
• 자동차: tesla, bmw, ferrari, lamborghini…
• 기타: apple, ibm, nvidia, spotify…

또한 자신의 DESIGN.md 파일을 업로드해 브랜드 컬러, 폰트, 간격 등 9개 차원의 디자인 규칙을 정의할 수도 있습니다.

6) 디자인 지시 보내기

입력창에 원하는 디자인 요구사항을 적어 주세요. 예를 들면:

피트니스 앱을 위한 다크 테마 모바일 온보딩 플로우를 만들어줘

폼을 채운 뒤 제출하면, 에이전트는:

1. TodoWrite 계획을 생성하고 실시간으로 스트리밍 업데이트
2. 스킬 템플릿과 디자인 시스템을 읽음
3. 5가지 차원 자가 점검(철학, 계층, 실행, 특이성, 절제)
4. <artifact> 코드를 출력
5. 샌드박스 iframe에서 미리보기 렌더링

7) 미리보기와 내보내기

디자인 시안을 렌더링한 뒤에는 다음을 할 수 있습니다:

• 실시간 편집: 오른쪽 파일 작업 영역에서 HTML/CSS를 직접 수정
• 다운로드: HTML(인라인 리소스), PDF, PPTX, ZIP 또는 Markdown으로 내보내기
• 디스크에 저장: 「Save to disk」를 클릭하면 산출물이 .od/artifacts/에 저장됨
• 대화 계속하기: 에이전트에게 “버튼을 둥근 모서리로 바꿔줘” 또는 “색감을 바꿔줘”라고 말하면, 현재 시안을 기반으로 추가 수정

그 외 자주 쓰는 명령:

# 실행 상태 확인
pnpm tools-dev status

# 로그 확인
pnpm tools-dev logs

# 모든 서비스 중지
pnpm tools-dev stop

# 재시작(포트 변경 시나리오)
pnpm tools-dev restart --daemon-port 17456 --web-port 17573

# 문제 진단
pnpm tools-dev check

---

기존 프로젝트 수정

많은 사람이 Open Design을 처음 받고 든 생각은 “결국 새 페이지를 만들어 주는 도구 아닌가?”입니다. 하지만 실제로 Open Design은 기존 프로젝트를 수정하는 용도로도 완벽하게 사용할 수 있으며, 당신의 프로젝트에 DESIGN.md가 무엇이든 필요하지 않습니다.

핵심 로직은 아주 단순합니다: 에이전트는 파일 시스템에 대한 완전한 권한을 가집니다—Read, Write, Bash, WebFetch 모두 가능. 이를 통해 코드(또는 프로젝트)를 분석하면 디자인 언어를 이해하고, 기존 스타일을 바탕으로 결과를 출력할 수 있습니다.

방향 선택기로 빠르게 시각적 기준선 만들기

디자인 규칙이 없다면 Turn 2에서 5가지 프리셋 방향이 뜨며, 각 방향은**결정적(deterministic)**인 OKLch 컬러 팔레트 + 폰트 스택을 제공합니다:

한 방향을 선택하면, 에이전트가 이 팔레트로 스킬 템플릿의 :root 변수들을 덮어씁니다. 이후 모든 컴포넌트는 이 규칙을 따르게 됩니다.

스크린샷을 업로드해 에이전트가 디자인 언어를 추출

이 방식이 실제 프로젝트에 더 잘 맞습니다. Open Design에는 브랜드 자산 추출 프로토콜이 내장되어 있습니다:

1. Locate  — 스크린샷에서 핵심 컬러 영역을 찾음
2. Download — 스크린샷을 프로젝트 디렉터리에 다운로드
3. Grep hex — hex 컬러 값을 추출
4. Codify   — brand-spec.md에 기록
5. Vocalise — 에이전트가 brand-spec.md를 기반으로 출력(기억만으로 추측하지 않음)

절차는 매우 간단합니다:

"현재 우리 앱이야. 스타일을 맞춰 줬으면 해"
# 그리고 스크린샷을 첨부하거나, 기존 페이지 URL을 붙여넣기

에이전트는 스크린샷의 주색/보조색, 폰트, 간격 특성을 분석해 brand-spec.md를 생성하고, 이후 수정은 이 규칙을 기반으로 진행됩니다.

스크린샷보다 더 정확한 ‘코드 직접 읽기’

에이전트의 기본 작업 디렉터리는 .od/projects/<id>/이지만, 이미 있는 프로젝트를 여기에 넣을 수 있습니다:

# 프로젝트를 Open Design의 작업 디렉터리에 복사
cp -r ~/my-app/.   .od/projects/<프로젝트ID>/

또는 MCP 서버를 사용해 디렉터리를 가로질러 읽게 할 수도 있습니다(다음 절 참조).

그 다음 이런 지시를 보내세요:

"./src/styles의 모든 .css 파일을 읽고 컬러 팔레트를 추출해"

"./components/의 컴포넌트 라이브러리를 읽어줘.
같은 간격과 border-radius 토큰을 사용해 새 form 컴포넌트를 만들어"

"Tailwind를 쓰는 걸 확인했어. 
기존 primary/secondary 버튼 스타일과 맞는 새 버튼 variant를 추가해줘"

에이전트는 파일을 순회하며 CSS 변수 / Tailwind 설정을 파싱하고 디자인 토큰을 추출한 뒤, 기존 코드 스타일과 일치하는 산출물을 생성합니다.

MCP 서버: 프로젝트 간 디자인 파일 읽기

파일을 복사하고 싶지 않나요? Open Design은 MCP 서버를 제공해, 여러분의 코딩 에이전트가 Open Design 프로젝트 안의 파일을 직접 읽을 수 있게 해 줍니다.

Open Design의 Settings → MCP Server 페이지에서 클라이언트별 설정 가이드를 제공합니다. 설정이 완료되면, 다른 프로젝트(예: ~/my-app)에서 실행 중인 Claude Code / Cursor 에이전트가 Open Design에서 열려 있는 프로젝트의 디자인 파일을 직접 질의할 수 있습니다.

수정 시나리오용 추천 흐름

1. Open Design을 열고, 프로젝트 스타일과 비슷한 스킬을 선택(예: web-prototype)

2. Turn 1 폼:
   - Surface: Web
   - Audience: 기존 사용자 그룹
   - Tone: 기존 제품과 동일하게

3. Turn 2 방향 선택:
   - 일관성을 유지하고 싶다면 → 기존 페이지 스크린샷을 업로드해 brand-spec.md를 추출
   - 적당한 리디자인을 허용한다면 → 방향을 하나 선택해 시각적 기준선으로 사용

4. 지시 보내기:
   "./src에 있는 기존 프로젝트에 설정 페이지를 추가하고,
    첨부된 스크린샷의 컬러 팔레트와 타이포그래피를 맞춰줘"

에이전트는:

1. 스크린샷을 읽고 brand-spec.md를 추출(또는 코드의 CSS 변수를 읽음)
2. 프로젝트의 기존 파일을 읽음
3. 새 페이지에서 주색/보조색/폰트를 재사용
4. 실행 가능한 HTML을 출력하되, 기존 프로젝트와 같은 스타일로 유지

---

자주 묻는 문제 해결

Q1: Node 버전이 틀려서 오류 Requested version v24.x.x is not currently installed가 발생

Open Design은 Node 24를 요구합니다. nvm 또는 fnm으로 설치하세요:

nvm install 24 && nvm use 24
# 또는
fnm install 24 && fnm use 24

fnm을 사용하는 경우, 쉘 설정 파일이 fnm env를 로드하도록 되어 있는지 확인하세요(참조: fnm 공식 문서 ).

Q2: 코딩 에이전트가 감지되지 않음

Open Design은 첫 실행 시 PATH를 스캔합니다. CLI가 설치되어 있고 전역에서 사용할 수 있는지 확인하세요:

# 특정 에이전트 검증
which claude     # macOS/Linux
where claude     # Windows

# 설치했는데도 감지되지 않으면 서비스 재시작 시도
pnpm tools-dev stop && pnpm tools-dev start web

Q3: 포트가 점유됨

기본 포트 17456(daemon)과 17573(web)이 이미 사용 중일 수 있습니다:

# 다른 포트로 변경
pnpm tools-dev run web --daemon-port 17457 --web-port 17574

Q4: 디자인 시스템을 전환해도 스타일이 바뀌지 않음

Open Design의 디자인 시스템은 DESIGN.md의 CSS 변수를 읽어서 주입합니다. 매번 시스템을 전환한 뒤, 에이전트는 새 대화에서 새 변수를 사용합니다. 이미 생성된 기존 대화는 자동으로 새로고침되지 않습니다. 새 대화를 열면 새 시스템이 적용됩니다.

Q5: 미리보기 iframe이 빈 화면으로 로드됨

샌드박스 iframe은 srcdoc로 렌더링합니다. 내용이 보이지 않으면:

1. 브라우저 콘솔에 CSP 오류가 있는지 확인
2. 광고 차단 플러그인이 iframe 로딩을 차단하지 않는지 확인
3. 「Download HTML」을 눌러 다운로드한 뒤 로컬에서 직접 열어 확인

Q6: BYOK 모드에서 API Key 오류

BYOK 에이전트는 /api/proxy/{anthropic,openai,azure,google}/stream에 있습니다. 확인 사항:

1. Settings 페이지의 baseUrl이 올바른지( OpenAI 호환 형식 )
2. API Key가 유효하고 해당 모델 권한이 있는지
3. apiKey 필드를 입력하지 않으면 서버가 요청을 거절함(SSRF 방어)

---

확장 읽기 / 고급 방향

커스텀 디자인 스킬 추가

스킬은 SKILL.md + assets/ + references/ 폴더 형태로 존재하며, Claude Code의 SKILL.md 규칙을 따릅니다.

skills/ 아래에 새 폴더를 만들고 SKILL.md를 추가한 다음 od: frontmatter(mode, scenario, design_system.requires 등)를 정의합니다. 서비스를 재시작하면 스킬 선택기에서 자동으로 나타납니다.

Claude Design 내보내기 패키지 가져오기

Anthropic의 Claude Design은 ZIP 내보내기를 지원합니다. ZIP을 Open Design의 환영 대화상자에 드래그하면, POST /api/import/claude-design이 프로젝트를 파싱하고 재구성합니다. 에이전트는 중단 없이 이어서 편집할 수 있습니다.

MCP 서버 통합

Open Design은 stdio MCP 서버를 제공합니다. Claude Code/Cursor/VS Code 같은 MCP 클라이언트에서 설정하면, 에이전트가 Open Design 프로젝트의 디자인 파일과 소스를 직접 읽을 수 있어 ZIP을 수동으로 내보낼 필요가 없습니다.

데스크톱 앱 빌드

Electron 데스크톱 버전은 macOS(Apple Silicon)와 Windows(x64)를 지원합니다:

# macOS
pnpm tools-pack mac build --to all
pnpm tools-pack mac install

# Windows
pnpm tools-pack win build --to nsis
pnpm tools-pack win install

패키징된 App은 독립적으로 실행 가능하며, 데이터는 시스템 AppData 디렉터리에 저장됩니다.

확장 미디어 생성 기능

코드 산출물뿐 아니라 Open Design은 이미지(gpt-image-2), 비디오(Seedance 2.0, HyperFrames), 오디오(Suno, Udio) 생성 모델도 통합합니다. API Key를 설정하면 디자인 프로세스에서 바로 .mp4, .png 같은 미디어 파일을 출력할 수 있습니다.

---

프로젝트 주소: nexu-io/open-design