"기획서는 피그마에 있습니다" | 따로 문서 만들지 않는 피그마 스펙(Spec) 작성법
"기획서는 피그마에 있습니다" - 따로 문서 만들지 않는 '피그마 스펙' 작성법
피그마에서 화면을 수정하면 노션 기획서 스크린샷도 다시 찍고, 정책도 고치고, 링크도 갈아끼우고… 이건 기획이 아니라 복붙(CTRL+C/CTRL+V) 올림픽입니다. 🥲
이제 화면과 기획서를 분리하지 마세요. 피그마를 단순한 디자인 툴이 아니라 살아있는 기획서(Spec)로 만드는 방법을 정리했습니다. 목표는 하나, 팀원이 묻기 전에 파일이 답하게 만들기입니다.
1) 왜 '피그마 네이티브' 기획서인가?
화면과 정책이 한곳에 모이면 협업 효율이 확 올라갑니다. 피그마 네이티브 기획서의 핵심 가치는 아래 3가지입니다.
- Single Source of Truth: "어디가 최신이에요?" 질문이 사라집니다.
- 맥락 유지: 기능을 보면서 바로 옆에서 정책을 읽으면 오해가 줄어듭니다.
- 업데이트 부담 감소: 화면이 바뀌면 기획서도 사실상 같이 바뀝니다. (스크린샷 재촬영 지옥 탈출)
한 줄로 요약하면 이겁니다. 기획은 문서가 아니라 ‘정합성’입니다. 정합성이 유지되는 장소에 스펙을 두면, 팀 전체가 편해집니다.
2) 따로 문서 만들지 않는 3가지 레이아웃 전략
전략 A. 화면 옆 '정책 블록(Policy Block)' 배치하기
화면(와이어프레임/GUI) 오른쪽에 텍스트 블록을 붙여 “스펙 박스”를 만듭니다. 핵심은 글을 잘 쓰는 게 아니라, 형식을 통일하는 것입니다.
추천 포맷 (복붙용)
[Input]
- 허용: 숫자만
- 길이: 11자
- 포맷: 하이픈 자동 삽입 여부(Yes/No)
[Action]
- CTA: "저장"
- 성공: 토스트 + 이전 화면 데이터 갱신
- 실패: 에러 메시지 위치(필드 하단/상단 배너)
[Exception]
- Empty: 데이터 0건 시 CTA 노출
- Error: 네트워크 실패 시 Retry/Home 제공
전략 B. 흐름은 “파일 밖”이 아니라 “파일 안”에서 보여주기
복잡한 분기(로그인 여부, 권한, 실패 처리)는 화면 위에서 한눈에 보이는 편이 좋습니다. 사용자 흐름 다이어그램은 FigJam 커넥터로 빠르게 만들고, 최종 화면 스펙이 있는 Figma Design 파일과 링크로 연결하면 “문서 분산”이 줄어듭니다.
분기 라벨 예시
[A 버튼 클릭] → [로그인 여부 확인]
├─ YES → 홈 이동
└─ NO → 로그인 오버레이
전략 C. 위젯(Widget)과 컴포넌트로 “상태”를 표준화하기
스펙 파일이 커질수록 중요한 건 “내용”보다 “표지판”입니다. 아래 요소를 컴포넌트(또는 위젯)로 만들어두면 팀원들이 길을 덜 잃습니다.
- Status Badge: Draft / In Review / Final
- Note: 정책 변경 메모, 의사결정 결과 1줄 기록
- Changelog: 수정 날짜 + 변경 요약(최대 3줄만)
상태 배지는 컴포넌트 속성(Component properties)으로 토글/스왑이 가능하게 만들면 유지보수가 쉬워집니다. 위젯은 파일 안에서 모두가 볼 수 있는 오브젝트로 동작하므로, “공유되는 표지판” 역할에 적합합니다.
3) 개발자가 읽기 편한 스펙 기술 가이드 (Data/Logic/Interaction/Edge)
피그마 스펙은 ‘장문 에세이’가 아니라 ‘구현 가능한 규칙표’입니다. 아래 4가지 카테고리로만 정리해도, 개발자가 필요한 정보를 빠르게 찾습니다.
| 구분 | 작성 요령 | 예시 |
|---|---|---|
| Data | API로 불러올 데이터 필드와 표시 규칙을 명시 | nickname, profileImage, pointBalance(0이면 0원 표기) |
| Logic | 정렬/필터/활성 조건처럼 “분기 조건”을 문장으로 고정 | 필수값 모두 유효할 때만 저장 버튼 Enabled |
| Interaction | 클릭/스와이프/롱프레스 등 트리거와 결과를 1:1로 매칭 | 카드 클릭 → 상세 이동(id 전달), 뒤로가기 → Back |
| Edge Case | Empty/Error/Overflow(말줄임) 같은 실패 시나리오를 반드시 포함 | 제목 2줄 초과 시 ellipsis, 네트워크 오류 시 Retry 제공 |
스펙 문장 공식(아주 유용한 주문)
When(조건): ______ 일 때
Then(행동): ______ 를 보여준다/막는다/이동한다
Where(위치): ______ 에 노출한다
4) Dev Mode로 스펙을 '링크+주석+상태'로 완성하기
“기획서는 피그마에 있다”를 현실로 만드는 핵심은 Dev Mode입니다. Dev Mode에서는 개발자가 측정/속성/리소스를 확인하고, 기획자는 스펙을 레이어에 붙여 고정할 수 있습니다.
4-1. Annotation(주석)으로 정책을 레이어에 붙이기
화면 옆 텍스트도 좋지만, 핵심 규칙은 해당 레이어에 직접 붙여야 놓치지 않습니다. 주석은 Design/Dev Mode에서 추가할 수 있고, 텍스트뿐 아니라 속성(Property)도 함께 넣을 수 있습니다.
[Rule]
- 숫자만 입력
- 11자 미만이면 Disabled
[Edge]
- Empty: CTA 노출
- Error: Retry/Home 제공
4-2. Dev resources로 “외부 문서”는 링크로만 연결하기
피그마에 모든 것을 다 적으면 화면이 지저분해질 수 있습니다. API 명세, 법무 고지, 긴 정책 문서는 Dev resources 링크로 연결하세요. 특히 컴포넌트에 Dev resource를 추가하면 해당 컴포넌트의 인스턴스가 링크를 상속할 수 있어, 공통 요소의 문서를 한 번에 묶기 좋습니다.
추천 링크 분배
- 섹션: 기능 정책 노션 링크
- 프레임: Jira 구현 티켓
- 컴포넌트: Storybook/GitHub 경로
4-3. 섹션(Section)으로 “여기까지 확정”을 표시하기
섹션은 캔버스의 영역을 묶는 최상위 단위라, 스펙 파일의 가독성을 크게 올립니다. 또한 섹션은 개발 핸드오프를 위해 Ready for development로 표시할 수 있어, 팀원이 “어디부터 보면 돼요?”를 묻지 않아도 됩니다.
섹션 네이밍 규칙 예시
🟢 [Final] 주문서(결제) - 전달완료_2026-02-17
🟡 [Review] 쿠폰 적용 - 논의 필요(정책)
🔴 [Draft] 결제 실패 - 케이스 추가 필요
5) 피그마 스펙이 지저분해지지 않게 만드는 정리 규칙
- 한 화면당 “정책 블록 1개”: 스펙이 늘어나면 링크로 넘기기
- 주석은 핵심 레이어에만: 모든 레이어에 붙이면 Dev Mode가 과밀해집니다
- 변경 이력은 3줄 제한: 장문은 Jira/노션으로, 피그마는 “현재 상태” 중심
- 상태 표지판을 컴포넌트화: Draft/Review/Final을 손으로 쓰지 말기
- 흐름은 FigJam, 스펙은 Figma Design: 역할을 분리하면 파일이 덜 무거워집니다
6) 공유 전 5분 점검 체크리스트
- 최신 화면이 맞는가? (중복 프레임, 옛 버전 섞임 제거)
- Data/Logic/Interaction/Edge가 최소 1줄씩은 있는가?
- Empty/Error의 “복구 동선”(Retry/Home/Back)이 존재하는가?
- 길게 설명해야 하는 내용은 Dev resources 링크로 연결했는가?
- 섹션 상태(🟢🟡🔴)와 Ready for development 표시가 실제 상태와 일치하는가?
이 체크리스트를 통과하면, 팀원들은 “기획서 어디 있어요?” 대신 “피그마 링크 하나면 되네요”라고 말하게 됩니다. (그리고 기획자는 조용히 미소를 짓습니다.)
FAQ
Q 피그마에 스펙을 다 넣으면 너무 지저분해지지 않나요?
A 그래서 “정책 블록 1개 + 핵심 레이어 주석 + 나머지는 Dev resources 링크” 3단 구조가 중요합니다. 피그마에는 핵심 규칙만 남기고, 긴 문서는 링크로 연결하세요.
Q 주석(Annotation)은 어디에 붙이는 게 가장 효과적인가요?
A 개발자가 클릭할 가능성이 높은 레이어에 붙이는 게 좋습니다. 예: CTA 버튼, 입력 필드, 에러 메시지 영역, Empty CTA 영역.
Q Dev resources 링크는 컴포넌트에 붙이는 게 좋은가요?
A 공통 컴포넌트라면 컴포넌트에 붙이는 편이 효율적입니다. 컴포넌트에 추가한 Dev resource는 인스턴스가 상속할 수 있어 “한 번 붙이고 끝”이 됩니다.
Q 흐름(분기)은 Figma Design에서 그리면 안 되나요?
A 간단한 이동은 프로토타입 연결로도 충분하지만, 다이어그램 형태의 커넥터 흐름은 FigJam이 더 편합니다. 흐름을 FigJam에서 확정하고, 스펙은 Figma Design에서 고정하는 식으로 역할을 나누면 관리가 쉬워집니다.
Q 상태 배지(Status Badge)는 어떻게 만들면 좋나요?
A 배지를 컴포넌트로 만들고, 컴포넌트 속성(Component properties)으로 Draft/Review/Final을 토글하는 방식이 깔끔합니다. 팀이 자주 쓰는 “표지판”일수록 컴포넌트화가 정답입니다.