07 · 시스템 소개

네이밍 원칙Naming

컴포넌트 · 토큰 · props · 파일의 이름은 디자인 시스템의 얼굴입니다. 잘 지은 이름은 문서를 읽지 않아도 짐작이 가능하고, 잘못된 이름은 쓸 때마다 확인이 필요합니다.

왜 이름에 공을 들이는가

디자인 시스템을 쓸 때 사람들은 문서를 거의 읽지 않습니다. 자동완성에 뜬 이름 · 동료 코드에 쓰인 이름만 보고 판단합니다. 즉 이름이 문서의 요약이 되어야 합니다.

이 디자인 시스템은 네이밍에서 두 가지 원칙을 지킵니다. 첫째, 업계 통용어가 있으면 새로 만들지 않는다. 둘째, 역할을 먼저, 모양은 나중에. 두 원칙이 충돌하면 역할 우선입니다.

종류	권장	지양	비고
기본 요소	Button · Input · Checkbox	Btn · TextField2 · CBox	HTML 요소와 동일한 명칭을 먼저 고려. 축약하지 않습니다.
조합 컴포넌트	DatePicker · Combobox · Dropdown	DateSelector · AutoCompleteInput · SelectMenu	기능이 명확한 업계 통용어를 씁니다. 새로 만들지 않습니다.
레이아웃	Stack · Grid · Divider	VerticalBox · MainGrid · Line	레이아웃 원시 개념을 그대로 이름으로 씁니다.
상태 · 피드백	Alert · Toast · Skeleton	Warning · Popup · LoadingBox	역할을 드러내는 명사. “Warning”은 variant 이름이지 컴포넌트 이름이 아닙니다.

종류	권장	지양	비고
시맨틱 색	--color-text · --color-accent · --color-danger	--color-black · --color-red-500 · --red	원시(raw) 이름 대신 역할(semantic) 이름. 테마 교체가 가능해집니다.
팔레트 스케일	--color-gray-50 … --color-gray-900	--color-light-gray · --color-dark-gray	숫자 스케일로 연속성을 표현. 중간값을 나중에 끼워 넣기도 쉽습니다.
공간	--space-2 · --space-4 · --space-8	--gap-small · --padding-md	용도가 아닌 크기로 명명. 같은 8px을 gap · padding · margin 모두에서 씁니다.
타이포	--text-body · --text-heading-lg · --text-caption	--font-14 · --font-h1 · --small-text	역할 기반. 실제 크기는 토큰 값으로만 바꿉니다.

종류	권장	지양	비고
불리언	disabled · loading · required	isDisabled · hasLoader · isRequired	is/has 접두사를 붙이지 않습니다. 이미 충분히 불리언처럼 읽힙니다.
변형	variant="primary" · size="sm" · tone="danger"	type="primary" · btnSize="small" · color="red"	variant · size · tone 세 슬롯에 담습니다. HTML의 type과 충돌하지 않게.
이벤트	onChange · onSelect · onOpen	handleChange · onValueChanged · openHandler	React 규약(on + 이벤트명)을 따릅니다. 콜백은 수동태로 짓지 않습니다.
제어 · 비제어	value / defaultValue · open / defaultOpen	inputValue / initialValue · isOpen / startOpen	React의 form 요소 규약과 동일한 쌍. 학습 비용을 줄입니다.

Don't