Skip to content

docs(identity-placeholder): document usage and a11y notes #1403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dohy-eon wants to merge 2 commits into
base: dev
Choose a base branch
from
Open

docs(identity-placeholder): document usage and a11y notes #1403

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6f0928
docs(identity-placeholder): document usage and a11y notes
dohy-eon Apr 3, 2026
8e012ef
docs: clarify aria-hidden guidance
dohy-eon Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions docs/content/react/components/identity-placeholder.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,36 @@ npx @seed-design/cli@latest add ui:identity-placeholder

<ManualInstallation name="identity-placeholder" />

## Usage

스니펫을 설치했다면 `seed-design/ui`에서 import합니다.

```tsx
import { IdentityPlaceholder } from "seed-design/ui/identity-placeholder";

export function Example() {
return <IdentityPlaceholder identity="person" />;
}
```

[`Avatar`](/react/components/avatar)의 `fallback`으로 자주 씁니다. 이미지가 없을 때 프로필 자리를 시각적으로 채우는 용도입니다.

```tsx
import { Avatar } from "seed-design/ui/avatar";
import { IdentityPlaceholder } from "seed-design/ui/identity-placeholder";

<Avatar size="48" fallback={<IdentityPlaceholder />} />
```

`@seed-design/react`의 컴파운드 API(`IdentityPlaceholder.Root`, `IdentityPlaceholder.Image`)로 동일한 UI를 조합할 수 있습니다. 스니펫은 이 조합을 한 컴포넌트로 감싼 형태입니다.

## Accessibility

내부 SVG(`IdentityPlaceholder.Image`)에는 기본으로 `role="img"`와 `aria-label="Identity placeholder"`(영문)가 설정되어 있습니다. 스크린 리더는 플레이스홀더 그래픽을 이미지로 인식합니다.

- **`Avatar` 안에서 사용할 때**: 접근성은 주로 `Avatar`와 상위 맥락(목록 항목 이름, 버튼 레이블 등)에 맡기는 패턴이 일반적입니다. 자세한 내용은 [Avatar](/react/components/avatar) 문서를 참고하세요.
- **단독으로 쓰는 경우**: 주변에 동일한 정보를 텍스트로 이미 제공하고 있다면, 중복 안내를 피하기 위해 **장식용 플레이스홀더 요소 자체**에 `aria-hidden="true"` 적용을 검토할 수 있습니다. 포커스 가능한 요소나 인터랙티브 컨테이너에는 적용하지 마세요. 앱의 정보 구조에 맞게 선택하세요.

## Props

<react-type-table
Expand Down