Tooltip

구조는 당근 SEED Help Bubble Tooltip(Apache-2.0)을 따른다 — Help Bubble 과 같은 말풍선(짙은 바탕 · 13 · 모서리 12 · 화살표 · 최대 280)을 마우스 · 키보드로 여는 것이다. 값은 groo 토큰이고, SEED 와 다른 자리는 맨 아래 "SEED 와 다른 점" 에 적었다(2026-10-02 사용자 결정).

수치 원본은 help-bubble.yaml의 opens: hover 다 — 모양은 Help Bubble 과 한 벌이다. 툴팁만의 수치 파일(tooltip.yaml · 내보낸 tooltip.json)은 두지 않는다 — SEED 도 rootage 에 help-bubble 하나다. 웹 · 앱의 검사는 툴팁을 help-bubble 의 opens: hover 로 잰다(구현 세션 질문 Q-009-1). 수치 표 자리([표: …])와 그림 자리([그림: …])는 사이트가 그 파일로 그린다 — GitHub 에서는 그 파일 · 그림 코드로 가는 링크로 보인다.

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

글 길이 · 위치를 고르면 스펙대로 그린 툴팁과 그 코드가 바뀐다. 마우스를 올리거나 Tab 으로 초점을 옮겨 열 수 있다.

import { Settings } from "lucide-react"
import { TopNavigationIconButton } from "@/components/ui/top-navigation"
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"

{/* 화면에 한 번 — 이어서 여는 툴팁은 기다리지 않는다 */}
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <TopNavigationIconButton aria-label="설정" onClick={openSettings}><Settings /></TopNavigationIconButton>
    </TooltipTrigger>
    <TooltipContent>설정</TooltipContent>
  </Tooltip>
</TooltipProvider>

Anatomy제목 링크 복사

Properties제목 링크 복사

말풍선제목 링크 복사

모양 · 여백 · 위치는 Help Bubble 과 같다 — 위아래 10 · 좌우 12, 모서리 12, 글 13 / 18, 최대 280, 화살표 끝과 트리거 사이 4. 툴팁은 글 하나만 둔다(굵게 — Help Bubble 의 제목 자리).

말풍선

여는 방식제목 링크 복사

마우스를 올리면 200ms 뒤에 열고, 트리거와 말풍선을 모두 벗어나면 100ms 뒤에 닫는다 — 말풍선 위로 포인터를 옮겨도 닫히지 않는다. 키보드 초점이 오면 바로 연다. 하나가 열린 뒤 옆 트리거로 옮기면 기다리지 않고 모션 없이 바로 바꿔 연다. 손가락으로 누르면 열지 않는다.

여는 방식

모션

Guidelines제목 링크 복사

툴팁은 보조다제목 링크 복사

툴팁은 마우스 · 키보드에서만 열린다. 그래서 툴팁에만 있는 정보는 손가락으로 쓰는 사람에게 없다.

• 이름은 aria-label — 아이콘 버튼의 이름은 늘 aria-label 에 둔다. 툴팁은 그 이름을 마우스 · 키보드 사용자에게 보여 주는 것이지 이름을 대신하지 않는다.
• 막힌 이유는 가까운 글로 — 막힌 버튼은 초점을 받지 못해 키보드로 툴팁을 열 수 없다. 왜 안 되는지는 버튼 가까이 글로 보인다("복사할 지난달 예산이 없어요.").
• 폰에서도 읽어야 하면 Help Bubble — ⓘ 를 눌러 여는 말풍선.
• 네이티브 title 은 쓰지 않는다 — 터치 · 키보드에서 뜨지 않고 모양도 브라우저마다 다르다. 이름은 aria-label, 설명은 툴팁 · 보이는 글.

어디에 쓰나제목 링크 복사

짧게제목 링크 복사

한 줄이 원칙이다 — "검색" · "알림" · "필터 초기화". 최대 280 을 넘기면 줄을 바꾸지만, 두 줄이 넘는 설명은 Help Bubble 로 옮긴다. 이름이면 명사 · 동사구 그대로, 문장이면 해요체에 마침표.

코드제목 링크 복사

레시피 recipes/shadcn/components/ui/tooltip.tsx 를 쓴다(Radix Tooltip 위 — 모양은 Help Bubble 과 같은 클래스). 화면에 TooltipProvider 를 한 번 두면 이어서 여는 툴팁이 기다리지 않는다. 아래 미리보기는 스펙 값으로 그린 모습이다.

아이콘 버튼의 이름제목 링크 복사

import { Settings } from "lucide-react"
import { TopNavigationIconButton } from "@/components/ui/top-navigation"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

{/* Desk 웹 데스크톱 머리의 아이콘 버튼(알림 · 설정) */}
<Tooltip>
  <TooltipTrigger asChild>
    {/* 이름은 aria-label — 툴팁은 그 이름을 마우스 · 키보드 사용자에게 보여 준다 */}
    <TopNavigationIconButton aria-label="설정" onClick={openSettings}><Settings /></TopNavigationIconButton>
  </TooltipTrigger>
  <TooltipContent>설정</TooltipContent>
</Tooltip>

막힌 버튼 — 이유는 툴팁이 아니라 가까운 글제목 링크 복사

<div className="flex flex-col gap-1.5">
  <Button variant="neutralWeak" disabled={!hasLastMonth} aria-describedby="copy-reason">
    지난달 예산 복사
  </Button>
  {!hasLastMonth && (
    <p id="copy-reason" className="text-t3 text-fg-neutral-subtle">복사할 지난달 예산이 없어요.</p>
  )}
</div>

Behavior제목 링크 복사

Accessibility제목 링크 복사

Do / Don't제목 링크 복사

✅ Do제목 링크 복사

• 아이콘 버튼에는 aria-label 과 같은 글의 툴팁.
• 한 줄로 짧게.
• 막힌 이유는 버튼 가까이 글로.
• 화면에 TooltipProvider 한 번.

❌ Don't제목 링크 복사

• 이름 · 막힌 이유 · 꼭 알아야 하는 정보를 툴팁에만.
• 네이티브 title.
• 툴팁 안에 링크 · 버튼.
• 글자가 이미 보이는 버튼에 같은 말의 툴팁.

Specification제목 링크 복사

툴팁은 Help Bubble 과 같은 help-bubble.yaml 을 쓴다 — opens: hover 의 규칙이 툴팁이다.

SEED 와 다른 점제목 링크 복사

• 말풍선 위로 포인터를 옮겨도 닫히지 않는다(WCAG 1.4.13) — SEED 는 기본으로 닫히고 keepOpenOnContentHover 를 켜야 남는다.
• 바탕은 groo bg-neutral-inverted — Help Bubble 과 같다.
• z-index 는 specs/z-index.md 의 L4(z-tooltip 210) — SEED 는 포털 없이 99.

Migration notes제목 링크 복사

2026-10-16 — 머리의 예시를 알림 · 설정으로제목 링크 복사

데스크톱 머리에서 금액 가리기 눈을 뺐다(2026-10-16 사용자 결정 — 구현 세션 질문 Q-017-3c = Q-018-3 B, Top Navigation). 툴팁 예시 · 그림의 트리거를 머리에 남은 알림 · 설정으로 바꿨다. 규칙은 그대로다.

2026-10-15 — 수치 파일 하나 · 앱에도 둔다제목 링크 복사

구현 세션 질문 두 가지를 있는 규칙으로 정리했다.

• tooltip.json 을 따로 만들지 않는다(Q-009-1) — 원본은 help-bubble.yaml 하나다(SEED 도 하나). 따로 두면 같은 말풍선을 두 곳에 정의하게 된다. 웹 카탈로그 · 검사기는 툴팁을 help-bubble 의 opens: hover 로 잡는다.
• 앱에도 둔다(Q-009-2) — 2026-10-02 8A(마우스 · 키보드에서만, 터치에 기대지 않음)와 2026-10-08 "앱도 하드웨어 키보드로 옮길 때 누를 수 있는 것은 모두 초점을 받는다" 가 답한다. 손가락 사용자에게는 차이가 없고(길게 누르기 툴팁은 그때 고르지 않았다), 키보드 · 마우스를 붙인 사용자에게는 이름이 보인다. 옛 길게 누르기 툴팁은 옮길 때 걷는다.

2026-10-02 — SEED Help Bubble Tooltip 으로 바꾼다제목 링크 복사

사용자가 비교 페이지에서 정했다 — 툴팁 모양은 SEED Help Bubble(짙은 바탕 · 13 · 모서리 12 · 화살표 · 최대 280, 옛 반전 13 · 모서리 2 · 화살표 없음 · 그림자에서), 쓰임은 SEED(마우스 200 / 100ms · 키보드 바로 · 터치에 기대지 않음 · 이름은 aria-label · 막힌 이유는 가까운 글 · title 걷음). 옛 스펙은 tooltip.history/v-pre-seed-tooltip.* — 수치 파일(tooltip.yaml)은 help-bubble.yaml 로 합쳤다.

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

• Desk 웹 — 툴팁은 접힌 사이드바 하나(지연 0ms, 태블릿 터치로 탭하면 안 뜬다). 네이티브 title 29곳 — 아이콘 버튼의 유일한 이름 7곳, 막힌 버튼의 이유 2곳(예산 "복사할 지난달 예산이 없어요"), 키보드로 못 닿는 설명 4곳. 데스크톱 줄의 아이콘 6개는 이름도 툴팁도 없다.
• Desk 앱 — PTooltip 17(반전 13 · 모서리 2) · Material 기본 툴팁 9(회색 14 · 모서리 4), 길게 누르면 뜬다. 아이콘 버튼 37 중 20 이 이름이 없다.
• HR 웹 — 툴팁은 브랜드 파랑 12 · 모서리 6 · 화살표(바탕 대비 4.95 · 4.73), 지연 늘 0(Provider 가 겹친다). 네이티브 title 11곳.
• 차트 · 데이터 툴팁(웹 7 · 앱 8 · HR 2)은 이 스펙이 아니다 — groo 차트 부품으로 따로 정하고 말풍선 모양만 맞춘다.