---
{"id":"toggle","title":"스위치","category":"컴포넌트","order":36,"summary":"즉시 적용되는 가역적인 이진 설정의 사용·상태·접근성 계약.","status":"문서 기준 · UI 미검증","references":["components/toggle/usage"]}
---

# 스위치

## 목적과 사용

즉시 적용되는 가역적인 이진 설정에 사용합니다. 결제·삭제·추가 저장이 필요한 설정에 쓰지 않습니다.

## 구성과 변형

고정된 설정 이름, on/off 상태, 저장 피드백. 변형의 외형은 각 제품의 기존 [토큰](tokens.md)을 사용합니다. Carbon의 크기·색·모서리·아이콘을 가져오지 않습니다.

## 동작 규칙

- SWT-01 MUST: 이름은 상태에 따라 뒤집지 않고 설정 자체를 설명합니다.
- SWT-02 MUST: 저장 실패 시 실제 상태를 복구하고 실패를 알립니다.
- SWT-03 MUST: 처리 중 반복 변경을 안전하게 제어합니다.
- SWT-04 SHOULD: 끄기가 되돌릴 수 없는 작업이면 별도 버튼·확인을 사용합니다.

## 접근성

role=switch를 사용한다면 aria-checked와 이름을 제공하고 Space 동작을 보장합니다. 공통 [접근성 기준](accessibility.md)도 함께 적용합니다.

## 콘텐츠 예시

좋음: ‘자동 갱신’과 현재 상태 / 피함: 현재 동작과 반대 뜻의 ‘비활성화 끄기’.

## 우리 구현과 연결

Pterodactyl 스위치는 48×24 트랙, 4px 트랙 모서리, 16×16 네모 손잡이, 2px 손잡이 모서리를 사용합니다. 꺼짐은 muted 손잡이와 panel-hover 배경이며, 켜짐은 panel 배경을 유지하고 accent 테두리·손잡이로 바뀝니다. 원형 손잡이·강조색으로 채운 트랙은 이 구현과 다릅니다.

2026-09-12 운영 설치본 .blueprint/extensions/nebula/public/libraries/teamwickedPanelFixes.css와 로컬 Blueprint 원본의 SHA-256이 일치했습니다. Switch__ToggleContainer 규칙을 선언값 그대로 추출하고 #app 범위만 문서 .sample 범위로 바꿨습니다. 네이티브 input은 키보드 접근을 위해 display:none 대신 시각적으로만 숨깁니다. 이는 운영 코드의 전수 복제나 접근성 인증이 아닙니다.

2026-09-12 통일 결정에 따라 vPanel·Pterodactyl·Blesta는 같은 Panel 기반 DemoSwitch와 공통 토큰을 사용합니다. Store도 **공통 확정 기준**에 포함되며 더 이상 별도 제안 테마가 아닙니다. 단, 운영 Store의 테마 배포는 문서·예제 적용과 별도로 남아 있습니다. TeamWicked 자체 스위치 스타일은 변경하지 않습니다.

## 실물 상태와 실패 복구

| 상태 | 표현과 동작 |
| --- | --- |
| 꺼짐 | muted 네모 손잡이, 비강조 트랙 |
| 켜짐 | accent 테두리·손잡이, panel 배경 |
| 비활성 | 상태 보존, 대비를 낮추고 조작 제한 |
| 읽기 전용 | 상태 읽기 가능, 포커스 가능, 변경 불가 |
| 저장 중 | 중복 조작 제한, 진행 안내 |
| 저장 실패 | 이전 checked 값으로 복구, 실패 원인 안내 |

‘다음 저장 실패 재현’을 켜고 스위치를 변경하면 700ms 뒤 원래 값으로 돌아갑니다. 타이머는 컴포넌트 이탈 시 정리되며 실제 저장 요청은 없습니다.

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

## 상태와 검증

성공·실패 롤백·연속 클릭·읽기 전용·키보드 전환을 확인합니다.

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