Avatar

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

• 사용자 이미지를 보여주세요. 이미지가 없거나 로드에 실패하면 이니셜이나 SVG가 fallback으로 표시됩니다. alt 텍스트나 Root name을 설정해 가까운 이름이 두 번 읽히지 않게 하세요. Status는 이미지와 분리된 장식 배지입니다. 실제 상태는 Root의 aria-description이나 인접 텍스트로 노출하세요.
• 프로젝트, 세션, 호스트처럼 사진이 없는 대상에는 category={categoryFor(name)}을 설정하세요. 같은 이름은 12가지 카테고리 색 중 늘 같은 색을 받고, 그 색이 이니셜 뒤를 옅게 채웁니다. 이니셜은 잉크색 그대로입니다.
• Status.tone은 StatusBadge의 톤으로 마커를 칠합니다. live는 지금 작업 중인 세션처럼 일이 진행되는 동안 마커를 맥동시키고, 모션 줄이기 설정에서는 멈춥니다. 상태는 이름 옆의 StatusBadge처럼 글로도 알려 주세요. 묶음의 개수 옆처럼 아바타가 없는 곳에는 같은 점을 StatusDot으로 따로 둡니다.

• Avatar span 자체를 계정 메뉴로 만들지 마세요. 이름이 있는 button이나 Popover.Trigger로 감싸세요.
• 카테고리 색을 손으로 고르거나 상태에 따라 바꾸지 마세요. categoryFor를 쓰면 어느 화면에서든 같은 이름이 같은 색을 지킵니다. 상태는 Status와 StatusBadge로 나타내세요.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

Avatar.Root → Image + Fallback(initials or default SVG) + optional Status

키보드와 접근성

정적 Avatar는 Tab 순서에 없습니다. button 안에서는 button이 포커스와 동작을 제공합니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { Avatar, categoryFor } from '@surflane/ui'

<Avatar.Root role='img' aria-label='Preview user' size='default'>
  <Avatar.Image src='/profile.png' alt='' />
  <Avatar.Fallback aria-hidden='true'>CG</Avatar.Fallback>
</Avatar.Root>

// A project's mark: its hue from its name, and a pulse while it works.
<Avatar.Root category={categoryFor('platform-api')} aria-hidden='true'>
  <Avatar.Fallback>PA</Avatar.Fallback>
  <Avatar.Status tone='progress' live />
</Avatar.Root>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