Components · 피드백

Spinner (스피너)

완료 시점을 알 수 없는 짧은 대기를 회전 애니메이션으로 알리는 피드백 컴포넌트. 1초 이상 걸리는 로딩에 쓴다.

정의

완료 시점을 알 수 없는 짧은 대기 상태를 회전 애니메이션으로 알리는 피드백 컴포넌트다.

Anatomy

부위	토큰
① 트랙(track)	`--spinner-track` 원형 배경 링, 크기 `--spinner-size`(40)
② 인디케이터 arc	`--spinner-indicator`(브랜드) 회전하는 호(arc)
③ 상태 텍스트(선택)	진행 상황 안내("불러오는 중…"), 스크린리더에도 전달

변형

변형	용도
비확정형(기본)	남은 시간을 모를 때 — 무한 회전(대부분의 로딩)
인라인	버튼·인풋 옆의 작은 로딩 — 크기를 텍스트에 맞게 축소
블록(중앙)	영역 전체 로딩 — 컨테이너 가운데 배치

상태

상태	규칙
로딩 중	arc 회전(`--duration-slower` 주기), 컨테이너 `aria-busy="true"`
모션 감소	`prefers-reduced-motion: reduce`에서 회전 정지 — 정적 링 + 텍스트로 대체
완료	스피너 제거 후 결과 표시, `aria-busy="false"`

Do / Don't

1초 이상 걸리는 작업에만 쓴다 — 그보다 짧으면 즉시 결과를 보여 준다(깜빡임 방지, KRDS).
"불러오는 중" 같은 상태 텍스트를 함께 두어 무엇을 기다리는지 알린다.
prefers-reduced-motion에서 회전을 멈추고 정적 표시로 바꾼다.

Don't

1초 미만 작업에 스피너를 띄우지 말 것 — 나타났다 사라져 오히려 산만하다.
진행률을 알 수 있는 작업(업로드 등)에 쓰지 말 것 — 남은 정도는 진행률 바로 보인다.
스피너만 남기고 화면을 완전히 가리지 말 것 — 맥락(자리표시자·골격)을 함께 유지한다.

콘텐츠 규칙

상태 텍스트는 진행형 명사구·짧은 문장("저장하는 중…"·"카탈로그 불러오는 중…").
말줄임표(…)로 진행 중임을 나타내되 문장을 길게 쓰지 않는다.
완료·실패 시엔 스피너 텍스트를 결과 메시지(Toast·Alert)로 교체한다.
전역 규칙: ../guidelines/ux-writing.md.

키보드 인터랙션

해당 없음 — 스피너는 포커스를 받지 않는 비인터랙티브 상태 표시다(로딩이 끝나면 포커스는 결과 영역으로 옮긴다).

접근성

로딩 영역에 role="status" + aria-live="polite" + aria-busy="true" — 스크린리더가 상태 변화를 알린다.
시각 텍스트가 없으면 시각적으로 숨긴 라벨이나 aria-label로 "불러오는 중"을 제공한다.
회전 링은 장식이므로 aria-hidden="true"(상태는 텍스트로 전달).
prefers-reduced-motion: reduce에서 애니메이션 제거는 접근성 필수(전정 장애 배려).
기준: ../guidelines/accessibility.md.

코드

카탈로그 불러오는 중…

html

<div class="pi-spinner" role="status" aria-live="polite" aria-busy="true">
  <span class="pi-spinner__ring" aria-hidden="true"></span>
  <span class="pi-spinner__label">카탈로그 불러오는 중…</span>
</div>

css

.pi-spinner { display: inline-flex; align-items: center; gap: var(--space-3); }
.pi-spinner__ring {
  width: var(--spinner-size); height: var(--spinner-size);
  border-radius: var(--radius-full);
  border: var(--border-thick) solid var(--spinner-track);
  border-top-color: var(--spinner-indicator);
  animation: pi-spinner-rotate var(--duration-slower) var(--easing-linear) infinite;
}
.pi-spinner__label {
  font: var(--text-body-sm); color: var(--color-text-secondary); word-break: keep-all;
}
@keyframes pi-spinner-rotate {
  to { transform: rotate(360deg); }
}
@media (prefers-reduced-motion: reduce) {
  .pi-spinner__ring { animation: none; }
}

Changelog

날짜	변경
2026-07-15	문서 계약(10섹션) 적용 — KRDS 벤치마킹 규격(2026-07-15) 승계, Anatomy 도해·변형·상태·콘텐츠 규칙·모션 감소 처리 실코드 신설