---
{"id":"empty-state","title":"빈 화면·권한·실패","category":"컴포넌트","order":71.06,"summary":"데이터 없음·검색 결과 없음·권한 없음·실패를 다른 상황으로 설명합니다.","status":"문서용 동작 예제 · 운영 이식 미검증","references":[]}
---

# 빈 화면·권한·실패

## 목적과 사용

데이터 없음·검색 결과 없음·권한 없음·실패를 다른 상황으로 설명합니다. TeamWicked와 WickedHost의 공통 행동 규칙으로 재사용하되 각 체계의 토큰을 적용합니다.

## 구성과 변형

- 처음 사용
- 검색 없음
- 권한 없음
- 로딩 실패

보여 주는 형태는 해당 제품 토큰으로 구성한 문서용 예제입니다. 별도 원본 연결 표시가 없으면 운영 컴포넌트를 그대로 복제했다는 의미가 아닙니다.

## 동작 규칙

- EMP-01 MUST: 요청 실패를 데이터 0개로 표시하지 않습니다.
- EMP-02 MUST: 첫 사용에는 시작 행동을, 필터 없음에는 초기화 행동을 제공합니다.
- EMP-03 MUST: 권한 없음에서 실행할 수 없는 생성 버튼을 유일한 복구 수단으로 두지 않습니다.
- EMP-04 MUST: 빈 상태 문구는 사용자를 탓하지 않고 다음 단계를 설명합니다.

## 접근성

컨트롤은 보이는 목적과 같은 접근 가능한 이름을 가집니다. 키보드로 진입·조작·이탈할 수 있어야 하며 오류와 현재 상태를 텍스트로 설명합니다. [접근성 기준](accessibility.md)과 [읽기 전용·권한](disabled-readonly.md)을 함께 적용합니다.

## 콘텐츠 예시

예제 이름·주소·금액은 실제 고객 데이터가 아닙니다. example.test, 개발 서버, 예제 계정처럼 목적이 분명한 가상 자료를 사용합니다. 실제 권한·저장·전송이 완료되었다고 오해할 문구는 사용하지 않습니다.

## 우리 구현과 연결

web/expanded-specimens.tsx의 실행 코드와 이 페이지의 구현 코드 탭이 같은 함수를 사용합니다. 공통 요소는 web/primitives.tsx, 스타일은 web/expanded-specimens.css에서 관리합니다. 공통 행동 규칙과 시각 토큰을 구분하고, 같은 이름의 운영 구현과 props 계약이 같다고 가정하지 않습니다.

## 상태와 검증

상황을 바꾸며 제목·설명·다음 행동이 함께 바뀌는지 확인합니다.

라이트·다크 / desktop·mobile / 키보드 / 빈 값·긴 값 / 권한·실패 / 데이터 변경 요청 없음에 대한 증거를 기록합니다. 제품의 실제 업무 성공이나 전체 WCAG 준수 여부는 별도 검증입니다.