IconButton

접근 가능한 이름과 시스템 소유 아이콘으로 compact action을 일관되게 표현합니다.

예제

사용해야 할 때

공간이 제한된 toolbar, 닫기·검색·정보처럼 널리 이해되는 compact action에 사용합니다. 아이콘만 보이더라도 동작을 정확히 설명하는 localizable label을 반드시 제공합니다.

사용하지 말아야 할 때

아이콘 의미가 낯설거나 행동을 오해할 가능성이 크면 visible text가 있는 Button 또는 TextButton을 사용합니다. 원격 이미지 URL, 임의 SVG, caller children을 넣는 범용 원형 container로 사용하지 않습니다.

구조

root는 native button이고 그 안에는 디자인 시스템이 소유하는 decorative Icon 하나만 있습니다. label은 trim한 뒤 root의 aria-label이 되며, name은 native form field name이 아니라 owned Icon 이름입니다.

크기와 변형

small, medium, large box는 정확히 44, 48, 56px입니다. small은 20px Icon, medium과 large는 24px Icon을 사용합니다. clear는 가벼운 action, fill은 가장 강한 강조, outline은 surface 경계를 유지하는 중간 위계입니다.

상태와 동작

기본값은 size="medium", variant="clear", native type="button"입니다. hover 다음 pressed가 적용되고 disabled가 모든 interactive state보다 우선합니다. type="submit"을 명시할 때만 form을 제출하며 native disabled, events, form, value, ref를 전달합니다. Inline style은 외부 배치 whitelist만 보존하고 정확한 box, 색상, 배경, flex sizing을 덮지 못합니다.

반응형 동작

고정된 pointer box를 유지하면서 주변 layout에서 줄바꿈됩니다. 같은 API와 44px minimum target이 mobile, tablet, desktop에 적용되고 예제 grid는 좁은 화면에서 한 열로 전환됩니다.

접근성

trim 후 빈 label은 runtime에서 거부합니다. button이 accessible name을 소유하므로 내부 Icon은 aria-hidden="true"입니다. native Enter·Space activation, form behavior, normal/forced-colors focus indicator, reduced-motion 처리를 보존합니다.

React 예제

import { IconButton } from '@hds/react';
import '@hds/react/styles.css';

export function SearchToolbar() {
  return (
    <div role="toolbar" aria-label="검색 도구">
      <IconButton label="검색 열기" name="search" />
      <IconButton label="도움말" name="info" variant="outline" />
      <IconButton label="닫기" name="close" variant="fill" />
    </div>
  );
}

API

사용 토큰

• size/control/small, size/control/medium, size/control/large, size/icon/medium, size/icon/large
• space/0, space/2, space/4, radius/full, font/family/sans
• motion/duration/fast, motion/easing/standard, color/action/*, color/bg/*, color/text/*, color/border/*, color/focus/ring

Figma

IconButton component set은 Size 3 × Variant 3 × State Default/Pressed/Disabled = 27 variants를 가집니다. Icon INSTANCE_SWAP의 기본값은 owned Close이고 preferred values는 Check, ChevronRight, Close, Info, Search 다섯 owned Icon component key로 제한됩니다. 프레임은 44/48/56px, icon은 20/24/24px이며 모든 상태 paint와 geometry가 token에 바인딩되어 있습니다. 구현 방향은 TDS Mobile IconButton reference와 함께 검토합니다.

지원 상태