Accordion

현재 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 background `transparent`, cursor pointer. 기존 underline/focus 정책 유지, 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는 transparent다. 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의 transparent를 따른다.

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 폭.

7.7 KiB Raw Blame History