# Checkbox

여러 항목을 독립적으로 켜고 끌 수 있게 하는 선택 컴포넌트입니다.

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

---

## 1. 구성

네모난 **Control** 과 그 안의 **Check**, 그리고 **Label** 로 구성됩니다. 보충 설명이
필요하면 라벨 아래에 Description 을 둡니다.

```
┌──┐
│✓ │  마케팅 정보 수신 동의
└──┘  선택 항목이에요
 ①②     ③
        ④
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| — | Root | 필수 | `atom-checkbox` | `<label>` — 라벨 전체가 눌리게 합니다. |
| — | Input | 실제 컨트롤일 때 | `atom-checkbox__input` | 시각적으로 감춘 `<input type="checkbox">`. Control 바로 앞에 둡니다. |
| ① | Control | 필수 | `atom-checkbox__control` | 22px 네모. 배경·테두리로 상태를 그립니다. |
| ② | Check | 필수 | `atom-checkbox__check` (indeterminate 는 `atom-checkbox__indeterminate`) | Control 안의 체크 아이콘(또는 가로 막대). |
| ③ | Label | 필수 | — (`<span>`) | 항목 이름입니다. |
| ④ | Description | 선택 | `atom-checkbox__description` | 라벨 아래 보충 설명. Label 과 함께 `atom-checkbox__text` 로 묶습니다. |

> [!NOTE]
> **터치 영역은 라벨까지**
> Control 만 22px 이라 단독으로는 너무 작습니다. 항상 `<label>` 로 감싸 라벨 전체가
> 눌리게 만드세요.

---

## 2. 종류 / 크기

### State

`unchecked`, `checked`, `indeterminate` 세 가지 선택 상태에, `invalid` 와 `disabled` 가
겹쳐질 수 있습니다.

| State | 의미 | 언제 쓰나 |
|---|---|---|
| `unchecked` | 선택되지 않음 | 기본값 |
| `checked` | 선택됨 | 사용자가 켠 항목 |
| `indeterminate` | 일부만 선택됨 | 하위 항목 중 일부만 켜진 '전체 선택' 체크박스 |
| `invalid` | 검증 실패 | 필수 동의를 켜지 않고 제출한 경우 |
| `disabled` | 조작 불가 | 권한이 없거나 선행 조건이 미충족인 경우 |

`checked` 와 `indeterminate` 는 같은 배경(`--atom-bg-neutral-solid`)을 쓰고, 안에 그려지는
표식(체크 아이콘 또는 가로 막대)만 다릅니다.

`invalid` 는 **Control 테두리만** 오류 색으로 바꿉니다. 오류 메시지는 Checkbox 가 갖지 않고
[Field](./field.md) 의 `__error` 에만 노출합니다.

### Size

`medium` 이 기본입니다. `small` 은 필터 시트처럼 항목이 촘촘한 곳, `large` 는 약관 동의처럼
항목 하나가 중요한 곳에 씁니다.

| Size | Control | 모서리 | Check | 라벨 폰트 | gap |
|---|---|---|---|---|---|
| `small` | 18×18px | 4px | 12px | 14px | 8px |
| `medium` | 22×22px | 4px | 14px | 15px | 10px |
| `large` | 26×26px | 5px | 17px | 16px | 12px |

### Group

여러 개를 묶을 때는 `atom-checkbox-group` 으로 감쌉니다. 기본은 세로 배치이고, 라벨이 아주
짧을 때만 `horizontal` 을 씁니다.

세로 간격은 `--atom-x4`(16px), 가로 배치의 간격은 `--atom-x5`(20px)입니다. 가로가 더 넓은
것은 옆으로 늘어선 항목이 세로로 쌓인 항목보다 서로 붙어 보이기 때문입니다.

### 실제 input 과 함께

`data-state` 없이 숨겨진 `<input type="checkbox">` 만 넣어도 동작합니다. `:checked` 규칙이
함께 정의되어 있으니, 아래 데모는 실제로 눌러볼 수 있습니다.

### Align

CSS 헤더의 `--align_top` 은 라벨이 한 줄을 넘을 때(label wraps to more than one line) Control 을 첫 줄에 맞춥니다.
원본 Props 표에는 없고, 원본 Anatomy 데모가 Description 과 함께 씁니다.

### 클래스 계약

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

| Prop | 값 | 클래스 |
|---|---|---|
| `size` | `small` · `medium` · `large` | `--size_small` · — · `--size_large` |
| (`alignTop`) | `true` | `--align_top` |
| `checked` | `false` · `true` · `"indeterminate"` | `[data-state="unchecked"]` · `[data-state="checked"]` · `[data-state="indeterminate"]` |
| `invalid` | `true` | `[data-invalid]` |
| `disabled` | `true` | `[data-disabled]` |
| `CheckboxGroup` `layout` | `vertical` · `horizontal` | — · `atom-checkbox-group--layout_horizontal` |

상태 선택자: `[data-state="unchecked|checked|indeterminate"]` · `.atom-checkbox__input:checked + .atom-checkbox__control` · `:hover:not([data-disabled])` · `.atom-checkbox__input:focus-visible + .atom-checkbox__control` · `[data-invalid]` · `[data-disabled]`

---

## 3. 상태

| State | 표현 | 선택자 |
|---|---|---|
| `unchecked` | `--atom-bg-layer` 배경, `--atom-border-default` 1.5px inset 테두리 | `[data-state="unchecked"]` |
| `checked` | `--atom-bg-neutral-solid` 로 채우고 Check 표시 | `[data-state="checked"]` · `__input:checked + __control` |
| `indeterminate` | `--atom-bg-neutral-solid` 로 채우고 가로 막대 표시 | `[data-state="indeterminate"]` |
| `hover` | 테두리 `--atom-fg-neutral-subtle`. 선택됐을 때는 `filter: brightness(0.9)` | `:hover:not([data-disabled])` |
| `focus-visible` | Control 에 `--atom-primary-600` 2px outline, offset 2px | `__input:focus-visible + __control` |
| `invalid` | Control 테두리 `--atom-fg-critical`, Description 도 오류 색 | `[data-invalid]` |
| `disabled` | `opacity: 0.4`, 커서 `not-allowed` | `[data-disabled]` |

---

## 4. Props

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `checked` | `boolean \| "indeterminate"` | `false` | | 선택 상태입니다. |
| `size` | `"small" \| "medium" \| "large"` | `"medium"` | | Control 크기와 폰트 크기를 결정합니다. |
| `invalid` | `boolean` | `false` | | Control 테두리를 오류 색으로 바꿉니다. 오류 메시지는 Field 가 보여줍니다. |
| `disabled` | `boolean` | `false` | | 조작할 수 없게 만듭니다. |
| `description` | `ReactNode` | | | 라벨 아래에 놓이는 보충 설명입니다. |
| `onCheckedChange` | `(checked: boolean) => void` | | | 선택 상태가 바뀔 때 호출됩니다. |

### Parts (compound)

| Part | 요소 | 설명 |
|---|---|---|
| `Checkbox` | `<label class="atom-checkbox">` > `<input class="atom-checkbox__input">` + `<span class="atom-checkbox__control">` + 라벨 | 위 Props 를 받습니다. 나머지 속성(`name` · `value` · `required` …)과 `ref` 는 실제 `<input>` 에, `className` 은 바깥 `<label>` 에 붙습니다. 구현은 uncontrolled 용 `defaultChecked` 와 `alignTop` 을 더 받습니다. Field 안에서는 `useFieldControl()` 로 id · aria-describedby · aria-invalid · disabled · required 를 맞춥니다. |
| `Checkbox.Label` | `<span>` | 라벨 텍스트. 문자열 자식은 자동으로 이 자리에 들어가므로 Description 파트와 함께 쓸 때만 필요합니다. |
| `Checkbox.Description` | `<span class="atom-checkbox__description">` | 보충 설명. `description` prop 과 같은 결과이며, 있으면 Label 과 함께 `atom-checkbox__text` 로 묶고 `--align_top` 을 켭니다. |
| `CheckboxGroup` | `<div class="atom-checkbox-group" role="group">` | 묶음. `layout`(`"vertical"` · `"horizontal"`), `value` · `defaultValue` · `onValueChange`(`string[]`), `name`, `disabled`, `invalid` 를 받고 안의 `Checkbox` 는 `value` 로 식별됩니다. `aria-label` / `aria-labelledby` 로 이름을 붙이며, Field 안에서는 Field.Label 이 이름이 됩니다. |

---

## 5. Component tokens

| 대상 | 속성 | Token | Value |
|---|---|---|---|
| Control | radius | `{radius.r1}` | 4px |
| Control | background | `{color.bg.layer}` | |
| Control | border | `{color.border.default}` 1.5px inset | |
| Control (checked) | background · border | `{color.bg.neutral-solid}` | |
| Check | color | `{color.fg.on-solid}` | |
| Indeterminate 막대 | radius | `{radius.full}` | 9999px |
| Label | color | `{color.fg.neutral}` | |
| Description | color | `{color.fg.neutral-muted}` | 13px |
| hover | border | `{color.fg.neutral-subtle}` 1.5px inset | |
| focus | outline | `{color.primary.600}` 2px, offset 2px | |
| invalid | border | `{color.fg.critical}` 1.5px inset | |
| disabled | opacity | — | `0.4` |
| Group | gap | `{space.x4}` / `{space.x5}` | 16px / 20px |
| transition | duration | `{duration.fast}` | 120ms |

> [!WARNING]
> **`large` 의 모서리는 토큰이 아닙니다**
> `.atom-checkbox--size_large .atom-checkbox__control` 이 `border-radius: 5px` 를 직접
> 씁니다. `--atom-radius-r1`(4px)과 `r2`(8px) 사이 값이 필요했던 것으로 보입니다.
> Radius 에도 기록되어 있습니다. `r1` 로 되돌리거나
> 6px 토큰을 추가할지 정해야 합니다.

```json
{
  "checkbox": {
    "control": {
      "radius": {
        "$type": "dimension",
        "default": { "$value": "{radius.r1}" },
        "large": { "$value": "5px" }
      },
      "bg": { "$type": "color", "$value": "{color.bg.layer}" },
      "border": { "$type": "color", "$value": "{color.border.default}" },
      "checked-bg": { "$type": "color", "$value": "{color.bg.neutral-solid}" },
      "hover-border": { "$type": "color", "$value": "{color.fg.neutral-subtle}" },
      "invalid-border": { "$type": "color", "$value": "{color.fg.critical}" }
    },
    "check": { "$type": "color", "$value": "{color.fg.on-solid}" },
    "indeterminate-radius": { "$type": "dimension", "$value": "{radius.full}" },
    "label": { "$type": "color", "$value": "{color.fg.neutral}" },
    "description": { "$type": "color", "$value": "{color.fg.neutral-muted}" },
    "focus-ring": { "$type": "color", "$value": "{color.primary.600}" },
    "disabled-opacity": { "$type": "number", "$value": 0.4 },
    "group": {
      "$type": "dimension",
      "gap-vertical": { "$value": "{space.x4}" },
      "gap-horizontal": { "$value": "{space.x5}" }
    },
    "transition": { "$type": "duration", "$value": "{duration.fast}" }
  }
}
```

---

## 6. 접근성

- **요소** — `<label>` 로 감싼 `<input type="checkbox">` 를 씁니다. 이렇게 하면 라벨 클릭,
  키보드 조작, 스크린리더 읽기가 전부 브라우저 기본 동작으로 해결됩니다.
- **키보드** — `Tab` 으로 포커스, `Space` 로 토글합니다. `Enter` 는 동작하지 않습니다
  (체크박스는 버튼이 아니라 폼 컨트롤이므로 `Enter` 는 폼을 제출합니다).
- **`indeterminate`** — CSS 클래스만으로는 스크린리더에 전달되지 않습니다.
  JavaScript 로 `input.indeterminate = true` 를 설정해야 `aria-checked="mixed"` 로 읽힙니다.
  `data-state="indeterminate"` 는 겉모습만 바꿉니다.
- **포커스 표시** — `.atom-checkbox__input:focus-visible + .atom-checkbox__control` 이
  `--atom-primary-600` 2px outline 을 그립니다. 숨겨진 input 이 포커스를 받으므로
  포커스 링은 Control 에 나타납니다.
- **그룹** — 여러 체크박스에 공통 질문이 있으면 `<fieldset>` + `<legend>` 로 묶습니다.
  `role="group"` + `aria-labelledby` 도 같은 역할을 합니다.
- **오류** — `invalid` 는 색만 바꿉니다. 스크린리더에 알리려면 `aria-invalid="true"` 와
  `aria-describedby` 로 Field 의 오류 메시지를 연결해야 합니다.
  [Form Field](./field.md) 로 감싸면 이 배선이 함께 처리됩니다.
- **터치 영역** — Control 은 `small` 18px · `medium` 22px 로 권장 최소 44×44px 에 크게
  못 미칩니다. `<label>` 로 감싸 라벨 전체를 타깃으로 만드는 것이 필수입니다.
- **대비** — 기본 테두리 `--atom-border-default` 는 흰 배경 대비 **1.36:1** 로
  WCAG 1.4.11 의 UI 요소 기준 3:1 에 미달합니다.
  Color 의 Accessibility 항목을 참고하세요.
- **강제 색상 모드** — 테두리를 `inset box-shadow` 로 그리므로 Windows 고대비 모드에서
  사라집니다.

---

## 7. 사용 가이드

### Switch 와 구분하기

Checkbox 는 **제출해야 반영되는 선택**이고, [Switch](./switch.md) 는 **켜는 즉시 반영되는
설정**입니다.

| | Checkbox | Switch |
|---|---|---|
| 반영 시점 | 제출 버튼을 눌렀을 때 | 조작하는 즉시 |
| 개수 | 여러 개를 함께 | 보통 하나씩 |
| 상하위 관계 | 상위가 하위를 제어한다 | 부모-자식 관계가 없다 |
| 예시 | 약관 동의, 필터 선택 | 알림 켜기 |

동의·수락에는 Switch 를 쓰지 않습니다. 동의는 제출 전에 하는 **선택**이므로 Checkbox 를
씁니다.

### 라벨은 긍정문으로

부정문 라벨은 체크했을 때의 상태를 이해하기 어렵게 만듭니다.

- ✅ **Do** 체크하면 켜지는 것을 그대로 적습니다.
- ❌ **Don't** '~하지 않음' 같은 부정문을 쓰지 않습니다.

### 전체 선택

- 하위 항목이 모두 켜지면 전체 선택은 `checked` 입니다.
- 일부만 켜지면 `indeterminate` 입니다. `unchecked` 로 두면 사용자가 아무것도 선택하지
  않았다고 오해합니다.
- 전체 선택을 누르면 하위 전부를 같은 상태로 맞춥니다.

`indeterminate` 는 **사용자가 직접 만들 수 있는 상태가 아닙니다.** 하위 항목의 조합에서
파생되는 값이므로, 전체 선택 체크박스를 눌러 `indeterminate` 로 가는 경로는 없어야 합니다.

### 항목이 하나뿐이면 그룹으로 묶지 않습니다

체크박스 하나에 그룹 라벨을 붙이면 불필요한 위계가 생깁니다. 체크박스 라벨 하나만 둡니다.

- ✅ **Do** 단일 동의 항목은 체크박스 하나로 둡니다.
- ❌ **Don't** 항목 하나짜리 `atom-checkbox-group` 을 만들지 않습니다.

### Description 은 선택을 돕는 정보만

라벨로 이미 알 수 있는 내용을 반복하면 목록이 두 배로 길어집니다. 선택을 바꿀 만한 정보가
있을 때만 붙입니다.

- ✅ **Do** "월 1회 자동 실행 · 언제든 해제 가능" 처럼 판단에 필요한 조건을 적습니다.
- ❌ **Don't** 라벨을 풀어 쓴 문장을 Description 으로 두지 않습니다.

### 관련 컴포넌트

- [Radio](./radio.md) — 여러 항목 중 하나만 골라야 할 때.
- [Field](./field.md) — 라벨·오류 메시지를 붙일 때 감싸는 래퍼.

---

## 8. 예시

```tsx
<Checkbox description="선택 항목이에요">마케팅 정보 수신 동의</Checkbox>

