SoDam-Design-Kit
Health Uyari
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 6 GitHub stars
Code Uyari
- network request — Outbound network request in scripts/dashboard-server.mjs
- network request — Outbound network request in scripts/dashboard-web/dashboard.js
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Figma 디자인을 shadcn/ui 코드로 변환하고 실제 브라우저 검증(Playwright+axe-core)을 통과해야 완료로 인정하는 Claude Code 디자인 자동화 플러그인 (Phase 1~3 완료, Claude Desktop MCP 확장 지원)
SoDam-Design-Kit
Figma 디자인을 shadcn/ui 코드로 만들고, 실제 브라우저 검증(Playwright + axe-core + 3개 화면 크기)을 통과해야만 "완료"로 인정되는 Claude Code 디자인 자동화 킷입니다.
✅ 현재 상태 (2026-08-21 기준, 실측 확인): **Phase 1(MVP)**과 **Phase 2(대시보드 · 화면 변경 자동 감지 · 한글 폰트 자동화)**가 공식 완료되었고, Phase 3(고도화)도 상세페이지 · AI 생성 이력 기록 · 마케팅 이미지 생성(OG·포스터·배너·명함) · 라이선스 게이트 확장 · Claude Desktop용 MCP 확장(검증 이력 열람)까지 완료되었습니다(남은 항목은 베타 공개 여부뿐, 사용자 결정 사항). 자동 테스트 330개 전부 통과, 알려진 보안 취약점 0건(
npm audit기준), 간접 의존성까지 포함한 126개 패키지 라이선스 전수 감사 완료(카피레프트 0건). 사용 가능한 명령은 총 5개(setup·pipeline·open·detail-page·marketing-asset)이며, 전부 실제 프로젝트를 대상으로 왕복 검증(PASS 확인)까지 마쳤습니다. 자세한 이력은 7장을 참고하세요.⚠️ 이 킷은 아직 **버전 0.3.0(정식 출시 전, 개발 진행 중)**입니다. 명령어 이름·동작 방식·파일 구조가 앞으로 바뀔 수 있습니다 — 바뀔 때마다 이 문서도 함께 갱신됩니다.
목차
- 이 문서를 시작하기 전에 (용어 5분 정리)
- 이 도구는 무엇인가
- 사전 준비물 · 필요 프로그램 (다운로드 방법 포함)
- 다운로드 및 설치 방법
- 빠른 시작 (5분 안에 첫 성공 보기)
- 실행 · 사용 · 작동 방법
- 명령어 표
- 업데이트 내용 요약
- 워크플로우
- 아키텍처 · 파일/문서 위치
- 보안 · 데이터 흐름
- 문제/오류 대처 (트러블슈팅)
- FAQ (자주 묻는 질문)
- 법률 · 저작권 · 라이선스 · 상업적 용도
0. 이 문서를 시작하기 전에 (용어 5분 정리)
이 문서는 컴퓨터 · AI · 메신저 앱을 거의 처음 써보는 분도 따라 할 수 있도록 썼습니다. 다만 아래 단어들이 문서 전체에서 계속 나오므로, 먼저 한 번 훑어보고 시작하면 훨씬 편합니다. 이미 익숙한 분은 건너뛰고 1장부터 읽어도 됩니다.
| 용어 | 쉬운 설명 |
|---|---|
| AI (인공지능) | 사람의 말(자연어)을 이해하고 대신 작업해주는 프로그램. 이 문서에서 "AI"는 곧 "Claude Code"를 가리킵니다. |
| Claude Code | Anthropic이 만든, 채팅으로 대화하면서 컴퓨터 작업(코드 작성 등)을 대신 시키는 프로그램. 메신저처럼 "채팅창"이 있고, 거기에 원하는 것을 문장으로 입력하면 됩니다. |
| 터미널 | 글자로 명령을 입력해 컴퓨터에게 시키는 화면. Claude Code를 설치하면 그 채팅창 자체가 터미널 역할도 겸합니다 — 따로 배우거나 설치할 필요가 없습니다. |
| 명령 / 슬래시 명령 | /(슬래시)로 시작하는, 미리 정해진 지시어. 오픈채팅방이나 디스코드에서 /공지처럼 /로 시작하는 채팅 명령을 써본 적이 있다면 원리가 똑같습니다. 이 킷도 /sodam-design-kit:setup처럼 /로 시작하는 명령 5개를 씁니다. |
| 플러그인 | 원래 프로그램(Claude Code)에 나중에 끼워 넣는 "추가 기능 묶음". 스마트폰에 새 앱을 설치하는 것과 비슷합니다 — 이 킷 자체가 하나의 플러그인입니다. |
| 폴더 / 경로 | "폴더"는 파일을 담는 서랍이고, "경로"는 그 서랍이 컴퓨터 안 어디에 있는지 적은 주소(예: D:\내문서\프로젝트)입니다. |
| 다운로드 / 설치 | "다운로드"는 인터넷의 파일을 내 컴퓨터로 가져오는 것, "설치"는 그 파일을 컴퓨터가 쓸 수 있는 상태로 준비해두는 것입니다. |
| 브라우저 | 크롬(Chrome) · 엣지(Edge)처럼 인터넷 화면(웹사이트)을 보는 프로그램. 이 킷은 사람이 보는 브라우저 창을 직접 열지 않고, 눈에 보이지 않는 자동화된 브라우저로 화면을 대신 확인합니다. |
| 서버 (개발 서버) | 웹사이트 화면을 실제로 "보여주는" 역할을 하는 프로그램. 이 킷은 검증할 때마다 이 서버를 컴퓨터 안에서 자동으로 켰다 끕니다 — 사람이 직접 켤 필요가 없습니다. |
| 코드 / 파일 / 확장자 | "코드"는 컴퓨터에게 어떻게 동작하라고 적어놓은 글자들이고, "파일"은 그 글자들이 저장된 문서 하나하나입니다. .tsx · .json · .md처럼 파일 이름 끝에 붙는 부분을 "확장자"라 부르며, 파일의 종류를 나타냅니다. |
| 저장소 (repository) | 관련된 파일들을 통째로 모아놓은 폴더 묶음. 이 킷 전체, 그리고 여러분이 코드를 옮겨 넣을 프로젝트 전체가 각각 하나의 저장소입니다. |
| 킷 (kit) | "도구 모음"이라는 뜻. 이 문서에서 "이 킷"은 항상 SoDam-Design-Kit(지금 이 프로그램) 자신을 가리킵니다. |
| Figma | 디자이너들이 화면(버튼 · 앱 화면 등)을 그리는 데 널리 쓰이는 온라인 디자인 프로그램. 이 킷은 Figma에 그려진 디자인을 읽어옵니다. |
| 컴포넌트 | 버튼 · 입력창처럼, 여러 화면에서 반복해서 재사용하는 작은 화면 조각(부품) 하나. |
| 판정서 | 이 킷이 검사를 마치고 "통과(PASS)" 또는 "실패(FAIL)"를 적어서 남기는 결과 기록 파일. |
| 토글 (접기/펼치기) | 클릭하면 내용이 펼쳐지거나 다시 접히는 화면 요소. 이 문서의 7장이 이 방식으로 되어 있습니다 — 제목을 한번 클릭해보세요. |
| 라이선스 | 이 프로그램(코드)을 남이 써도 되는지, 쓴다면 어떤 조건을 지켜야 하는지 정해놓은 규칙 문서. 13장에서 자세히 다룹니다. |
💬 정말 처음이신가요?: 이 킷을 쓰려면 최소한 "Claude Code를 열고 채팅창에 글자를 입력해본 경험" 정도는 필요합니다. 컴퓨터를 정말 처음 켜보는 단계라면, 먼저 claude.com/claude-code 공식 안내를 따라 Claude Code부터 설치하고 몇 마디 대화를 나눠본 뒤 이 문서로 돌아오시길 권합니다. (이 킷은 Node.js·Figma 계정 등 몇 가지가 더 필요한 개발 도구라, "앱 하나만 깔면 바로 되는" 종류는 아닙니다 — 2장에서 필요한 것을 전부 확인할 수 있습니다.)
1. 이 도구는 무엇인가
한 줄로 말하면: "Figma 디자인 → 실제로 작동하는 코드"를 자동으로 만들어 주되, 브라우저에서 실제로 확인해보지 않은 결과는 "완료"라고 말하지 못하게 강제로 막는 도구입니다.
- Figma에 그려진 화면(예: 버튼 하나)을 읽습니다.
- 그 화면과 같은 모양의 코드를 shadcn/ui(React 컴포넌트 모음) 스타일로 만듭니다.
- 만든 코드를 눈에 보이지 않는 자동화된 브라우저에 띄우고, 화면이 깨지지 않았는지 · 장애인 접근성(스크린 리더 등)에 문제가 없는지 · 휴대폰(360px) · 태블릿(768px) · PC(1440px) 3가지 화면 크기에서 다 괜찮은지 자동으로 검사합니다.
- 검사를 통과하면 "판정서"라는 기록을 남기고, 실패하면 "완료"라고 보고하는 것 자체를 시스템이 기계적으로 막습니다(사람이 깜빡 잊거나, AI가 눈속임하려 해도 소용없습니다).
Figma 디자인 ──▶ 코드 생성 ──▶ 실제 브라우저에서 검사 ──▶ 통과해야만 "완료"
왜 이런 도구가 필요한가: AI에게 "이 디자인대로 코드 만들어줘"라고만 시키면, AI는 코드를 만들고 "다 됐습니다"라고 말할 수 있습니다. 하지만 그 코드가 실제로 화면에 정상적으로 나오는지, 글자가 깨지지는 않는지, 스크린 리더 사용자도 쓸 수 있는지는 AI 혼자 "말로만" 확인한 것일 수 있습니다. 이 킷은 그 마지막 확인을 사람이 아니라 진짜 브라우저 프로그램이 기계적으로 하게 만들어서, "말로는 됐다는데 실제로는 안 됐다"는 상황 자체를 원천적으로 막습니다.
누구를 위한 도구인가: Figma로 디자인을 만드는 사람과, Claude Code로 그 디자인을 코드로 옮기는 사람(1인이어도 무방) — 특히 "AI가 코드는 만들었다는데, 실제로 화면이 제대로 나오는지는 안 봤다"는 불안을 없애고 싶은 사람.
누구를 위한 도구가 아닌가(정직한 한계 고지): 코딩을 전혀 모르는 채로 "완성된 웹사이트"를 통째로 만들어주는 도구는 아닙니다. 이 킷이 만드는 것은 이미 존재하는 프로젝트(Next.js + Tailwind + shadcn/ui) 안의 화면 부품 하나하나입니다 — 2장에서 이 전제를 자세히 설명합니다.
2. 사전 준비물 · 필요 프로그램 (다운로드 방법 포함)
이 4가지가 전부 준비되어 있어야 합니다. 하나라도 없으면 3장(설치)부터 진행할 수 없습니다.
| 번호 | 준비물 | 왜 필요한가 | 다운로드 / 확인 방법 |
|---|---|---|---|
| 1 | Claude Code | 이 킷 자체가 Claude Code의 "플러그인"이라 Claude Code가 없으면 실행할 수 없음 | claude.com/claude-code 공식 안내에 따라 설치 |
| 2 | Node.js 18 이상 | 이 킷의 모든 검증 스크립트가 Node.js(자바스크립트 실행기)로 작성됨 | nodejs.org에서 "LTS" 버전 다운로드 · 설치. 설치 후 터미널(명령 입력 창)에 node -v 입력 → 버전 번호가 나오면 성공 (이 킷의 개발 · 검증 환경은 v22.19.0) |
| 3 | 대상 프로젝트: Next.js + Tailwind CSS + shadcn/ui | 이 킷이 만드는 코드가 이 3가지 조합을 전제로 함(다른 프레임워크는 아직 미지원) | 이미 이 조합으로 만들어진 프로젝트가 있어야 함. 없다면 npx create-next-app@latest 등 Next.js 공식 방법으로 새로 만들고 shadcn/ui 공식 설치 안내를 따라 준비 |
| 4 | Figma 파일 접근 권한 | 코드로 옮길 디자인 원본이 Figma에 있어야 함 | claude.ai에 이미 연결된 Figma 커넥터를 쓰거나, 공식 Figma MCP(https://mcp.figma.com/mcp)로 로그인. Figma 계정 자체는 무료(Starter) 플랜도 가능하나 한 달에 6회만 읽기 가능(뒤 10장 참고) |
처음 보는 단어가 있다면 0장 용어 사전을 먼저 확인하세요. 특히 "터미널"이 뭔지 모르겠다면: 글자로 명령을 입력해 컴퓨터에게 시키는 검은/흰 화면입니다. Claude Code를 설치하면 그 안에서 명령을 입력하는 창이 곧 터미널입니다. 별도로 새로 설치할 필요는 없습니다.
준비물 3번이 없다면?: 이 킷은 "이미 어느 정도 만들어진 웹사이트 프로젝트"가 있다는 전제로 작동합니다. 아무 프로젝트도 없는 상태에서 "웹사이트를 통째로 만들어줘"라는 용도로는 설계되어 있지 않습니다. 그런 프로젝트가 아직 없다면, Claude Code에게 "Next.js + Tailwind + shadcn/ui로 빈 프로젝트를 만들어줘"라고 자연어로 요청해 먼저 준비하는 것도 방법입니다.
3. 다운로드 및 설치 방법
아래 절차는 이 킷이 GitHub 마켓플레이스가 아니라, 내 컴퓨터의 폴더 경로를 직접 지정해서 설치하는 "로컬 폴더 방식" 기준입니다(2026-07-20 실측 확정, 현재도 동일). 나중에 별도 GitHub 마켓플레이스 방식으로 전환되면 1번 명령의 주소가 폴더 경로 대신 다른 주소로 바뀔 수 있습니다 — 그때는 이 절이 다시 갱신됩니다.
마켓플레이스 등록 — Claude Code 채팅창 안에서 아래 명령을 그대로 입력합니다(주소 부분만 여러분 컴퓨터의 실제 경로로 바꿉니다):
/plugin marketplace add <이 저장소 폴더의 전체 경로>(예:
D:\AI_Dev_Work\2026y\26y_07m_26d_SoDam-Design-Kit)플러그인 설치 — 이어서 아래 명령을 입력합니다:
/plugin install sodam-design-kit@sodamClaude Code 완전 재시작 — 창을 완전히 닫고 다시 엽니다. (이유는 11장 트러블슈팅 "설치했는데 명령이 안 보여요" 참고 — 단순 새로고침이 아니라 완전히 닫았다가 다시 켜야 합니다.)
의존성 설치 (최초 1회만) — 이 플러그인 저장소 폴더 자체(지금 이
README.md가 있는 위치)에서 터미널에 아래를 입력합니다:npm install검증 게이트가 사용하는 브라우저 자동화 도구(Playwright)와 접근성 검사 도구(axe-core)는 킷 코드에 같이 들어있지 않고 이 명령으로 직접 받아야 합니다.
중요(실측 확인된 함정): 이 플러그인은 "로컬 폴더 방식"이라서 설치해도 별도의 복사본이 다른 곳에 만들어지지 않습니다. Claude Code는 1번에서 지정한 원본 폴더를 그대로 사용합니다. 그래서
npm install도 반드시 이 원본 폴더 안에서 실행해야 하며, 별도의 "설치된 위치"를 찾아다닐 필요가 없습니다.설치 확인 — 코드로 옮기고 싶은 대상 프로젝트(2장 준비물의 Next.js 프로젝트) 안에서 아래 명령을 입력합니다:
/sodam-design-kit:setup이 명령이 자동완성 목록에 뜨고 정상 실행되면 설치 성공입니다.
설치가 안 됐다는 걸 어떻게 아나요?: 4번째 글자까지 입력했는데(/sod) 자동완성 목록에 아무것도 안 뜨면 설치가 안 된 것입니다. 11장의 첫 번째 항목을 확인하세요.
3장 보충 — Claude Desktop에서도 검증 이력을 보고 싶다면 (선택, 2026-08-20 추가)
위 1~5번은 Claude Code(터미널형 채팅) 전용입니다. Claude Desktop(일반 데스크톱 앱)에서도 이 킷이 만든 검증 이력·판정서·스크린샷을 보고 재검증을 실행하고 싶다면 아래 확장을 추가로 설치할 수 있습니다 — 둘은 서로 다른 앱이고, 이 확장은 선택 사항입니다.
- 이 저장소 폴더에서 다음 명령으로 확장 파일(
.mcpb)을 만듭니다(터미널, 이 저장소 폴더 안에서):
이 저장소 폴더 이름을 딴npx @anthropic-ai/mcpb pack ..mcpb파일이 폴더 안에 새로 생깁니다(방금 만들어진 파일이니 폴더에서 바로 확인 가능합니다). 크기는 약 20MB입니다(2026-08-21 기준 — 실제 브라우저로 재검증하는 기능이 들어있어 다른 확장보다 큰 편입니다. 이전엔 실수로 무관한 파일까지 포함돼 약 70MB였으나, 불필요한 파일을 제외하도록 고쳐 지금 크기로 줄었습니다). - 생성된
.mcpb파일을 더블클릭하면 Claude Desktop이 설치 화면을 띄웁니다. 내용을 확인하고 설치를 승인하세요. - 설치 확인: Claude Desktop에서 "최근 검증 이력을 보여줘"처럼 물어봤을 때 이 킷의 도구(
list_runs등)가 호출되면 성공입니다.
이 확장으로 할 수 있는 것 / 못 하는 것 (정직 고지):
- 할 수 있음: 검증 이력 열람, 판정서·스크린샷 확인, 재검증 실행 — Claude Code의
/sodam-design-kit:open대시보드와 같은 데이터입니다. (2026-08-20 추가)component-map.json에 이미 등록된 컴포넌트를 검증용 프리뷰 화면에 다시 연결하는 것도 가능합니다(Figma를 새로 읽거나 새 코드를 쓰지는 않습니다 — 이미 있는 매핑을 재사용할 뿐입니다). - 못 함: 완료를 기계적으로 차단하는 것은 Claude Code 훅 전용 기능입니다. Claude Desktop에서는 재검증 결과(PASS/FAIL)를 보여줄 뿐, FAIL이어도 작업을 강제로 멈추지 않습니다. 또한 새 컴포넌트를 위한 실제 코드를 Claude Desktop이 대신 만들어 프로젝트에 넣어주지는 않습니다 — 검증 없이 실제 코드가 조용히 들어갈 수 있는 위험이 있다고 판단해 이번엔 의도적으로 포함하지 않았습니다.
- 이 확장의 재검증 기능은 내부적으로 실제 브라우저(Playwright)를 실행합니다 — 이 저장소에서
npm install을 이미 한 번 했다면 준비가 끝난 상태입니다. 이 확장만 단독으로 받은 경우라면 별도로npx playwright install이 필요할 수 있습니다.
4. 빠른 시작 (5분 안에 첫 성공 보기)
준비물이 다 있고 설치까지 마쳤다면, 아래 순서로 첫 결과를 5분 안에 볼 수 있습니다.
1단계 — 초기 설정 (최초 1회, 대상 프로젝트당)
/sodam-design-kit:setup
→ 성공 기준: .design-kit/config.json과 .design-kit/component-map.json이 생성되었다는 메시지가 나옴.
2단계 — 첫 파이프라인 실행 (이미 매핑된 컴포넌트가 있을 때)
/sodam-design-kit:pipeline
→ Figma 링크를 물어보면, 버튼 하나처럼 작은 단위의 Figma 공유 링크(주소에 node-id=가 포함된 링크)를 붙여넣습니다.
→ 성공 기준: 마지막에 PASS 판정과 함께 .design-kit/reports/에 판정서 파일이 생겼다는 메시지가 나옴.
3단계 — 판정서 확인
.design-kit/reports/2026-XX-XX-XXX.md
이 파일을 열어 **PASS** 표시와 360px/768px/1440px 스크린샷 경로 3줄이 있는지 확인합니다. 이게 보이면 "실제 브라우저 검증까지 완료됐다"는 뜻입니다.
실패(FAIL)해도 정상입니다 — 오히려 게이트가 제대로 작동한다는 뜻입니다. 11장 "완료가 차단됐다고 나와요" 항목을 보세요.
4단계(선택) — 만든 결과를 한눈에 보기
/sodam-design-kit:open
→ 브라우저 화면(대시보드)이 자동으로 열려서, 지금까지의 검증 이력 · 판정서 · 스크린샷을 한 곳에서 볼 수 있습니다. 다 봤으면 채팅창에 /sodam-design-kit:open --stop을 입력해 끌 수 있습니다(안 꺼도 무해하지만, 안 쓸 때는 꺼두는 것을 권장합니다).
5. 실행 · 사용 · 작동 방법
이 킷은 Claude Code 안에서 슬래시 명령(/로 시작하는 명령)으로 실행합니다. 사람이 터미널에 직접 Node 명령을 칠 필요는 없습니다(킷을 만드는 개발자가 자체 테스트할 때만 터미널 명령을 씁니다 — .PRD/04_PROJECT_SPEC.md "테스트 방법" 참고).
/sodam-design-kit:setup — 초기 설정
- 입력: 없음(현재 프로젝트 폴더를 자동으로 사용) / 선택: Figma 파일 링크
- 하는 일:
components.json(shadcn 설정)을 읽어 실제 컴포넌트 폴더를 찾고, 그 안의.tsx파일을 스캔해.design-kit/component-map.json을 만듭니다..design-kit/config.json(화면 크기 3종 · 자동재시도 3회 등 기본값)도 함께 생성합니다. - 작동 방법: 프로젝트당 1회만 실행하면 됩니다. 이미 설정이 있으면 자동으로 건너뛰고, 다시 스캔하려면
--force를 붙입니다(이때도 이미 확보한 Figma 매핑 정보는 보존되고 새 컴포넌트만 추가됩니다). - 성공 기준: "완료" 메시지 +
.design-kit/폴더 생성.
/sodam-design-kit:pipeline — 디자인→코드→검증
- 입력: Figma 공유 링크(페이지/노드 단위 직접 링크, 파일 전체 링크 아님 — 10장 참고)
- 하는 일: Figma 읽기 →
component-map.json에 매핑 기록 → shadcn/ui 코드 생성 → 미리보기 화면(/design-kit-preview/{컴포넌트}) 자동 생성 → 개발 서버 자동 실행 → 실제 브라우저 검증(Playwright+axe-core+3뷰포트) → 판정서 기록. - 작동 방법: 실패(FAIL)하면 최대 3회까지 자동으로 다시 시도합니다(연속 2회 실패해야 최종 FAIL로 확정). **이미 매핑된 컴포넌트를 재사용하는 경로와, 매핑이 없는 완전히 새로운 컴포넌트를 처음부터 만드는 경로 둘 다 실제로 검증 완료(PASS)**되었습니다. 신규 컴포넌트를 배치하기 전에는 색상 · 간격 같은 값이 하드코딩(예:
#ff0000)되어 있지 않은지 자동으로 검사해서, 걸리면 배치 자체를 거부합니다. - 성공 기준:
.design-kit/reports/에**PASS**가 적힌 판정서 파일 생성.
/sodam-design-kit:open — 검증 이력 대시보드 열람
- 입력: 없음 / 종료할 때만
--stop - 하는 일: 지금까지 쌓인 판정서 · 실행 기록 · 스크린샷을 사람이 보기 편한 브라우저 화면(대시보드)으로 열어줍니다. 화면에서 판정서를 눌러 상세를 보거나, "재검증" 버튼으로 다시 검사를 돌릴 수 있습니다.
- 작동 방법: 내 컴퓨터 안에서만 접속되는 주소(
127.0.0.1, 즉 "이 컴퓨터 자신"이라는 뜻)로 열리며, 다른 사람의 컴퓨터에서는 접속할 수 없습니다. 이미 켜져 있으면 새로 켜지 않고 기존 것을 재사용합니다. - 성공 기준: 브라우저 창이 자동으로 열리고 판정서 목록이 보임.
/sodam-design-kit:detail-page — 상품 상세페이지 파이프라인 (Phase 3)
- 입력: 상품 데이터 파일(CSV 또는 JSON — 상품 이름 · 특징 등이 적힌 표 형식 파일)
- 하는 일: 상품 데이터를 읽어 → AI가 소개 문구(제목 · 핵심 장점 · 설명 · 자주 묻는 질문)를 작성 → 그 문구를 보여주는 상세페이지 코드로 연결 → 기존과 동일한 검증 게이트(실브라우저+접근성 검사+3개 화면 크기) 통과.
- 작동 방법: 상품마다 새 페이지 파일을 따로 만들지 않고, 페이지 틀(템플릿)은 1개만 만든 뒤 상품 데이터만 상품마다 저장하는 방식입니다(새 파일이 무한정 늘어나는 것을 방지).
- 성공 기준: 다른 명령과 동일하게
.design-kit/reports/에**PASS**판정서 생성.
/sodam-design-kit:marketing-asset — 마케팅 이미지(OG · 포스터 · 배너 · 명함) 생성 (Phase 3)
- 입력: 제목(필수) + 부제목(선택), 명함은 추가로 회사 · 전화 · 이메일 등 여러 줄(선택)
- 하는 일: 4가지 규격 중 하나로 이미지를 자동 렌더링합니다 — OG(1200×630, SNS 공유용) · 포스터(1080×1350, 인스타그램 세로형) · 배너(1200×400, 가로형) · 명함(1050×600, 3.5×2인치 실제 인쇄 규격). 규격 · 형식 · 용량 기준을 통과 못 하면 파일을 아예 만들지 않습니다.
- 작동 방법: 한글 폰트(Pretendard)를 자동으로 재사용해 글자가 네모로 깨지지 않게 렌더링하고, 만든 이미지 정보를 AI 생성 이력(
AI-GENERATION-LOG.md)에 자동으로 남깁니다. - 성공 기준:
public/design-kit-assets/<규격>-<제목>.png파일 생성. SNS 카드 등 그 외 규격은 아직 지원하지 않습니다(필요성이 확인되면 추가 검토).
P1 완료 확인 절차 (프로젝트 관리자용)
이건 일반 사용마다 할 일이 아니라, 이 킷이 "새 대화(세션)에서도 처음부터 똑같이 작동하는지"를 최종 확인하는 절차입니다(
.PRD/01_PRD.md§9 성공 기준 5·6번). 새 Claude Code 세션에서 아래 순서대로 하면 이 문서만 보고도 그대로 재현할 수 있습니다.
- 대상 프로젝트를 정합니다 — 이미
/sodam-design-kit:setup을 마치고 Figma 매핑도 있는 프로젝트가 이상적입니다(Figma를 다시 호출하지 않아도 되어 무료 월 6회 한도를 쓰지 않습니다). - 실행 직전, 판정서 폴더의 현재 상태를 먼저 확인해 기준으로 삼습니다 (PowerShell):
여기 나온 파일 목록을 잠깐 기억해둡니다 — 나중에 "기존 파일이 안 지워졌는지" 비교할 기준입니다.Get-ChildItem "<대상 프로젝트 경로>\.design-kit\runs" | Sort-Object Name | Select-Object -Last 3 - Claude Code에서 아래를 실행합니다.
대상 프로젝트 경로와 Figma 노드(또는 이미 있는 매핑)를 알려주면 됩니다./sodam-design-kit:pipeline - 성공 기준 (이게 전부 보이면 성공):
- 결과에
"verdict": "PASS"가 나온다 .design-kit\reports\폴더에 새 판정서 파일 1개가 생겼다- 2번에서 확인해둔 기존 파일들이 하나도 사라지지 않았다(덮어쓰기 없음)
- 에이전트가 임시 스크립트를 즉석에서 따로 만들지 않았다 —
verify-runner.mjs --target ...명령 하나로 검증과 판정서 기록이 동시에 끝나야 합니다
- 결과에
- 꼭 PowerShell로 실행하세요 — Git Bash에서는
/design-kit-preview/...처럼/로 시작하는 값이 경로로 잘못 해석되는 함정이 있습니다(11장 트러블슈팅 참고).
6. 명령어 표
| 명령 | 설명 | 입력 | 실행 위치 | 현재 상태 |
|---|---|---|---|---|
/sodam-design-kit:setup |
config.json 생성 + shadcn 컴포넌트 스캔으로 component-map 초기 시드 | 없음(선택: Figma 파일 링크) | 대상 프로젝트(Next.js) 안 | ✅ 실측 검증 완료 |
/sodam-design-kit:pipeline |
Figma 읽기 → 매핑 → shadcn/ui 코드 생성 → 검증 게이트 | Figma 페이지/노드 링크 | 대상 프로젝트(Next.js) 안 | ✅ 재사용(매핑) 경로 · 신규 컴포넌트 생성 경로 둘 다 실측 PASS |
/sodam-design-kit:open |
검증 이력 · 판정서 · 스크린샷을 브라우저 대시보드로 열람 + 재검증 트리거 (127.0.0.1 전용, 종료는 --stop) |
없음 | 대상 프로젝트 안 | ✅ 실제 백그라운드 기동 · 재사용 · 종료 왕복 실측 PASS |
/sodam-design-kit:detail-page |
상품 데이터(CSV/JSON) → 카피 생성 → 상세페이지 코드 → 동일 검증 게이트 (Phase 3) | 상품 데이터 파일(CSV 또는 JSON) | 대상 프로젝트(Next.js) 안 | ✅ 실측 PASS→FAIL(의도적 접근성 위반)→PASS 복귀 왕복 확인 |
/sodam-design-kit:marketing-asset |
제목/부제(+명함은 추가 정보) → OG · 포스터 · 배너 · 명함 이미지 자동 생성 (Phase 3) | 제목(필수) · 부제(선택) · 명함 추가 정보(선택) | 대상 프로젝트 안 (public/design-kit-assets/) |
✅ 4종 전부 실측 PASS(한글 렌더 · 규격 확인) |
킷 개발자(코드를 직접 고치는 사람) 전용 명령(일반 사용자는 몰라도 됩니다):
| 명령 | 설명 | 실행 위치 |
|---|---|---|
npm install |
검증용 브라우저 · 접근성 도구 설치(최초 1회) | 이 킷 저장소 폴더 |
npm test |
킷 자체의 자동 테스트 실행(2026-08-20 기준 330개, 실행 시점에 따라 늘어날 수 있음) | 이 킷 저장소 폴더 |
npm run selftest (= node scripts/e2e-selftest.mjs) |
전체 파이프라인 왕복(PASS/FAIL/재검증) 자체 점검 | 이 킷 저장소 폴더 |
7. 업데이트 내용 요약
▶ 2026-08-21 — 저장소 보안 강화 + 라이선스 전수 감사 + 배포 패키지 정보 유출 결함 수정 (클릭해서 접기)아래 항목들은 접었다 펼 수 있는 "토글" 형태입니다 — 제목(▶ 표시가 있는 줄)을 클릭하면 자세한 내용이 펼쳐집니다. 가장 최근 것이 맨 위에 있습니다.
- GitHub 저장소(공개 상태)의 보안 기능 3가지(비밀정보 자동 탐지 · 커밋 차단 · 오래된 의존성 자동 알림)가 열흘 넘게 꺼져 있던 걸 발견해서 켰습니다.
- 지금까지는 직접 설치하는 프로그램 8개만 라이선스를 확인했는데, 이번엔 그 8개가 딸려서 데려오는 나머지 프로그램까지 합쳐 총 126개 전부를 하나하나 확인했습니다. 문제가 될 만한 라이선스는 없었지만, 이미지 변환에 쓰는 프로그램(sharp)이 내부적으로 포함하는 부품 하나가 다른 종류의 라이선스(LGPL)를 쓰고 있다는 걸 새로 발견해서 13장에 정직하게 적어뒀습니다(법적으로 문제는 없습니다).
- 실제 발견한 결함: Claude Desktop용 확장 파일(
.mcpb)을 만들 때, 원래는 실행에 필요한 프로그램 코드만 들어가야 하는데, 실수로 이 킷 개발 중에만 쓰는 내부 기록 파일(CHECKPOINT.md등)과 전혀 상관없는 대용량 테스트 파일까지 통째로 같이 포장되고 있었습니다. 즉시 원인부터 고쳐서, 확장 파일 용량이 약 70MB에서 약 20MB로 줄었고, 문제였던 파일들은 전부 빠진 것을 확인했습니다. - 자동 테스트는 그대로 330개이며(이번 라운드는 문서 · 저장소 설정 수정), 330개 전부 통과합니다. 새로운 프로그램(의존성)은 추가하지 않았습니다.
- Figma 디자인 안에 사진이나 아이콘이 들어있는 화면을 코드로 만들 때, 지금까지는 그 이미지 주소를 임시 주소 그대로 코드에 넣고 있었습니다. 이 임시 주소는 Figma가 7일 뒤에 없애버리는 주소라서, 시간이 지나면 화면에서 그림이 갑자기 사라지는 문제가 있었습니다.
- 처음부터 이 문제가 있다는 건 문서에 적혀 있었지만, 실제로 막아주는 장치는 없이 "알아서 조심하기"에만 의존하고 있었다는 걸 이번에 재확인해서 고쳤습니다.
- 이제부터는 이미지가 있는 화면을 만들 때 그 이미지를 자동으로 내 프로젝트 폴더 안에 내려받아 저장하고, 코드에는 그 저장된 파일을 가리키게 만듭니다 — 7일이 지나도 그림이 사라지지 않습니다.
- 안전장치도 같이 넣었습니다: 진짜 이미지 파일이 맞는지 확인 후에만 저장하고, 아이콘 파일(SVG) 안에 위험한 코드가 숨어 있으면 저장을 거부합니다.
- 자동 테스트 15개 추가(314→329개), 전부 통과. 새로운 프로그램(의존성)은 추가하지 않았습니다.
- Claude Desktop 확장(바로 아래 항목에서 처음 추가)에 기능 1개를 더했습니다 —
component-map.json에 이미 등록된 컴포넌트를 검증용 프리뷰 화면에 다시 연결하는 기능입니다. - 이 기능을 설계하면서 중요한 걸 하나 확인했습니다: 이 킷은 "Figma 디자인을 읽어서 새 코드를 자동으로 쓰는" 기능과 "이미 있는 컴포넌트를 프리뷰에 연결하는" 기능이 완전히 다른 위험 등급이라는 걸 코드를 직접 열어 확인했습니다. 전자(새 코드를 실제로 프로젝트에 쓰는 것)는 Claude Desktop에 "검증 통과 전엔 완료로 인정 안 함"을 강제하는 장치가 없어서, 검증 안 된 코드가 조용히 프로젝트에 들어갈 수 있는 위험이 있습니다.
- 그래서 이번엔 안전한 쪽(이미 있는 컴포넌트를 프리뷰에 연결하는 것)만 추가했고, 위험한 쪽(새 코드를 프로젝트에 쓰는 것)은 의도적으로 포함하지 않았습니다.
- 자동 테스트 6개 추가(308→314개), 전부 통과. 새로운 프로그램(의존성)은 추가하지 않았습니다(기존 기능을 그대로 재사용).
- 실제 테스트 프로젝트로 "컴포넌트를 프리뷰에 연결→재검증까지" 왕복이 실제로 되는 것을 직접 확인했습니다.
- 바로 아래 두 기능(Claude Desktop용 확장, 마케팅 이미지 규격 추가)을 다시 꼼꼼히 확인하는 과정에서 실제 문제 2건을 찾아 고쳤습니다.
- ① Claude Desktop 확장에서 "어느 프로젝트인지" 값을 빈 값으로 잘못 보내면, 오류로 알려주는 대신 엉뚱하게 확장 프로그램 자신이 있는 위치를 대상으로 삼아버리는 문제가 있었습니다. 이제는 빈 값을 주면 바로 명확한 오류로 알려줍니다.
- ② 명함 이미지를 만들 때 "추가 정보"(회사·전화번호 등)를 정해진 형식이 아닌 값으로 잘못 넣으면, 오류 없이 조용히 글자가 한 자씩 따로따로 그려진 잘못된 이미지가 만들어지고, 한참 뒤 엉뚱한 단계에서 알아보기 어려운 오류가 나는 문제가 있었습니다. 이제는 잘못된 형식을 넣는 즉시 명확한 오류로 알려줍니다.
- 재확인 결과 이 두 가지 외에 새로 발견된 문제는 없었습니다(경로 조작·비정상적으로 긴 입력값·잘못된 형식의 다른 값들은 전부 기존대로 안전하게 처리됨을 재확인).
- 자동 테스트 4개 추가(305→308개), 전부 통과. 새로 추가한 기능·명령은 없습니다(기존 기능의 안전장치 보강).
- 지금까지는 Claude Code(터미널형 채팅)에서만 이 킷을 쓸 수 있었는데, 이제 Claude Desktop(일반 데스크톱 앱)에서도 검증 이력·판정서·스크린샷을 보고 재검증을 실행할 수 있는 확장(
.mcpb파일)을 만들 수 있습니다. - 설계 도중 중요한 사실을 하나 발견했습니다 — 원래 계획은 "이미 있는 대시보드(웹 서버)를 그대로 같이 쓴다"였는데, 실제로 Claude Desktop의 이런 확장은 웹 서버 방식이 아니라 완전히 다른 방식(프로그램을 직접 실행해서 대화하는 방식)으로 동작한다는 걸 공식 문서를 직접 찾아보고 알게 됐습니다. 그래서 "서버를 같이 쓴다"가 아니라 "이미 만들어둔 기능을 그대로 재사용한다"는 더 간단한 방식으로 다시 설계했습니다.
- 정직하게 밝혀둘 점: 이 확장은 "검증 결과를 보여주는 것"까지만 하고, Claude Code처럼 실패했을 때 작업을 강제로 멈추는 기능은 없습니다(Claude Code 전용 기능이라 기술적으로 다른 프로그램에서는 안 됩니다). 이 사실을 도구 설명 자체에 명시해뒀습니다.
- 신규 자동 테스트 16개 추가(289→305개), 전부 통과. 새 의존성 2개(공식 MCP 도구 · 입력값 검증 도구) 추가,
npm audit0건 유지. - 다음 범위(Figma 데이터를 받아 코드를 직접 생성하는 기능)는 이번엔 포함하지 않았습니다 — 이번엔 "검증 이력을 보고 재검증하는 기능"까지만 먼저 확실하게 만들었습니다.
- 지금까지는 SNS 공유용 이미지(OG, 1200×630) 1가지만 만들 수 있었는데, 이제 포스터(1080×1350, 인스타그램 세로형) · 배너(1200×400, 가로형) · 명함(1050×600, 실제 명함 인쇄 규격) 3가지를 더 만들 수 있습니다.
- 명함은 이름·직함만으로는 부족해서(회사·전화번호·이메일 등도 필요) 여러 줄을 추가로 넣을 수 있는 기능(
--extraLines)을 새로 만들었습니다. - 이전에 만든 OG 이미지 기능 자체가 "규격 하나를 검증했다고 다른 규격도 똑같이 되는 건 아니다"라고 미리 경고해뒀던 대로, 3가지 규격을 각각 실제로 만들어보고 눈으로 직접 확인했습니다(글자가 안 잘리고, 한글이 깨지지 않는지).
- 신규 자동 테스트 10개 추가(279→289개), 전부 통과. 새 의존성 없음(
npm audit0건 유지).
- Phase 3 진행 순서의 네 번째 항목을 완료했습니다. 지금까지는 폰트만 "어디서 가져왔는지·무슨 라이선스인지"를 자동 기록·검사했는데, 이제 이미지·아이콘 파일도 같은 방식으로 확인할 수 있습니다(선택 기능 — 원할 때만 켬).
- 마케팅 이미지 자동 생성 기능(바로 아래 항목)이 만든 이미지와 검증용 스크린샷은 이 검사 대상이 아닙니다 — 그건 이미 다른 기록(AI 생성 이력)에 남기 때문입니다. 이 경계를 처음부터 정확히 설계하고 실제 프로젝트로 확인했습니다.
- 출처 정리 문서(
ATTRIBUTION.md)를 자동으로 만들어주는 기능도 함께 추가했습니다. - 실측 검증: 실제 픽스처 프로젝트에 원래 있던 등록 안 된 이미지 파일(기본 아이콘 5개+파비콘 1개)이 정확히 걸리는 것을 확인했고, 그중 하나를 대장에 등록하니 그 파일만 정확히 목록에서 빠지는 것도 확인했습니다.
- 신규 자동 테스트 26개 추가(246→272개), 전부 통과. 새 의존성 없음(
npm audit0건 유지).
- 새로 만든 기능(AI 생성 이력 기록·마케팅 소재 생성)을 정상 상황뿐 아니라 예외·실패 상황까지 폭넓게 재검증하다가 진짜 문제 3가지를 찾아 고쳤습니다.
- ① 존재하지 않는 프로젝트 경로를 주면 조용히 새 폴더를 만들어버리던 문제 → 명확한 오류 메시지로 바꿨습니다.
- ② 입력한 문구에 코드블록(백틱 3개)이 들어가면 기록 파일의 서식이 깨질 수 있던 문제 → 항상 안전하게 감싸도록 고쳤습니다.
- ③ 문장부호만 다른 비슷한 제목으로 이미지를 두 번 만들면 첫 번째 이미지가 조용히 사라지던(덮어써지던) 문제 → 자동으로 구분되도록 고쳤습니다.
- 회귀 테스트 5개를 추가했고, 전부 통과합니다(241개 → 246개).
- 제목·부제목을 주면 SNS 공유용 이미지(1200×630 규격)를 자동으로 만들어주는 기능을 추가했습니다.
- 한글 글자가 깨지지 않는지 이 컴퓨터에 실제로 설치해서 먼저 확인한 뒤 착수했습니다.
- 만들어진 이미지가 규격·형식·용량 기준을 통과하지 못하면 아예 파일을 만들지 않습니다 — "검증 없이 결과물이 나오지 않는다"는 이 킷의 원칙을 이미지에도 그대로 적용했습니다.
- 포스터·배너·명함 등 다른 규격은 이번 범위가 아니며, 나중에 추가할 때는 각각 따로 실제 검증을 거칩니다.
- 신규 자동 테스트 17개를 추가했고, 전부 통과합니다(224개 → 241개).
- 에이전트가 자유롭게 작성하는 콘텐츠(현재는 상세페이지 카피)를 언제·어떤 모델로·어떻게 만들었는지 자동으로 기록에 남기는 기능을 추가했습니다.
- 이 기록 파일은 검증 스크린샷 등과 달리 저장소에 실제로 커밋되는 파일이라, 프로젝트가 공개 저장소라면 기록에 시크릿(비밀번호·API 키 등)이 그대로 남을 위험이 있었습니다 — 기록하기 전에 항상 시크릿 패턴을 걸러내는 필터를 적용해 이 위험을 막았습니다.
- 신규 자동 테스트 18개를 추가했고, 전부 통과합니다(206개 → 224개).
- Phase 3(마케팅 소재+상세페이지+공개 검토)의 전제 조건("Phase 1+2가 본인 실사용에서 안정적")이 사용자의 실제 라이브 테스트(대시보드 스크린샷 확인 + 재검증 버튼 정상 작동 확인)로 충족되어, Phase 3의 첫 기능으로 상세페이지 파이프라인을 구현했습니다.
- 하는 일: 상품 데이터 파일(CSV 또는 JSON) 한 개에서 상품을 골라 카피(제목 · 핵심 장점 · 설명 · 자주 묻는 질문)를 작성하고, 그 카피를 보여주는 상세페이지 코드로 연결한 뒤 기존과 동일한 검증 게이트(실브라우저+접근성 검사+3개 화면 크기)를 통과해야 완료로 표시됩니다.
- 설계 원칙: 상품마다 새 페이지 파일을 만드는 대신, 페이지 템플릿은 1개만 만들고 상품 데이터만 상품마다 따로 저장합니다 — 이 킷이 스스로 "새 파일을 가장 많이 만드는 단계라 위험이 가장 크다"고 표시해둔 단계라, 파일 수를 늘리지 않는 방향으로 그 위험을 낮췄습니다.
- 실측 검증: 실제 픽스처 프로젝트에 더미 상품 데이터를 넣어 전체 과정을 실행해 PASS를 확인했고, 일부러 접근성 결함(대체 텍스트 없는 이미지)을 주입해 게이트가 실제로 FAIL을 내는 것까지 확인한 뒤 원상복구해 다시 PASS로 돌아오는 것까지 확인했습니다.
- 신규 자동 테스트 22개 추가(178→200개), 전부 통과. 새 의존성 없음(
npm audit0건 유지). - 상품 생성 이력을 자동으로 남기는 기능(AI-GENERATION-LOG.md)과 마케팅 이미지 소재 파이프라인은 다음 증분으로 남겨뒀습니다(이번 범위 아님).
- Phase 2가 처음으로 "AI가 픽스처로 검증"이 아니라 사용자 본인이 새 대화창을 열어 직접 사용하는 방식으로 시험됐습니다:
/sodam-design-kit:open(대시보드 열기) → 판정서 열람 → 재검증 버튼 클릭 → 폰트/화면 변경 감지 기능에 대한 자연어 질문까지 전부 직접 실행했습니다. - 그 과정에서 진짜 결함 1건을 발견했습니다: 자체 점검(
e2e-selftest)이 만든 판정서에 원래 검사했던 화면 주소(route)가 기록되지 않아서, 대시보드의 "재검증" 버튼을 눌러도 영구적으로 재검증이 안 되는 문제였습니다. 발견 즉시 수정하고 재검증까지 마쳤습니다. - 대시보드를 열고 판정서를 눌러보는 것까지는 "본인 실사용으로 확인됨"이라 볼 수 있지만, 폰트 자동화 · 화면 변경 감지 기능 자체를 명령으로 직접 켜본 것은 아니라서, 완전한 "실사용 확인"으로 보기엔 아직 이릅니다.
- 대시보드 화면(2026-08-09 완료 선언)이 실은 판정 스크린샷을 브라우저에 한 번도 제대로 못 보여주고 있었다는 것을, 이번에 헤드리스(눈에 안 보이는) 브라우저로 실제 화면을 열어보고서야 발견했습니다.
- 원인은 두 가지가 겹쳐 있었습니다: ① 이미지 파일 경로 앞부분이 중복으로 붙어 "파일을 찾을 수 없음(404)" 오류가 났고, ② 보안 설정(CSP)이 이미지가 사용하는 특수한 형식(blob:)을 허용하지 않아 브라우저가 화면 표시 자체를 차단했습니다. 둘 다 화면이 "조용히" 안 보이기만 하고 프로그램이 죽지는 않아서 지금까지 발견되지 않았습니다.
- 수정 전(콘솔 오류 3건) → 원인 하나씩 해결하며 재확인 → 수정 후(콘솔 오류 0건, 이미지 3개가 실제 픽셀로 화면에 나타남)까지 직접 확인했습니다. 자동 테스트가 175개 → 178개로 늘었고 전부 통과합니다.
- 교훈: "검증 완료"라고 표시된 과거 기능이라도, 실제 화면 요소(이미지 등)까지 사람 눈으로 본 것이 아니라 데이터 차원에서만 확인했을 가능성이 있다는 것을 이번에 알게 되었습니다. 앞으로 화면 관련 기능은 눈에 보이지 않는 자동화 브라우저로 실제 픽셀까지 확인하는 것을 기본으로 삼기로 했습니다.
- 프로젝트가 정식으로 등록해둔 한글 폰트가 아닌, 출처를 알 수 없는 폰트 파일이 섞여 있으면 검증을 실패(FAIL) 처리하는 검사를 새로 추가했습니다(선택 기능 — 켜고 싶을 때만
--fontGate옵션으로 켤 수 있습니다). - 실측 검증: 일부러 등록되지 않은 폰트 파일을 프로젝트에 넣고 검사를 돌려 실제로 FAIL이 뜨는 것을 확인했고, 그 파일을 지운 뒤 다시 PASS로 돌아오는 것까지 확인했습니다. 이미 정식 등록된 폰트(예: Pretendard)는 이 검사로 인해 잘못 걸리지 않는 것도 함께 확인했습니다.
- 자동 테스트가 157개 → 172개로 늘었고 전부 통과합니다.
- 대시보드가 판정서를 화면에 보여줄 때, "화면 변경 감지(시각 회귀)" 결과를 적어둔 부분을 스크린샷 파일로 착각해서 잘못 표시하려던 결함을 발견해 고쳤습니다.
- 스크린샷 파일이 손상돼 있을 경우 검증 프로그램 전체가 멈춰버리던(크래시) 결함도 함께 발견해 고쳤습니다 — 이제는 손상된 파일 1개 때문에 전체 검증이 멈추지 않습니다.
- 자동 테스트가 155개 → 157개로 늘었고 전부 통과합니다.
- 지금까지는 프로젝트에 한글 폰트를 직접 준비해서 넣어야 했지만, 이제는 상업적 이용이 자유로운 오픈소스 한글 폰트(Pretendard, Noto Sans KR) 중에서 골라 자동으로 다운로드하고 프로젝트에 바로 쓸 수 있게 설정해주는 기능이 생겼습니다.
- 다운로드한 폰트가 어떤 라이선스인지 자동으로 기록해두는 대장(
ASSET-LEDGER.csv)도 이때 처음 만들어졌습니다 — 나중에 "이 폰트를 어떤 조건으로 썼는지" 확인이 필요할 때 참고할 수 있습니다. - 실측 검증: 실제 인터넷에서 Pretendard 폰트 파일(약 1.5MB)을 실제로 내려받는 것까지 확인했고, 같은 명령을 다시 실행해도 중복으로 받지 않는 것(멱등성)도 확인했습니다.
- 자동 테스트가 143개 → 155개로 늘었고 전부 통과합니다.
- 코드를 고친 뒤 화면이 이전과 비교해 실수로 달라지지는 않았는지, 스크린샷을 픽셀 단위로 자동 비교해주는 기능이 생겼습니다(선택 기능 —
--visualRegression옵션으로 켤 수 있습니다). "이 화면이 맞다"고 사람이 승인한 기준 화면과 비교하는 방식이며, 기준 화면 승인은 반드시 검증을 통과(PASS)한 화면에 대해서만, 사람이 직접(--promoteBaseline) 하도록 만들어져 있습니다. - 실측 검증: 기준 화면을 승인한 뒤 아무것도 안 바꾸면 "동일함"으로 나오는 것, 일부러 배경색을 바꾸면 3개 화면 크기 전부에서 "달라짐"으로 잡히며 검사가 실패(FAIL)하고 차이를 보여주는 이미지가 실제로 생성되는 것, 원상복구하면 다시 "동일함"으로 돌아오는 것까지 전부 확인했습니다.
- 자동 테스트가 135개 → 143개로 늘었고 전부 통과합니다.
- 이 킷이 자동으로 만드는 미리보기 화면에 "제목(
<h1>)이 없다"는 경미한 접근성 경고가 있었습니다. 화면에는 보이지 않지만 스크린 리더는 인식할 수 있는 방식으로 제목을 추가해 해소했습니다. - 실측 검증: 실제로 다시 검증을 돌려 이 경고가 사라진 것(1건 → 0건)을 확인했습니다.
- 자동 테스트가 134개 → 135개로 늘었고 전부 통과합니다.
- 그동안 판정서 · 실행 기록은 파일로만 존재해서 하나하나 직접 열어봐야 했습니다. 이제
/sodam-design-kit:open명령 하나로, 지금까지의 검증 이력을 브라우저 화면(대시보드)에서 한눈에 보고, 그 자리에서 바로 재검증까지 실행할 수 있습니다. - 안전장치: 대시보드는 내 컴퓨터 자신(
127.0.0.1)에서만 접속 가능하고, 로그인 정보나 비밀번호 없이도 안전하도록 여러 겹의 보호 장치(경로 조작 시도 차단, 잘못된 요청 차단, 파이프라인 실행 중에는 재검증 요청을 거부하는 잠금 장치 등)를 함께 만들고 각각 실제로 공격을 흉내 내 막히는지 확인했습니다. - 실측 검증: 실제로 대시보드를 켜서 → 브라우저에 정상적으로 화면이 뜨는 것 → 이미 켜져 있으면 새로 켜지 않고 재사용하는 것 →
--stop으로 끄면 정말로 꺼지는 것까지 전 과정을 실제로 확인했습니다. - 자동 테스트가 123개 → 134개로 늘었고 전부 통과합니다.
- 완료 선언 전 마지막 관문("완전히 새로운 대화(세션)에서 처음부터 재현하기")을 실제로 4번 시도했습니다. 그 과정에서 이전에는 드러나지 않았던 진짜 결함 3가지를 실사용 중에 발견해서 고쳤습니다:
- 스크린샷이 프로젝트 폴더 밖(사용자의 다른 폴더)에 저장되던 문제: 검증 결과 스크린샷을 저장하는 경로를 상대 경로로 처리할 때, "지금 어느 폴더에서 실행 중인지"에 따라 엉뚱한 곳에 저장될 수 있었습니다. 판정서에는 "성공"이라고 정확히 적혀 있었지만, 정작 그 파일이 프로젝트 안에는 없는 상황이 실제로 발생했습니다. 이제는 항상 프로젝트 폴더를 기준으로 저장 위치를 다시 계산하도록 고쳤습니다.
- 스크린샷이
.design-kit폴더 밖(같은 프로젝트 안이지만 관리 대상 밖)에 저장되던 문제: 1번을 고친 직후 발견한 조금 더 미묘한 문제입니다 — 프로젝트 폴더 "안"에는 저장되지만, 이 킷이 정식으로 관리하는.design-kit/폴더 "밖"에 저장되어 자동 정리 대상에서 빠지고, git에 실수로 올라갈 수 있는 위치에 남는 문제였습니다. 기준 위치를.design-kit/폴더 자체로 다시 잡아 해결했습니다. - 이미 매핑된 컴포넌트인데도 Figma 파일 주소를 다시 물어보던 문제: "재사용" 경로(이미 연결된 컴포넌트를 다시 쓰는 경우)는 원래 Figma를 다시 호출할 필요가 없도록 설계되어 있었는데, 실행 절차 문서의 한 단계가 이 조건을 확인하지 않고 무조건 Figma 주소를 요구하도록 되어 있어서, 이미 연결이 끝난 컴포넌트인데도 진행이 멈추는 문제가 있었습니다. 절차 맨 앞에 "이미 연결돼 있으면 건너뛴다"는 확인 단계를 추가해 해결했습니다.
- 세 가지를 전부 고친 뒤 네 번째 시도에서 마침내 완전히 성공했습니다 — 임시로 급하게 짜맞춘 코드 없이, 기존 판정 기록을 하나도 지우지 않고, 스크린샷도 정확한 위치에 저장된 채로 끝까지 통과했습니다.
- 이로써
.PRD/01_PRD.md§9(성공 기준) 6개 항목이 전부 실제 증거로 충족되어, Phase 1(MVP)을 공식적으로 완료 처리했습니다. - 자동 테스트는 68개 그대로이며(이번 라운드는 문서 · 실행 절차 수정이 대부분), 68개 전부 통과합니다.
- 자체 점검 명령이 조용히 엉뚱한 걸 실행하고 있던 문제: 이 킷을 관리하는 개발자가 쓰는
npm run selftest명령이, 실제로는 존재하지 않는 옵션을 가리키고 있어서 진짜 점검(scripts/e2e-selftest.mjs)은 실행되지 않고 사용법 안내만 나오는 상태였습니다. 사용자가 이 명령을 직접 쓸 일은 없습니다 — 이 문서는 항상 올바른 스크립트 실행 방법을 안내해 왔으므로, 지금까지 이 문서를 따라온 사용자에게는 영향이 없었습니다. 그래도 발견 즉시 올바른 스크립트를 가리키도록 고쳤습니다. - 정해진 순서(setup → pipeline)를 따르지 않고 검증만 따로 실행하면 스크린샷이 git에 노출될 수 있던 구멍: 이 킷을 안내된 순서대로 쓰면 스크린샷 폴더가 자동으로
.gitignore에 등록되지만,setup을 거치지 않고 검증 기능만 독립적으로 실행하는 예외적인 경로(주로 킷 개발자의 자체 테스트용)에서는 이 등록이 빠져 있는 것을 실제로 재현해서 확인했습니다. 판정서를 기록하는 코드에도 같은 등록 로직을 추가해 막았습니다. 이 경로 역시 안내된 순서대로 사용해 온 사용자에게는 영향이 없었습니다. - 두 수정 모두 기존 자동 테스트 66개에 영향 없이 그대로 전부 통과합니다.
- 예전엔 접근성 검사(axe-core)가 실패해도 판정서에 "critical 1건"처럼 개수만 적혀 있어서, 정확히 어떤 부분이 왜 잘못됐는지는 사람이 다시 찾아봐야 했습니다.
- 이제는 판정서의 "위반 상세" 항목에 규칙 이름 · 설명 · 문제가 된 화면 요소까지 구체적으로 적히도록 만들었습니다. 자동 재시도 때도 이 상세 내용을 다음 시도에 참고하도록 넘겨줘서, 같은 이유로 계속 실패하는 상황을 줄입니다.
- 자동 테스트 5개를 새로 추가했고, 전부 통과합니다(61개 → 66개).
- 지금까지는 Figma에서 이미 매핑해둔 컴포넌트를 "재사용"하는 경로만 실제로 검증됐고, 매핑이 아예 없는 새 컴포넌트를 처음부터 만드는 기능은 계획만 있고 구현되지 않은 상태였습니다.
- 이제 이 경로도 실제로 구현하고 검증까지 마쳤습니다. 새로 만든 코드를 프로젝트에 배치하기 전에, 색상 · 간격 값이 숫자로 하드코딩되어 있으면(예:
#ff0000,12px) 자동으로 배치 자체를 거부하도록 만들어서, 프로젝트가 원래 쓰던 디자인 값(토큰)을 우회하는 코드가 섞여 들어가는 것을 원천적으로 막습니다. - 자동 테스트 8개를 새로 추가했고, 전부 통과합니다(53개 → 61개).
- 가장 심각했던 문제 — 검사한 게 진짜 내 프로젝트가 아닐 수도 있었습니다: 이 킷은 검사용 화면을 띄울 때 사용 중인 포트(예: 3000번)를 피해서 자동으로 다음 포트를 쓰도록 되어 있는데, 컴퓨터에 이미 다른 프로그램(예: 다른 프로젝트의 개발 서버)이 그 포트를 쓰고 있어도 "비어있다"고 착각하는 경우가 있었습니다. 이렇게 되면 검사 프로그램이 내 화면이 아니라 완전히 다른 프로그램의 화면을 열어서 검사하고서도, 마치 내 프로젝트를 검사한 것처럼 보이는 판정서를 만들어냈습니다.
- 실제로 이 문제가 일어나는 상황을 발견했습니다: 전혀 관련 없는 다른 프로젝트의 개발 서버가 3000번 포트를 쓰고 있었는데, 이 킷이 그 포트를 "비어있다"고 착각해서 그 다른 프로그램의 화면을 검사하고 있었습니다.
- 포트가 실제로 쓰이고 있는지 확인하는 방식을 더 정확한 방법으로 바꿔서 해결했습니다. 다른 프로그램이 여전히 포트를 쓰고 있는 상태에서 다시 확인해보니, 이번엔 정확히 다음 포트로 피해가서 내 프로젝트만 정확히 검사하는 것을 확인했습니다.
- 앞으로 같은 문제가 다시 생기면 자동으로 잡히도록 자동 테스트 1개를 새로 넣었습니다.
- 이 수정 덕분에 자동 테스트가 53개가 되었고, 53개 전부 통과합니다(2026-07-27 실제 실행 확인).
- 가장 중요한 수정 — "완료 차단"이 조용히 사라지던 문제: 이 킷이 설치된 폴더 경로에 띄어쓰기(예:
My Projects)나 한글(예: 윈도우 사용자 이름이 한글일 때C:\사용자\홍길동\...)이 들어 있으면, 검사 프로그램이 아무 일도 안 하고 조용히 끝나는 문제가 있었습니다. 오류 메시지조차 안 나와서 사용자 입장에선 "잘 된 것처럼" 보입니다. 특히 완료를 막아주는 부분(hooks/verify-gate.mjs)에서 이 일이 벌어지면 검사 실패인데도 "완료"라고 보고되는 것을 못 막게 됩니다. 이 킷의 존재 이유가 사라지는 셈이라 가장 먼저 고쳤습니다.- 실제로 세 가지 경로에서 재현해 확인했습니다: 띄어쓰기 있는 폴더 → 꺼짐 / 한글 폴더 → 꺼짐 / 영문 폴더 → 정상. 고친 뒤에는 세 경우 모두 정상입니다.
- 고치기 전 버전을 한글+띄어쓰기 폴더에서 직접 실행해 정말 아무것도 출력하지 않는 것을 눈으로 확인했고, 고친 버전은 같은 자리에서 정상적으로 "차단" 판정을 출력합니다.
- 앞으로 같은 문제가 다시 생기면 자동으로 잡히도록, 일부러 띄어쓰기와 한글이 들어간 폴더에서 실행해보는 자동 테스트 2개를 새로 넣었습니다.
- 자동 테스트가 실제로는 1개 실패하고 있었던 문제: 문서에는 "50개 전부 통과"라고 적혀 있었지만, 실제로 돌려보니 49개만 통과했습니다. 원인은 테스트 하나가 "2026년 7월 20일"이라는 날짜에 묶여 있어서 그 날 하루만 통과하고 다음 날부터 깨지는 구조였기 때문입니다. 날짜를 밖에서 넣어줄 수 있게 고쳐서 해결했습니다(실제 사용에는 아무 영향 없음).
- 위 두 가지를 합쳐 자동 테스트가 50개 → 53개가 되었고, 53개 전부 통과합니다(2026-07-27 실제 실행 확인).
- 검증과 판정서 기록을 명령 하나로 통합: 예전에는 "실제 브라우저 검증"과 "그 결과를 기록으로 남기기"가 별개 단계처럼 문서에 적혀 있었지만, 실제로는 기록 스크립트에 명령 실행 방법(CLI)이 없어서 AI가 매번 임시로 이어붙이는 코드를 직접 짜야 했습니다. 이제
verify-runner.mjs에--target옵션을 추가해 검증과 기록이 명령 하나로 끝나도록 고쳤습니다. - 판정 기록이 조용히 사라지는 버그 수정: 판정서 파일 이름에 붙는 순번을 "지금까지 만들어진 파일 개수"로 계산하고 있었는데, 중간 파일이 하나라도 지워지면 이미 있는 번호와 겹쳐서 서로 다른 실행 결과가 파일 1개로 덮어써지며 사라지는 문제가 실제로 발생했습니다. 순번을 "실제로 존재하는 가장 큰 번호 + 1"로 계산하도록 고쳤고, 이 상황을 그대로 재현하는 자동 테스트 2개를 추가했습니다.
- 이 두 수정 덕분에 자동 테스트가 48개 → 50개로 늘었고, 전부 통과합니다.
- 초기 설정(setup), 디자인→코드 생성(pipeline-codegen), 미리보기 화면 자동 생성(preview-route), 실제 브라우저 검증(verify-runner), 판정서 기록(report-writer), 완료 차단 훅(verify-gate)까지 핵심 스크립트를 모두 구현했습니다.
- 실제 Figma 커뮤니티 파일(Coffee Shop Mobile App)의 화면 하나를 읽어 코드로 만들고, 실제 브라우저 검증까지 통과(PASS)하는 전체 과정을 실측으로 확인했습니다.
- 완전히 새로운 대화(세션)에서 설치부터 다시 해봐도 똑같이 동작하는지 확인했습니다(단, 이때는 위 항목의 수정이 있기 전 버전으로 확인한 것이라 — 고쳐진 버전으로 다시 한번 확인하는 절차가 남아 있습니다).
앞으로의 변경 사항은 이 섹션에 날짜순으로 계속 추가됩니다. 전체 개발 이력(내부 감사 기록 포함)의 정본은
.PRD/README.md입니다.
8. 워크플로우
사용자 Claude Code(AI) 이 킷의 코드
│ │ │
│ "이 버튼 코드로 만들어줘" │ │
├──────────────────────▶│ │
│ │ Figma 디자인 읽기 (MCP/커넥터) │
│ │◀── 레이어 구조 · 색상 · 글자 크기 ──┤
│ │ │
│ │ component-map.json에 매핑 기록 │
│ ├───────────────────────────▶│
│ │ │
│ │ shadcn/ui 코드 생성 요청 │
│ ├───────────────────────────▶│
│ │◀── 생성된 .tsx 파일 ────────────┤
│ │ │
│ │ 개발 서버 자동 실행 │
│ │ → 자동화 브라우저(Playwright)로 열기│
│ │ → 접근성 검사(axe-core) │
│ │ → 360px · 768px · 1440px 3종 검사│
│ │◀── PASS 또는 FAIL 판정 ─────────┤
│ │ │
│ ┌───── PASS ─────┐ │ 판정서(runs/·reports/) 기록 │
│ │ "완료" 보고 가능 │◀──┤ │
│ └───────────────┘ │ │
│ ┌───── FAIL ─────┐ │ 최대 3회 자동 재시도 │
│ │ 완료 보고가 │◀──┤ (2연속 FAIL이면 최종 FAIL) │
│ │ 훅으로 차단됨 │ │ │
│ └───────────────┘ │ │
핵심은 마지막 갈림길입니다: PASS 판정서 없이는 "완료"라고 말하는 것 자체를 hooks/verify-gate.mjs가 기계적으로 막습니다. AI가 실수로 잊거나 눈속임하려 해도 소용없습니다.
9. 아키텍처 · 파일/문서 위치
이 킷 저장소 자체의 구조
SoDam-Design-Kit/ ← 이 킷의 저장소(지금 이 README가 있는 폴더)
├── .claude-plugin/
│ ├── plugin.json ← 플러그인 설명서(이름 · 버전)
│ └── marketplace.json ← 마켓플레이스 등록 정보(마켓 이름: sodam)
├── manifest.json ← Claude Desktop용 확장(.mcpb) 설명서 — plugin.json과는 별개 파일 (Phase 3)
├── commands/
│ ├── setup.md ← /sodam-design-kit:setup 명령의 실제 정의
│ ├── pipeline.md ← /sodam-design-kit:pipeline 명령의 실제 정의
│ ├── open.md ← /sodam-design-kit:open 명령의 실제 정의
│ ├── detail-page.md ← /sodam-design-kit:detail-page 명령의 실제 정의 (Phase 3)
│ └── marketing-asset.md ← /sodam-design-kit:marketing-asset 명령의 실제 정의 (Phase 3, og·포스터·배너·명함)
├── hooks/
│ └── verify-gate.mjs ← 완료 차단 로직(FAIL이면 차단)
├── scripts/ ← 실제 동작하는 엔진(전부 Node.js, 목록은 대표 예시 — 전체는 scripts/ 폴더 참조)
│ ├── setup-wizard.mjs
│ ├── pipeline-codegen.mjs
│ ├── detail-page-pipeline.mjs ← 상세페이지 파이프라인 엔진 (Phase 3)
│ ├── preview-route.mjs
│ ├── verify-runner.mjs
│ ├── report-writer.mjs
│ ├── asset-downloader.mjs ← Figma 이미지·아이콘 자동 다운로드 엔진(7일 만료 URL 문제 해결)
│ ├── font-pipeline.mjs ← 한글 폰트 자동 다운로드/설정 엔진
│ ├── visual-regression.mjs ← 화면 변경 자동 감지 엔진
│ ├── ai-generation-log.mjs ← AI 생성 이력 자동 기록 엔진 (Phase 3)
│ ├── marketing-asset-pipeline.mjs ← 마케팅 이미지 자동 생성 엔진 (Phase 3, og·포스터·배너·명함)
│ ├── asset-ledger.mjs ← 라이선스 게이트 확장(이미지·아이콘 자산) + 출처 정리 문서 자동 생성 (Phase 3)
│ └── mcp-server.mjs ← Claude Desktop용 확장 엔진 — 검증 이력 열람 · 재검증 (Phase 3)
├── tests/ ← 자동 테스트(2026-08-20 기준 330개)
├── .PRD/ ← 이 킷의 설계 문서 정본(가장 상세한 근거 자료)
├── CHECKPOINT.md ← 다음에 이어서 할 작업 목록(개발자용, git에는 올라가지 않음)
├── README.md / README.en.md ← 지금 이 문서
└── package.json
대상 프로젝트(코드를 옮겨 넣는 쪽) 안에 생기는 것
/sodam-design-kit:setup을 실행한 대상 프로젝트 폴더 안에는 .design-kit/ 폴더 하나만 새로 생깁니다:
(대상 프로젝트)/.design-kit/
├── config.json ← 화면 크기 · 자동재시도 횟수 등 설정값 (지워도 setup으로 재생성 가능)
├── component-map.json ← 컴포넌트 ↔ Figma 노드 매핑 기록 (지우면 매핑 정보 사라짐 — 주의)
├── product-pages.json ← 상세페이지 템플릿 1개 + 상품 데이터 위치 목록 (Phase 3, /sodam-design-kit:detail-page)
├── runs/*.json ← 실행 기록(기계가 읽는 판정 원본) — git 커밋 대상
├── reports/*.md ← 판정서(사람이 읽는 결과) — git 커밋 대상
└── reports/screenshots/ ← 검증 스크린샷 — 최근 10개 실행분만 자동 보관(오래된 것은 자동 삭제)
위 목록은 대표 예시입니다(Phase 2가 추가한
fonts/·ASSET-LEDGER.csv·.api-token·.lock·.dashboard.json·reports/baseline/등은.PRD/02_DATA_MODEL.md가 정본입니다).
지워도 되는 것:reports/screenshots/(자동 재생성됨). 지우면 안 되는 것:component-map.json(다시 만들려면 Figma를 또 읽어야 하는데, Figma 무료 플랜은 한 달 6회 제한이 있습니다 — 10장 참고).
10. 보안 · 데이터 흐름
과장 없이, 사실만 적습니다.
- 외부로 나가는 것: Figma 서버로의 읽기 요청(사용자 본인의 Figma 로그인 정보로, 사용자가 지정한 디자인 페이지만). 그 외에는 이 킷이 어떤 서버로도 데이터를 전송하지 않습니다. 로그인 정보(토큰 등)는 킷 코드가 직접 저장하지 않고, Claude Code에 이미 연결된 Figma 커넥터/공식 MCP의 기존 로그인을 그대로 사용합니다.
- 로컬(내 컴퓨터)에만 남는 것: 생성된 코드,
.design-kit/안의 설정 · 매핑 · 판정 기록 · 스크린샷 전부. 전부 내 컴퓨터 디스크에만 저장되고 외부로 전송되지 않습니다. - Figma 이미지 주소는 7일 후 만료: Figma가 돌려주는 이미지 · 아이콘 등의 파일 주소는 임시 주소라 7일이 지나면 깨집니다. 이 킷은 코드에 그 임시 주소를 그대로 박아넣지 않고, 즉시 로컬로 내려받아 저장하도록 설계되어 있습니다.
- Figma 무료 플랜 읽기 한도: 사용자 본인 계정이 무료(Starter/View) 플랜이면 한 달에 6회만 Figma 읽기가 허용됩니다(유료 Dev/Full 플랜은 하루 200~600회). 이 킷은 한 번 읽은 정보를
component-map.json에 저장해두고 재사용하는 방식으로 이 한도를 아끼도록 설계되어 있습니다. - 개인정보 · 실제 데이터 금지: 이 킷의 규칙(
.PRD/04_PROJECT_SPEC.md"절대 하지 마" 목록)은 개인정보나 실제 고객 데이터가 담긴 Figma 파일 · 상품 데이터를 연결하는 것을 금지합니다. 디자인 시안 · 상품 데이터 예시는 더미(가짜) 데이터로 만든 것만 사용해야 합니다. - 외부 명령 실행 방식: 개발 서버 실행 등 컴퓨터 명령을 실행할 때, 문자열을 이어붙이는 방식(명령어 주입 위험)이 아니라 인자를 배열로 분리해 실행하는 안전한 방식만 사용합니다.
- 대시보드(
/open)는 내 컴퓨터 안에서만 열림:127.0.0.1(이 컴퓨터 자신을 가리키는 주소)로만 접속되며, 다른 사람이 인터넷을 통해 접속할 수 없습니다. 경로 조작 시도 차단 · 잘못된 요청 차단 · 실행 중 잠금 장치가 함께 구현되어 있고, 실제로 흉내를 내 막히는지 확인했습니다. - 판정서에 민감정보 없음: 판정서 · 실행 기록에는 시크릿(비밀번호 · 토큰)이나 내 컴퓨터의 절대경로가 기록되지 않도록 설계되어 있고, 자동 테스트로 이를 확인하고 있습니다.
- API 키 없음(현재): 이 킷의 현재 버전은 별도의 API 키 · 환경변수가 필요 없습니다. 나중에 유료 이미지 생성 API 등을 붙이는 기능이 추가되면(Phase 3 후반, 아직 계획 단계) 그때는
.env파일로만 관리하도록 설계되어 있습니다.
11. 문제/오류 대처 (트러블슈팅)
| 증상 | 원인 | 해결 방법 | 성공 기준 |
|---|---|---|---|
설치했는데 /sodam-design-kit:setup 명령이 안 보여요 |
Claude Code가 옛날 설정을 그대로 기억하고 있음(캐시) | Claude Code 창을 완전히 닫았다가 다시 켜기(새로고침이 아니라 완전 종료 · 재시작) | 명령을 입력할 때 자동완성 목록에 /sodam-design-kit:setup이 뜸 |
| "완료가 차단됐다"는 메시지가 나와요 | 정상 동작입니다. 검증 게이트가 FAIL을 감지하면 "완료"라고 보고하는 것을 의도적으로 막습니다 | .design-kit/reports/의 최신 판정서를 열어 실패 사유를 확인 → 재시도 또는 사람이 직접 확인 |
판정서에 실패 사유가 구체적으로 적혀 있음 |
| 게이트 FAIL이 계속 반복돼요 | 자동 재시도(최대 3회)로도 못 고치는 문제일 수 있음 | 판정서의 실패 사유(접근성 위반 항목 · 콘솔 에러 메시지)를 사람이 직접 읽고 원인 확인. gateEnabled 값은 사용자 본인이 .design-kit/config.json에서 직접 바꿀 때만 변경 |
재시도 후 PASS로 바뀌거나, 사람이 원인을 파악함 |
| Figma 연결이 안 되거나 읽기가 부족해요 | Figma 커넥터 로그인이 끊겼거나, 공식 MCP 전환이 필요할 수 있음 | 커넥터 로그인 상태 확인 → 필요 시 공식 원격 MCP(mcp.figma.com/mcp)로 전환 |
Figma 읽기 요청이 정상적으로 결과를 돌려줌 |
내 컴퓨터에 저장된 .fig 파일이 안 읽혀요 |
Figma 커넥터 · MCP는 Figma 계정에 저장된 파일만 읽을 수 있고, 로컬 파일을 직접 읽지 못함 | Figma 데스크톱 앱에서 그 파일을 열어 계정에 저장한 뒤, 공유 링크를 사용 | 공유 링크로 정상 읽힘 |
| shadcn 또는 Playwright(검증용 자동화 브라우저)가 설치되어 있지 않다고 나와요 | 대상 프로젝트에 shadcn/ui가 없거나, 이 킷 저장소에서 npm install을 안 함 |
shadcn 미설치면 npx shadcn init 실행 여부를 물어보는 안내를 따르고, Playwright 문제면 이 킷 저장소 폴더에서 npm install 재실행 |
안내된 설치가 끝난 뒤 명령이 정상 실행됨 |
| 검증할 때 포트(주소)가 충돌한다고 나와요 | 이미 다른 프로그램이 같은 포트를 쓰고 있음 | 사용자가 직접 조치할 필요 없음 — 이 킷이 자동으로 다음 포트를 찾아 우회하도록 설계되어 있음 | 별도 조치 없이 검증이 계속 진행됨 |
Windows에서 --route /...처럼 /로 시작하는 옵션을 직접 입력했더니 이상한 결과가 나와요 |
Git Bash(MSYS) 환경에서 /로 시작하는 값이 파일 경로로 잘못 바뀌는 환경 문제(이 킷의 코드 결함 아님, 개발자용 참고) |
PowerShell을 사용 | 정상적인 검증 결과가 나옴 |
| 한글이 깨지거나 네모(□)로 보여요 | 프로젝트에 아직 한글 폰트가 설정되지 않음 | 개발자에게 font-pipeline 기능(Pretendard 등 자동 설정)을 요청 — 일반 사용자는 셋업/파이프라인 절차만 그대로 따르면 됩니다 |
화면에 정상적인 한글이 보임 |
대시보드(/open)가 안 켜지거나 화면이 비어 있어요 |
이미 다른 인스턴스가 열려 있거나, 이 킷 저장소에서 npm install을 안 함 |
/sodam-design-kit:open --stop으로 한 번 끈 뒤 다시 실행. 그래도 안 되면 npm install 재실행 |
브라우저에 판정서 목록이 정상적으로 보임 |
| 명령 입력이 익숙하지 않아요 | 컴퓨터 · 채팅형 도구가 처음이라 그럴 수 있습니다 | 0장 용어 사전을 먼저 읽고, 4장 빠른 시작을 한 줄씩 그대로 따라 입력해보세요 | 4장의 각 단계마다 적힌 "성공 기준"이 그대로 나타남 |
12. FAQ (자주 묻는 질문)
Q. 코딩을 전혀 몰라도 쓸 수 있나요?
A. 명령을 실행하는 것 자체는 슬래시 명령 몇 개(/sodam-design-kit:setup, /sodam-design-kit:pipeline 등)만 알면 됩니다. 다만 "대상 프로젝트"(Next.js+Tailwind+shadcn/ui)는 누군가 미리 준비되어 있어야 합니다. 나머지는 전부 자연어로 AI에게 요청하면 됩니다.
Q. 컴퓨터 · 메신저 · AI를 정말 처음 써보는데 시작할 수 있나요?
A. 0장 용어 사전을 먼저 읽고 4장 빠른 시작을 그대로 따라 입력해보시길 권합니다. 다만 정직하게 말씀드리면, 이 킷은 "개발 도구"라서 Node.js 설치 · 터미널 사용처럼 컴퓨터를 어느 정도 다뤄야 하는 부분이 남아있습니다 — 완전한 비전공자 혼자보다는, 이미 준비된 프로젝트(2장 준비물 3번)를 옆에서 도와줄 사람이 한 명 있으면 훨씬 수월합니다.
Q. Figma 유료 플랜이 꼭 필요한가요?
A. 아니요, 무료(Starter) 플랜으로도 됩니다. 다만 한 달에 6회만 읽을 수 있는 제한이 있습니다(10장 참고). 이 킷은 한 번 읽은 내용을 저장해두고 재사용하도록 만들어져 있어 이 한도 안에서도 여러 번 파이프라인을 돌릴 수 있습니다.
Q. 검증이 실패(FAIL)하면 제 코드가 잘못된 건가요?
A. 꼭 그런 건 아닙니다. 접근성 규칙 위반, 콘솔 에러, 화면 렌더링 실패 등 여러 이유가 있을 수 있고, 판정서에 구체적인 이유가 남습니다. 실패도 "이 킷이 정상적으로 검사하고 있다"는 증거입니다.
Q. 생성된 코드를 제가 마음대로 고쳐도 되나요?
A. 네, 생성된 코드는 사용자의 프로젝트 파일이 되므로 자유롭게 수정할 수 있습니다. 단, 다시 파이프라인을 돌리면 재검증이 이루어집니다.
Q. 이 킷을 상업적으로 써도 되나요? 다른 사람에게 나눠줘도 되나요?
A. 네, Apache License 2.0 조건을 지키면 가능합니다(2026-08-09 확정) — 라이선스 사본 동봉, 수정 사실 표시, 원저작물 고지 유지가 조건입니다. 단 "SoDam-Design-Kit" 이름 · 상표 자체를 쓸 권리는 포함되지 않습니다. 자세한 내용은 13장을 반드시 읽어보세요.
Q. 이 킷으로 만든 결과물(상세페이지 · 코드)을 팔거나 고객사에 납품해도 되나요?
A. 이 킷 자체의 라이선스는 그것을 막지 않습니다. 다만 원본 Figma 디자인의 저작권, 상품 데이터의 출처, AI 생성 코드/문구의 법적 지위는 이 킷과 별개의 문제이며 전적으로 사용자 책임입니다 — 13장에서 각각 자세히 설명합니다.
Q. Windows/Mac/Linux 다 되나요?
A. 이 킷은 Node.js 스크립트로 만들어져 있어 이론적으로 셋 다 실행 가능하지만, 지금까지 실제로 상세하게 검증된 환경은 Windows입니다(개발 · 테스트 환경). Mac/Linux에서의 실측 검증은 아직 이루어지지 않았습니다.
Q. 이 킷은 안정적인 정식 버전인가요?
A. 아니요. 현재 버전은 **0.3.0(정식 출시 전)**입니다. 핵심 기능(Phase 1 · Phase 2 · Phase 3 대부분)은 실제 프로젝트로 왕복 검증까지 마쳤지만, 명령어 이름이나 세부 동작이 앞으로 바뀔 수 있습니다. 중요한 프로젝트에 쓰기 전에는 CHECKPOINT.md와 7장에서 최신 상태를 먼저 확인하는 것을 권장합니다.
13. 법률 · 저작권 · 라이선스 · 상업적 용도
⚠️ 가장 먼저 읽어야 할 요약: 이 킷 자체는 상업적 이용 · 재배포가 가능합니다(Apache License 2.0). 하지만 이 킷으로 "만들어낸 결과물"(코드 · 문구 · 이미지)에 대한 법적 책임은 별개이며, 전적으로 사용자 본인의 책임입니다. 이 섹션은 법률 자문이 아니며 법적 효력을 보장하지 않습니다. 확정되지 않은 사항은 아래에 "미정"으로 명확히 구분해 표시했습니다. 상업적 이용 · 재배포 · 법적 판단이 필요한 경우 반드시 변호사 등 전문가의 확인을 받으시기 바랍니다.
이 킷(SoDam-Design-Kit) 자체의 라이선스 — Apache License 2.0 (2026-08-09 확정)
- 현재 상태(확인된 사실): 이 저장소 최상위에
LICENSE파일(Apache License 2.0 전문)이 있습니다. 저작권자는 SoDam AI Studio, 연도는 2026년입니다. - 이것이 의미하는 것: Apache License 2.0은 코드 · 문서의 사용 · 복제 · 수정 · 재배포 · 상업적 이용을 허용하는 permissive(허용적) 라이선스입니다. 단, 라이선스 사본을 함께 배포해야 하고, 수정한 파일에는 변경 사실을 표시해야 하며, 원저작물의 저작권 · 특허 · 상표 고지를 유지해야 합니다(라이선스 전문 4조 참고). "SoDam-Design-Kit"라는 이름 · 상표에 대한 권리는 이 라이선스에 포함되지 않습니다(라이선스 전문 6조 — 상표 조항).
- NOTICE 파일은 별도로 두지 않습니다(신규 저작물이라 승계할 상위 NOTICE가 없다고 판단).
- 책임 제한 · 보증 없음(라이선스 전문 7 · 8조): 이 킷은 "있는 그대로(AS IS)" 제공되며, 특정 목적에의 적합성이나 오류 없음을 보증하지 않습니다. 이 킷을 사용해 발생하는 모든 손해(직접 · 간접 · 특수 · 부수적 손해 포함)에 대해 제작자는 책임지지 않습니다.
해서는 안 되는 것 (엄격 기준 — 명확히 금지)
- ❌ "SoDam-Design-Kit"라는 이름 · 로고를 자신이 만든 것처럼 다시 배포하는 행위 (라이선스가 코드 사용은 허용해도 이름 · 상표권까지 주지는 않습니다)
- ❌ 저작권 · 라이선스 고지,
LICENSE파일을 삭제하거나 가리고 재배포하는 행위 - ❌ 수정한 파일에 변경 사실을 표시하지 않고 원본인 것처럼 재배포하는 행위
- ❌ 타인의 Figma 디자인을 정당한 권한 없이 읽어와 상업적으로 사용하는 행위(디자인 원본의 저작권은 이 킷과 무관하게 그 디자인을 만든 사람에게 있습니다)
- ❌ 개인정보 · 실제 고객 데이터가 담긴 Figma 파일 · 상품 데이터를 이 킷에 연결하는 행위(10장 참고)
이 킷이 사용하는 오픈소스 구성요소(의존성) 라이선스 — 실측 확인됨
이 킷 자체의 라이선스와 별개로, 이 킷이 검증 기능을 위해 내부적으로 사용하는 오픈소스 라이브러리들은 각자의 라이선스를 따르며, 이 킷은 이들을 수정하지 않고 그대로(설치 의존성으로만) 사용합니다.
| 구성요소 | 라이선스 | 용도 |
|---|---|---|
| Playwright / playwright-core | Apache License 2.0 (실측 확인됨) | 자동화 브라우저로 화면을 실제로 확인 |
| axe-core / @axe-core/playwright | Mozilla Public License 2.0 (실측 확인됨) | 접근성(장애인 사용성) 자동 검사 |
| pixelmatch | ISC License (실측 확인됨) | 화면 변경 자동 감지의 픽셀 단위 이미지 비교 |
| pngjs | MIT License (실측 확인됨) | 화면 변경 자동 감지용 PNG 이미지 읽기/쓰기 |
| satori | Mozilla Public License 2.0 (실측 확인됨) | 마케팅 이미지 소재(OG 이미지 등)의 텍스트 레이아웃을 SVG로 렌더링(Phase 3) |
| sharp | Apache License 2.0 (실측 확인됨) | 마케팅 이미지 소재를 SVG에서 PNG로 변환(Phase 3) |
| @modelcontextprotocol/sdk | MIT License (실측 확인됨) | Claude Desktop용 확장(MCP) 공식 SDK(Phase 3) |
| zod | MIT License (실측 확인됨) | MCP 도구 입력값 형식 검증(Phase 3) |
이 라이선스들은 이 킷의 라이선스와 무관하게 각 프로젝트가 독자적으로 부여한 것이며, 각 구성요소를 직접 사용하고 싶다면 해당 프로젝트의 원문 라이선스를 확인해야 합니다.
간접 의존성까지 포함한 전체 126개 패키지 라이선스 전수 감사 (2026-08-21)
위 표는 이 킷이 직접 설치하는 8개 패키지만 다룹니다. 이 8개가 각자 데려오는 간접 의존성까지 포함하면 실제로는 126개 패키지가 설치되는데, 이 126개 전체를 확인한 적은 이번이 처음입니다. ScanCode Toolkit(표준 라이선스 스캐너)을 쓰려 했으나 이 도구는 Python 3.12 이하만 지원해 이 환경의 Python 3.14와 호환되지 않았고, 같은 목적을 Node.js로 직접 구현해(모든 패키지의 package.json의 license 필드 전수 대조) 확인했습니다.
| 라이선스 | 패키지 수 |
|---|---|
| MIT | 103 |
| ISC | 10 |
| Apache-2.0 | 4 |
| MPL-2.0 | 3 |
| BSD-3-Clause | 2 |
| Apache-2.0 AND LGPL-3.0-or-later (일부 MIT 포함) | 2 |
| BSD-2-Clause | 1 |
| 0BSD | 1 |
- license 필드가 없는 패키지: 0개
- GPL · AGPL 등 강한 카피레프트 라이선스: 0개
- 주의가 필요해 별도로 기록하는 발견 1건: 위 표의
sharp가 함께 설치하는 플랫폼별 네이티브 바이너리 패키지 2개(@img/sharp-win32-x64,@img/sharp-wasm32)가 LGPL-3.0-or-later를 포함합니다(내부적으로libvips라이브러리를 동적으로 링크하기 때문). 법적으로 문제는 없습니다 — LGPL은 코드를 직접 복사·수정하지 않고 "동적으로 링크"만 하는 경우 그 라이선스가 링크하는 프로그램 전체로 전이되지 않는 것을 명시적으로 허용하며, 이 킷은sharp를 수정 없이 설치 의존성으로만 사용하므로 이 조건에 해당합니다.
이 킷이 자동으로 다운로드하는 폰트의 라이선스
7장의 "한글 폰트 자동화" 기능은 오픈소스 폰트 라이선스인 **OFL(SIL Open Font License)**을 따르는 폰트(Pretendard, Noto Sans KR)만 화이트리스트로 미리 정해두고 자동으로 내려받습니다. OFL은 폰트를 수정 · 재배포 · 상업적 이용하는 것을 허용하지만, 폰트 파일 자체를 단독으로 재판매하는 것은 금지합니다. 다운로드한 폰트 각각의 라이선스 근거는 대상 프로젝트의 ASSET-LEDGER.csv에 자동 기록됩니다.
Figma 디자인 데이터에 대한 책임
이 킷은 사용자 본인의 Figma 계정으로 사용자가 직접 접근 권한을 가진 디자인만 읽으며, Figma 디자인 데이터 자체를 재배포하거나 저장 · 전송하지 않습니다. 다만 읽어온 디자인을 코드로 옮겨서 사용할 권리(저작권)가 있는지는 전적으로 사용자의 책임입니다 — 디자인 원본의 저작권은 그 디자인을 만든 사람(또는 조직)에게 있으며, 이 킷이 그 권리 관계를 대신 확인하거나 보장하지 않습니다.
상품 데이터 · AI가 작성한 카피(문구)에 대한 책임 (Phase 3, /sodam-design-kit:detail-page)
이 기능이 만드는 상세페이지 카피(제목 · 설명 · 자주 묻는 질문 등)는 사용자가 입력한 상품 데이터를 근거로 AI가 작성합니다. 상품 정보의 사실 정확성 · 과장 광고 여부 · 표시 · 광고에 관한 법률(예: 전자상거래법, 표시 · 광고의 공정화에 관한 법률 등) 준수 여부는 이 킷이 판단하지 않으며, 실제로 그 문구를 상업적으로 게시하기 전에는 반드시 사용자가 직접 사실 확인과 검토를 거쳐야 합니다.
AI가 생성한 코드 · 문구에 대한 책임
이 킷이 생성하는 코드와 카피(문구)는 Claude(AI)가 만든 것입니다. AI 생성물의 저작권 귀속 · 보호 범위는 국가마다 법 해석이 다르고 아직 확립되지 않은 영역입니다. 생성된 코드 · 문구를 상업적으로 사용하기 전에는 사용자 본인의 책임 하에 필요 시 전문가 확인을 받으시기 바랍니다. 이 킷과 그 문서는 이에 대해 어떠한 법적 보장도 하지 않습니다.
요약 표 (Apache License 2.0 기준)
| 행위 | 현재 허용 여부 |
|---|---|
| 제작자 본인이 개인적으로 사용 | ✅ 가능 |
| 코드를 수정해서 나 혼자/우리 팀 내부용으로 쓰기 | ✅ 가능 |
| 제3자에게 이 킷 자체를 배포 · 복사해서 나눠주기 | ✅ 가능 — 라이선스 사본 동봉 + 수정 사실 표시 필요 |
| 이 킷을 활용한 유료 서비스 · 상품 판매 | ✅ 가능 — 위 조건 동일 적용 |
| 회사 · 고객사에 이 킷을 납품 | ✅ 가능 — 위 조건 동일 적용 |
| "SoDam-Design-Kit" 이름 · 상표를 그대로 써서 배포 | ❌ 금지 — 라이선스가 코드 사용은 허용하지만 이름 · 상표권까지 부여하지 않음 |
| 저작권 · 라이선스 고지를 지우고 재배포 | ❌ 금지 (라이선스 위반) |
| 이 킷이 생성한 코드 · 카피를 내 프로젝트 · 상품에서 쓰기 | ✅ 가능 — 단, 원본 Figma 디자인의 저작권 · 상품 정보의 사실 정확성 확인은 사용자 책임 |
| 타인의 Figma 디자인을 무단으로 가져와 상업적으로 사용 | ❌ 이 킷의 라이선스와 무관하게, 원 디자인 저작권자의 권리 침해가 될 수 있음(사용자 책임) |
| 이 킷이 내부적으로 쓰는 오픈소스(Playwright · axe-core · pixelmatch · pngjs · satori · sharp · @modelcontextprotocol/sdk · zod)를 별도로 직접 쓰기 | ✅ 각 프로젝트의 라이선스(Apache-2.0 / MPL-2.0 / ISC / MIT)를 따르면 가능 |
| 이 킷이 자동 다운로드하는 폰트(Pretendard 등)를 폰트 파일 자체로 재판매 | ❌ 금지 (OFL 라이선스 위반) |
책임 제한 · 보증 없음: 이 킷과 문서는 "있는 그대로(as-is)" 제공되며, 특정 목적에의 적합성이나 오류 없음을 보증하지 않습니다. 사용으로 인해 발생하는 모든 결과에 대한 책임은 사용자 본인에게 있습니다.
부록: 전체 설계 문서
이 문서에 담지 못한 더 상세한 사양 · 결정 근거 · 개발 이력은 .PRD/ 폴더가 정본입니다:
01_PRD.md— 무엇을 왜 만드는지, UI/UX · 보안 · 법률 · 문서화 · 성공 기준02_DATA_MODEL.md— 데이터 구조(config.json 등 파일 스키마)03_PHASES.md— 단계별(Phase 1/2/3) 개발 계획과 현재 진행 상태04_PROJECT_SPEC.md— 기술 스택, 절대 규칙(하지 말 것/항상 할 것).PRD/README.md— 개발 과정 전체 감사(audit) 이력CHECKPOINT.md— 다음에 이어서 해야 할 작업 목록(개발자용)
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi