Snackbar

구조는 당근 SEED Snackbar(Apache-2.0)를 따른다 — 짙은 띠 · 아이콘(성공 · 실패에만) · 글 · 액션 하나, 화면 아래 가운데에 한 번에 하나. 값은 groo 토큰이고, SEED 와 다른 자리는 맨 아래 "SEED 와 다른 점" 에 적었다(2026-10-02 사용자 결정). 옛 Sonner(토스트) 스펙을 대신한다.

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

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

톤 · 액션 · 글 길이를 고르고 띄우면 스펙대로 그린 띠가 아래에서 뜨고, 시간이 지나면 사라진다. 마우스를 올리거나 키보드로 옮기면 멈춘다.

import { useSnackbar } from "@/components/ui/snackbar"

const snackbar = useSnackbar()

snackbar.show({
  message: "거래를 삭제했어요.",
  action: { label: "되돌리기", onClick: undo },
})

Anatomy제목 링크 복사

부위

Properties제목 링크 복사

띠제목 링크 복사

최소 44 · 여백 10 + 글 좌우 6(글은 띠 가장자리에서 16) · 모서리 8 · 그림자 없음. 글 14 / 19, 아이콘 24, 액션 14 · 700. 폭은 화면에서 좌우 8 을 뺀 만큼이고 최대 464 — 넓은 화면에서는 가운데에 선다. 글이 길면 줄을 바꾸고 자르지 않는다 — 두 줄 안에서 끝나게 쓴다.

공통

Tone제목 링크 복사

neutral(기본)은 아이콘이 없다. 성공을 눈에 띄게 알릴 때만 positive(체크), 가볍게 실패했을 때 critical(느낌표) — 아이콘 색만 바뀐다. 짙은 띠 위에서 보이게 아이콘 · 액션은 반전 짝 색(fg-*-inverted)이다.

톤

State제목 링크 복사

상태

모션

Guidelines제목 링크 복사

무엇으로 알리나 — 상황 → 고를 것제목 링크 복사

알리는 부품 다섯(Snackbar · Callout · Page Banner · Result Section · Alert Dialog)을 고르는 표는 여기 한 벌이다 — Callout · Page Banner · Help Bubble · Alert Dialog 문서는 자기 줄만 두고 이 표로 링크한다(2026-10-22 사용자 결정 3B — https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX). 나누는 법(일로 나눈다)은 2026-10-02 결정 그대로다.

먼저 묻는다 — 사용자가 지금 답해야 하나? 그렇다면 Alert Dialog. 아니면 얼마나 오래 보여야 하나(잠깐 · 조치할 때까지 · 상태가 풀릴 때까지)와 무엇에 걸린 일인가(방금 한 일 · 그 기능 · 페이지 전체 · 그 영역)로 고른다.

다섯 부품 견주기

수치(폭 · 시간 · 쌓임)는 각 부품의 YAML 이다 — 이 표는 고르는 법만 적는다. 입력칸의 오류(Field)와 몰라도 되는 설명(Help Bubble)은 이 표 밖 — 각 문서의 표가 맡는다.

오류는 자리에서제목 링크 복사

모든 실패를 한곳에서 스낵바로 띄우지 않는다 — 서버가 보낸 글 · 영어 · 코드가 그대로 나가고, 같은 실패가 둘 · 넷씩 뜬다. 각 화면이 실패한 자리에서 알린다: 불러오기 실패는 Result Section, 저장 실패는 폼 맨 위 Callout, 칸 오류는 칸 아래. 스낵바는 그 자리에 둘 곳이 없는 가벼운 실패에만 쓴다.

자리 — 화면 아래 가운데제목 링크 복사

어느 폭이든 화면 아래 가운데다. 탭 바(Bottom Navigation) · 떠 있는 버튼(Floating Action Button) · 바닥 고정 버튼이 있으면 그 위 8 에 서고, 안전 영역(홈 표시줄)을 피한다. 화면 키보드가 올라와 있으면 키보드 바로 위 8 에 선다 — 탭 바 · 바닥 버튼이 키보드 뒤로 가도 띠는 보인다. 웹도 폰 브라우저에서 같다(키보드가 화면을 줄이지 않아도 보이는 화면의 아래 끝을 재어 피할 자리에 더한다). 2026-10-15 사용자 결정 — 구현 세션 질문 Q-003-1. 시트 · 대화상자가 열려 있어도 그 위에 뜬다(z L6). 다만 시트 · 대화상자에서 한 일은 창이 열린 채인지 닫히며 끝나는지로 가른다(2026-10-02 사용자 결정 그대로 — 2026-10-22 사용자 결정 2B 로 상황을 풀어 썼다, https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX).

