커뮤니케이션의 완성: 데브 모드(Dev Mode)를 활용한 친절한 기획서 작성법
커뮤니케이션의 완성: 데브 모드(Dev Mode)를 활용한 친절한 기획서 작성법
기획자가 피그마에서 화면 설계를 마쳤다고 해서 기획이 끝난 건 아닙니다. 진짜 완성은 개발자가 내 의도를 100% 이해하고 구현에 착수하는 순간에 옵니다.
이제는 PPT/노션에 캡처를 붙여 설명하지 않아도 됩니다. 피그마의 데브 모드(Dev Mode)와 몇 가지 장치만으로도 충분히 ‘친절한 기획서’를 만들 수 있어요.
1) Dev Mode, 기획자가 왜 알아야 할까?
Dev Mode는 개발자가 디자인을 코드로 옮기기 쉽게 돕는 환경입니다. 기획자가 이 환경을 이해하면 “전달”이 아니라 “구현 시작”을 만들어낼 수 있습니다.
- 정확한 데이터 전달: 텍스트 속성(크기, 행간, 자간)과 간격을 개발자가 직접 확인
- 불필요한 커뮤니케이션 감소: “이 버튼 높이 몇인가요?” 같은 확인 질문이 급감
- 에셋 추출 최적화: 아이콘/이미지 소스를 별도 전달하지 않아도 개발자가 확인 및 추출
한 줄 결론: Dev Mode는 “개발자 관점의 최종 납품 포맷”입니다.
2) 친절한 기획서의 뼈대: 3단 구조(상태-주석-링크)
Dev Mode 기반 기획서는 아래 3가지만 갖추면, 문서가 얇아져도 오해가 줄어듭니다.
- 상태(Ready): 어디가 개발 가능한 범위인지 표시
- 주석(Annotation): 로직/예외/조건을 레이어에 고정
- 링크(Dev resources): Jira/Notion/정책 문서를 “해당 레이어”에 연결
이 3단 구조는 “회의에서 말로 하던 것”을 “파일 안에 고정”시키는 장치입니다.
3) 섹션(Section)과 Ready for dev로 “여기부터 개발하세요” 표시하기
3-1. 섹션으로 작업 구역을 묶고, 상태를 이름에 넣기
- 🟢 완료: [결제] 주문서 화면(완료)
- 🟡 수정 중: [마이] 프로필 편집(수정 중)
- 🔴 논의 필요: [검색] 필터 정책(논의 필요)
3-2. Ready for dev로 ‘개발 시작점’을 공식 표시하기
섹션/프레임/컴포넌트에 Ready for dev 상태를 붙이면 개발자는 Dev Mode에서 Ready for dev view로 “준비된 영역만” 빠르게 확인할 수 있습니다.
추천 운영 규칙(팀 합의용)
- Ready for dev는 “디자인 확정”이 아니라 “개발 착수 가능” 기준으로 표시
- Ready 표시 후 변경이 생기면: 상태는 유지하되, 변경 내용은 주석으로 남기기
- 표시 단위는 “섹션 1개 = 기능 1개”가 가장 관리가 쉬움
4) Annotation(주석)으로 ‘로직’을 레이어에 직접 고정하기
화면 옆 텍스트 박스는 잘 놓칩니다. Annotation은 레이어에 붙어서, 개발자가 요소를 클릭할 때 같이 따라오는 설명이 됩니다.
4-1. 주석 문법을 짧고 단단하게 통일하기
[Rule] 입력 규칙
- 숫자만 입력 가능
- 최대 11자
- 11자 미만이면 버튼 Disabled
[API] 호출/응답
- GET /users/me 성공: 프로필 노출
- 실패(401): 로그인 화면 이동
[Edge] 예외
- 데이터 0건: Empty State(CTA: 등록하기)
- 네트워크 오류: Error State(Primary: Retry, Secondary: Home)
[Track] 이벤트(선택)
- click_save_profile
- view_empty_profile
4-2. 주석은 “조건(When) + 행동(Then)”만 적어도 충분하다
개발자가 가장 원하는 건 감상이 아니라 분기 조건입니다. 조건이 명확하면, 화면은 ‘그림’이 아니라 ‘명세’가 됩니다.
5) [추가] 화면 유형별 Annotation 템플릿(목록/상세/폼/결제)
Q1에서 요청한 “화면 유형별 주석 템플릿”입니다. 아래를 그대로 복사해서 섹션 또는 핵심 컴포넌트에 붙이면, Dev Mode에서 바로 먹힙니다.
5-1. 목록(List) 화면 템플릿
[List Screen Template]
[Data]
- Source: GET /items
- Paging: cursor | offset
- Sort: 최신순(default) | 인기순
- Filter: (필요 시) status, category
[States]
- Loading: 스켈레톤 n개 노출(또는 로더)
- Empty: items.length === 0 → Empty State(Primary CTA: 생성/추가)
- Error: timeout/5xx → Error State(Primary: Retry, Secondary: Home)
- Partial: 일부 실패 시 토스트 + 기존 데이터 유지 여부(유지/초기화)
[Interaction]
- Tap Card → Detail 이동(id 전달)
- Pull to refresh: 지원 여부(Yes/No)
[Edge]
- 긴 제목 말줄임 처리(1줄/2줄)
- 이미지 없는 항목: placeholder 사용
5-2. 상세(Detail) 화면 템플릿
[Detail Screen Template]
[Entry]
- Entry params: id (required)
- Entry guards: 로그인 필요(Yes/No), 권한 체크(Owner/Admin)
[Data]
- Source: GET /items/{id}
- Stale 처리: 캐시 사용 여부(Yes/No)
[States]
- Loading: 전체 로딩/영역 로딩(선택)
- Empty: id는 있으나 데이터 없음 → 404 or Empty(정책 결정)
- Error: 5xx/timeout → Error State(Primary: Retry, Secondary: Back)
[Actions]
- Primary CTA: (예: 구매/저장) 조건
- Disabled 조건: (예: 재고 0, 필수 값 미입력)
- Loading: 중복 요청 방지(버튼 disabled + spinner)
[Edge]
- 데이터가 길 때 스크롤 기준(상단 고정/탭 유지)
- 삭제된 항목 접근 시 처리(안내 문구 + Home)
5-3. 폼(Form) 화면 템플릿
[Form Screen Template]
[Validation]
- Field rules:
- phone: 숫자만, 11자, 하이픈 자동 삽입(Yes/No)
- email: 형식 검증, 공백 제거
- Inline error: 필드 하단 표시(문구/색)
- Submit enable:
- allRequiredValid === true 일 때만 Enabled
[Submission]
- POST /submit
- Success: 완료 화면 이동 or 토스트 + 이전 화면 갱신
- Fail:
- 400(검증): 해당 필드로 포커스 이동 + 메시지
- 401(세션): 로그인 유도
- 5xx/timeout: Error State(Retry)
[Data Safety]
- 실패 시 입력값 유지(Yes/No)
- 뒤로가기 시 이탈 확인 모달(Yes/No)
[Edge]
- 키보드 올라올 때 CTA 고정 여부
- 자동완성/붙여넣기 허용 여부
5-4. 결제/구매(Payment) 화면 템플릿
[Payment Screen Template]
[Pre-check]
- 로그인 필수(Yes)
- 결제수단 등록 여부 체크
- 재고/한도/쿠폰 유효성 체크(서버 기준)
[Flow]
- Tap "결제하기"
- Create order: POST /orders
- Pay request: 결제사 호출
- Result:
- Success → 완료 화면 + 영수증/주문내역 링크
- Fail(사용자 취소) → 결제 화면 복귀 + 안내 토스트
- Fail(네트워크) → Error State(Retry) + 중복 결제 방지 정책
[States]
- Loading: 결제 처리 중 화면(뒤로가기 차단 여부 포함)
- Disabled:
- 필수 약관 미동의
- 결제수단 미선택
- Error:
- 401: 로그인 만료 → 로그인 이동 후 복귀 정책
- 409/중복: 이미 처리된 주문 안내 + 주문내역 이동
[Edge]
- 앱 전환/백그라운드 복귀 시 상태 동기화 방식
- 결제 성공 후 새로고침/재진입 처리
핵심: 주석은 “설명”이 아니라 “조건표”입니다. 개발자는 이 조건표를 그대로 코드 분기로 옮깁니다.
6) 컴포넌트 이름/라이브러리 유지가 Dev Mode에서 빛나는 이유
라이브러리 인스턴스를 유지(Detach 지양)하면, 개발자는 Dev Mode에서 “공통 컴포넌트인지, 신규 개발인지”를 더 빨리 판단합니다.
- 변경은 Swap/Properties로: 규격의 변형은 속성 변경으로 해결
- 상태는 Variant로: Default/Disabled/Loading/Error
- 기획자 수정 범위: 텍스트, 스왑, 프로퍼티 변경까지만
7) Dev resources로 Jira/Notion 링크를 “레이어에 붙이는” 방법
Dev resources는 링크를 “문서 어딘가”가 아니라 해당 레이어에 직접 붙입니다. 그리고 메인 컴포넌트에 붙인 링크는 인스턴스에 상속될 수 있어 공통 요소 운영에 특히 유리합니다.
추천 분배 전략
- 섹션: 기능 전체 정책(노션), Epic 개요
- 프레임: 화면별 Jira 스토리(구현 단위)
- 컴포넌트: 공통 요소 코드/스토리북 링크
[Dev resources 연결 예시]
- Section: "결제" → Notion(환불/쿠폰/포인트 정책)
- Frame: "주문서" → Jira: PAY-102(구현 티켓)
- Component: "Button/Primary" → Storybook or GitHub path
8) Variables로 다크모드·다국어까지 Dev Mode에서 확인 가능하게
다크모드/다국어는 화면 복제로 관리하면 금방 무너집니다. Variables의 Modes를 사용하면 같은 화면을 모드 전환으로 검증할 수 있습니다.
- Color 변수 컬렉션: Light/Dark 모드
- 문구 변수 컬렉션: KR/EN 모드(문장 길이 내성 테스트)
- Dev Mode에서 변수 정보를 읽기 전용으로 확인 가능
9) 기획서 퀄리티를 올리는 마지막 1%: 스펙 자동화
Dev Mode만으로 충분히 강력하지만, 팀이 “간격 정보를 표 형태로” 보고 싶다면 스펙 문서화 플러그인을 보조로 사용할 수 있습니다.
- 예: Specs Plugin (간격/스펙 문서화 보조)
운영 팁: 플러그인은 팀 표준이 정해졌을 때만 “마지막 1%”로 얹는 편이 안전합니다.
10) 개발자가 바로 코딩하는 Dev Mode 체크리스트
- 섹션 정리: 기능 단위로 묶고 상태(🟢🟡🔴)를 표시했는가?
- Ready for dev: 개발 착수 가능한 범위를 표시했는가?
- 주석 문법 통일: [Rule]/[API]/[Edge]/[Track]로 작성했는가?
- 화면 유형 템플릿 적용: 목록/상세/폼/결제 중 해당 템플릿을 붙였는가?
- 예외 케이스: Empty/Error/Permission의 트리거와 복구 동선이 있는가?
- 라이브러리 유지: Detach 없이 인스턴스를 유지했는가?
- Dev resources 링크: 섹션/프레임/컴포넌트에 링크를 분배했는가?
- Variables 모드: 라이트/다크, KR/EN 전환 시 깨지는 구간이 없는가?
한 줄 메시지: 기획서는 예쁜 그림이 아니라, 약속된 설명서입니다.
결론
Dev Mode는 기획자와 개발자 사이의 거리를 확 줄여주는 도구입니다. Ready for dev로 시작점을 표시하고, Annotation으로 로직을 고정하고, Dev resources로 맥락을 레이어에 붙이면 개발자는 “질문” 대신 “구현”을 시작합니다.
이제 캡처 도구를 내려놓고, 피그마 안에서 소통하는 피그마 네이티브 기획자로 진화해 보세요.
FAQ
Q 주석(Annotation)은 어떻게 추가하나요?
AAnnotation 도구를 선택해 레이어를 지정한 뒤, 텍스트로 메모를 남기거나 ‘Property’를 추가해 속성을 함께 넣을 수 있습니다. (단축키: Shift + T)
Q Ready for dev 표시를 하면 개발자에게 알림이 가나요?
ADev Mode의 상태/알림 기능은 상태 변경을 기반으로 개발자가 디자인 상태에 대응할 수 있게 돕습니다. 팀 요금제/좌석에 따라 제공 범위가 달라질 수 있습니다.
Q Dev resources 링크는 어디까지 붙일 수 있나요?
A캔버스의 모든 레이어에 추가할 수 있고, 메인 컴포넌트에 추가한 링크는 인스턴스에 상속될 수 있습니다. 공통 컴포넌트 운영에 특히 유용합니다.
Q Variables는 Dev Mode에서도 보이나요?
ADev Mode에서 로컬 변수 컬렉션과 모드별 값(라이트/다크 등)을 확인할 수 있으며, 변수 모달은 읽기 전용으로 제공됩니다.
Q 주석을 어느 정도까지 자세히 써야 하나요?
A전부 적지 않아도 됩니다. 개발자가 꼭 물어볼 것만 적으면 충분합니다. 추천 우선순위는 입력 규칙, 분기 조건, Empty/Error 처리, 복구 동선입니다.