<Checkbox checked={all} onCheckedChange={toggleAll}>전체 선택</Checkbox>  {/* all: boolean | "indeterminate" */}

<CheckboxGroup aria-label="약관 동의" value={value} onValueChange={setValue}>
  <Checkbox value="terms">서비스 이용약관 동의 (필수)</Checkbox>
  <Checkbox value="marketing">
    <Checkbox.Label>마케팅 정보 수신 동의 (선택)</Checkbox.Label>
    <Checkbox.Description>월 1회 · 언제든 해제 가능</Checkbox.Description>
  </Checkbox>
</CheckboxGroup>
```

```html
<label class="atom-checkbox">
  <input class="atom-checkbox__input" type="checkbox" />
  <span class="atom-checkbox__control">
    <svg class="atom-checkbox__check" viewBox="0 0 16 16" aria-hidden="true">
      <path d="m3 8.5 3.2 3.2L13 5" fill="none" stroke="currentColor"
            stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" />
    </svg>
  </span>
  <span>서비스 이용약관 동의</span>
</label>
```

```html
<!-- 전체 선택 (indeterminate) -->
<label class="atom-checkbox" data-state="indeterminate">
  <span class="atom-checkbox__control">
    <span class="atom-checkbox__indeterminate"></span>
  </span>
  <span>전체 선택</span>
</label>
```

---

## Checkbox Group

여러 체크박스를 묶는 블록입니다. `checkbox.css` 안에 함께 정의된 `atom-checkbox-group` 입니다 (`role: sibling`).

| 클래스 | 배치 | 간격 |
|---|---|---|
| `atom-checkbox-group` | 세로 (기본) | `--atom-x4` 16px |
| `atom-checkbox-group--layout_horizontal` | 가로, 줄바꿈 허용 | `--atom-x5` 20px |

```html
<div class="atom-checkbox-group atom-checkbox-group--layout_horizontal">
  <span class="atom-checkbox atom-checkbox--size_small" data-state="checked">…</span>
  <span class="atom-checkbox atom-checkbox--size_small" data-state="unchecked">…</span>
</div>
```

그룹 이름은 `<fieldset>` + `<legend>` 나 `role="group"` + `aria-labelledby` 로 붙입니다(접근성 참조).