컴포넌트 네이밍 규칙 — 팀이 커져도 안 무너지는 법

컴포넌트 네이밍 규칙은 미적 취향의 문제가 아니라, 팀이 커져도 라이브러리가 무너지지 않게 하는 최소한의 인프라입니다. “Button 2 copy final real” 같은 레이어 이름을 본 적이 있다면 그 팀은 이미 규칙 없이 컴포넌트를 늘려온 것입니다. 이름 규칙은 처음 라이브러리를 만들 때는 사소해 보이지만, 나중에 되돌리려면 수백 개의 레이어를 하나씩 다시 정리해야 하는 값비싼 부채가 됩니다.

1. 규칙 없는 이름 vs 규칙 있는 이름

컴포넌트 수가 열 개일 때는 대충 지어도 헷갈리지 않지만, 백 개를 넘어가는 순간부터는 이름 하나가 검색 결과를 좌우합니다. 이 글에서는 실무에서 쓸 수 있는 네이밍 규칙의 기준을 정리합니다.

기본 구조 — 카테고리, 컴포넌트, 변형

가장 널리 쓰이는 방식은 슬래시로 계층을 나누는 구조입니다. 이 구조를 쓰기로 했다면 팀 전체가 같은 순서와 같은 depth를 지켜야 합니다. 어떤 컴포넌트는 2단계, 어떤 컴포넌트는 4단계로 제각각이면 검색 결과는 다시 뒤섞입니다.

2. 영문 표기와 코드에 맞춘 이름

한글 이름과 영문 이름을 섞어 쓰면 코드와 매핑할 때 반드시 문제가 생깁니다. 개발자는 결국 영문 변수명으로 컴포넌트를 참조하기 때문에, 처음부터 영문 표기를 기본으로 하고 필요하면 설명란에 한글 맥락을 덧붙이는 방식이 낫습니다. 대소문자도 PascalCase로 통일할지, kebab-case로 통일할지 팀 컨벤션 문서에 명시해두어야, 새로 합류한 디자이너가 임의로 다른 규칙을 쓰는 일을 막을 수 있습니다.

변형 이름을 “기본, 호버, 눌림”처럼 한글로 적어두면 보기엔 편하지만, 코드에서는 default, hover, pressed 같은 영문 키가 필요합니다. 변형 이름을 처음부터 코드에서 쓸 이름과 동일하게 맞춰두면, Dev Mode에서 생성되는 코드 스니펫도 실제 코드베이스와 자연스럽게 이어집니다.

3. 왜 이름 규칙이 팀 규모의 문제인가

혼자 작업하거나 팀원이 두세 명일 때는 파일 안에서 컴포넌트를 눈으로 훑어봐도 금방 찾을 수 있다. 문제는 라이브러리가 수백 개의 컴포넌트로 늘어나고, 디자이너가 여러 명 합류하면서 시작된다. 이름이 제각각이면 검색 패널이 있어도 무용지물이 되고, 같은 버튼을 두 사람이 각자 다른 이름으로 새로 만들어버리는 중복도 잦아진다. 네이밍 규칙은 처음에는 불필요한 격식처럼 느껴지지만, 팀 규모가 커질수록 라이브러리의 생존을 결정하는 조건이 된다.

흔한 오해는 네이밍 규칙을 “한 번 정해두면 끝나는 문서”로 여기는 것이다. 실제로는 새 컴포넌트가 추가될 때마다 그 규칙이 계속 지켜지는지 확인하는 절차가 함께 있어야 의미가 있다. 규칙 문서만 있고 실제로 지켜지는지 아무도 확인하지 않으면, 반년 뒤 라이브러리는 다시 규칙 없는 이름들로 뒤섞이게 된다.

4. 마치며 — 규칙은 강제해야 유지된다

규칙 문서를 만들어놓아도 실제로 지켜지지 않으면 소용이 없습니다. 새 컴포넌트를 게시하기 전에 리뷰어를 지정해 이름 규칙을 확인하는 절차를 넣거나, 정기적으로 라이브러리 전체를 훑어보며 규칙에서 벗어난 이름을 정리하는 시간을 따로 잡아두는 것이 효과적입니다. 팀이 작을 때는 암묵적으로 지켜지던 규칙도, 인원이 늘어나면 문서와 리뷰 프로세스 없이는 유지되지 않습니다.

변형과 프로퍼티 설계 기준은 피그마 컴포넌트 제대로 만들기에서 다뤘습니다. 라이브러리 규모가 커지면서 반복 작업을 자동화하고 싶다면 디자인 시스템에 AI를 넣는 방법도 참고할 만합니다. 컴포넌트 이름과 구조를 정리하는 공식 가이드는 피그마 공식 문서에서 확인할 수 있습니다.

이름 하나 짓는 데 그렇게까지 신경 써야 하냐고 물을 수 있지만, 컴포넌트 수백 개를 검색해야 하는 순간이 오면 답은 명확해집니다.