---
{"id":"progress-bar","title":"진행률 표시","category":"컴포넌트","order":53,"summary":"실제 작업량의 진행을 알림의 사용·상태·접근성 계약.","status":"문서 기준 · UI 미검증","references":["components/progress-bar/usage"]}
---

# 진행률 표시

## 목적과 사용

실제 작업량의 진행을 알림에 사용합니다. 측정값이 없는데 임의의 백분율·남은 시간을 만들지 않습니다.

## 구성과 변형

작업 이름, 측정 가능 여부, 값, 상태·후속 행동. 변형의 외형은 각 제품의 기존 [토큰](tokens.md)을 사용합니다. Carbon의 크기·색·모서리·아이콘을 가져오지 않습니다.

## 동작 규칙

- PRG-01 MUST: 실제 계산 근거가 있을 때만 퍼센트를 표시합니다.
- PRG-02 MUST: 측정 불가 상태는 불확정 진행으로 표현합니다.
- PRG-03 MUST: 전송 100%와 서버 처리 완료를 구분합니다.
- PRG-04 SHOULD: 실패·취소·재시도에서 진행 상태를 명시적으로 전환합니다.

## 접근성

progressbar 또는 네이티브 progress에 이름을 제공하고 값 변경을 지나치게 낭독하지 않습니다. 공통 [접근성 기준](accessibility.md)도 함께 적용합니다.

## 콘텐츠 예시

좋음: ‘전송 완료 · 검증 중’ / 피함: 타이머로 99%까지 진행.

## 우리 구현과 연결

백업·재설치·업로드 결과는 각 서버 작업 상태가 권한을 가집니다.

제품별 소유 경로는 [WICKEDVPS](product-vps.md), [Panel](product-panel.md), [Blesta](product-blesta.md)와 [소스 근거](source-evidence.md)를 확인합니다. 코드 존재와 모든 사용처의 준수는 다르며, 별도 표시가 없는 제품별 준수 상태는 미검증입니다.

## 코드 계약 예시

다음은 의미 구조 설명용이며 운영 API에 연결된 완성 구현이 아닙니다.

```html
<label for="transfer">파일 전송</label>
<progress id="transfer" value="40" max="100">40%</progress>
```

## 상태와 검증

실제 0/100·단위 변경·중단·불확정→확정·실패를 확인합니다.

일반·hover·focus·실행 중·실패·성공·disabled·read-only 중 해당하는 상태를 기록합니다. 해당하지 않는 상태를 임의로 만들지 말고 이유를 남깁니다. [검증 체크리스트](testing.md)에 증거를 연결합니다.