Anatomy
Text Button은 버튼 영역과 텍스트 레이블이 기본입니다. 필요하면 아이콘, 단축키, 진행 표시를 덧붙일 수 있습니다.
Container
실제 구현은 native <button>에 .wbds-button을 적용합니다. 배경색, 테두리, 모서리, 눌림 효과는 WBDS CSS가 담당합니다.
Label
버튼을 눌렀을 때 무엇이 일어나는지 짧고 분명하게 씁니다. Text Button에서는 이 텍스트가 기본 accessible name이 됩니다.
Optional affordance
아이콘, 단축키, 진행 표시는 레이블 옆에 둘 수 있습니다. 텍스트가 있는 버튼에서는 아이콘만으로 의미를 대신하지 않습니다. 아이콘만 쓰는 버튼은 IconButton으로 분리합니다.
Variants
Primary, Secondary, Quiet는 버튼의 기본 위계입니다. Signal과 Critical은 검토가 필요하거나 위험한 행동처럼 의미를 더 분명히 보여줘야 할 때만 씁니다.
Structural variants
한 작업 영역에서 가장 중요한 행동은 Primary로 두고, 그 밖의 선택지는 Secondary 또는 Quiet로 한 단계 낮춥니다.
Semantic tones
Signal은 검토·실행처럼 눈에 띄어야 하는 행동에, Critical은 삭제처럼 되돌리기 어려운 행동에 사용합니다. 단순히 더 강조하고 싶다는 이유로 Primary 대신 쓰지는 않습니다.
States
Hover, focus-visible, active는 직접 조작해 확인할 수 있습니다. Disabled, loading, success, error는 구현에 정의된 state attribute를 그대로 보여줍니다.
Tab으로 포커스 표시를 확인하고, 마우스나 키보드로 hover·pressed 상태를 확인할 수 있습니다. 성공·오류 상태는 테두리 색만 바꾸지 말고 텍스트나 상태 정보도 함께 전달해야 합니다.
Size
현재 alpha는 하나의 기본 크기를 사용합니다. Small/Large 옵션은 아직 공개 API가 아닙니다.
Default control
= . Horizontal padding은 를 사용합니다.
Narrow viewport
현재 package는 620px 이하에서 non-icon Button의 minimum height를 로 올립니다. 별도 Small/Large public API는 아직 없습니다.
Loading
처리 중에는 작은 spinner와 상태 레이블을 함께 보여줍니다. busy 상태는 명확히 알리고, 같은 작업이 중복 실행되지 않도록 실제 기능에서 제어해야 합니다.
와 를 함께 사용합니다. spinner는 진행 중임을 빠르게 보여주고, 상태 레이블은 무엇을 처리하는지 알려줍니다. 중복 실행 방지는 실제 작업 로직에서 처리합니다.
Usage
버튼 모양보다 중요한 것은 무엇을 눌렀을 때 어떤 일이 일어나는지 바로 이해되는지입니다.
With text
“Save changes”처럼 결과가 바로 보이는 동사형 레이블을 씁니다. “Click here”처럼 앞뒤 문장을 읽어야 이해되는 표현은 피합니다.
In component
같은 영역에 중요한 버튼이 이미 있다면 나머지 행동은 Secondary 또는 Quiet로 낮춰 우선순위를 보여줍니다.
Destructive action
삭제처럼 되돌리기 어렵거나 위험한 행동에만 Critical을 쓰고, 무엇이 삭제되는지 레이블에 적습니다.
Icon
아이콘은 텍스트를 빠르게 알아보게 돕는 보조 요소입니다.
일반 아이콘은 18px를 사용합니다. 을 쓰는 Run 버튼은 아이콘과 간격을 조금 더 크게 잡습니다. 단축키가 있어도 버튼 자체는 그대로 클릭하거나 키보드로 실행할 수 있어야 합니다.
How to use
버튼을 더 눈에 띄게 만드는 것보다 한 화면 안에서 우선순위가 헷갈리지 않게 만드는 것을 먼저 봅니다.
- 같은 작업 영역에서 가장 중요한 행동은 하나만 Primary로 둡니다.
- label만 읽어도 결과를 예측할 수 있게 씁니다.
- Signal/Critical은 검토 필요성이나 위험도가 실제로 다를 때만 사용합니다.
- 모든 CTA를 Sakura Signal이나 tactile command로 만들지 않습니다.
- disabled를 설명 없이 오류/권한 부족의 대체 표현으로 쓰지 않습니다.
- icon이나 shortcut만으로 버튼의 의미를 전달하지 않습니다.
Customize
지금 alpha에서 실제로 지원하는 속성만 정리합니다. 아직 없는 prop/API는 문서에서 먼저 만들지 않습니다.
| Surface | Current values | Contract |
|---|---|---|
| 미지정 상태가 Primary입니다. | ||
| semantic emphasis용이며 generic variant가 아닙니다. | ||
| approved tactile command treatment를 opt in합니다. | ||
| state semantics는 text/ARIA와 함께 제공해야 합니다. | ||
| 18px default | 텍스트 옆에 두는 보조 아이콘입니다. | |
| 16px orbit | Loading 상태에서 사용하는 작은 진행 표시입니다. |
Accessibility
기본 button semantics, 보이는 포커스, 읽을 수 있는 이름, loading 상태 전달을 함께 지켜야 합니다.
Semantics & keyboard
Native <button>을 우선하고 Enter/Space activation을 보존합니다. package 전역 :focus-visible outline을 제거하거나 대체하지 않습니다.
Name & state
텍스트 레이블을 기본 accessible name으로 사용합니다. disabled는 실제로 실행할 수 없는 경우에만 쓰고, loading/error/success는 텍스트나 적절한 ARIA 상태와 함께 전달합니다.
Target & motion
좁은 화면에서는 Text Button 높이가 touch minimum으로 늘어납니다. Loading spinner는 reduced motion에서 회전을 멈추고, command 눌림 효과도 상태를 이해하는 데 필요한 수준으로만 사용합니다.