# Accordion

여러 항목을 접고 펼쳐 필요한 내용만 보여주는 컴포넌트입니다.

> 원본: `03_ASSET_GUIDE/catalog/accordion.js` · CSS: `03_ASSET_GUIDE/styles/elements/accordion.css`
> kind `component` · category `display` · status `stable` · specSource `measured`

> [!NOTE]
> Spectrum 에는 Accordion 페이지가 없어 레퍼런스가 세 곳뿐입니다.

---

## 1. 구성

**Container** 안에 **Item** 이 쌓이고, 각 Item 은 항상 보이는 **Trigger** 와 펼쳐졌을 때만
보이는 **Content** 로 나뉩니다. 행 전체가 하나의 버튼입니다.

```
┌──────────────────────────────────────────┐ ①
│ 등록을 취소할 수 있나요?               ⌃ │ ② ③ ④ ⑤
│ 등록한 날로부터 7일 이내에 신청할 수 있어요. │ ⑥
├──────────────────────────────────────────┤ ⑦
│ 내용을 어떻게 수정하나요?              ⌄ │ ②
└──────────────────────────────────────────┘
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| ① | Container | 필수 | `atom-accordion` | 항목 전체를 감싸는 표면입니다. `card` 는 테두리를 두르고 `flush` 는 두르지 않습니다. |
| ② | Item | 필수 | `atom-accordion__item` | 하나의 접히는 단위. 열림 상태를 `data-state` 로 가집니다. |
| ③ | Trigger | 필수 | `atom-accordion__trigger` | 제목과 Caret 을 담은 `<button>`. **행 전체가 클릭 영역**입니다. |
| ④ | Title | 필수 | `atom-accordion__title` | 접힌 상태에서 보이는 유일한 정보입니다. |
| ⑤ | Caret | 필수 | `atom-accordion__caret` | 펼쳐지면 180° 회전합니다. `aria-hidden` 이라 상태는 `aria-expanded` 가 전달합니다. |
| ⑥ | Content · Body | 필수 | `atom-accordion__content` · `atom-accordion__body` | Content 가 높이를 애니메이션하고, Body 가 내용과 여백을 담습니다. |
| ⑦ | Divider | — | (`__item + __item` 의 inset shadow) | 두 번째 항목부터 위쪽에 그어집니다. |

---

## 2. 종류 / 크기

### 치수

| 대상 | 값 |
| --- | --- |
| Container 모서리 | `--atom-radius-r3` (12px) · `flush` 는 0 |
| Container 배경 | `--atom-bg-layer` · `flush` 는 투명 |
| Container 경계 | 1px `--atom-border-subtle` inset · `flush` 는 없음 |
| Item 구분선 | 1px `--atom-border-subtle` (두 번째 항목부터, inset shadow) |
| Trigger 최소 높이 | 48px |
| Trigger 좌우 여백 | `--atom-x4` (16px) · `flush` 는 0 |
| Trigger 상하 여백 | `--atom-x3` (12px) — 제목이 두 줄이 되면 높이가 늘어납니다 |
| Trigger 폰트 | 15px / 600 |
| Trigger gap | `--atom-x3` (12px) |
| Caret | 24px |
| Body 좌우 여백 | `--atom-x4` (16px) — Trigger 와 같은 값이라 제목과 본문이 한 줄에 섭니다 |
| Body 아래 여백 | `--atom-x4` (16px) |
| Content 폰트 | 15px / 1.6 `--atom-fg-neutral-muted` |

좌우 여백은 Container 가 아니라 **Trigger 와 Body 가 각각** 가집니다. Trigger 가 행 끝까지
닿는 클릭 영역이어야 하고, hover 배경과 구분선이 표면 가장자리까지 이어져야 하기 때문입니다.

구분선을 `border-top` 이 아니라 inset `box-shadow` 로 그리고 `+` 셀렉터를 쓰기 때문에,
첫 항목에는 선이 없고 항목을 추가·제거해도 자동으로 맞습니다.

### Variant

`card` 가 기본입니다. 본문 흐름 안에 그대로 얹을 때는 `flush` 를 써서 좌우 여백을 없애면
주변 문단과 글머리가 맞습니다.

| Variant | 표면 | 쓸 곳 |
| --- | --- | --- |
| `card` | 테두리 + radius + 배경 | 카드 사이에 놓이는 FAQ, 설정 묶음 |
| `flush` | 없음. 구분선만 | 본문에 이어 붙는 안내, 좁은 화면 |

> [!NOTE]
> **그림자 대신 테두리를 씁니다**
> 프리뷰는 `--atom-shadow-s1` 을 썼지만 엘리먼트 CSS 는 `--atom-border-subtle` inset 으로
> 바꿨습니다. Accordion 은 본문에 늘 있는 요소이므로 Shadow 의 "상시 노출 요소에는
> 그림자를 쓰지 않는다" 는 원칙에 맞췄습니다.

### 펼침 방식

CSS 는 각 Item 의 `data-state` 만 봅니다. **하나만 열리게 할지 여러 개를 열 수 있게 할지는
스크립트가 정하고**, Container 의 `--type_single` · `--type_multiple` 은 그 계약을 마크업에
적어 두는 표시입니다. 두 값의 겉모습은 같습니다.

| 방식 | 설명 | 쓸 곳 |
| --- | --- | --- |
| `multiple` (기본) | 여러 항목을 동시에 열 수 있습니다. 각 항목의 상태가 독립적입니다 | FAQ, 내용이 많은 영역 |
| `single` | 하나를 열면 다른 항목이 닫힙니다 | 단계별 프로세스, 좁은 화면 |

**기본은 다중 펼침**입니다. 단일 펼침은 열어 둔 항목을 자동으로 닫으므로 두 항목을 비교하기
어렵습니다.

기본 상태는 **전부 닫힘**입니다. 목록의 전체 구조를 먼저 보여주기 위해 첫 항목도 미리 열어
두지 않습니다.

`--type_*` modifier 는 컴포넌트 로컬 커스텀 프로퍼티 `--atom-accordion-type`(`multiple` · `single`)을 함께 정의합니다.
디자인 토큰이 아니라, 스크립트가 클래스 이름을 맞추지 않고 한 곳에서 모드를 읽기 위한 값입니다(원본 CSS 주석).

### 모션

Content 는 `grid-template-rows: minmax(0, 0fr) → minmax(0, 1fr)` 로 높이를
전환합니다 (`--atom-duration-base` `--atom-ease-out`). 내용 높이를 몰라도 동작하고,
`max-height` 방식과 달리 내용 길이에 따라 속도가 달라지지 않습니다. Caret 회전도 같은 시간에
맞춥니다.

하한값을 적지 않은 `0fr` 은 `minmax(auto, 0fr)` 과 같습니다. 이때 `auto` 는 트랙을 항목의
최소 크기까지 밀어 올리고, 그 최소 크기에는 Body 의 padding 이 포함됩니다. 이 때문에 닫힌
패널에 `--atom-x4` 만큼 빈 높이가 남았습니다. 그래서 하한값을 0 에 고정하고 Content 가
직접 `overflow: hidden` 으로 자릅니다. 닫힌 상태의 Content 는 어떤 영역도 차지하지 않습니다.

Body 는 `align-self: start` 로 트랙에 늘어나지 않고 자신의 자연 높이를 유지합니다. 크기가
변하는 것은 트랙뿐이고 넘치는 부분은 Content 가 자르므로, 열리고 닫히는 동안 내부 콘텐츠가
다시 배치되거나 줄어들거나 줄바꿈이 달라지지 않습니다.

> [!WARNING]
> **높이만 0 으로 만들면 접근성이 깨집니다**
> 높이가 0 인 패널도 여전히 포커스를 받고 스크린리더가 읽습니다. Accordion 은
> `visibility: hidden` 을 함께 걸고, 닫힐 때만 `transition-delay` 로 애니메이션이 끝난 뒤
> 적용되게 합니다. `prefers-reduced-motion: reduce` 에서는 전환 전체를 끄고 지연도 함께
> 없앱니다.

### 클래스 계약

`styles/elements/accordion.css` 헤더와 원본 `registry.json` `css.blocks` 기준입니다. 두 축 모두 기본값에도 클래스가 정의되어 있습니다.

| Prop | 값 | 클래스 |
|---|---|---|
| `variant` | `card` · `flush` | `--variant_card` · `--variant_flush` |
| `type` | `multiple` · `single` | `--type_multiple` · `--type_single` |

상태 선택자: `__item[data-state="open\|closed"]` · `__item[data-disabled]` · `__trigger[disabled]` · `__trigger[aria-disabled="true"]` · `:hover` · `:focus-visible`

로컬 커스텀 프로퍼티: `--atom-accordion-type`

---

## 3. 상태

열림 여부는 Item 의 `data-state` 가, 나머지는 Trigger 자신의 상태가 결정합니다.

| State | 표현 | 선택자 |
| --- | --- | --- |
| closed (기본) | Content 높이 0 · `visibility: hidden` · Caret 0° | `[data-state="closed"]` |
| open | Content 높이 auto · Caret 180° | `[data-state="open"]` |
| hover | Trigger 배경 `--atom-bg-neutral-weak` | `:hover` |
| focus-visible | 2px `--atom-fg-brand` 링, offset `-2px` | `:focus-visible` |
| disabled | 불투명도 0.4 · `not-allowed` | `[disabled]` · `[data-disabled]` |

> [!NOTE]
> **포커스 링은 안쪽으로 넣습니다**
> Trigger 가 행 전체 너비라 `base.css` 의 공통 `:focus-visible`(offset `2px`)은 Container
> 경계 위에 그려집니다. Accordion 은 `outline-offset: -2px` 로 링을 안쪽에 그립니다.

---

## 4. Props

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `items` | `Array<{ value, title, content, disabled? }>` | | ● | 항목 목록입니다. 최소 2개. |
| `type` | `"multiple" \| "single"` | `"multiple"` | | 동시에 열 수 있는 개수입니다. |
| `variant` | `"card" \| "flush"` | `"card"` | | Container 의 표면 처리입니다. |
| `value` | `string[] \| string` | `[]` | | 열려 있는 항목입니다. `type` 이 `single` 이면 문자열 하나입니다. |
| `onValueChange` | `(value: string[] \| string) => void` | | | 열림 상태가 바뀔 때 호출됩니다. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | | Trigger 를 감쌀 제목 태그의 레벨입니다. |

### Parts (compound)

`items` 대신 파트로 직접 조립할 수 있습니다. 두 방식의 DOM 은 같습니다.

| Part | 요소 | 설명 |
|---|---|---|
| `Accordion` | `<div class="atom-accordion">` | Container. 위 Props 를 받습니다. 구현은 비제어용 `defaultValue` 를 함께 받습니다. |
| `Accordion.Item` | `<div class="atom-accordion__item">` | `value` · `disabled`. `data-state` · `data-disabled` 를 냅니다. |
| `Accordion.Trigger` | `<hN>` > `<button class="atom-accordion__trigger">` | 자식을 `__title` 로 감싸고 `__caret`(chevron-down)을 붙입니다. `aria-expanded` · `aria-controls`. |
| `Accordion.Content` | `<div class="atom-accordion__content" role="region">` > `__body` | `aria-labelledby` 로 Trigger 를 가리킵니다. |

---

## 5. Component tokens

| 대상 | 속성 | Token | Value |
|---|---|---|---|
| Container | radius | `{radius.r3}` | 12px |
| Container | background | `{color.bg.layer}` | |
| Container | border | `{color.border.subtle}` | 1px inset |
| Item 구분선 | color | `{color.border.subtle}` | 1px inset |
| Trigger | padding-inline | `{space.x4}` | 16px |
| Trigger | padding-block | `{space.x3}` | 12px |
| Trigger | gap | `{space.x3}` | 12px |
| Trigger | color | `{color.fg.neutral}` | 15px / 600 |
| Trigger hover | background | `{color.bg.neutral-weak}` | |
| Trigger hover | transition | `{duration.fast}` | 120ms |
| Trigger focus | outline | `{color.fg.brand}` | 2px / offset -2px |
| Caret | color | `{color.fg.neutral-muted}` | 24px |
| Caret | transition | `{duration.base}` | 200ms · `{easing.out}` |
| Body | padding-inline | `{space.x4}` | 16px |
| Body | padding-block-end | `{space.x4}` | 16px |
| Content | color | `{color.fg.neutral-muted}` | 15px / 1.6 |
| Content | transition | `{duration.base}` | 200ms · `{easing.out}` |

Trigger 최소 높이(48px), 폰트(15px), Caret 크기(24px)는 토큰이 아닙니다.

```json
{
  "accordion": {
    "container": {
      "radius":     { "$type": "dimension", "$value": "{radius.r3}" },
      "background": { "$type": "color", "$value": "{color.bg.layer}" },
      "border":     { "$type": "color", "$value": "{color.border.subtle}" }
    },
    "divider": { "$type": "color", "$value": "{color.border.subtle}" },
    "trigger": {
      "padding-inline": { "$type": "dimension", "$value": "{space.x4}" },
      "padding-block":  { "$type": "dimension", "$value": "{space.x3}" },
      "gap":            { "$type": "dimension", "$value": "{space.x3}" },
      "color":          { "$type": "color", "$value": "{color.fg.neutral}" },
      "bg-hover":       { "$type": "color", "$value": "{color.bg.neutral-weak}" },
      "transition":     { "$type": "duration", "$value": "{duration.fast}" },
      "focus-ring":     { "$type": "color", "$value": "{color.fg.brand}" }
    },
    "caret": {
      "color":      { "$type": "color", "$value": "{color.fg.neutral-muted}" },
      "duration":   { "$type": "duration", "$value": "{duration.base}" },
      "easing":     { "$type": "cubicBezier", "$value": "{easing.out}" }
    },
    "body": {
      "padding-inline":    { "$type": "dimension", "$value": "{space.x4}" },
      "padding-block-end": { "$type": "dimension", "$value": "{space.x4}" }
    },
    "content": {
      "color":    { "$type": "color", "$value": "{color.fg.neutral-muted}" },
      "duration": { "$type": "duration", "$value": "{duration.base}" },
      "easing":   { "$type": "cubicBezier", "$value": "{easing.out}" }
    }
  }
}
```

---

## 6. 접근성

> [!NOTE]
> 참고한 세 시스템 모두 Accordion 의 접근성을 문서화하지 않았습니다.
> 아래 규칙은 ATOM 이 WAI-ARIA 관례를 근거로 정한 것입니다.

- Trigger 는 `<button>` 입니다. `<div onclick>` 은 키보드로 도달할 수 없습니다.
- 각 Trigger 를 주변 위계에 맞는 제목 태그(`<h3>` 등) 안에 넣으면 스크린리더 사용자가 제목 목록으로 항목을 훑어볼 수 있습니다.
- Trigger 에 `aria-expanded` 를 지정합니다. `data-state` 는 겉모습만 바꾸므로 **둘을 함께 갱신해야 합니다.**
- Trigger 가 `aria-controls` 로 패널의 `id` 를 가리키고, 패널이 `role="region"` 과 `aria-labelledby` 로 Trigger 를 되돌아 가리킵니다.
- Caret 은 `aria-hidden="true"` 입니다. 상태는 `aria-expanded` 가 전달합니다.
- `Tab` 으로 Trigger 사이를 이동하고 `Enter` · `Space` 로 토글합니다. 화살표 키는 쓰지 않습니다. 각 Trigger 가 독립된 탭 정거장이라는 점이 Tabs 나 [Radio](./radio.md) 와 다릅니다.
- 탭 순서는 Trigger → 그 항목의 Content → 다음 Trigger 입니다. 열린 패널 안의 링크가 다음 제목보다 먼저 나와야 합니다.
- 닫힌 패널은 `visibility: hidden` 이라 스크린리더가 읽지 않고 탭 순서에도 들어가지 않습니다. `opacity: 0` 이나 높이만 0 으로 숨기면 보이지 않는 내용에 포커스가 들어갑니다.
- 포커스 링은 `outline-offset: -2px` 로 Container 안쪽에 그립니다.
- 대비 — Trigger `--atom-fg-neutral`(17.19:1), Content `--atom-fg-neutral-muted`(6.99:1) 모두 본문 기준을 넘습니다. Caret 은 UI 요소라 3:1 기준이며 같은 토큰으로 충족합니다.
- `prefers-reduced-motion: reduce` 에서 높이 전환과 Caret 회전을 모두 끕니다.

---

## 7. 사용 가이드

### 항목이 하나면 Accordion 을 쓰지 않습니다

접고 펼치며 **탐색**하는 컴포넌트이므로 최소 두 개가 필요합니다. 하나뿐인 내용을 접어야
한다면 그 항목 자체에 펼침 동작을 붙입니다.

- ✅ **Do** 두 개 이상의 항목으로 구성합니다.
- ❌ **Don't** 항목 하나짜리 Accordion 을 만들지 않습니다.

### 제목만 읽고 안에 무엇이 있는지 알게

접힌 상태에서는 제목만 보입니다. "자세히" 나 "기타" 같은 제목으로는 내용을 짐작할 수
없습니다.

- ✅ **Do** 질문이나 결론을 그대로 제목에 씁니다.
- ❌ **Don't** "기타 안내" 처럼 무엇이 들었는지 알 수 없는 제목을 쓰지 않습니다.

### 패널 안에서 스크롤하지 않습니다

Content 에 고정 높이를 주고 내부 스크롤을 만들면, 스크롤 컨테이너가 겹쳐 휠과 스와이프가
갇히고 패널의 실제 길이를 알 수 없습니다. 페이지가 스크롤되게 둡니다.

- ✅ **Do** 내용이 길면 페이지가 늘어나게 둡니다.
- ❌ **Don't** 패널에 `max-height` 와 `overflow: auto` 를 주지 않습니다.

### 행 전체가 클릭 영역입니다

Caret 만 눌리게 만들면 타깃이 24px 로 작아집니다. 그래서 Trigger 는 `width: 100%` 버튼이고
좌우 여백을 직접 가집니다. 최소 높이 48px 는 손가락 타깃 기준을 넘깁니다.

- ✅ **Do** 제목을 눌러도 펼쳐지게 합니다.
- ❌ **Don't** Caret 만 클릭 가능하게 만들지 않습니다.

### 중요한 내용을 접어 두지 않습니다

접힌 내용은 브라우저 검색(`Ctrl F`)에 걸리지 않고 인쇄에서도 빠집니다. 사용자가 열어 보지
않을 수도 있습니다.

- ✅ **Do** 필수 안내는 펼쳐진 상태로 두거나 본문에 둡니다.
- ❌ **Don't** 처리 기한이나 비용 조건을 Accordion 안에만 두지 않습니다.

> [!WARNING]
> **법적으로 알려야 하는 내용은 접지 않습니다**
> 약관·취소 규정처럼 고지 의무가 있는 내용을 Accordion 안에 두면 사용자가 내용을 열어 보지
> 않고 동의하게 됩니다.

> [!NOTE]
> 이 원칙은 참고한 세 시스템(seed · Codeit · Ant) 어디에도 없습니다. ATOM 이 정한 것입니다.

### 중첩하지 않습니다

Accordion 안의 Accordion 은 어느 깊이에 있는지 알기 어렵고, 좌우 여백이 겹쳐 들여쓰기가
무의미해집니다. 두 단계 구조가 필요하면 정보 구조를 다시 검토합니다.

> [!NOTE]
> 중첩에 대한 규칙도 세 레퍼런스 모두 다루지 않습니다. ATOM 이 정한 것입니다.

### Tabs 와 구분하기

| 상황 | 쓸 컴포넌트 |
| --- | --- |
| 여러 개를 동시에 펼쳐 비교할 수 있어야 한다 | **Accordion** |
| 항목이 많고(6개 이상) 각각 내용이 짧다 | **Accordion** |
| 긴 페이지의 스크롤을 줄여야 한다 | **Accordion** |
| 한 번에 하나만 보여주고 항목이 2~5개 | **Tabs** |
| 항목 사이를 자주 왕복한다 | **Tabs** |

Accordion 은 **세로 길이**에 제약을 받고 Tabs 는 **가로 폭**에 제약을 받습니다. 항목이
많으면 Accordion, 라벨이 짧고 개수가 적으면 Tabs 입니다.

### 관련 컴포넌트

- [Select](./select.md) — 같은 자리에서 목록을 펼치지만, 값을 고르고 바로 닫힙니다. Accordion 은 내용을 읽는 동안 열어 둡니다.

---

## 8. 예시

```tsx
<Accordion
  items={[
    { value: "cancel", title: "등록을 취소할 수 있나요?", content: "등록한 날로부터 7일 이내에 신청할 수 있어요." },
    { value: "edit", title: "내용을 어떻게 수정하나요?", content: "등록 내역에서 수정 버튼을 눌러주세요." },
  ]}