창이 열린 채 그 안의 결과를 스낵바로 띄우지 않는다 — 시트 위의 띠를 누르면 시트가 바깥 누름으로 닫히고 액션이 먹지 않는다.

시간 · 한 번에 하나제목 링크 복사

액션이 없으면 4초, 있으면 6초. 마우스를 올리거나, 손가락으로 누르고 있거나, 키보드 초점이 들어오면 멈추고, 떠나면 처음부터 다시 센다. 한 번에 하나만 — 새 띠가 오면 지금 띠를 바로 바꾼다(쌓지 않는다). 다만 지금 띠에 액션(되돌리기 · 다시 시도)이 있으면 그 띠는 끝날 때까지(시간 · 액션 · 닫기) 지키고, 새 띠는 그 뒤에 뜬다 — 그 경우만 줄을 세운다(SEED React strategy: "queued"). 기다리는 띠는 하나다 — 그 사이 또 오면 마지막 것만 남는다. 되돌리기 6초(사용자 결정)가 다음 결과에 잘리지 않고, 연달아 저장하는 흔한 경우(액션 없는 결과끼리)는 늦어지지 않는다(2026-10-22 사용자 결정 1B — https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX). 되돌리기 같은 액션은 스낵바에만 두지 않는다 — 시간이 지나면 사라지므로 같은 일을 할 다른 길(목록 · 상세)이 있어야 한다.

글제목 링크 복사

해요체 문장에 마침표(Writing v106) — 무엇이 됐는지 먼저: "거래를 저장했어요." · "거래를 삭제하지 못했어요."(액션 [다시 시도] 가 있으면 한 문장 — 버튼과 같은 말을 되풀이하지 않고, 폰에서 두 줄이 되지 않는다) · 액션이 없으면 "관심 종목에 넣지 못했어요. 잠시 뒤 다시 시도해주세요." 시스템 말("처리가 완료되었습니다") · "실패" 로 끝나는 말 · 서버가 보낸 글 · 영어 · 코드를 쓰지 않는다. 액션은 구체적인 동작 이름 한두 마디("되돌리기" · "잔액 고치기") — "확인" · "취소" 로 뭉뚱그리지 않는다.

