HelpBubble

HelpBubble은 사용자가 보고 있던 화면을 벗어나지 않고, Trigger 근처에서 짧은 도움말을 확인할 때 사용해요. 반드시 선택해야 하는 내용이나 다음 행동을 막아야 하는 상황이라면 Dialog나 AlertDialog를 사용해요.

overlay 사이 선택이 헷갈린다면 Overlay Patterns에서 Dialog, AlertDialog, HelpBubble를 먼저 비교해보세요.

Anatomy

HelpBubble은 Root, Trigger, Positioner, Content, Title, Description을 중심으로 사용해요. Positioner가 Trigger 근처 배치를 맡고, Content가 실제 도움말 표면을 보여줘요. 별도의 닫기 버튼이 필요하면 선택적으로 Close를 함께 둘 수 있어요.

기본 사용에서는 HelpBubble.Trigger로 열고 HelpBubble.Positioner 안에 HelpBubble.Content를 둬요. 외부 상태와 맞춰야 할 때만 open과 onOpenChange를 함께 사용해요.

Properties

State

HelpBubble은 열린 상태와 닫힌 상태를 가져요. 열린 동안에는 role="dialog"와 접근 가능한 이름이 적용돼요. 사용자는 바깥을 누르거나 Escape로 HelpBubble을 닫을 수 있어요. 기본 예제의 trigger를 눌러 실제 열림과 닫힘 흐름을 확인할 수 있어요.

Guidelines

짧은 도움말에 사용하기

폼 설명, 단축키 안내, 가벼운 보조 정보처럼 지금 흐름을 유지한 채 짧게 읽고 닫아도 되는 내용에 사용해요. 결과가 크거나 사용자가 확인과 취소 중 하나를 골라야 하는 액션에는 AlertDialog를 사용해요.

다른 overlay와 구분하기

Trigger 근처에서 짧게 읽고 지나가면 되는 설명이라면 HelpBubble을 사용해요. 내용이 길어지거나 별도 조작이 필요하면 Dialog를 사용하고, 사용자가 취소와 확인 중 하나를 골라야 한다면 AlertDialog를 사용해요.

제목으로 목적을 먼저 알려주기

제목은 이 버블이 왜 떠 있는지 바로 알 수 있게 써요. 설명은 다음 행동을 돕는 짧은 맥락만 덧붙이면 충분해요.

Tooltip처럼 너무 짧게 줄이지 않기

HelpBubble은 단순한 hover 라벨보다 설명이 조금 더 필요한 상황에 잘 맞아요. 한두 단어 이름만 보여주면 충분하다면 HelpBubble까지 쓰지 말고 더 가벼운 패턴을 사용해요.

다음에 읽으면 좋은 문서

• overlay 차이는 Overlay Patterns에서 한 번에 비교해요.
• 제목과 설명 문구는 Writing 기준을 따라요.
• 제목과 설명의 텍스트 크기와 계층은 Typography에서 확인해요.
• bubble과 inverse neutral 색상 기준은 Color에서 확인해요.

Schema