Help Bubble

구조는 당근 SEED Help Bubble(Apache-2.0)를 따른다 — 말풍선 · 화살표 · 제목 · 설명 · 닫기 버튼. Tooltip 도 같은 말풍선을 쓴다(SEED 도 두 컴포넌트가 스펙 하나를 쓴다) — 여는 방식만 다르다. 값은 groo 토큰이고, SEED 와 다른 자리는 맨 아래 "SEED 와 다른 점" 에 적었다(2026-10-02 사용자 결정).

수치 원본은 help-bubble.yaml이다(Tooltip 과 같은 파일). 수치 표 자리([표: …])와 그림 자리([그림: …])는 사이트가 그 파일로 그린다 — GitHub 에서는 그 파일 · 그림 코드로 가는 링크로 보인다.

직접 골라 보기제목 링크 복사

설명 · 닫기 버튼 · 위치를 고르면 스펙대로 그린 말풍선과 그 코드가 바뀐다. 실제로 눌러 열고 닫을 수 있다.

import { HelpBubble, HelpBubbleContent, HelpBubbleTrigger } from "@/components/ui/help-bubble"

<HelpBubble>
  <HelpBubbleTrigger asChild>
    <Button variant="ghost" ghostColor="neutralSubtle" layout="iconOnly" aria-label="연차 사용 규정 안내">
      <Info />
    </Button>
  </HelpBubbleTrigger>
  <HelpBubbleContent
    title="연차 사용 규정"
    description="입사 1년 미만은 한 달에 1일씩 생기고, 1년이 지나면 15일이 생겨요."
  />
</HelpBubble>

Anatomy제목 링크 복사

부위

Properties제목 링크 복사

말풍선제목 링크 복사

위아래 10 · 좌우 12, 모서리 12, 그림자 없음. 제목 13 / 18 · 700, 설명 13 / 18 · 400, 제목 ↔ 설명 2 — 한 줄이면 38, 설명이 있으면 58. 폭은 내용만큼이고 최대 280(여백 포함)이다 — 한 줄에 20자 안팎, 2 ~ 3줄이면 넘지 않는다.

공통

위치제목 링크 복사

기본은 트리거 위다. 자리가 모자라면 반대편으로 뒤집고 옆으로 민다 — 화면 가장자리와 16 을 남긴다. 화살표는 늘 트리거 가운데를 가리키고 말풍선 모서리와 14 를 남긴다.

셋이 부딪히면 순서는 이렇다(2026-10-15 사용자 결정 — 구현 세션 질문 Q-004-1).

1. 화살표는 트리거 가운데 — 비켜 그리지 않고, 지우지도 않는다.
2. 화살표 ↔ 말풍선 모서리 14 — 화살표 가운데가 말풍선 끝에서 20(14 + 화살표 폭의 반 6) 안쪽에 오도록 말풍선을 트리거 쪽으로 민다.
3. 화면 가장자리 16 — 위 둘을 지키느라 모자라면 16 보다 가장자리에 붙는다. 붙는 만큼에 하한은 없다 — 화면 끝(0)까지 간다. 트리거가 화면 끝에 붙어도 누르는 자리가 40 이상이면 가운데가 끝에서 20 이상이라 말풍선은 화면 밖으로 나가지 않는다.

상단 바 오른쪽 끝의 알림(아이콘 버튼 44 · 화면 끝 6)에서는 말풍선 오른쪽이 화면 끝에서 8, 화면 왼쪽 끝 0 에 붙은 ⓘ 40 에서는 0 이다. 위 · 아래로 뒤집어도 가로 자리는 같으므로 뒤집기로 풀지 않는다.

닫기 버튼제목 링크 복사

닫기 전까지 남겨 둘 안내(처음 쓰는 기능의 설명처럼 처음부터 열어 두는 말풍선)에만 둔다. 상자 38 · 아이콘 14 이고 누르는 영역은 44 다.

닫기 버튼

State제목 링크 복사

상태

모션

Guidelines제목 링크 복사

도움말을 어디에 두나제목 링크 복사

결과 · 상태 · 오류처럼 알리는 일(Snackbar · Callout · Page Banner · Result Section · Alert Dialog)을 고르는 표는 Snackbar 의 "무엇으로 알리나" 한 벌이다(2026-10-22 사용자 결정 3B — https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX). 이 표는 도움말의 자리만 맡는다.

터치에서도 닿는 도움말제목 링크 복사

Tooltip 은 손가락으로 누르면 열리지 않는다. 폰에서도 읽어야 하는 설명은 이 말풍선에 둔다 — 트리거는 ⓘ 아이콘 버튼(이름 "{무엇} 안내")이고, 누르면 열고 다시 누르거나 바깥을 누르면 닫는다.

