# Switch

현재 HM 구현의 기준 문서. 공통 원칙은 `docs/guidelines/프로젝트-지침.md`(§6, §7), Token 구조 원칙은 `테마-토큰-가이드.md`를 따른다. 이 문서는 Switch 고유의 API·Token·상태·결정만 기록한다.

## 1. 상태

| 항목 | 내용 |
|---|---|
| 구현 상태 | 구현 완료 (현재 HM 규격) |
| 기준일 | 2026-10-02 |
| 기반 | shadcn/ui Switch (Radix `Switch`) |
| 대표 Story | `Components/Form/Switch` → `All` (이름 "Switch") |
| 보류 | 아래 §11 |

## 2. 적용 근거

- **참고 근거**: ui-viz 기존 테스트 규격에는 Switch 규격이 없다(후보 목록뿐). 참고할 수치가 없어 현재 HM Semantic으로 새로 정했다.
- **현재 HM 규격**: §3~§4.
- **구현 방식**: Radix Switch(`role=switch`, `data-state`, Space/Enter, 폼 동작)와 shadcn의 transition(`transition-all`, 썸 `transition-transform`)을 유지하고 theme CSS로 HM 스타일을 연결. 새 motion은 정의하지 않았다.
- **보류**: §11.

## 3. 기본 규격

| 항목 | 값 |
|---|---|
| Track | 36 × 20px, pill radius |
| Thumb | 16px 원, `--hm-sem-bg-surface`, 좌우 offset 2px (On: translate `36 − 16 − 2`) |
| Off 색 | track `--hm-sem-stroke-default` |
| On 색 | track `--hm-sem-state-active` |
| Label | `<Label htmlFor>` 조합 |

## 4. 상태 규격

| 상태 | 값 |
|---|---|
| Off / On | 위 기본 규격 (`data-state="unchecked"` / `"checked"`) |
| Hover | Black 20% overlay (`--hm-color-action-overlay-hover`) |
| Focus (`:focus-visible`) | shadcn ring 유지 |
| Disabled | `opacity: 0.6`, `cursor: not-allowed` |

## 5. API

Radix Switch props 그대로 (`checked`/`defaultChecked`/`onCheckedChange`, `disabled`, `required`, `name`, `value`). 추가 prop 없음. 출력 속성: `data-slot="switch"`, `"switch-thumb"`, Radix `data-state`.

## 6. Token

`packages/ui/src/theme/switch.css` (`--hm-switch-*`): `width`, `height`, `thumb-size`, `thumb-offset`, `off-background`, `on-background`, `thumb-color`, `hover-overlay`. Semantic 참조. Primitive 신규 추가 없음.

## 7. shadcn / Radix에서 유지한 항목

Radix 구조·ARIA·키보드, `data-slot`, `cn(..., className)`, shadcn transition, focus ring, disabled 커서.

## 8. HM에서 변경한 항목

shadcn의 `h-[1.15rem] w-8`, `border`, `shadow-xs`, `dark:` class 제거 → theme CSS. Off 색을 `input`(옅음) 대신 stroke 색으로, Disabled opacity 50 → 60.

## 9. Storybook

대표 Story `All`: `off`, `on`, `interactive`(controlled), `hover`, `focus`, `disabled`. Focus는 `play`로 실제 focus. verification: `Off`, `On`, `Disabled`.

## 10. 사용자 확정 결정

2026-10-02: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 이 컴포넌트에 대한 개별 수치 결정은 없다.

## 11. 미확정 / 보류

- size 변형(sm/md), 라벨 위치 규칙: 미결정.
- 수치(36×20, 썸 16)는 현재 HM 규격이며 디자인 확정 시 재검토.
- motion은 shadcn 기본 유지.

## 12. 관련 파일

```
packages/ui/src/components/ui/switch.tsx
packages/ui/src/theme/switch.css
packages/ui/src/theme.css            (import)
packages/ui/src/index.ts             (export Switch)
src/components/switch.stories.tsx
```

## 13. 검증 상태

- `npm run typecheck`, `npm run build`: 통과(2026-10-02).
- computed style: track 36×20, Off `rgb(154,146,132)`, On `rgb(18,51,40)`, 썸 16px White, translate 2px / 18px, Disabled opacity 0.6.
- interaction: controlled click으로 `data-state`·`aria-checked` 토글 확인.
- 미확인: 실제 pointer hover·focus ring 시각, transition 실제 재생, 사이드바 화면.