Banner

Banner는 광고·프로모션·넛지 전용 컴포넌트다 (mobile · desktop 공통). 작업 흐름을 막지 않는 비-모달 방식으로 행동을 유도한다.

오류·경고는 Banner를 사용하지 않는다 — 일시적 피드백·경고는 Toast, 사용자 액션이 필수인 오류는 AlertDialog로 처리한다.

Toast와의 차이: Toast는 일시적 피드백(4–6s 자동 dismiss)이고, Banner는 사용자가 명시적으로 닫거나 조건이 해소될 때까지 지속적으로 노출된다.

Mobile

모바일 배너는 두 가지 variant를 가진다. variant는 시각 구조를 결정한다 — 색상 의미용 variant는 없다.

default variant — 기본 안내 배너

flex-direction: row  ·  align-items: center
padding: 12px 20px  ·  gap: 10px
background: #E7E5E4 (stone-200)  ·  border: 1px solid #E7E5E4
border-radius: 8px

[icon 20px] + 텍스트 컬럼 구조. 텍스트 컬럼은 title 위 · description 아래 세로 스택이며, description 행에는 16px chevron(ChevronRight)을 gap 2px로 붙여 탐색 가능함을 표시할 수 있다.

• title: Pretendard Bold 14 · line-height 1.5 · letter-spacing -0.3px · brown-800 #3A2018
• description: Pretendard Regular 14 (Mo/Body2 14) · line-height 1.5 · letter-spacing -0.3px · stone-500 #78716C

nudge variant — 강한 행동 유도 배너

flex-direction: row  ·  justify-content: center  ·  align-items: center
padding: 10px 14px
background: #FFFFFF  ·  border: 1px solid #E7E5E4 (stone-200)
border-radius: 10px

내부는 콘텐츠 행(gap 12px) = 텍스트 컬럼(flex-1, gap 6px) + 우측 CTA 버튼.

• title: Pretendard SemiBold 12 (Mo/Tip 12 SB) · line-height 1.1 · letter-spacing -0.2px · blue-900 #1E3A8A
• description: Pretendard Regular 12 (Mo/Tip 12) · line-height 1.2 · letter-spacing -0.2px · grey-900 #212121
• CTA: bg brown-800 #3A2018 · padding 8px · radius 6px · gap 10px — 16px icon + label Pretendard Bold 14 (Mo/Button1 14) · line-height 1.2 · #F8F2F0

흰 배경과 중앙 정렬로 주변 UI에서 시각적으로 부각된다. 더 강한 CTA가 필요할 때 사용한다. 색상 의미는 배경이 아닌 CTA 버튼으로 전달한다. close 버튼은 사용하지 않는다.

nudge 배너 확장 (collapsed ⇄ expanded)

mobile nudge 배너는 필요한 경우 아래 확장 상태로 펼쳐질 수 있다. 확장 상태에는 접기 버튼을 반드시 포함한다.

flex-direction: column  ·  gap: 10px
padding: 14px 0 20px  (콘텐츠 행은 각자 px 20px)
background: #FFFFFF  ·  border-radius: 20px
shadow: 0 -11px 24px rgba(43,47,49,0.15)   ← 하단 고정 기준 (위쪽 그림자)

구성 (위 → 아래)