짧게제목 링크 복사

제목 한 줄, 설명 2 ~ 3줄이면 충분하다. 그보다 길면 화면 안 글이나 시트로 옮긴다. 말풍선 안에 링크 · 버튼을 두지 않는다(닫기 버튼만) — 누를 것이 있으면 Popover 다.

글제목 링크 복사

제목은 무엇의 설명인지 — "연차 사용 규정". 설명은 해요체 문장에 마침표 — "입사 1년 미만은 한 달에 1일씩 생기고, 1년이 지나면 15일이 생겨요."

코드제목 링크 복사

레시피 recipes/shadcn/components/ui/help-bubble.tsx 를 쓴다(Radix Popover 위). 아래 미리보기는 스펙 값으로 그린 모습이다.

ⓘ 를 눌러 여는 규정 안내제목 링크 복사

import { HelpBubble, HelpBubbleContent, HelpBubbleTrigger } from "@/components/ui/help-bubble"

<HelpBubble>
  <HelpBubbleTrigger asChild>
    <Button variant="ghost" ghostColor="neutralSubtle" layout="iconOnly" aria-label="연차 사용 규정 안내">
      <Info />
    </Button>
  </HelpBubbleTrigger>
  <HelpBubbleContent
    title="연차 사용 규정"
    description="입사 1년 미만은 한 달에 1일씩 생기고, 1년이 지나면 15일이 생겨요."
  />
</HelpBubble>

처음부터 열어 두는 안내 — 닫기 버튼제목 링크 복사

import { Search } from "lucide-react"
import { HelpBubble, HelpBubbleAnchor, HelpBubbleContent } from "@/components/ui/help-bubble"
import { TopNavigationIconButton } from "@/components/ui/top-navigation"

{/* 처음 쓰는 사람에게 한 번 — 닫으면 다시 열지 않는다. Anchor 는 자리만 잡는다(누르면 원래 동작 — 홈 상단 바의 검색).
    closeOnInteractOutside={false} — 바깥 누르기 · 바깥으로 간 초점(Tab)에 닫히지 않는다. 닫기 버튼 · Esc · 말풍선에서 Tab 으로 나가기로 닫는다 */}
<HelpBubble defaultOpen={!seen} onOpenChange={(open) => !open && markSeen()}>
  <HelpBubbleAnchor asChild>
    <TopNavigationIconButton aria-label="검색" onClick={openSearch}><Search /></TopNavigationIconButton>
  </HelpBubbleAnchor>
  <HelpBubbleContent title="거래를 찾아보세요" description="가맹점 이름 · 메모 · 금액으로 찾을 수 있어요." showCloseButton closeOnInteractOutside={false} side="bottom" />
</HelpBubble>

Behavior제목 링크 복사

Accessibility제목 링크 복사

Do / Don't제목 링크 복사

✅ Do제목 링크 복사

• 폰에서도 읽어야 하는 설명은 ⓘ 를 눌러 여는 말풍선으로.
• 제목 한 줄 · 설명 2 ~ 3줄.
• 처음부터 열어 두는 안내에만 닫기 버튼.

❌ Don't제목 링크 복사

• 말풍선 안에 링크 · 버튼(닫기 버튼 말고) — 누를 것이 있으면 Popover.
• 일을 하려면 꼭 읽어야 하는 안내를 말풍선 뒤에 숨기기.
• 한 화면에 처음부터 열린 말풍선 여럿.

Specification제목 링크 복사

help-bubble.yaml 의 규칙을 하나도 빼지 않고 조건마다 그린다 — 웹 · 앱이 Help Bubble · Tooltip 을 만들 때 이 값을 그대로 쓴다. 조건이 없는 Base 가 모든 조합에 걸리고, 뒤의 규칙이 앞의 같은 값을 덮는다. 상태는 enabled 에서 바뀌는 값만 적었다.

SEED 와 다른 점제목 링크 복사

• 바탕은 groo bg-neutral-inverted(SEED neutral-solid 의 역할 짝) — 다크에서는 밝은 말풍선에 짙은 글자(SEED 와 같은 방향).
• 닫기 버튼의 누르는 영역은 44 — SEED 38(기초의 "누르는 영역 44").
• 닫기 버튼의 초점 링은 말풍선 글자색 — groo 브랜드 링은 짙은 말풍선 위에서 3:1 에 못 미친다(SEED 링은 파랑이라 닿는다).
• 화면 끝에서 화살표는 트리거 가운데에 남고 말풍선이 16 보다 가장자리에 붙는다(사용자 결정 2026-10-15) — SEED 는 16 을 지키고 화살표를 옮긴다("조정시 최소 14px").
• z-index 는 specs/z-index.md 의 L4(z-tooltip 210) — 팝오버 · 메뉴 안에서 열어도 그 위에 뜬다. SEED 는 포털 없이 99 로 그려 둘레 상자가 자를 수 있다.

