# Chip

목록을 좁히거나 속성을 토글하는 작은 알약 모양 컨트롤입니다. 네 가지 타입으로 동작합니다.

> 원본: `03_ASSET_GUIDE/catalog/chip.js` · CSS: `03_ASSET_GUIDE/styles/elements/chip.css`
> kind `element` · category `display` · status `stable` · specSource `measured`
> 함께 정의된 블록: [Chip Group](#chip-group) (`atom-chip-group`)

> [!NOTE]
> **기존 프리뷰를 문서화 항목으로 승격한 것입니다**
> `chip` 은 이미 카탈로그에 있었지만 프리뷰 파티셜 안의 인라인 `<style>` 에 variant 3개만
> 정의된 상태였습니다. 그 CSS 를 `styles/elements/chip.css` 로 빼고 네 가지 타입과 선택
> 상태를 얹었습니다. 기존 클래스명(`--variant_neutral-solid` 등)은 그대로 살렸습니다.
> deprecated 항목인 `action-chip` · `control-chip` 이 이 Chip 으로 대체된 것들입니다.

---

## 1. 구성

필수 부품은 Label 과 이를 감싸는 알약 모양 **Container** 이고, 나머지는 선택 사항입니다. 슬롯을
늘릴수록 한 줄에 들어가는 Chip 개수가 줄어드니 필요한 것만 답니다.

```
╭────────────────╮   ╭──────────────────────────╮
│ [✓] 사용중      │   │ [🔍] 분류  3  [⌄]         │
╰────────────────╯   ╰──────────────────────────╯
 ①  ②   ③              ④     ③   ⑤   ⑥
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| ① | Container | 필수 | `atom-chip` | 터치 영역과 배경, 알약 모서리를 담당합니다. 높이가 size 를 결정합니다. |
| ② | Check | 선택 | `atom-chip__check` | 선택됐을 때만 자리를 차지합니다. |
| ③ | Label | 필수 | `atom-chip__label` | 필수입니다. |
| ④ | Prefix icon | 선택 | `atom-chip__prefix` | 라벨의 의미를 보조합니다. |
| ⑤ | Count | 선택 | `atom-chip__count` | 뒤에 붙는 개수입니다. |
| ⑥ | Caret | 선택 | `atom-chip__caret` | 메뉴를 여는 button 타입에서만 씁니다. |
| — | Input | radio · checkbox 타입 | `atom-chip__input` | `<label>` 뒤에 시각적으로 감춘 실제 radio/checkbox 입니다. |

---

## 2. 종류 / 크기

### Type

타입은 네 가지입니다. **상태를 갖는지**, 갖는다면 **그룹 안에서 배타적인지**로
구분합니다.

| Type | 상태 | 마크업 | 상태 속성 |
|---|---|---|---|
| `button` | 없음 | `<button type="button">` | — |
| `toggle` | 혼자 on / off | `<button type="button">` | `aria-pressed` |
| `radio` | 그룹 안에서 하나만 | `<label>` | `<input type="radio">` |
| `checkbox` | 그룹 안에서 여러 개 | `<label>` | `<input type="checkbox">` |

> [!WARNING]
> **`--type_*` 는 마크업 규칙을 나타냅니다**
> 이 모디파이어는 스타일을 거의 바꾸지 않습니다. 실제 차이는 위 표의 마크업에 있고, 클래스는
> 이 Chip 이 어느 타입의 마크업을 따르는지 나타냅니다. `--type_radio` 를 붙이고
> `<button>` 을 쓰면 스크린리더는 그것을 그룹으로 읽지 않습니다.

### 선택 상태

toggle · radio · checkbox 세 타입이 공유합니다. 선택되면 variant 와 관계없이 **solid 로
채워집니다.** 정적인 마크업에서는 `data-selected`, 실제 컨트롤에서는
`aria-pressed="true"` 나 `__input:checked` 가 같은 결과를 냅니다.

`__check` 는 넣으면 선택됐을 때만 폭을 얻습니다. 자리를 미리 비워두면 선택되지 않은 줄의
정렬이 어긋나 보이기 때문입니다. 라벨이 짧고 개수가 많은 그룹에서는 빼는 것을 권장합니다.

### Variant

**선택되지 않았을 때**의 생김새입니다. `neutral-weak` 가 기본이고, 배경이 이미 회색인 표면
위에서는 `neutral-outline` 을 씁니다. `neutral-solid` 는 상태가 없는 button 타입 중 강조가
필요한 것에만 씁니다.

### Size

`medium` 33px 이 기본이고, 표 안이나 카드 안처럼 이미 밀도가 높은 곳에서 `small` 28px 을
씁니다. 한 화면에서 두 사이즈를 섞지 않습니다.

| Size | 높이 | 좌우 여백 | 폰트 | 주 사용처 |
|---|---|---|---|---|
| `small` | 28px | 8px | 12px | 표·카드 안 |
| `medium` | 33px | 12px | 13px | 본문 기본값 |

### 슬롯

Prefix icon · Count · Caret 은 전부 선택 사항입니다. Caret 이 붙은 Chip 은 누르면 메뉴가
열린다는 뜻이므로, 그 자리에서 값이 바뀌는 toggle 에는 쓰지 않습니다.

### Chip Group

Chip 은 거의 항상 여러 개가 함께 놓입니다. 줄바꿈과 가로 스크롤 중 하나를 고르세요.

| | 동작 | 쓰는 곳 |
|---|---|---|
| `--scroll` | 한 줄을 유지하고 옆으로 넘김 | 헤더 아래 고정된 필터 바 — 높이가 변하면 안 되는 자리 |
| `--wrap` | 다음 줄로 넘어감 | 전체 선택지를 한눈에 보여야 하는 폼 |

> [!NOTE]
> **radio 그룹에는 `role="radiogroup"` 을 답니다**
> `<input type="radio">` 들이 같은 `name` 을 공유해도, 그것을 감싼 상자에 역할과 이름이 없으면
> 스크린리더는 무엇을 고르는 중인지 알려주지 못합니다.

### 클래스 계약

`styles/elements/chip.css` 헤더와 원본 `registry.json` `css.blocks` 기준입니다. 클래스가 없는 값(—)은 기본 스타일 그대로입니다.

| Prop | 값 | 클래스 |
|---|---|---|
| `type` | `button` · `toggle` · `radio` · `checkbox` | `--type_button` · `--type_toggle` · `--type_radio` · `--type_checkbox` |
| `variant` | `neutral-weak` · `neutral-outline` · `neutral-solid` | `--variant_neutral-weak` · `--variant_neutral-outline` · `--variant_neutral-solid` |
| `size` | `small` · `medium` | `--size_small` · — |
| `showCheck` | `true` | `__check` |
| `prefixIcon` | | `__prefix` |
| `count` | | `__count` |
| `caret` | `true` | `__caret` |
| `ChipGroup` `overflow` | `wrap` · `scroll` | `atom-chip-group--wrap` · `atom-chip-group--scroll` |

상태 선택자: `[data-selected]` · `[aria-pressed="true"]` · `:has(.atom-chip__input:checked)` · `:hover` · `[data-state="open"]` · `:focus-visible` · `:has(.atom-chip__input:focus-visible)` · `[disabled]` · `[aria-disabled="true"]`

---

## 3. 상태

| State | 표현 | 선택자 |
|---|---|---|
| `selected` | variant 와 관계없이 `--atom-bg-neutral-solid` 로 채우고 글자 `--atom-fg-on-solid` · 600. `__check` 가 폭을 얻음 | `[data-selected]` · `[aria-pressed="true"]` · `:has(.atom-chip__input:checked)` |
| `hover` | `filter: brightness(0.96)` | `:hover:not([disabled]):not([aria-disabled="true"])` |
| `open` | Caret 이 180° 회전 | `[data-state="open"]` |
| `focus-visible` | `--atom-fg-brand` 2px outline, offset 2px | `:focus-visible` · `:has(.atom-chip__input:focus-visible)` |
| `disabled` | `opacity: 0.4`, 커서 `not-allowed` | `[disabled]` · `[aria-disabled="true"]` |

---

## 4. Props

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `type` | `"button" \| "toggle" \| "radio" \| "checkbox"` | `"button"` | | Chip 이 따르는 동작 계약입니다. 렌더되는 마크업이 함께 바뀝니다. |
| `children` | `ReactNode` | | ● | 라벨 텍스트입니다. |
| `variant` | `"neutral-weak" \| "neutral-outline" \| "neutral-solid"` | `"neutral-weak"` | | 선택되지 않았을 때의 생김새입니다. |
| `size` | `"small" \| "medium"` | `"medium"` | | Chip 높이와 폰트 크기를 결정합니다. |
| `selected` | `boolean` | `false` | | `button` 을 뺀 세 타입에서 씁니다. 켜지면 solid 로 채워집니다. |
| `showCheck` | `boolean` | `false` | | 선택됐을 때 앞에 체크 표시를 넣습니다. |
| `prefixIcon` | `ReactNode` | | | 라벨 앞 아이콘입니다. |
| `count` | `number` | | | 라벨 뒤에 붙는 개수입니다. |
| `caret` | `boolean` | `false` | | 메뉴를 여는 `button` 타입에 화살표를 답니다. |
| `open` | `boolean` | `false` | | `caret` 이 있을 때 화살표를 뒤집습니다. |
| `disabled` | `boolean` | `false` | | 누를 수 없게 만듭니다. |
| `name` | `string` | | | `radio` 타입에서 같은 그룹을 묶는 이름입니다. |
| `onClick` | `() => void` | | | `button` 타입에서 호출됩니다. |
| `onSelectedChange` | `(selected: boolean) => void` | | | `toggle` · `radio` · `checkbox` 에서 상태가 바뀔 때 호출됩니다. |

### Parts (compound)

| Part | 요소 | 설명 |
|---|---|---|
| `Chip` | `button` · `toggle`: `<button type="button" class="atom-chip">` / `radio` · `checkbox`: `<label class="atom-chip">` + `<input class="atom-chip__input">` | 위 Props 를 받습니다. 구현은 uncontrolled 용 `defaultSelected`, 폼 값 `value`, 실제 input 에 넘길 `inputProps` 를 더 받습니다. |
| `ChipGroup` | `<div class="atom-chip-group">` | 묶음. `overflow`(`"wrap"` · `"scroll"`)로 `--wrap` · `--scroll` 을 고르고, `name` 을 안의 radio · checkbox Chip 에 나눠 줍니다. radio 묶음에는 `role="radiogroup"` 과 `aria-label` 을 함께 넘깁니다. |

---

## 5. Component tokens

| 대상 | 속성 | Token | Value |
|---|---|---|---|
| Container | radius | `{radius.full}` | |
| Container (weak) | background | `{color.bg.neutral-weak}` | |
| Container (outline) | border | `{color.border.default}` | inset 1px |
| Container (solid · 선택됨) | background | `{color.bg.neutral-solid}` | |
| Label (solid · 선택됨) | color | `{color.fg.on-solid}` | |
| Label | color | `{color.fg.neutral}` | |
| Container | padding-inline | `{space.x3}` (small `{space.x2}`) | 12px / 8px |
| Group | gap | `{space.x2}` | |
| Focus ring | outline | `{color.fg.brand}` | 2px, offset 2px |
| 전환 | duration | `{duration.fast}` | |
| Caret 회전 | duration · easing | `{duration.base}` · `{easing.out}` | |

```json
{
  "chip": {
    "radius": { "$type": "dimension", "$value": "{radius.full}" },
    "padding-inline": {
      "$type": "dimension",
      "medium": { "$value": "{space.x3}" },
      "small": { "$value": "{space.x2}" }
    },
    "neutral-weak":    { "$type": "color", "bg": { "$value": "{color.bg.neutral-weak}" }, "fg": { "$value": "{color.fg.neutral}" } },
    "neutral-outline": { "$type": "color", "border": { "$value": "{color.border.default}" }, "fg": { "$value": "{color.fg.neutral}" } },
    "neutral-solid":   { "$type": "color", "bg": { "$value": "{color.bg.neutral-solid}" }, "fg": { "$value": "{color.fg.on-solid}" } },
    "selected":        { "$type": "color", "bg": { "$value": "{color.bg.neutral-solid}" }, "fg": { "$value": "{color.fg.on-solid}" } },
    "focus-ring":      { "$type": "color", "$value": "{color.fg.brand}" },
    "transition":      { "$type": "duration", "$value": "{duration.fast}" },
    "caret-rotate": {
      "duration": { "$type": "duration", "$value": "{duration.base}" },
      "easing": { "$type": "cubicBezier", "$value": "{easing.out}" }
    },
    "group": {
      "gap": { "$type": "dimension", "$value": "{space.x2}" }
    }
  }
}
```

---

## 6. 접근성

- **마크업** — 타입마다 다릅니다. button · toggle 은 `<button type="button">`, radio ·
  checkbox 는 `<label>` 안에 실제 `<input>` 을 둡니다.
- **toggle** — `aria-pressed` 를 `true` / `false` 로 갱신합니다. 눌린 상태를 클래스로만
  표시하면 스크린리더에 전달되지 않습니다.
- **radio 그룹** — 감싸는 요소에 `role="radiogroup"` 과 `aria-label` 을 답니다.
- **숨긴 input** — `__input` 은 화면에서만 감춥니다. `display: none` 이나
  `visibility: hidden` 은 초점과 접근성 트리에서도 제거하므로 쓰지 않습니다.
- **아이콘** — `__check` · `__prefix` · `__caret` 은 전부 장식이므로 `aria-hidden="true"` 를
  답니다. 상태는 `aria-pressed` / `:checked` 가 전달합니다.
- **초점** — `:focus-visible` 로 두고, `<input>` 이 초점을 받을 때는 감싼 Chip 에 표시가
  나타나야 합니다.
- **비활성** — `<button disabled>` 또는 `aria-disabled="true"` 로 알립니다. 흐리게만 하면
  초점은 계속 들어갑니다.
- **대비** — 선택된 Chip 은 `--atom-bg-neutral-solid` 위에 `--atom-fg-on-solid` 로 본문 대비
  4.5:1 을 충족합니다.

원본 Specification 의 Accessibility 절:

- **역할** — button·toggle 은 `button`, radio·checkbox 는 실제 `<input>`. 타입을 클래스로만
  바꾸면 보조기술에 전달되지 않습니다.
- **키보드** — Tab 으로 이동, Space·Enter 로 활성화. radio 그룹은 화살표로 이동합니다.
- **스크린리더** — `aria-pressed` / `:checked` 가 상태를, `role="radiogroup"` + `aria-label`
  이 그룹의 목적을 전달합니다.
- **대비** — 선택 상태는 색상 대신 명도 차이(채움)로 구분합니다.

---

## 7. 사용 가이드

### 선택은 채움으로 알립니다

테두리 색이나 글자 색만 바꾸면 선택 여부가 잘 보이지 않고, 색각 이상 사용자는 구분할 수
없습니다.

- ✅ **Do** 선택된 Chip 을 채웁니다. 명도 차이로 구분됩니다.
- ❌ **Don't** 테두리와 글자 색만 바꾸지 않습니다.

### 라벨은 한 덩어리로

Chip 은 줄바꿈하지 않습니다(`white-space: nowrap`). 라벨이 길면 한 개가 줄 전체를
차지하므로 명사 한 덩어리로 씁니다. 설명이 필요하면 [Checkbox](./checkbox.md) 를
씁니다.

- ✅ **Do** 명사 한 덩어리. 한 줄에 여러 개가 들어갑니다.
- ❌ **Don't** 문장을 라벨로 쓰지 않습니다.

### 다른 컨트롤과 구분하기

| 상황 | 쓸 컴포넌트 |
|---|---|
| 목록을 좁히는 조건을 한 줄에 늘어놓는다 | **Chip** |
| 선택지마다 설명이 붙고 세로로 읽는다 | [Checkbox](./checkbox.md) · [Radio](./radio.md) |
| 선택지가 6개 이상이라 펼쳐서 고른다 | [Select](./select.md) |
| 여러 개를 고르는데 선택지가 많다 | [Multi Select](./multi-select.md) |
| 설정 하나를 켜고 끄고, 라벨이 왼쪽에 따로 있다 | Switch |

> [!NOTE]
> **Badge 와 구분합니다**
> [Badge](./badge.md) 는 읽기 전용 표식이고 누를 수 없습니다. Chip 은 전부 누를 수
> 있습니다. 누를 수 없는 요소에 Chip 을 쓰면 누를 수 있는 것으로 오해합니다.

### 관련 컴포넌트

- [Checkbox](./checkbox.md) — 선택지마다 설명이 붙고 세로로 읽을 때.
- [Radio](./radio.md) — 배타 선택을 전부 펼쳐 보여줄 때.
- [Badge](./badge.md) — 누를 수 없는 읽기 전용 표식.

---

## 8. 예시

```tsx
<Chip>필터 초기화</Chip>

<Chip type="toggle" selected={on} onSelectedChange={setOn}>알림 받기</Chip>

<ChipGroup role="radiogroup" aria-label="정렬" name="sort">
  <Chip type="radio" selected={sort === "new"} onSelectedChange={() => setSort("new")}>최신순</Chip>
  <Chip type="radio" selected={sort === "name"} onSelectedChange={() => setSort("name")}>이름순</Chip>
</ChipGroup>

<ChipGroup overflow="scroll">
  <Chip type="checkbox" showCheck defaultSelected>사용중</Chip>
</ChipGroup>
```

```html
<!-- button — 상태 없음 -->
<button class="atom-chip atom-chip--type_button" type="button">
  <span class="atom-chip__label">필터 초기화</span>
</button>

<!-- toggle — 혼자 켜고 끈다 -->
<button class="atom-chip atom-chip--type_toggle" type="button"
        aria-pressed="true">
  <span class="atom-chip__label">알림 받기</span>
</button>

<!-- radio — 그룹 안에서 하나만 -->
<div class="atom-chip-group" role="radiogroup" aria-label="정렬">
  <label class="atom-chip atom-chip--type_radio">
    <input class="atom-chip__input" type="radio" name="sort" checked />
    <span class="atom-chip__label">최신순</span>
  </label>
  <label class="atom-chip atom-chip--type_radio">
    <input class="atom-chip__input" type="radio" name="sort" />
    <span class="atom-chip__label">이름순</span>
  </label>
</div>

<!-- checkbox — 그룹 안에서 여러 개 -->
<div class="atom-chip-group atom-chip-group--scroll">
  <label class="atom-chip atom-chip--type_checkbox">
    <input class="atom-chip__input" type="checkbox" checked />
    <svg class="atom-chip__check" aria-hidden="true">
      <use href="#atom-i-check" />
    </svg>
    <span class="atom-chip__label">사용중</span>
  </label>
</div>
```

---

## Chip Group

Chip 을 여러 개 늘어놓는 묶음입니다. `chip.css` 안에 함께 정의된 `atom-chip-group` 블록입니다 (`role: sibling`).

| 클래스 | 동작 | 쓰는 곳 |
|---|---|---|
| `atom-chip-group` | 한 줄 flex, gap `--atom-x2` | 기본 |
| `atom-chip-group--scroll` | 한 줄을 유지하고 옆으로 넘김 (스크롤바 숨김, Chip 이 줄어들지 않음) | 헤더 아래 고정된 필터 바 — 높이가 변하면 안 되는 자리 |
| `atom-chip-group--wrap` | 다음 줄로 넘어감 (row-gap `--atom-x2`) | 전체 선택지를 한눈에 보여야 하는 폼 |

radio Chip 을 묶을 때는 `role="radiogroup"` 과 `aria-label` 을 답니다.