Stepper
단계 표시기 — ol/li 시맨틱. 완료는 체크+primary, 현재는 aria-current="step", 미래는 muted 숫자로 색+마커를 병행합니다.
마지막 업데이트 2026-06-11
한눈에#
다단계 흐름에서 순차적 진행 단계를 표시합니다 — 완료는 체크+primary, 현재는 aria-current="step", 미래는 muted 숫자로 색+마커를 병행합니다.
- 계정 정보 (완료)이름·이메일
- 팀 설정워크스페이스 구성
- 완료시작하기
- ol/li 순서 시맨틱
- aria-current=step
- 색+마커 병행
- 완료·현재·미래
상태는 색과 마커(체크/숫자)를 함께 써 색맹 환경에서도 구분됩니다
사용 시점#
다단계 흐름의 순차 진행 단계를 표시하면 Stepper — 수량 입력이나 계층 경로는 다른 컴포넌트입니다.
쓴다
- 장바구니 (완료)
- 결제
- 완료
온보딩·결제처럼 순서가 있는 다단계 흐름의 진행 상태(완료·현재·미래)
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
- 장바구니 (완료)상품 확인
- 결제카드·계좌
- 주문 완료영수증
import { Stepper } from '@wds/ui-web';
<Stepper
steps={[
{ label: '장바구니', description: '상품 확인' },
{ label: '결제', description: '카드·계좌' },
{ label: '주문 완료', description: '영수증' },
]}
activeIndex={1}
/>변형#
- 장바구니
- 결제
- 주문 완료
크기#
size prop이 없습니다 — 마커는 32px(space.8) 원형 고정이고, 각 단계가
가로 공간을 균등 분할(flex: 1)합니다.
상태#
- 요구사항 (완료)
- 디자인 (완료)
- 구현
- 검증
- complete (
index < activeIndex) — primary 채움 + CheckIcon, 나가는 연결선도 primary - current (
index === activeIndex) — primary-subtle 배경 + primary 보더 + 숫자 - upcoming (
index > activeIndex) — surface-muted + muted 숫자
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
steps | readonly StepperStep[] | — | 단계 목록 — StepperStep은 `{ label: string; description?: string }` |
activeIndex | number | — | 현재 단계 인덱스 (0-based, 필수) — 이전은 완료, 이후는 미래 |
completeLabel | string | '완료' | 완료 단계의 스크린리더 전용 보조 텍스트 |
…rest | HTMLAttributes<ol> | — | className 등 네이티브 속성 전달 |
접근성#
<ol>시맨틱 — 단계의 순서가 보조기술에 그대로 전달됩니다- 현재 단계는
aria-current="step" - 완료 단계는 체크 아이콘(장식,
aria-hidden)과 별개로 스크린리더 전용 "(완료)" 텍스트가 붙습니다 — 시각/비시각 정보가 동일합니다 - 상태는 색 + 마커(체크/숫자) 병행 — 색맹 환경에서도 구분됩니다
토큰#
component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).
| 속성 | 토큰 |
|---|---|
| complete 마커 | color.primary + color.on-primary |
| current 마커 | color.primary-subtle + color.primary-text + color.primary 보더 |
| upcoming 마커 | color.surface-muted + color.text-muted |
| 연결선 | color.border (완료 구간은 color.primary) |
| 라벨/설명 | color.text/color.text-muted · font-size.body-2/caption |
| 형태 | space.8(마커) · space.1/2/4 · radius.full · icon.size-sm |