/>

<Accordion type="single" variant="flush" headingLevel={2}>
  <Accordion.Item value="step1">
    <Accordion.Trigger>1단계 · 내용 확인</Accordion.Trigger>
    <Accordion.Content>등록 내역을 확인해주세요.</Accordion.Content>
  </Accordion.Item>
  <Accordion.Item value="step2">
    <Accordion.Trigger>2단계 · 승인</Accordion.Trigger>
    <Accordion.Content>승인자를 골라주세요.</Accordion.Content>
  </Accordion.Item>
</Accordion>
```

```html
<div class="atom-accordion atom-accordion--type_multiple">
  <div class="atom-accordion__item" data-state="closed">
    <h3>
      <button class="atom-accordion__trigger" type="button"
              id="acc-1-t" aria-expanded="false" aria-controls="acc-1-p">
        <span class="atom-accordion__title">등록을 취소할 수 있나요?</span>
        <svg class="atom-accordion__caret" aria-hidden="true">
          <use href="#atom-i-chevron-down" />
        </svg>
      </button>
    </h3>
    <div class="atom-accordion__content" role="region"
         id="acc-1-p" aria-labelledby="acc-1-t">
      <div class="atom-accordion__body">
        등록한 날로부터 7일 이내에 신청할 수 있어요.
      </div>
    </div>
  </div>

  <div class="atom-accordion__item" data-state="closed">
    …
  </div>
</div>
```