shkim4
4c29894e56
Drop page / section descriptions, state notes and repeated captions from the representative Stories of 44 components, the Patterns, Center Graphic and OrgChart pages. Value readouts, spec lists and captions hide only on the representative page; hidden verification Stories keep them. Tabs Default API and the Filter Bar draft / applied counts move to the hidden DefaultApi and DraftApplied Stories; Center Overview is hidden with its direct URL kept. Story IDs are unchanged. Align the component, pattern and OrgChart docs with the pages, point the quality reference check at the DraftApplied Story, and make the P8 styles check expect no section header on the preview-only Expanded page.
87 lines
3.7 KiB
Markdown
87 lines
3.7 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/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`, `hover`, `focus`, `disabled`(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 실제 재생, 사이드바 화면.
|