v0.10.0

ComponentsP3 본문

Avatar

사용자/팀 표시 — src 이미지 또는 이름 이니셜 폴백(primary-subtle 원형). 서로게이트 쌍 안전 이니셜, 3단 크기.

마지막 업데이트 2026-06-11

한눈에#

사용자·팀의 정체성을 표시합니다 — src 이미지가 있으면 원형에 채우고, 없으면 name의 첫 글자 이니셜로 폴백합니다(이모지처럼 서로게이트 쌍으로 표현되는 글자도 안전하게 잘림).

  • 이미지·이니셜 폴백
  • 3 크기(sm·md·lg)
  • 서로게이트 안전
  • role=img

이니셜 폴백 배경은 primary-subtle + primary-text(AA) — 이니셜 글자는 장식(이중 낭독 없음)

사용 시점#

사용자·팀의 정체성을 표시하면 Avatar — 상태 표식이나 정체성+상태 카드는 다른 컴포넌트입니다.

쓴다

사용자·팀 정체성을 이미지 또는 이름 이니셜로 표시

대신 Badge
Badge

사용자가 아니라 상태·개수를 표식할 때

대신 AgentCard
AgentCard

정체성 + 상태·메타를 함께 담은 엔티티 카드가 필요할 때

플레이그라운드#

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

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

<Avatar name="김위즈" />

변형#

이미지/이니셜 두 모드입니다. 이미지는 src를 주면 object-fit: cover로 원형에 맞춰 채워집니다:

<Avatar name="배현영" src="/team/hy-bae.jpg" />
<Avatar name="배현영" src="/team/hy-bae.jpg" alt="배현영 프로필 사진" />

RSC 계약이라 시드의 onError 클라이언트 폴백은 없습니다 — 이미지 로드에 실패하면 브라우저가 alt 텍스트를 표시합니다.

크기#

세 크기를 공유 베이스라인에 올려 지름차를 한눈에 — space 토큰 정렬
sizediametertokenfontsm32pxspace.8captionmd40pxspace.10body-2lg48pxspace.12body-1

이니셜 폰트도 크기에 따라 caption/body-2/body-1로 함께 커집니다.

상태#

정적 컴포넌트라 인터랙션 상태가 없습니다(RSC). 상태 표시가 필요하면 AgentCard처럼 칩을 병행 배치하세요.

Props#

Prop타입기본값설명
namestring—이름 (필수) — 이니셜 폴백과 접근성 라벨의 원천
srcstring—이미지 URL — 부재 시 이니셜 폴백
altstringname이미지 대체 텍스트 / 폴백 aria-label
size'sm' | 'md' | 'lg''md'지름 32/40/48px — space 토큰 정렬
…restHTMLAttributes<span>—className 등 네이티브 속성 전달

접근성#

  • 이미지 모드 — <img alt>가 이름을 전달합니다 (alt 기본값은 name)
  • 이니셜 모드 — 루트에 role="img" + aria-label이 붙고, 이니셜 글자 자체는 장식(aria-hidden)이라 이중 낭독이 없습니다
  • 장식용 아바타 무리(facepile)라면 호출부에서 aria-hidden을 부여하세요

토큰#

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

속성토큰
폴백 배경/잉크color.primary-subtle + color.primary-text (AgentCard 아바타 선례)
형태radius.full
크기space.8(sm) / space.10(md) / space.12(lg)
이니셜 타이포font-size.caption/body-2/body-1 + font-weight.semibold