1. 접기 버튼 행 — 우측 정렬 chevron 20px. 확장 상태에서 필수.
2. 콘텐츠 컬럼 (px 20 · gap 12)
   • label: Mo/Tip 12 SB · blue-900 #1E3A8A — 접힌 상태(nudge) title과 동일 토큰
   • title: Mo/Subtitle1 18 — SemiBold 18 · lh 1.3 · ls -0.2px · stone-950 #0C0A09
   • body: Mo/Body2 14 — Regular 14 · lh 1.5 · ls -0.3px · stone-600 #57534E (강조는 Bold span)
   • divider: 1px · stone-200
   • benefit list (gap 4px): 행 = check 아이콘 + PC,Tablet/Tip1 14 (Regular 14 · lh 20px · ls -0.7px · stone-900 #1C1917) · px-[6px] py-[5px] rounded-[8px] · bg blue-50 #EFF6FF(강조 항목) / stone-100 #F5F5F4(일반 항목)
3. CTA 행 (px 20) — full-width · bg brown-800 #3A2018 · radius 10px · px-[20px] py-[10px] · gap 10px — 20px icon + label Mo/Button1 16 (Bold 16 · lh 24px · ls -0.3px) · #FFFFFF

확장 동작 — 위치별 축 고정

chevron은 항상 접히는 방향을 가리킨다. 하단 고정이 기준 케이스이며, 상단 고정은 이를 수직 미러링한다.

Mobile Preview

Desktop

데스크탑 배너의 default variant는 아래 스펙을 따른다. nudge variant는 모바일과 동일한 구조(흰 배경 · 중앙 정렬 · 강한 CTA)를 사용한다 — Token Mapping 참조.

flex-direction: row  ·  align-items: flex-end  ·  gap: 10px
padding: 21px
background: #FDFDFC (grey-99)  ·  border: 1px solid #E7E5E4 (stone-200)
border-radius: 14px
shadow: 0 1px 1.5px rgba(0,0,0,.04), 0 1px 1px rgba(0,0,0,.02)

• 좌측 텍스트 컬럼 (height 54px, space-between)
  • eyebrow: Pretendard Medium 16 · line-height 26px · letter-spacing -0.05px · brown-400 #885F53
  • title: Pretendard Bold 18 · line-height 26px · letter-spacing -0.05px · #151619
• 우측 컬럼 (items-end · justify-between): 상단 illustration 슬롯(앱 아이콘 등) + 하단 CTA 버튼
  • CTA: bg brown-700 #5C372B · radius 8px · padding 10px (left 10 / right 6) · 우측 컬럼 full-width — label Pretendard Bold 14 · line-height 1.4 · letter-spacing -0.05px · #F8F2F0

description prop은 데스크탑 default에서 title 위 eyebrow로 렌더링된다.

Desktop Preview

Anatomy

default variant

[icon 20]  title (Bold 14 · brown-800)              ← 텍스트 컬럼은 세로 스택
           description (Regular 14 · stone-500) [›16]
←─ gap 10px ─→                    └ gap 2px ┘

nudge variant

←──────────── px 14 · py 10 ────────────→
[ title (SemiBold 12)       ]  [ CTA: icon 16 + label (Bold 14) ]
[ description (Regular 12)  ]       ↑ bg brown-800 · r6 · p8
 └ 텍스트 컬럼 gap 6px ┘       ←─ 행 gap 12px ─→

Desktop default

←───────────── p 21 · r 14 · bg grey-99 · shadow ─────────────→
[ eyebrow (Medium 16 · brown-400) ]      [ illustration       ]
[ title   (Bold 18 · #151619)     ]      [ CTA (full-width)   ]
 └ 좌측 텍스트 컬럼 (h 54) ┘              └ 우측 컬럼 items-end ┘

Variants

variant는 default · nudge 두 가지뿐이다 (desktop · mobile 공통). variant는 시각 구조를 결정한다 — 색상 의미용 variant는 없으며, 오류·경고용 variant도 없다 (Toast / AlertDialog 사용).

색상 의미는 배경이 아닌 아이콘 선택과 카피, CTA 버튼으로 전달한다.

Token Mapping

Variant별 구조 토큰 (Mobile)

Variant별 구조 토큰 (Desktop)

Typography

nudge는 항상 흰 배경(bg-white)을 사용한다. 색상 의미는 CTA 버튼으로 전달.

States

visible · dismissed · collapsed ⇄ expanded (mobile nudge 배너)

• dismissed: dismissKey로 AsyncStorage / localStorage에 저장. 재진입 시 표시하지 않음.
• 자동 재노출 기간이 필요한 경우 dismissKey에 날짜를 포함 (promo-2026-q2).
• collapsed ⇄ expanded: mobile nudge 배너는 확장 콘텐츠를 가질 수 있다. 확장 상태에는 접기 버튼 필수. 축 고정·확장 방향은 Mobile → nudge 배너 확장 참조 — 하단 배치 시 하단 변 고정·위로 확장, 상단 배치 시 상단 변 고정·아래로 확장.

Props

type BannerProps = {
  variant?: 'default' | 'nudge'   // default: 'default' — 광고·넛지 전용, 오류·경고 variant 없음
  icon?: ReactNode                // default variant의 20px leading 아이콘
  title: string
  description?: string            // mobile: title 아래 · desktop: title 위 eyebrow
  illustration?: ReactNode        // desktop 전용. 우측 상단 콘텐츠 슬롯
  expandedContent?: ReactNode     // mobile nudge 배너 확장 영역. expanded 시 접기 버튼 자동 표시(필수)
  position?: 'top' | 'bottom'     // 축 고정 위치 — bottom: 위로 확장 · top: 아래로 확장 (default: 'bottom')
  action?: ReactNode              // Button size="sm" 또는 text link
  onClose?: () => void            // undefined면 close 버튼 미표시 (nudge에서는 생략 권장)
  dismissKey?: string             // 중복 노출 방지 키
}

Usage

{/* default */}
<Banner
  title="캘린더를 연동해보세요"
  description="오늘 미팅을 한눈에"
  illustration={<CalendarAppIcons />}
  action={<Button size="sm">캘린더 연동</Button>}
  onClose={dismiss}
  dismissKey="calendar-connect-nudge"
/>

{/* default — illustration 없이 */}
<Banner
  title="데스크탑 앱을 설치해보세요"
  description="더 많은 기능이 기다려요"
  action={<Button size="sm">설치하기</Button>}
  onClose={dismiss}
  dismissKey="desktop-install-nudge"
/>

{/* nudge — 강한 CTA */}
<Banner
  variant="nudge"
  title="무료체험이 끝났어요."
  description="구독 후 새 기록을 시작할 수 있어요."
  action={<Button size="sm">구독하기</Button>}
/>

A11y

• role="status" — 광고·넛지이므로 화면 판독기가 현재 작업을 방해하지 않고 읽음 (role="alert"는 사용하지 않음 — 오류·경고는 Banner가 아님)
• close 버튼: accessibilityLabel="배너 닫기" 필수
• 아이콘 단독으로 의미를 전달하지 않는다 — title 텍스트가 항상 존재해야 함

Do / Don't

• Do: 광고·프로모션·넛지 목적에만 사용한다 (mobile · desktop 공통)
• Do: 한 화면에 Banner는 한 개만
• Do: dismissKey를 사용해 사용자가 닫은 배너의 재노출을 막는다
• Do: action은 1개, 레이블은 동사 단어 ("설치하기", "업그레이드", "구독하기")
• Do: expanded 상태에는 접기 버튼을 반드시 포함한다 — chevron은 접히는 방향을 가리킴
• Do: 확장 시 화면 내 위치 기준으로 축을 고정한다 — 하단 배너는 하단 고정 후 위로, 상단 배너는 상단 고정 후 아래로
• Don't: 오류·경고·상태 알림을 Banner로 표현하지 않는다 — 일시적 피드백은 Toast, 사용자 액션이 필수인 오류는 AlertDialog
• Don't: 동일 목적의 배너를 중복 노출하지 않는다
• Don't: Banner 안에 다른 Banner를 중첩하지 않는다
• Don't: nudge variant의 title·description을 각 2줄 이상으로 쓰지 않는다 — 컴팩트 레이아웃이 깨짐
• Don't: nudge variant에 close 버튼을 넣지 않는다 — 중앙 정렬 구조와 충돌함

관련 컴포넌트

• Toast — 일시적 피드백·경고 (4–6s 자동 dismiss). 오류·경고는 Banner 대신 여기로.
• AlertDialog — 사용자 액션이 필수인 오류·확인. critical 오류는 Banner 대신 여기로.
• Card — 지속적 정보 컨테이너 (dismiss 없음)
• Badge — 인라인 상태 라벨