Avatar

사람이나 주체를 작은 시각 식별자로 나타냅니다.

목적

Avatar는 사람, 팀, 봇처럼 식별 가능한 주체를 작은 원형 영역에 표현한다. 이미지가 없거나 불러오지 못해도 AvatarFallback으로 동일한 자리와 식별 단서를 유지한다.

선택 기준

목록이나 대화에서 주체를 빠르게 구분하는 보조 단서로 사용한다.
이름이 핵심 정보라면 Avatar만 보여주지 말고 텍스트 이름을 함께 제공한다.
제품 로고에는 DotIcon, 큰 브랜드 표현에는 승인된 brand component를 사용한다.
상태 아이콘이나 일반 장식 이미지를 Avatar로 표현하지 않는다.

구조

Avatar root 안에 AvatarImage와 AvatarFallback을 함께 둔다. Image가 표시될 수 없을 때 Fallback이 같은 영역을 채운다. 상태 표시가 필요하면 root 바깥의 별도 레이블이나 배지와 조합한다.

변형과 크기

기본 크기는 40×40px이고 원형이다. 전용 size prop은 없다. className으로 크기를 바꿀 수 있지만 같은 목록에서는 하나의 크기를 유지하고, 너무 작아 인물 구분이나 fallback 글자를 읽기 어려운 크기는 피한다.

상태와 동작

Avatar 자체는 interactive component가 아니다. Image의 로딩 성공 여부에 따라 Fallback 노출이 바뀐다. 클릭 가능한 프로필 진입점으로 사용할 때는 Avatar에 직접 클릭 동작을 넣지 말고 접근 가능한 링크나 버튼 안에 이름과 함께 배치한다.

콘텐츠

Fallback은 보통 이름에서 가져온 1–2자의 식별 가능한 글자를 사용한다. 임의 이모지나 매번 달라지는 문자를 사용하지 않는다. 같은 글자가 반복될 수 있는 목록에서는 이름 텍스트를 반드시 함께 보여준다.

접근성

이미지가 주변 이름과 같은 정보를 반복하면 alt=""로 장식 이미지로 처리할 수 있다. 이미지 자체가 유일한 식별 정보라면 정확한 대체 텍스트를 제공한다. 클릭 동작이 있는 경우 링크나 버튼이 focus와 접근 가능한 이름을 소유해야 한다.

좁은 화면과 긴 콘텐츠

좁은 화면에서도 Avatar를 찌그러뜨리지 않는다. root는 기본적으로 축소되지 않으므로 이름 영역에 min-width: 0과 말줄임을 적용해 공간을 조절한다. 긴 이름을 Avatar 글자 수로 해결하지 말고 옆의 텍스트 레이아웃에서 처리한다.

공개 API

Avatar: 40×40px 원형 root
AvatarImage: root를 채우는 이미지
AvatarFallback: 이미지 대체 표면

세 요소는 각 기반 요소의 props와 className을 전달한다.

예제

import { Avatar, AvatarFallback, AvatarImage } from '@classum/dot-design-system/ui';

export function MemberAvatar() {
  return (
    <div className="flex items-center gap-3">
      <Avatar>
        <AvatarImage src="/members/young.png" alt="" />
        <AvatarFallback>김영</AvatarFallback>
      </Avatar>
      <div className="min-w-0">
        <p className="truncate font-medium">김영</p>
        <p className="truncate text-sm text-muted-foreground">콘텐츠 운영자</p>
      </div>
    </div>
  );
}

피해야 할 사용

이름 없이 Avatar만으로 사용자를 식별하게 하지 않는다.
fallback에 의미 없는 기본 사람 아이콘만 반복하지 않는다.
원본 비율을 무시한 이미지를 넣어 얼굴이나 로고가 찌그러지게 하지 않는다.
Avatar 자체를 button처럼 보이게 만들고 keyboard 동작을 빠뜨리지 않는다.

목적