Migration notes제목 링크 복사

2026-10-22 — 알림 고르는 표는 한 벌제목 링크 복사

알리는 일을 고르는 표는 Snackbar 문서 한 벌로 링크하고, 이 문서의 표는 도움말의 자리만 맡는다(사용자 결정 3B — https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX). 값 변경 없음.

2026-10-16 — 예시의 트리거를 검색 · 알림으로제목 링크 복사

상단 바에서 금액 가리기 눈을 뺐다(2026-10-16 사용자 결정 — 구현 세션 질문 Q-017-2b A · Q-017-3c = Q-018-3 B — 그 눈은 켜고 끄지 않고 설정으로 가는 버튼이었다). 처음부터 열어 두는 안내의 예시를 홈 상단 바의 검색(Q-017-2a A 로 더해진 자리)으로, 화면 끝 자리의 예시를 오른쪽 끝 알림으로 바꿨다. 규칙 · 수치는 그대로다.

2026-10-15 — 화면 끝 화살표 · 열림 알림제목 링크 복사

구현 세션 질문 두 가지를 사용자가 정했다.

• 화면 끝의 트리거 — 화살표는 가운데에 남고 말풍선이 가장자리 16 을 넘는다(Q-004-1). "위치" 절의 순서(가운데 → 모서리 14 → 가장자리 16). 앱은 화살표를 비켜 그렸고(16 · 14 를 지킴), 웹은 Radix 가 가운데를 못 가리키면 화살표를 지웠다(cannotCenterArrow) — 둘 다 고친다. 레시피는 트리거 자리를 재어 그쪽 가장자리 여백(collisionPadding)을 min(16, 트리거 가운데 − 20) 로 줄인다. 화살표를 비키는 안 · 옆으로 뒤집는 안 · 지우는 안은 고르지 않았다.
• 스크린 리더 — 초점은 트리거에 두고 열릴 때 제목 · 설명을 알린다(Q-004-2). 앱은 이미 그렇다(liveRegion). 웹은 트리거의 "펼쳐짐" 만 읽고 내용을 읽지 않았다 — 레시피에 열림 알림 자리를 더했다. 초점을 말풍선으로 옮기는 안 · 눌러 열 때만 옮기는 안은 고르지 않았다.

2026-10-08 — "처음부터 열어 두는 안내" 예제목 링크 복사

코드 예에 closeOnInteractOutside={false} 가 빠져 있었다 — 예대로 쓰면 바깥을 누르거나 Tab 으로 다른 칸에 가는 순간 처음 쓰는 사람용 안내가 사라졌다(Behavior 표와 다르다, desk-front #428). 예에 더했다. 레시피 · 사이트의 살아 있는 그림은 이미 그렇게 동작한다. SEED 의 같은 예(HelpBubbleAnchor + defaultOpen + showCloseButton)도 closeOnInteractOutside={false} 를 준다. 사용자 결정 — 비교 페이지 2.

2026-10-02 — SEED Help Bubble 로 새로 둔다제목 링크 복사

사용자가 비교 페이지에서 정했다 — 툴팁과 도움말 말풍선은 SEED 모양 하나(짙은 바탕 · 13 · 모서리 12 · 화살표 · 최대 280), 툴팁은 마우스 · 키보드의 보조이고 터치에서 도움말이 필요하면 눌러서 여는 Help Bubble. 전에는 눌러서 여는 도움말이 따로 없었다.

제품은 앱 적용 단계에서 옮긴다(2026-10-02 조사).

• Desk 웹 — 눌러서 여는 도움말 0(ⓘ 는 늘 보이는 안내 상자 4곳뿐). 키보드로 못 닿는 글자 · 배지에 붙은 설명이 네이티브 title 에만 4곳("기본 캘린더는 숨길 수 없습니다" · "자동 기록" · "하루 전 알림" · "단종 포함") — 터치 · 키보드에서 안 보인다.
• Desk 앱 — 눌러서 여는 도움말 0.
• HR 웹 — 규정 안내 Popover 12곳(→ 화면마다 Help Bubble · Popover 를 고른다), 쓰는 곳이 없는 ⓘ 툴팁 부품 2.