Button

Button은 기본 상태 외에 loading, disabled 상태를 가져요. React API에서는 status="loading" 또는 status="disabled"로 표현해요. loading 상태에서는 현재 위계와 색은 유지한 채 중복 실행만 막고 aria-busy를 함께 설정해요.

Loading

loading은 이미 시작한 작업이 끝나기를 기다리는 동안 사용해요. 버튼의 의미와 위계는 유지하면서 중복 실행만 막아요.

Disabled

disabled는 지금 조건에서는 실행할 수 없는 액션에 사용해요. 가능해지는 조건을 주변 문맥에서 함께 알려주면 사용자가 다음 행동을 이해하기 쉬워요.

Disabled

Guidelines

가장 중요한 액션을 잘 보이게 하기

한 화면에서 가장 중요한 액션에는 primary를 사용해요. 취소, 닫기, 이전 단계 이동처럼 흐름을 보조하는 액션에는 secondary를 사용해 구분해요.

되돌리기 어려운 액션을 분명하게 보여주기

삭제, 초기화처럼 되돌리기 어려운 액션에는 danger를 사용해요. 결과가 큰 액션이라면 AlertDialog와 함께 보여주면 사용자가 한 번 더 확인하기 쉬워요.

Icon Only는 뜻이 분명할 때만 사용하기

아이콘만 있는 버튼은 뜻이 충분히 분명할 때만 사용해요. 이때는 aria-label 또는 aria-labelledby를 함께 써서 스크린 리더가 버튼 목적을 읽을 수 있게 해요.

다음에 읽으면 좋은 문서

액션 위계와 색상 기준은 Color에서 확인해요.
버튼 라벨과 텍스트 조합 기준은 Typography에서 확인해요.
일반적인 모달 액션 배치는 Dialog에서 확인해요.
되돌리기 어려운 확인 흐름은 AlertDialog에서 확인해요.

Schema

Public Anatomy

컴포넌트가 어떤 구성 요소로 이루어지는지 보여줘요. 스타일 타깃으로 표시된 항목만 definition과 recipe에서 직접 스타일링해요.

이름	필수	스타일 타깃	설명
`root`	필수	예	상호작용 상태와 button semantics를 소유하는 루트 컨트롤이에요.
`leadingIcon`	선택	예	라벨 앞에 표시하는 선택 아이콘이에요.
`label`	선택	아니오	시각적으로 보이는 텍스트 라벨이에요. 아이콘만 있는 조합이 접근 가능한 이름을 따로 제공하지 않는다면 필수예요.
`trailingIcon`	선택	예	라벨 뒤에 표시하는 선택 아이콘이에요.

Internal Anatomy

이름	스타일 타깃	설명
`spinner`	예	loading 상태에서 루트 안에 함께 렌더링되는 진행 표시예요.

Variants

이름	기본값	옵션
유형	`primary`	`primary`가장 높은 강조 액션이에요. `secondary`기본적인 낮은 강조 액션이에요. `outline`시각적 경계가 있는 액션이에요. `ghost`항상 보이는 컨테이너 없이 사용하는 액션이에요. `danger`삭제처럼 되돌릴 수 없는 액션이에요.
크기	`md`	`sm`작은 공간에서 사용하는 컨트롤이에요. `md`기본 폼 컨트롤 크기예요. `lg`높은 가시성이 필요한 컨트롤이에요.

States

사용자가 느끼거나 컴포넌트가 실제로 드러내는 상태를 설명해요. 각 항목에는 recipe와 runtime이 함께 읽는 바인딩 정보를 적어요.

이름	바인딩	설명
`disabled`	`:disabled` `[data-disabled]`	액션을 사용할 수 없으며 상호작용을 받을 수 없어요.
`loading`	`[data-loading]`	액션이 진행 중이에요. 현재 위계는 유지하고 중복 실행만 막아요.
`focusVisible`	`:focus-visible` `[data-focus-visible]`	키보드 포커스가 token 기반 focus ring으로 표시돼요.

Styling Hooks

사용자에게 보이는 상태라기보다 스타일을 나눌 때 쓰는 조건에 가까워요. 각 항목에는 상태와 마찬가지로 recipe와 runtime이 함께 읽는 바인딩 정보를 적어요.

이름	바인딩	설명
`iconOnly`	`[data-icon-only]`	텍스트 라벨 없이 아이콘이나 spinner만 보여주는 압축 레이아웃이에요.

Accessibility

역할	`button`
키보드	Enter로 Button을 실행해요. Space로 Button을 실행해요.
요구사항	Button Root는 button semantics와 keyboard interaction을 올바르게 제공해야 해요. 의도하지 않은 form submit을 막기 위해 기본 `type`은 `button`이어야 해요. 시각적으로 보이는 라벨 없이 아이콘만 보여줄 때는 `aria-label` 또는 `aria-labelledby`가 필요해요. `loading`이 `true`이면 `aria-busy`가 `true`이고 중복 실행을 막아야 해요.