Alert

한눈에#

Toast가 "지나가는 알림"이라면 Alert는 페이지에 머무는 배너입니다 — 폼 상단 오류 요약, 페이지 공지처럼 콘텐츠와 함께 읽혀야 할 때 씁니다.

사용 시점#

폼·페이지에 머물러 읽혀야 할 배너면 Alert — 그 외에는 목적에 맞는 컴포넌트를 가리킵니다.

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

import { Alert } from '@wds/ui-web';

<Alert title="저장되었습니다">변경 내용이 반영되기까지 잠시 걸릴 수 있습니다.</Alert>

변형#

의미색은 채운 아이콘 배지가 전담합니다 — 배지 채움은 *-text(깊은 잉크), 글리프는 surface입니다. 두 색은 테마마다 명도 양 끝에 있어 라이트·다크 모두 AA 4.5:1을 넘기고, 그 대비는 빌드 게이트가 강제합니다. (warning은 amber.500을 채우면 흰 글리프가 1.7:1로 미달이라, 더 진한 warning-text를 배지 채움색으로 씁니다.)

외형#

appearance로 두 외형을 고릅니다 — 기본 standard(뉴트럴 표면 + 떠오름 + solid 배지)와 tonal(의미색 8% 틴트 + 평면 + soft 배지 + 액센트 제목). 폼·리스트에 차분히 섞일 땐 standard, 페이지 상단 공지처럼 의미를 강하게 드러낼 땐 tonal을 권합니다.

tonal은 8% 틴트 위 *-text 제목이라 AA 4.5:1을 유지합니다(12%는 미달 — 기존 사용처 가드 실측). 배지는 standard가 solid(진한 채움 + 흰 글리프), tonal이 soft(연한 틴트 원 + 액센트 글리프) 로 갈립니다 — 글리프는 비텍스트라 두 외형 모두 대비를 확보합니다.

onDismiss를 주면 후행에 닫기 IconButton이 렌더됩니다. 가시성은 소비자가 소유합니다 — 클릭 시 onDismiss만 호출되고 실제 제거는 소비자가 합니다.

액션#

actions에 액션을 주면 본문 아래 액션 행이 렌더됩니다 — Material 3 banner처럼 변형 액센트색 텍스트 링크가 기본형입니다. 액션 색은 Alert이 변형 액센트(*-text)를 .actions에 상속 제공하므로, 링크는 color: inherit만으로 올바른 색을 받습니다(인라인 스타일 0). 닫기(onDismiss)와 병행 가능하고, ghost 버튼 등 다른 액션 위젯도 슬롯에 그대로 넣을 수 있습니다.

크기#

size prop이 없습니다 — 부모 폭을 채우는 유동 배너입니다. children을 생략하면 제목 한 줄짜리 컴팩트 배너가 됩니다. 배지는 본문·액션 유무와 무관하게 항상 제목 첫 줄 중심에 정렬됩니다(음의 마진으로 줄 위로 끌어올림).

상태#

기본은 정적 배너라 인터랙션 상태가 없습니다. onDismiss를 주면 후행 닫기 버튼이 렌더되어 닫을 수 있는 배너가 됩니다 — 단, 가시성은 소비자가 소유합니다 (클릭 시 onDismiss만 호출되고, 실제 제거는 소비자가 Alert를 언마운트). Toast/Modal이 제어를 소비자에게 넘기는 방식과 동일합니다. 닫기 버튼 접근성 이름은 기본 닫기이며 dismissLabel로 재정의합니다. 지나가며 자동 해제되는 알림은 Toast를 쓰세요.

Props#

접근성#

• error만 role="alert" — 마운트 시 즉시 낭독됩니다. 나머지 변형은 정적 콘텐츠라 role 없이 문서 흐름대로 읽힙니다
• 아이콘은 장식(aria-hidden) — 의미는 색 + 제목 텍스트가 병행 전달합니다(색맹 안전)
• 잉크는 *-text 토큰 — 라이트/다크 모두 AA 대비가 빌드 게이트로 보장됩니다
• 닫기 버튼은 아이콘 전용이라 접근성 이름이 필수입니다 — 기본 닫기, dismissLabel로 재정의(예: '공지 닫기')
• Alert 자체는 상태·이펙트가 없습니다 — onDismiss는 콜백만 받아 가시성 제어를 소비자에게 위임하므로 컴포넌트 RSC 호환성을 유지합니다

토큰#

component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).

관련#