네이밍 컨벤션 — 디자이너와 개발자가 같은 언어로 대화하는 법
솔직히 고백하자면 저도 한동안 레이어 패널이 "Rectangle 45", "그룹 복사본 2", "Frame 123" 같은 이름들로 가득한 채로 작업했어요. 혼자 쓸 땐 큰 문제 없었거든요. 🙈 근데 개발자에게 파일을 넘기는 순간부터 달라졌어요. "이 레이어가 버튼이에요, 배경이에요?" "이 컴포넌트 이름이랑 코드 이름이 다른데 맞는 거예요?" 질문이 쏟아지더라고요.
네이밍은 단순한 정리 습관이 아니에요. 디자이너·개발자·기획자가 같은 단어로 같은 것을 가리킬 수 있게 해주는 공통 언어예요. 오늘은 레이어·컴포넌트·페이지 구조 각각의 네이밍 원칙을 나쁜 예시 vs 좋은 예시로 대비해서 보여드릴게요. BEM, Atomic Design 같은 방법론과의 연결까지요!
왜 네이밍이 이렇게 중요한가요? 🤔
나쁜 네이밍이 실무에서 만들어내는 문제는 크게 세 가지예요.
- 탐색 비용 증가: "이 컴포넌트 어디 있더라?" 하고 레이어 패널을 뒤지는 시간이 쌓이면 하루에 몇십 분이 날아가요.
- 코드-디자인 불일치: Figma에서 "버튼-블루"인데 코드에선
ButtonPrimary예요. 신규 입사자가 무엇을 참조해야 할지 몰라요. - 인수인계 실패: 작업자가 바뀌면 파일을 처음부터 해석해야 해요. "이게 뭐지?" 시간이 온보딩의 절반을 잡아먹어요.
좋은 네이밍의 기준은 딱 하나예요. "이 이름만 보고도 무엇인지 알 수 있는가?" 이름을 보는 사람이 나 자신이 아닌 6개월 뒤의 동료라고 상상하면 대부분의 판단이 쉬워져요.
레이어 네이밍 — 나쁜 예 vs 좋은 예 🗂️
레이어 이름은 Figma에서 Dev Mode로 넘어갈 때 개발자가 가장 먼저 보는 정보예요. 그리고 CSS 클래스명, 컴포넌트명의 기반이 되기도 해요. 나쁜 습관과 좋은 습관을 직접 대비해 볼게요.
❌ 이렇게는 하지 마세요
그룹
그룹 복사본 2
Frame 123
버튼-최종
버튼-최종2
버튼-최종_진짜최종
이미지1
텍스트
이 이름들의 공통점은 "도구가 자동 생성한 이름 그대로", "작업자 본인만 아는 맥락", "버전 관리를 이름으로 하는 혼란"이에요.
✅ 이렇게 해보세요
button/primary/hover
input/text/error
card/product/thumbnail
icon/arrow/right
avatar/medium/with-badge
divider/horizontal
section/hero
슬래시(/)로 계층을 표현하면 Figma에서 자동으로 그룹핑되고, 개발자도 컴포넌트의 계층 구조를 직관적으로 파악할 수 있어요.
레이어 네이밍 4가지 원칙
| 원칙 | 나쁜 예 | 좋은 예 |
|---|---|---|
| 역할 기반 | Rectangle, Ellipse |
avatar/image, badge/dot |
| 소문자 + 구분자 | Button Primary, 버튼_블루 |
button/primary, button-primary |
| 상태 포함 | button2, button_gray |
button/primary/disabled |
| 버전 금지 | header-최종v2 |
header/nav (버전은 히스토리로) |
컴포넌트 네이밍 — BEM과 Atomic Design과 연결하기 🧩
컴포넌트 이름은 더 중요해요. 개발자가 코드를 짤 때 디자인 파일의 컴포넌트 이름을 직접 참조하거든요. 여기서 이름이 다르면 둘 사이에 번역 작업이 생겨요. 팀에서 BEM이나 Atomic Design을 쓰고 있다면 그 방법론의 언어를 디자인 파일에도 그대로 가져오는 게 핵심이에요.
BEM 방식과 연결하기
BEM(Block-Element-Modifier)은 block__element--modifier 구조로 CSS 클래스를 작성하는 방법론이에요. 개발팀이 BEM을 쓴다면 Figma 컴포넌트 이름도 같은 언어로 맞춰주면 인수인계가 훨씬 매끄러워요.
💬 BEM 기반 컴포넌트 네이밍 예시
| Figma 컴포넌트 이름 | 대응하는 CSS 클래스 | 설명 |
|---|---|---|
| card | .card | Block |
| card/thumbnail | .card__thumbnail | Block__Element |
| card/thumbnail--wide | .card__thumbnail--wide | Block__Element--Modifier |
| button--disabled | .button--disabled | Block--Modifier |
Atomic Design 방식과 연결하기
Atomic Design은 UI를 Atoms → Molecules → Organisms → Templates → Pages 5계층으로 분류해요. 이 구조를 Figma 페이지 구성과 컴포넌트 이름에 그대로 반영하면 팀 전체가 같은 계층 언어로 소통할 수 있어요.
| 계층 | 의미 | Figma 컴포넌트 예시 |
|---|---|---|
| Atom | 더 이상 쪼갤 수 없는 최소 단위 | atoms/button, atoms/icon, atoms/badge |
| Molecule | Atom 2개 이상 조합 | molecules/search-bar, molecules/form-field |
| Organism | 독립적으로 의미 있는 UI 덩어리 | organisms/header, organisms/product-card |
| Template | Organism을 조합한 페이지 레이아웃 | templates/list-page, templates/detail-page |
| Page | 실제 데이터가 들어간 최종 화면 | pages/home, pages/product-detail |
팀이 BEM도 Atomic Design도 쓰지 않는다면 굳이 갖다 붙일 필요 없어요. 중요한 건 팀 안에서 일관성이에요. 어떤 규칙을 쓰든 모든 팀원이 같은 규칙을 알고 따르는 게 완벽한 방법론을 혼자만 쓰는 것보다 훨씬 중요해요.
Figma 페이지 & 섹션 구조 — 나쁜 예 vs 좋은 예 📐
Figma 파일을 열었을 때 처음 만나는 건 페이지 목록이에요. 페이지 구조가 무너지면 "이 화면이 어디 있더라?" 하고 헤매는 시간이 쌓여요. 현실에서 자주 보이는 나쁜 구조와 개선된 구조를 비교해 볼게요.
❌ 현실에서 자주 보이는 페이지 구조
📄 디자인
📄 디자인 완료본
📄 개발 전달용
📄 구버전
📄 참고자료
📄 테스트
📄 최종
📄 진짜최종
✅ 이렇게 구조화하세요
📄 🧩 Components (컴포넌트 라이브러리)
📄 🏠 01. Home
📄 📋 02. List
📄 🔍 03. Detail
📄 👤 04. My Page
📄 📱 05. Onboarding
📄 🗄️ Archive (구버전 보관)
Cover 페이지를 첫 번째로 두는 습관이 있어요. 여기에 파일 목적, 마지막 업데이트 날짜, 네이밍 규칙 요약, 담당자 연락처를 넣어두면 인수인계 시 "이 파일 어떻게 쓰는 거예요?" 질문이 사라져요. Archive 페이지는 구버전 프레임을 쓰레기통에 버리는 대신 여기로 옮겨두면 히스토리 추적이 가능해요.
프레임(섹션) 내부 구조도 중요해요
각 페이지 안에서 프레임을 어떻게 구조화하느냐도 탐색 속도를 좌우해요. 특히 반응형 디자인에서 디바이스별 구분이 명확해야 해요.
❌ 나쁜 예
Frame 32 copy
모바일
모바일2
태블릿? 맞나?
✅ 좋은 예
home/tablet/768
home/mobile/375
home/mobile/375--dark
팀 네이밍 컨벤션 문서 만들기 📖
가장 좋은 네이밍 규칙은 팀 모두가 알고 있는 규칙이에요. 아무리 완벽한 규칙이어도 팀원 한 명이 모르면 파일은 금방 다시 "Frame 123"으로 돌아가요. 컨벤션 문서를 간단하게라도 만들어 두는 게 중요해요.
📋 팀 컨벤션 문서에 들어가면 좋은 항목
- 파일 구조: 페이지 순서, 이름 규칙, Cover 페이지 구성 방법
- 레이어 네이밍: 구분자 방식(슬래시 vs 하이픈), 계층 표현 방법, 금지 패턴 목록
- 컴포넌트 네이밍: 채택한 방법론(BEM / Atomic / 자체 규칙), 상태 표기 방식
- 텍스트·컬러 스타일: 이름 패턴 (
heading/h1,color/primary/500등) - 업데이트 규칙: 컨벤션 변경 시 공지 방법, 기존 파일 마이그레이션 가이드
처음부터 완벽한 문서를 만들려 하면 못 만들어요. Figma Cover 페이지에 핵심 규칙 5줄만 적어두는 것부터 시작해보세요. 그게 아무것도 없는 것보다 100배 낫고, 나중에 필요할 때 조금씩 보완하면 돼요.
핵심 내용 정리 📝
오늘 내용을 한 번 더 정리할게요!
- 레이어 이름: 역할 기반 + 소문자 + 슬래시 계층 + 상태 포함. "버전"은 이름으로 관리하지 않아요.
- 컴포넌트 이름: 개발팀이 BEM을 쓰면 BEM 언어로, Atomic Design을 쓰면 그 계층으로 맞춰요. 어떤 방법론이든 팀 전체가 같은 규칙을 써야 해요.
- 페이지 구조: Cover → Components → 화면 순서대로. Archive 페이지로 구버전을 보관해요.
- 프레임 이름:
화면/디바이스/너비패턴으로 디바이스와 반응형을 명확히 구분해요. - 컨벤션 문서: Cover 페이지 5줄부터 시작. 완벽하지 않아도 팀 모두가 아는 규칙이 최고예요.
네이밍 컨벤션 핵심 요약 카드
자주 묻는 질문 ❓
button/primary/hover처럼 쓰면 탐색이 훨씬 편해요. 코드에서 CSS 클래스명은 하이픈(-)을, Figma 레이어·컴포넌트명은 슬래시(/)를 구분자로 쓰는 혼용 방식이 실무에서 가장 많이 쓰여요.organisms/card__thumbnail--wide처럼 Atomic 계층 이름 아래에 BEM 방식의 이름을 쓰는 혼용도 가능해요.icon/[이름]/[크기] 또는 icon/[카테고리]/[이름] 패턴을 많이 써요. 예: icon/arrow/right, icon/social/github. 아이콘 라이브러리를 쓴다면 그 라이브러리의 이름 체계를 그대로 가져오는 게 개발자와 소통이 가장 쉬워요."레이어1", "그룹 복사본 3"으로 가득한 파일을 건드릴 때마다 느끼는 그 막막함, 다들 아시죠? 😅 좋은 네이밍은 타자 몇 번 더 치는 습관이에요. 하지만 그 몇 번이 팀 전체의 수십 시간을 아껴줘요. 오늘 내용 중 하나만 당장 적용해 본다면, 새로 만드는 컴포넌트 이름에 슬래시 계층 구조를 넣는 것부터 시작해보세요. 팀에서 쓰는 컨벤션이 있다면 댓글로 공유해 주세요, 저도 배우고 싶어요! 🌿