| name | design-system-to-figma |
| description | PRD나 스펙 문서를 기반으로 모바일 디자인 시스템을 생성하는 스킬. 디자인 토큰(tokens.css)과 컴포넌트 시스템 HTML을 만든다.
이 스킬은 다음과 같은 요청에 반드시 사용한다: "디자인 시스템 만들어줘", "디자인 토큰 생성", "컴포넌트 시스템", "PRD로 디자인", "/design-system-to-figma", "tokens.css 만들어줘".
기획서가 완성된 후 디자인 단계에 진입하는 맥락이면 이 스킬을 사용한다. HTML 생성이 기본이며, Figma 내보내기는 사용자 요청 시에만 수행.
|
| user_invocable | true |
Figma Design System
목적
PRD/스펙 마크다운 파일을 분석하여 디자인 시스템 HTML을 생성한다. HTML 파일을 로컬 브라우저에서 확인하는 것이 기본 워크플로우이며, Figma 내보내기는 사용자가 명시적으로 요청한 경우에만 수행한다.
사용법
/design-system-to-figma docs/plans/my-app-spec.md
/design-system-to-figma docs/plans/my-app-spec.md https://www.figma.com/design/ABC123/MyApp
- 첫 번째 인자: PRD 파일 경로 (필수)
- 두 번째 인자: Figma URL (선택, 있으면 Figma 내보내기도 수행)
실행 워크플로우
Step 1: PRD 분석
Read 도구로 PRD 마크다운 파일을 읽는다- 앱 성격을 파악하여 primary color 방향을 결정한다:
- 금융/핀테크 → 블루 계열 (
#3182F6)
- 배달/음식 → 오렌지 계열 (
#FF6B00)
- 헬스/운동 → 그린 계열 (
#34C759)
- 소셜/커뮤니티 → 퍼플 계열 (
#7C3AED)
- 커머스/쇼핑 → 레드 계열 (
#FF3B30)
- 생산성/도구 → 인디고 계열 (
#4F46E5)
- 교육/학습 → 틸 계열 (
#0D9488)
- 기본값 → 블루 (
#3182F6)
- 필요한 컴포넌트 유형을 식별한다 (Button, Input, Card, List, Tab, Navigation 등)
Step 2: 디자인 토큰 생성
아래 내장 토큰을 베이스로, Step 1에서 결정한 primary color로 커스터마이징한다.
내장 토큰 기본값:
:root {
--color-primary: #3182F6;
--color-secondary: #F2F4F6;
--color-success: #34C759;
--color-error: #FF3B30;
--color-text-primary: #191F28;
--color-text-secondary: #8B95A1;
--color-bg: #FFFFFF;
--font-family: -apple-system, 'Pretendard', sans-serif;
--text-hero: 26px/1.3;
--text-heading: 20px/1.4;
--text-body: 16px/1.5;
--text-caption: 13px/1.4;
--space-xs: 4px;
--space-sm: 8px;
--space-md: 16px;
--space-lg: 24px;
--space-xl: 32px;
--radius-sm: 8px;
--radius-md: 12px;
--radius-lg: 16px;
--radius-full: 9999px;
}
- PRD 힌트에 따라
--color-primary를 앱 성격에 맞게 변경
Write 도구로 docs/ssot/design/system/tokens.css에 저장
Step 2.5: 디자인 스킬 로드
HTML 생성 전에 반드시 frontend-design 스킬을 호출하여 디자인 원칙과 스타일 가이드를 로드한다:
Skill("frontend-design:frontend-design")
이 스킬이 제공하는 디자인 원칙(여백, 타이포그래피, 색상, 인터랙션 등)을 Step 3의 HTML 생성에 적용한다.
Step 3: 디자인 시스템 HTML 생성
390x844 모바일 프레임(iPhone 14) 기준으로 디자인 시스템 HTML을 생성한다.
HTML 구성 규칙:
- Tailwind CDN (
<script src="https://cdn.tailwindcss.com"></script>) + CSS 변수 스타일링
- 모든 텍스트는 실제 한국어 사용 (Lorem ipsum 절대 금지)
- 배경:
#F8F9FA (시스템 전체 배경)
페이지 섹션 구성:
- Color Palette - Primary, Secondary, Success, Error, Text Primary, Text Secondary, Background
- Typography Scale - Hero(26px), Heading(20px), Body(16px), Caption(13px) 각각 예시 텍스트
- Component Library:
- Button: Primary(filled), Secondary(outlined), Disabled 상태
- Input: Default, Focused, Error, Disabled 상태
- Card: 기본 카드, 리스트 아이템 카드
- List: 단일 행, 아이콘+텍스트 행, 화살표 포함 행
- Tab: 활성/비활성 탭 바
- Navigation: TopBar(뒤로가기+제목+액션), BottomNav(4~5탭)
- Spacing & Radius - xs/sm/md/lg/xl 간격 시각화, sm/md/lg/full 라운딩 시각화
HTML 파일 저장:
Write 도구로 docs/ssot/design/system/design-system.html에 저장- 파일은 단일 HTML (외부 리소스는 CDN만 허용)
Step 4: 로컬 브라우저 확인 (기본)
HTML 파일을 로컬 서버로 띄워 브라우저에서 바로 확인한다.
cd docs/ssot/design/system && python3 -m http.server 8765
사용자에게 안내:
디자인 시스템 HTML이 생성되었습니다.
브라우저에서 확인하세요: http://localhost:8765/design-system.html
HTML 파일을 직접 수정하고 브라우저를 새로고침하면 바로 반영됩니다.
수정이 필요하면 말씀해주세요.
Step 4-F: Figma 내보내기 (선택 - 사용자가 요청한 경우에만)
이 단계는 사용자가 Figma export를 명시적으로 요청한 경우에만 실행한다. 기본 워크플로우는 Step 4에서 종료된다.
4-F-1. Figma URL에서 fileKey 추출
URL 파싱 규칙:
| URL 패턴 | 추출 대상 |
|---|
figma.com/design/:fileKey/:fileName | fileKey |
figma.com/design/:fileKey/branch/:branchKey/:fileName | branchKey |
figma.com/file/:fileKey/:fileName | fileKey |
예시:
https://www.figma.com/design/ABC123/MyApp → fileKey = ABC123https://www.figma.com/design/ABC123/branch/DEF456/MyApp → fileKey = DEF456 (branch)
Figma URL이 없는 경우:
사용자에게 질문한다:
디자인 시스템을 내보낼 Figma 파일 URL을 알려주세요.
(예: https://www.figma.com/design/ABC123/MyApp)
4-F-2. Figma MCP로 내보내기
Phase A: 캡처 시작
ToolSearch로 mcp__figma__generate_figma_design을 로드한 뒤, 파라미터 없이 호출:
mcp__figma__generate_figma_design()
- 도구가 캡처 안내 지침을 반환한다
- 지침에 따라
http://localhost:8765/design-system.html 페이지를 캡처한다
- captureId를 획득한다
Phase B: 폴링
captureId로 5초 간격 폴링 (최대 10회):
mcp__figma__generate_figma_design(
captureId: "{captureId}"
)
- 상태가 완료될 때까지 반복
- 10회 초과 시 사용자에게 타임아웃 알림
Phase C: 파일에 삽입
캡처가 완료되면 기존 Figma 파일에 삽입:
mcp__figma__generate_figma_design(
captureId: "{captureId}",
outputMode: "existingFile",
fileKey: "{fileKey}"
)
4-F-3. 로컬 서버 종료
lsof -ti:8765 | xargs kill -9 2>/dev/null || true
Step 4.5: product-blueprint 자동 업데이트
product-blueprint.html의 디자인 시스템 탭을 자동 업데이트한다. /product-blueprint --tab=디자인시스템 실행.
Step 5: 완료 보고
최종 응답에 반드시 포함:
- 생성된 파일 목록:
- tokens.css 경로:
docs/ssot/design/system/tokens.css
- design-system.html 경로:
docs/ssot/design/system/design-system.html
- 로컬 확인 URL:
http://localhost:8765/design-system.html
- 생성된 컴포넌트 요약: Color, Typography, Button, Input, Card 등
- 다음 단계 안내:
/prd-to-figma로 실제 화면 생성 진행
- Figma 내보내기 안내: "Figma로 내보내려면
/design-system-to-figma 실행 시 Figma URL을 함께 전달하거나, 'Figma로 내보내줘'라고 요청하세요."
- (Figma export 수행한 경우) Figma 파일 링크:
https://www.figma.com/design/{fileKey}
디자인 원칙
frontend-design:frontend-design 스킬에서 제공하는 디자인 원칙을 따른다. Step 2.5에서 로드한 스킬의 가이드라인(여백, 타이포그래피 위계, 색상 사용, 곡선, 그리드 등)을 적용한다.
컴포넌트 상세 규칙
Button:
- Primary:
--color-primary 배경 + 흰색 텍스트, height 52px, radius 12px
- Secondary: 흰색 배경 +
--color-primary 테두리/텍스트, height 48px
- 전체 너비(width: 100%) 기본
Input:
- height 48px, radius 8px
- Default:
#F2F4F6 배경, placeholder #8B95A1
- Focused:
--color-primary 테두리 2px
- Error:
--color-error 테두리 + 하단 오류 메시지
Card:
- 흰색 배경 + radius 16px +
box-shadow: 0 2px 8px rgba(0,0,0,0.04)
- padding 16~20px
TopBar:
- height 56px, 뒤로가기 아이콘(좌) + 제목(중앙) + 액션(우)
- 제목: 18px semibold
BottomNav:
- height 72px (SafeArea 포함)
- 4~5개 탭, 아이콘(24px) + 라벨(11px)
- 활성 탭:
--color-primary, 비활성: #8B95A1
Troubleshooting
generate_figma_design 타임아웃
- 폴링 10회(50초) 초과 시 사용자에게 알림
- 원인: 네트워크 지연 또는 Figma 서버 과부하
- 해결: 잠시 후 captureId로 재시도하거나, HTML 파일을 수동으로 Figma에 임포트
로컬 서버 포트 충돌
Figma MCP 연결 안 됨
ToolSearch로 mcp__figma__generate_figma_design 로드 확인- 도구가 없으면
/mcp 명령으로 MCP 서버 재연결 안내
- Figma 앱이 실행 중이고 MCP 플러그인이 활성화되어 있는지 확인
Figma URL 파싱 실패
- URL 형식이 예상과 다를 경우 사용자에게 fileKey를 직접 질문
figma.com/design/ 또는 figma.com/file/ 패턴만 지원
금지 규칙
- Lorem ipsum / placeholder 텍스트 금지 - 실제 한국어 텍스트 사용
- description 프론트매터에 워크플로우 요약 금지
- 스펙에 없는 컴포넌트를 임의 추가하지 않는다
- 시각적 장식만 늘리고 정보 구조를 흐리게 만들지 않는다
- 외부 이미지/폰트 파일 직접 참조 금지 (CDN만 허용)