큰 글자에서 글이 좁아지는 것은 이 쓰기 규칙으로 막는다 — 글은 두 줄 안, 액션은 한두 마디. 띠 모양은 SEED 와 같다(액션은 줄지 않고 글이 남은 폭에서 줄을 바꾼다). 규칙을 어긴 긴 글 · 긴 액션이 오면 200% 에서 글이 한두 글자씩 세로로 쌓여 띠가 화면을 덮는다 — 문구 검토에서 막는다. 영어 로케일은 액션이 길어지기 쉬우니("Try again" · "Fix balance") 번역 문구도 같은 규칙으로 본다(2026-10-17 사용자 결정 — 03-F 2B, https://claude.ai/artifact/F5SKUbGEWDG82F7B5RRjQB — 추천 2A "글 칸 반 폭 아래로 줄지 않음 · 액션 아래 줄" 이 아니다).

코드제목 링크 복사

레시피 recipes/shadcn/components/ui/snackbar.tsx 를 쓴다. 앱 맨 위에 SnackbarProvider 를 한 번 두고, 띄울 때는 useSnackbar() 의 show 를 부른다. 탭 바 · 바닥 버튼처럼 띠가 피해야 할 것은 SnackbarAvoidOverlap 으로 감싼다. 아래 미리보기는 스펙 값으로 그린 모습이다.

결과 알리기제목 링크 복사

import { useSnackbar } from "@/components/ui/snackbar"

const snackbar = useSnackbar()

await saveTransaction(draft)
snackbar.show({ message: "거래를 저장했어요." })

되돌리기 — 액션이 있으면 6초제목 링크 복사

snackbar.show({
  message: "거래를 삭제했어요.",
  action: { label: "되돌리기", onClick: () => restoreTransaction(id) },
})

// 가볍게 실패 — 다시 하면 되는 일만. 저장 · 불러오기 실패는 그 자리에서 알린다.
// 켜고 끄는 단추(관심 등록)는 되돌린 뒤 같은 요청을 다시 보내는 "다시 시도" 를 단다(Toggle 20A)
snackbar.show({
  tone: "critical",
  message: "관심 종목에 넣지 못했어요. 다시 시도해주세요.",
  action: { label: "다시 시도", onClick: () => setWatched(stock.id, true) },
})

피할 자리 — 탭 바 · 바닥 버튼제목 링크 복사

import { SnackbarAvoidOverlap, SnackbarProvider } from "@/components/ui/snackbar"

<SnackbarProvider>
  <App />
  <SnackbarAvoidOverlap>
    <TabBar />
  </SnackbarAvoidOverlap>
</SnackbarProvider>

Behavior제목 링크 복사

Accessibility제목 링크 복사

Do / Don't제목 링크 복사

✅ Do제목 링크 복사

• 방금 한 일의 결과를 한 문장으로 — "거래를 저장했어요."
• 되돌릴 수 있는 삭제에 "되돌리기" — 그리고 다른 길도 둔다. 되돌리기가 달린 띠는 다음 결과에 밀리지 않는다.
• 시트를 연 채 결과를 봐야 하면 그 안 Callout, 닫으며 끝나면 닫힌 뒤 스낵바.
• 탭 바 · 바닥 버튼은 SnackbarAvoidOverlap 으로 피한다.

❌ Don't제목 링크 복사

• 모든 실패를 한곳에서 스낵바로 — 서버 글 그대로 · 중복.
• 조치가 필요한 오류 · 계속 보여야 할 경고를 스낵바에.
• 띠를 여러 장 쌓기.
• 시트 · 대화상자가 열린 채 그 안의 결과를 스낵바로 — 띠를 누르면 시트가 닫히고 액션이 먹지 않는다(그 안 Callout).
• "확인" 액션.

Specification제목 링크 복사

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

SEED 와 다른 점제목 링크 복사

• 아이콘 · 액션 색은 반전 짝 역할(v115 — fg-positive-inverted · fg-critical-inverted · fg-brand-inverted) — SEED 는 밝은 바탕용 색을 그대로 써 짙은 띠 위에서 대비가 모자란다(다크 아이콘 2.5:1 · 액션 2.67:1).
• 액션이 있으면 6초(사용자 결정 2026-10-02) — SEED 는 늘 4초.
• 글은 문장이면 마침표(Writing v106) — SEED 는 한 문장이면 뺀다.
• 모션 줄이기면 투명도만(v104) — SEED 는 그대로 돈다.
• 보조 기술용 닫기는 키보드 초점이 오면 보인다 — SEED 는 안 보이는 채로 Tab 이 선다.
• 포커스 링은 띠 글자색 — groo 브랜드 링은 짙은 띠 위에서 3:1 에 못 미친다.
• 아이콘은 lucide 선 아이콘(v106).
• z-index 는 specs/z-index.md 의 L6(z-snackbar 400).
• 띠 안에서 닫히면 초점을 돌려준다 — 띠에 들어오기 전 자리로. SEED 는 body 로 떨어뜨려 키보드 사용자가 처음부터 다시 찾아야 한다.
• 화면 키보드가 있으면 키보드 바로 위 8(사용자 결정 2026-10-15) — SEED 는 키보드를 말하지 않는다.
• 아래 자리는 안전 영역과 피할 자리 중 큰 쪽 — SEED 는 둘을 더해, 안전 영역을 품은 탭 바 위에서는 그만큼 더 뜬다.
• 새 띠는 바로 바꾸고, 액션이 달린 띠만 지킨다 — SEED 디자인 문서는 늘 큐("현재 표시 중인 항목이 사라진 후 순차적으로"), SEED React 는 기본이 바로 바꿈(immediate)이고 strategy: "queued" 를 띠마다 고른다. groo 는 액션(되돌리기 · 다시 시도)이 있는 띠가 떠 있을 때만 줄을 세운다(2026-10-22 사용자 결정 1B — https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX).

Migration notes제목 링크 복사

2026-10-22 — 액션 띠는 지킨다 · 알림 표는 한 벌 · 시트 안 결과 셋제목 링크 복사

사용자가 알리고 기다리는 것 정리 페이지에서 모두 추천 안으로 정했다.

• 새 띠(1B) — 바로 바꾸되, 지금 띠에 액션(되돌리기 · 다시 시도)이 있으면 끝날 때까지 지키고 새 띠는 뒤에(기다리는 띠는 하나 — 마지막 것만). 10-02 비교 페이지는 두 안 모두 "바로 바꾼다(SEED React 기본)" 로 그렸고 바꾸기 ↔ 줄 세우기는 묻지 않았다(따라오는 것). 레시피 snackbar.tsx 의 상태(떠 있는 띠 하나 + 기다리는 것 하나)에 조건 하나를 더했다 · 사이트 데모 · 시간 그림 · yaml 모션 비고. 제품(웹 ds snackbar.tsx · 앱 p_snackbar.dart)은 머지된 코드라 구현 지시로 고친다.
• 시트 · 대화상자 안 결과(2B) — 결정(그 안 Callout · 스낵바는 닫힌 뒤)은 그대로, 상황 셋의 표로 풀어 썼다(열린 채 → Callout · 닫으며 → 닫힌 뒤 스낵바 · 칸 하나 → 칸 아래).
• "무엇으로 알리나" 표(3B) — 다섯 문서에 따로 있던 표를 이 문서 한 벌(상황 → 고를 것 + 다섯 부품 견주기)로 모으고, Callout · Page Banner · Help Bubble · Alert Dialog 는 자기 줄만 두고 링크한다. Page Banner ↔ Callout 표에 SEED 의 "용도" · "Sticky" 두 줄을 더했다. 값 변경 없음.

2026-10-15 — 키보드 위 자리 · 앱의 Tab제목 링크 복사

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

• 화면 키보드가 올라와 있으면 키보드 바로 위 8(사용자 결정 — Q-003-1). 앱은 이미 그렇다. 웹은 position: fixed; bottom 만 써서 폰 브라우저에서 띠가 키보드 뒤로 갔다 — 보이는 화면(visualViewport)의 아래 끝을 재어 피할 자리에 더한다(레시피). 키보드가 있을 때 화면 위쪽에 띄우는 안 · 키보드가 내려간 뒤에 띄우는 안은 고르지 않았다.
• 앱의 화면 Tab 은 띠에 닿지 않는다(정리 — Q-003-2). 띠는 화면 밖(시트 · 대화상자 위)에 그려진다. 액션은 다른 길이 있어야 하고("시간 · 한 번에 하나"), 시트 · 대화상자 안의 결과는 그 안 Callout 이라("자리") 키보드로 띠에 닿지 못해도 잃는 일이 없다. Behavior 의 Tab 줄에 적었다.
• 자리가 옮겨 갈 때의 200ms easing 을 YAML(region.offsetDuration · offsetEasing)에 적었다 — 웹 · 앱이 이미 같은 값을 쓰고 SEED snackbar.region.offsetDuration 과 같다.

2026-10-02 — SEED Snackbar 로 새로 둔다(옛 Sonner 를 대신)제목 링크 복사

사용자가 비교 페이지에서 정했다 — 알림을 일로 나누고(결과 · 가벼운 실패만 스낵바), 오류는 자리에서 알리고(전역 오류 토스트를 걷는다), SEED 모양 + 반전 짝 색, 아래 가운데, 액션이 있으면 6초, 마침표는 v106 그대로. 옛 Sonner(흰 카드 · 그림자 · 아이콘 넷 · 글 16/600 · 위 가운데 · 3장 쌓기)는 걷었다 — 옛 스펙은 sonner.history/v-pre-seed-feedback.*. 2026-09-22 의 "글은 자르지 않는다" 는 그대로 둔다.

제품은 앱 적용 단계에서 옮긴다(2026-10-02 조사 — Desk 웹 · HR 은 크로미움에 띄워 쟀고, Desk 앱은 위젯 테스트로 쟀다).

• Desk 웹 — sonner 37곳(위 가운데) + 손으로 만든 토스트 2(반복 거래 · 별빛, 아래 가운데 · 역할 없음). 전역 오류 토스트가 서버 글을 그대로(11곳은 화면이 또 띄운다). 시트가 열린 동안 띠를 누르면 시트가 닫히고 액션이 먹지 않는다. 키보드 초점에서 멈추지 않는다. 더치페이 "송금 요청을 보냈어요" 는 아무것도 보내지 않는다.
• Desk 앱 — showPSnackBar 36(아래). 전역 오류 스낵바(값을 바꾸는 요청만, 영어 대체 문구 "Server error"), 높이를 줄인 시트 4곳에서 띠가 시트 뒤에 그려져 안 보인다, 대화상자 위로는 딤 아래. 액션 스낵바가 스크린리더가 켜져도 6초 뒤 사라진다.
• HR 웹 — sonner 46(위 가운데, 앱 테마가 아니라 OS 테마, 스타일 클래스가 먹지 않는다). 전역 오류 토스트가 GET 까지 · 재시도마다(실패 한 번에 최대 4), 19곳은 화면이 또 띄운다. 저장 성공을 알리지 않는 화면이 많다(30파일).