버튼 시스템 통합 설계 (Button System Spec)

상태: 설계 확정용 초안 (구현 전). 이 문서가 OK되면 design-system.css 구현 + 앱 마이그레이션 + docs(actions/buttons) 재작성의 기준이 된다.

목적: 현재 두 표기법 공존(① .ds-btn·.ds-btn-text 명명 클래스 ② bg-orange-500 px-3… utility-keyed + !important override)을 하나의 명명 체계로 통합한다. 버튼은 변수 조합, 맥락(모달 등)은 사용 규칙으로 관리한다.

원천: Figma 5노드 — solid 9010-10531 · line 9017-10430 · text 9036-1306 · interaction 9010-10532 · secondary 팔레트 9014-11311 · icon 9803-8531.

1. 원칙

1. 단일 베이스 .ds-btn + 평면 modifier — 변형·색·사이즈를 전부 .ds-btn--*로.
2. !important 금지 — 상태는 :hover / :focus-visible / :active / :disabled 자체 specificity로 해결. 기존 button[class*="bg-"] … !important override 블록 제거.
3. utility-keyed 폐지 — bg-orange-500 px-3 py-1.5 가로채기 방식 제거.
4. 용도별 이름 금지 — .ds-btn(모달)·.icon-btn 같은 역할 명명 대신 변수 조합 + 사용 규칙.
5. 단일 출처 — design-system.css에만 정의(앱 main.css 복제 없음).

2. 클래스 API

<button class="ds-btn  ds-btn--solid  ds-btn--primary  ds-btn--md">저장</button>
<!--          베이스    변형           색              사이즈        -->

축	클래스	필수
베이스	.ds-btn	✅
변형	.ds-btn--solid --line --text --icon	✅ (1개)
색	.ds-btn--primary --dark --red --green --purple --blue --yellow --aquablue --muted	✅ (1개)
사이즈	solid/line/icon: --xs --sm --md --ml --lg --xl · text: --text-sm/md/lg/xl	✅ (1개)
옵션	.ds-btn--bg(line 틴트 채움) · .ds-btn--full(width 100%)	—

3. 변형 (variation)

같은 색 modifier가 변형별로 다르게 적용된다.

	--solid	--line	--text	--icon
--primary	주황 채움 + 흰 글자	주황 보더 + 글자, 투명 bg	주황 글자만	주황 아이콘 (원형)
채움 옵션	(기본 채움)	--bg = 틴트/흰 채움	—	—
용도	주요 확정	보조·위험(테두리)	인라인 CTA·링크	표·툴바 아이콘 액션

4. 색 (color)

primary + neutral + secondary 팔레트(Figma 9014-11311, 값 일치).

modifier	토큰	의미
--primary	orange 500 / hover 600 / active 700	확정·저장
--dark	neutral-900	강한 확정
--red	secondary #e63224	삭제·경고
--green	secondary #30c93a	승인·완료
--purple	secondary #484acf	연동·Export
--blue	secondary #2463eb	정보
--yellow	secondary #fad064	주의
--aquablue	secondary #309bc9	보조
--muted	neutral-500/600	약한 액션

🔴 레거시 색 금지: gray→neutral · amber→yellow · emerald/indigo/teal→해당 secondary. 🟡 미확정 ④: solid white 계열(white-bk·white-or·lightor-or) modifier 표현 — 구현 시 확정.

5. 사이즈 (size)

solid · line · icon (높이 기준, Figma 스케일):

token	높이	padding(제안)	font(제안)	Figma
--xs	20	2 / 8	10	xsmall
--sm	28	4 / 12	12	small
--md	32	6 / 12	13	medium
--ml	40	9 / 16	14	semilarge
--lg	48	12 / 20	15	large
--xl	52	14 / 20	16	xlarge

text (별도 font 스케일 — 결정 ①): .ds-btn-text--sm(21) --md(22) --lg(24) --xl(26), 기본(14). 높이 없음(인라인).

6. 상태 (state) — Figma _intercation, !important 없이

