IconButton
아이콘 전용 버튼 — aria-label 필수. sm(시각 32px)은 ::after로 44px 히트 영역을 확보하고, 높이는 control 토큰으로 Button과 같은 줄에 정렬됩니다.
마지막 업데이트 2026-06-14
한눈에#
아이콘만으로 자명한 반복 행동을 압축한 컨트롤. 텍스트 라벨이 없는 대신 aria-label이 필수입니다.
- 3 변형
- 2 크기
- WCAG 2.5.5 · 44px
- aria-label 필수
ghost · subtle · solid — 시각 위계 3단
사용 시점#
아이콘만으로 의미가 분명할 때만 — 모호하면 텍스트 버튼이나 링크를 실물로 비교합니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — 아이콘만으로 자명한 반복 행동 — 검색·닫기·더보기(툴바)
대신 Button — 의미가 라벨을 요구하는 주요 행동
대신 Link — 페이지 이동·외부 링크
해부#
정사각 컨트롤 — 텍스트 패딩이 없고 아이콘이 중앙 정렬됩니다.
- height
- 44px
control.height-md - width
- 44px
정사각 - radius
- 10px
radius-control - border
- 0
- hit-area
- ≥44px
WCAG 2.5.5
크기#
높이는 control.height-* 토큰 — Button·Input과 같은 줄에 정렬됩니다. sm은 시각 32px이지만 ::after 오버레이로 히트 영역 44px을 보장합니다.
변형#
3단 위계. 색은 이름이 아니라 실제 스와치와 측정된 대비로 확인하세요.
- bg
transparent- fg
text-muted
- bg
surface-muted- fg
text-muted
- bg
primary-strong- fg
on-primary
- ghost — 배경 없음(기본). 툴바·반복 행동
- subtle — 옅은 표면 채움. 보조 행동을 시각적으로 묶을 때
- solid — Button primary와 동일한
primary-strong채움(DD-6 AA)
상태#
Hover·Active·Focus는 의사클래스라 정적 문서에선 잘 안 보입니다 — 매트릭스는 실제 IconButton에 동일 토큰을 적용해 모든 상태를 한 번에 보여줍니다.
셀은 실제 컴포넌트를 렌더하고 hover·active·focus를 동일 토큰으로 정적 재현 — 색 드리프트 0
loading은 아이콘을 Spinner로 대체하고 비활성화하며 aria-busy="true"를 부여합니다.
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
사용 지침#
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
권장 — 툴바에서 반복 행동을 아이콘으로 압축(ghost·subtle)
지양 — 주요 단일 CTA를 아이콘만으로 — 의미 모호. 텍스트 Button 권장
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
icon | ReactNode | — | 아이콘 노드 — @wds /ui-web icons 권장 (자체 크기 보유) |
aria-label | string | — | 접근성 필수 — 아이콘의 의미를 설명한다 |
variant | 'ghost' | 'subtle' | 'solid' | 'ink' | ghost | 시각 위계. solid는 Button primary와 동일 채움 |
size | 'sm' | 'md' | md | 32/44px — control.height 토큰과 동기. sm은 44px 히트 영역 |
shape | 'square' | 'round' | square | 모양 — square(기본) · round(완전 원형). AI 컴포저 액션은 round 권장(ChatGPT 정합). |
loading | boolean | false | 로딩 중 — 아이콘을 Spinner로 대체하고 비활성화 (불리언 prop 무접두, COMPONENT_API §1) |
ref | Ref<HTMLButtonElement> | — | 네이티브 <button>으로 전달되는 ref (React 19 ref-as-prop) |
접근성#
aria-label이 타입 레벨 필수 — 아이콘만으로는 보조기술에 의미가 전달되지 않습니다- 아이콘 노드는
aria-hidden래퍼로 감싸 중복 낭독을 차단합니다 loading시aria-busy="true"+ 비활성화 — 중복 제출을 막습니다- 시각 32px(sm)에도 히트 영역은 44px — WCAG 2.5.5 Target Size 충족
:focus-visible에 2px primary 아웃라인 링
토큰#
component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).
| 속성 | 토큰 |
|---|---|
| 크기 | control.height-sm/md · radius.control |
| ghost/subtle | color.text-muted → hover color.text + color.surface-hover → active color.surface-pressed · subtle 바탕 color.surface-muted |
| solid | color.primary-strong(-hover/-active) + color.on-primary (DD-6 AA 채움) |
| disabled | color.disabled-bg + color.disabled-fg |
| 포커스 링 | color.focus-ring 2px 아웃라인 |
| 모션 | duration.fast + ease.standard (배경·잉크·transform) |
| 히트 영역 | space.3 / 2 네거티브 inset — 32 + 12 = 44px |