shkim4
71d504407d
- Button page shows Toggle; new Selection Controls page compares Checkbox, Radio Group and Switch states (specimens moved to *-examples.tsx) - Date Picker page includes Calendar; Combobox, Input and Slider layouts (Korean slider labels) tidied - Absorbed representative Stories keep their IDs as verification Stories - Component docs updated to the new representative pages
87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
# 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/Selection Controls` → `All`의 상태 매트릭스 Switch 열(Default·Hover·Focus·Disabled, Validation 없음)(사이드바 `선택 컨트롤`, `components-form-selection-controls--all`). 기존 `Components/Form/Switch` → `All`(`components-form-switch--all`)은 URL 직접 접근용으로 유지(사이드바 숨김) Focus 칸의 링은 Storybook 전용 `data-sb-focus`(`.storybook/pseudo-states.ts`, 2026-11-13)로 고정해 보여 주며 실제 Tab 포커스 동작은 같다. |
|
||
| 보류 | 아래 §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
|
||
|
||
숨김 기존 `All`(URL 직접 접근용; 사이드바 대표는 Selection Controls, §표 참고): States 한 구역에 `off`, `on`, `hover`, `focus`, `disabled`(2026-11-09 Overview 제거, PC 5열; 2026-10-22 `interactive` 구역 제거, 모든 예시가 실제 클릭으로 토글). `hover`는 Off·On을 Storybook 전용 `data-sb-hover`로 고정해 보여 주며 Switch API가 아니다. 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 실제 재생, 사이드바 화면.
|