상태	solid	line · text	icon
hover	fill darken (600)	색 오버레이 20% (color-mix)	검정 오버레이
focus-visible	전역 링	전역 링 + 오버레이 30%	전역 링
pressed (active)	brightness(0.9)	오버레이 10%	오버레이
disabled	회색박스: neutral-100 bg + neutral-300 글자 (결정 ②)	line=보더 40% / text=opacity	아이콘 #c1c1c1

구현: .ds-btn--solid:hover 등 자체 specificity. 전역 button:focus-visible 링 유지.

7. 아이콘 버튼 (Figma Button/Icon 9803-8531)

Figma는 아이콘 버튼을 색·인터랙션을 공유하는 정식 컴포넌트로 정의 → .ds-btn--icon으로 통합.

• 형태: 원형(radius 999), 아이콘 전용. 24px(아이콘 inset 12.5% ≈ 18px).
• 색 4종: --dark(#1b1b1b, 기본) · --white(#fdfdfd) · --muted(#8f8f8f) · --primary(#f66014).
• 상태: 공통 _intercation 검정 오버레이. disabled 아이콘 #c1c1c1.
• title → 싱글톤 툴팁 자동(기존 유지).
• ⚠️ 결정 ③: 현재 .icon-btn 28px → Figma 24px로 정렬(78개 영향, "implement from Figma" 지시 반영).

8. 변수 체계 밖 — 특수 클래스 유지

일반 액션버튼과 성격이 달라 별도 유지(단, design-system.css 중앙화):

• .ds-modal__close (모달 닫기 X, 24px 원형)
• .ds-page-btn (페이지네이션 고스트)
• .ds-mini-modal__btn (미니 확인 모달)

9. 사용 규칙 (맥락 → 조합)

맥락	조합
모달/폼 푸터 주요 액션	solid · primary · md(32)
모달/폼 푸터 취소	line · dark · md
표/툴바 "추가"	solid · primary · sm(28)
인라인 링크 CTA	text · primary
삭제(위험)	line · red · md
모바일 풀폭 제출	solid · primary · lg + --full
표 행 아이콘 액션	icon · dark (또는 muted)

10. 마이그레이션 매핑

현재	→ 새
.ds-btn ds-btn--primary (모달)	ds-btn ds-btn--solid ds-btn--primary ds-btn--md
util solid bg-orange-500 px-3 py-1.5 text-white rounded	ds-btn ds-btn--solid ds-btn--primary ds-btn--md
util line border border-red-600 text-red-600 px-3 py-1.5	ds-btn ds-btn--line ds-btn--red ds-btn--md
.ds-btn-text ds-btn-text--primary ds-btn-text--sm	ds-btn ds-btn--text ds-btn--primary ds-btn-text--sm
.icon-btn (28px)	ds-btn ds-btn--icon ds-btn--dark (24px)
토글 칩 (:class 조건부 bg-orange-500)	버튼 아님 → 별도(선택 칩) 처리

11. 기존 PR 영향

• PR #344 (docs) — .ds-btn을 "4번째 시스템"으로 설명하던 buttons.md/탐색기를 이 통합 체계로 재작성. 데모도 새 클래스로. (현재 draft)
• PR #345 (중앙화) — 기존 .ds-btn/.icon-btn을 static으로 모으는 선행 정리. 어차피 이 체계로 재정의될 코드라, 중앙화는 유지하고 새 체계 구현 PR에서 덮어쓴다. (현재 draft)

12. 구현 순서(제안)

1. design-system.css에 .ds-btn 통합 체계 작성 (변형·색·사이즈·상태) — 작은 검증 단위로.
2. 기존 button[class*=…] !important override + 앱 복제 블록 제거.
3. docs(actions/buttons) 이 체계로 재작성 + 라이브 데모 갱신 → PR #344.
4. 앱 마이그레이션: DS 연결된 앱부터(general-affairs → admin → …), 앱별 PR, 브라우저 검증.
5. DS 미연결 앱(inventory·module-manager) 배선 + 마이그레이션.

13. 미확정 (확인 필요)

• ④ solid white 계열(white-bk/white-or/lightor-or) 색 modifier 표현 — 구현 시 확정 가능.
• 사이즈 padding/font 제안값(5절) — 구현 시 Figma 실측과 대조해 확정.