115 lines
8.0 KiB
Markdown
115 lines
8.0 KiB
Markdown
# Accordion
|
|
|
|
> 2026-10-10 추가 수정 요청 기준: 펼침·접힘 모두 hover한 제목 Trigger에만 Black 5% 배경. 본문 배경은 유지. 과거 검증 기록은 당시 결과이며 현재 검증은 [추가 수정 보고서](../guidelines/publisher-additional-review-2026-10-10.md)를 따릅니다.
|
|
|
|
현재 HM 구현의 기준 문서. 공통 원칙은 `docs/guidelines/프로젝트-지침.md`(§6, §7), Token 구조 원칙은 `테마-토큰-가이드.md`를 따른다. 이 문서는 Accordion 고유의 API·Token·상태·결정만 기록한다. Collapsible(`collapsible.md`)과 값을 공유하지 않는다.
|
|
|
|
## 1. 상태
|
|
|
|
| 항목 | 내용 |
|
|
|---|---|
|
|
| 구현 상태 | 구현 완료 (현재 HM 규격) |
|
|
| 기준일 | 2026-10-02 |
|
|
| 기반 | shadcn/ui Accordion (Radix `Accordion`) |
|
|
| 대표 Story | `Components/Disclosure/Accordion` → `All` (이름 "Accordion") |
|
|
| 보류 | 아래 §11 |
|
|
|
|
## 2. 적용 근거
|
|
|
|
- **참고 근거**: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Accordion이 컴포넌트 이름으로만 있고 규격은 없다. 참고할 수치가 없었다.
|
|
- **현재 HM 규격**: 아래 §3~§4. 현재 HM Semantic 체계(fg, stroke, divider 계열 Primitive)로 새로 정했다.
|
|
- **구현 방식**: shadcn / Radix Accordion 구조(Root·Item·Header·Trigger·Content), shadcn chevron과 open/close animation을 유지하고 theme CSS로 HM 스타일을 연결.
|
|
- **Collapsible과의 구분**: Accordion은 여러 item이 연속된 정보 구조라 item 사이 divider가 구조를 만든다. 단일 독립 disclosure는 Collapsible을 쓴다.
|
|
- **보류**: §11.
|
|
|
|
## 3. 기본 규격 (현재 HM 규격)
|
|
|
|
| 항목 | 값 | 비고 |
|
|
|---|---|---|
|
|
| Container | 바깥 박스·배경 없음 | |
|
|
| Item divider | 1px `--hm-sem-stroke-input-default`, 마지막 item 제외 | Dialog·Card와 같은 윤곽색(값 참조만) |
|
|
| Trigger | min-height 48px, padding `12px 0`, gap 16px, 위 정렬이 아니라 세로 가운데 | |
|
|
| Trigger typography | 16 / 24 / 500 | |
|
|
| Trigger 전경 | `--hm-sem-fg-primary` | |
|
|
| Indicator | shadcn `ChevronDownIcon` 20px, `--hm-sem-fg-secondary`, 열리면 180° 회전(200ms) | shadcn 유지 |
|
|
| Content | 14 / 20 / 400, `--hm-sem-fg-primary`, 아래 padding 16px | 안쪽 div에 padding |
|
|
| 긴 텍스트 | `overflow-wrap: anywhere`, 고정 높이 없음 | |
|
|
|
|
## 4. 상태 규격
|
|
|
|
| 상태 | 값 |
|
|
|---|---|
|
|
| Closed / Open | Radix `data-state` |
|
|
| Hover | 펼침·접힘 모두 Trigger에 Black Alpha 5%, cursor pointer. 본문 유지, disabled 제외 |
|
|
| Focus (`:focus-visible`) | shadcn ring (`ring-3 ring-ring/50`) 유지 |
|
|
| Disabled | `opacity: 0.6`(이 컴포넌트 값, 전역 Disabled 규칙으로 승격 안 함), `cursor: not-allowed`, 키보드 이동에서 제외 |
|
|
| Open / Close animation | shadcn `accordion-down` / `accordion-up` 0.2s ease-out (height). 첫 렌더에서는 Radix가 animation을 막는다 |
|
|
|
|
## 5. API
|
|
|
|
Radix Accordion props 그대로. export: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`.
|
|
|
|
- `Accordion`: `type="single" | "multiple"`, `collapsible`(single), `value`/`defaultValue`/`onValueChange`, `disabled`, `orientation`, `dir`.
|
|
- `AccordionItem`: `value`(필수), `disabled`.
|
|
- `AccordionTrigger`: chevron을 내장한다. 출력 `data-slot="accordion-trigger"`, 아이콘 `data-slot="accordion-trigger-icon"`.
|
|
- `AccordionContent`: `className`은 안쪽 div(`data-slot="accordion-content-inner"`)에 적용된다. Radix Content(`data-slot="accordion-content"`)는 `overflow-hidden`과 animation만 가진다.
|
|
- `variant`, `size`, `appearance` 등 HM 전용 prop은 만들지 않았다.
|
|
|
|
## 6. Token
|
|
|
|
Component Mapping 위치: `packages/ui/src/theme/accordion.css` (`--hm-accordion-*`).
|
|
|
|
`text`, `content-text`, `divider-width`, `divider-color`, `trigger-min-height`, `trigger-padding-y`, `trigger-gap`, `trigger-font-size|line-height|font-weight`, `icon-size`, `icon-color`, `content-font-size|line-height`, `content-padding-bottom`, `disabled-opacity`. Semantic과 Theme palette만 참조하고 다른 컴포넌트의 Component Token을 쓰지 않는다. 신규 Primitive 없음.
|
|
|
|
## 7. shadcn / Radix에서 유지한 항목
|
|
|
|
Radix 구조·ARIA(`aria-expanded`, `aria-controls`, `role=region`)·키보드(Arrow Up/Down은 trigger 사이 이동하며 끝에서 순환, Home/End, Enter/Space)·single/multiple/collapsible 동작, Header 요소(`h3`), `data-slot`, `cn(..., className)`, chevron 회전, `accordion-down/up` animation, focus ring.
|
|
|
|
## 8. HM에서 변경한 항목
|
|
|
|
- shadcn `py-4 text-sm font-medium hover:underline`, `size-4` 아이콘, Item `border-b`, Content `pb-4 text-sm` class를 제거하고 theme CSS로 이전.
|
|
- shadcn은 Content 안쪽 div가 없는 구조도 있었으나 height animation이 padding에 의해 흔들리지 않도록 padding은 안쪽 div에 둔다.
|
|
- Trigger의 `disabled:pointer-events-none`을 `disabled:cursor-not-allowed`로 교체(커서가 보이도록).
|
|
- animation을 `animate-[accordion-down_0.2s_ease-out]` 임의 값으로 연결(`animate-accordion-*` utility theme 변수가 이 패키지에 없다. keyframe은 `shadcn/tailwind.css`가 제공).
|
|
|
|
## 9. Storybook
|
|
|
|
- 대표 Story `All`("Accordion"): `StateBoard`로 Single(첫 항목 열림), Collapsible Single, Multiple(두 항목 열림), Disabled Item, Long Content(여러 줄 Trigger + 긴 콘텐츠 + 공백 없는 문자열)를 한 페이지에 둔다. 모두 실제 클릭·키보드로 동작.
|
|
- verification: `Single`, `Multiple`, `Disabled`, `Long Content`.
|
|
- meta에 `component`를 지정하지 않는다(Accordion props가 `single | multiple` union이라 args 없는 Story가 타입을 통과하지 못함).
|
|
|
|
## 10. 사용자 확정 결정
|
|
|
|
- 2026-10-02: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 개별 수치에 대한 별도 결정은 없다.
|
|
|
|
## 11. 미확정 / 보류
|
|
|
|
- 수치(48px, 16/24/500, padding, divider 색, Disabled opacity 0.6)는 현재 HM 규격이며 디자인 확정 시 재검토.
|
|
- 현재 Hover는 제목 영역 Black Alpha 5%다. Focus Light 2 50% 3px ring과 Disabled opacity 0.6·cursor not-allowed는 유지.
|
|
- Indicator는 shadcn chevron 유지(Select의 HM glyph와 별개). 별도 Source glyph 없음.
|
|
- Motion 규칙이 없어 shadcn animation 유지. `prefers-reduced-motion` 대응은 추가하지 않았다(기존 구현에도 없음).
|
|
- Container 외곽 박스/Card형 variant는 만들지 않았다.
|
|
- 소비 조합: Trigger 안 아이콘·부가 정보 슬롯은 정의하지 않았다.
|
|
|
|
## 12. 관련 파일
|
|
|
|
```
|
|
packages/ui/src/components/ui/accordion.tsx
|
|
packages/ui/src/theme/accordion.css
|
|
packages/ui/src/theme.css (import)
|
|
packages/ui/src/index.ts (export)
|
|
src/components/accordion.stories.tsx
|
|
```
|
|
|
|
## 13. 검증 상태
|
|
|
|
> HISTORICAL_RECORD: 아래 날짜별 검증은 당시 구현의 기록이다. 과거 soft surface 측정은 보존하며, 현재 Hover 규격은 §4의 Black Alpha 5%를 따른다.
|
|
|
|
- 2026-10-06 Visual QA: 1280/1024/768/390px에서 Closed/Open Hover의 전체 soft surface·pointer, Focus 3px ring, Disabled opacity 0.6·not-allowed 및 가로 overflow 없음 확인. `typecheck`, `build`, `build-storybook` 통과.
|
|
|
|
- `npm run typecheck`, `npm run build`: 통과(2026-10-02).
|
|
- 실제 interaction(Browser pane): ArrowDown으로 trigger 이동(비활성 항목 건너뜀, 끝에서 처음으로 순환), Home/End, Enter로 열기, Space로 닫기, single(다른 항목을 열면 이전 항목 닫힘, 열린 항목 재클릭은 닫히지 않음), collapsible single(재클릭으로 모두 닫힘), multiple(여러 항목 동시 열림), disabled 항목 클릭 무반응(`disabled`, `data-disabled`).
|
|
- animation: 열 때 `accordion-down`이 적용되고 높이가 5 → 36px로 변하는 것을 샘플링으로 확인.
|
|
- computed style: trigger 48px·16/24/500, 전경 `rgb(10,34,29)`, divider `1px rgb(222,219,210)`, icon 20px `rgb(110,103,89)`, content 14/20·아래 padding 16px. 긴 콘텐츠에서 가로 overflow 없음, 긴 Trigger는 여러 줄로 줄바꿈.
|
|
- 미확인: ArrowUp(ArrowDown과 대칭), 닫힘 animation 시각, 실제 pointer hover/focus ring 시각, 390px 폭.
|