# Radio

서로 배타적인 항목 중에서 하나만 고르게 하는 선택 컴포넌트입니다.

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

---

## 1. 구성

원형 **Control** 과 **Label** 로 구성됩니다. 선택지 사이의 차이를 설명해야 할 때는 라벨
아래에 Description 을 둡니다.

```
 ◉  직접 가져가기
    약속 장소에서 만나 거래해요
 ①  ②
    ③
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| — | Root | 필수 | `atom-radio` | `<label>` — 라벨까지 타깃에 포함시킵니다. Card 안에서는 `<span>` 입니다. |
| — | Input | 실제 컨트롤일 때 | `atom-radio__input` | 시각적으로 감춘 `<input type="radio">`. Control 바로 앞에 둡니다. |
| ① | Control | 필수 | `atom-radio__control` | 원형. checked 는 두꺼운 inset 그림자와 `::after` 점으로 그립니다. |
| ② | Label | 필수 | — (`<span>`) | 선택지 이름입니다. |
| ③ | Description | 선택 | `atom-radio__description` | 라벨 아래 보충 설명. Label 과 함께 `atom-radio__text` 로 묶습니다. |

> [!NOTE]
> Radio 는 **혼자 쓰이지 않습니다.** 항상 두 개 이상을 하나의 그룹으로 묶고,
> 그룹에 `role="radiogroup"` 을 지정하세요.

---

## 2. 종류 / 크기

### State

[Checkbox](./checkbox.md) 와 달리 `indeterminate` 가 없습니다. 그룹 안에서 항상 정확히
하나가 `checked` 이기 때문입니다.

| State | 표현 | 선택자 |
|---|---|---|
| `unchecked` | 1.5px 테두리, 빈 원 | `[data-state="unchecked"]` |
| `checked` | 링이 안쪽으로 채워지고 가운데 점이 남는다 | `[data-state="checked"]` · `:checked` |
| `hover` | 테두리가 `--atom-fg-neutral-subtle` 로 진해진다 (미선택일 때만) | `:hover` |
| `invalid` | 테두리가 오류 색 (미선택일 때만) | `[data-invalid]` |
| `disabled` | `opacity: 0.4`, 커서 `not-allowed` | `[data-disabled]` |

`checked` 는 별도의 점 요소를 그리는 대신 **두꺼운 inset 그림자로 링을 채웁니다.**
`--atom-bg-layer` 색의 `::after` 원이 가운데 남아 점처럼 보입니다.

### Size

`medium` 이 기본입니다. 선택지가 화면의 주된 결정일 때는 `large` 를 씁니다.

| Size | Control | 안쪽 점 | inset 두께 | 라벨 폰트 | gap |
|---|---|---|---|---|---|
| `small` | 18×18px | 6px | 6px | 14px | 8px |
| `medium` | 22×22px | 8px | 7px | 15px | 10px |
| `large` | 26×26px | 10px | 8px | 16px | 12px |

### Group

세로 배치가 기본입니다. 선택지가 2~3개이고 라벨이 아주 짧을 때만 `horizontal` 을 씁니다.

세로 간격 `--atom-x4`(16px), 가로 간격 `--atom-x5`(20px)입니다.

### Card 변형

선택지마다 설명이 붙어 길어지면, `atom-radio-card` 로 감싸 각 선택지의 경계를 명확히 하고
터치 영역을 넓힙니다.

카드는 `--atom-x4`(16px) 패딩에 `--atom-radius-r2`(8px) 모서리를 갖고, 선택되면
테두리가 `--atom-border-subtle` 1px 에서 `--atom-border-strong` 2px 으로 바뀝니다.

### 실제 input 과 함께

같은 `name` 을 가진 `<input type="radio">` 를 넣으면 브라우저가 배타 선택을 처리합니다.
아래 데모는 실제로 눌러볼 수 있습니다.

### Align

CSS 헤더의 `--align_top` 은 라벨이 여러 줄일 때 Control 을 첫 줄에 맞춥니다. 원본 Props 표에는 없고,
원본 Anatomy · Card 데모가 Description 과 함께 씁니다.

### 클래스 계약

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

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

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

---

## 3. 상태

| State | 표현 | 선택자 |
|---|---|---|
| `unchecked` | `--atom-bg-layer` 배경, `--atom-border-default` 1.5px inset 테두리 | `[data-state="unchecked"]` |
| `checked` | `--atom-bg-neutral-solid` inset 6/7/8px 로 링을 채우고 `::after` 점 표시 | `[data-state="checked"]` · `__input:checked + __control` |
| `hover` | 미선택일 때만 테두리 `--atom-fg-neutral-subtle` | `:hover:not([data-disabled])[data-state="unchecked"]` |
| `focus-visible` | Control 에 `--atom-primary-600` 2px outline, offset 2px | `__input:focus-visible + __control` |
| `invalid` | 미선택일 때만 테두리 `--atom-fg-critical` | `[data-invalid][data-state="unchecked"]` |
| `disabled` | `opacity: 0.4`, 커서 `not-allowed` | `[data-disabled]` |
| Card `checked` | 카드 테두리 `--atom-border-strong` 2px inset | `.atom-radio-card[data-state="checked"]` |
| Card `disabled` | `opacity: 0.4` | `.atom-radio-card[data-disabled]` |

---

## 4. Props

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `value` | `string` | | ● | 그룹 안에서 이 항목을 식별하는 값입니다. |
| `checked` | `boolean` | `false` | | 선택 상태입니다. 보통 그룹이 관리합니다. |
| `size` | `"small" \| "medium" \| "large"` | `"medium"` | | Control 크기와 폰트 크기를 결정합니다. |
| `invalid` | `boolean` | `false` | | 테두리를 오류 색으로 바꿉니다. |
| `disabled` | `boolean` | `false` | | 조작할 수 없게 만듭니다. |
| `description` | `ReactNode` | | | 라벨 아래에 놓이는 보충 설명입니다. |

### Parts (compound)

| Part | 요소 | 설명 |
|---|---|---|
| `Radio` | `<label class="atom-radio">` > `<input class="atom-radio__input">` + `<span class="atom-radio__control">` + 라벨 | 위 Props 를 받습니다. 나머지 속성과 `ref` 는 실제 `<input>` 에, `className` 은 바깥 `<label>` 에 붙습니다. 구현은 `alignTop` 을 더 받습니다. `RadioGroup` 안에서는 그룹이 `checked` · `name` 을 관리합니다. |
| `Radio.Label` | `<span>` | 라벨 텍스트. Description 파트와 함께 쓸 때만 필요합니다. |
| `Radio.Description` | `<span class="atom-radio__description">` | 보충 설명. `description` prop 과 같은 결과이며, 있으면 Label 과 함께 `atom-radio__text` 로 묶고 `--align_top` 을 켭니다. |
| `RadioGroup` | `<div class="atom-radio-group" role="radiogroup">` | 묶음. `layout`(`"vertical"` · `"horizontal"`), `value` · `defaultValue` · `onValueChange`(`string`), `name`(생략하면 자동), `disabled`, `invalid`, `required` 를 받습니다. `aria-label` / `aria-labelledby` 로 이름을 붙이며, Field 안에서는 Field.Label 이 이름이 되고 aria-describedby · aria-invalid · aria-required 를 함께 받습니다. |
| `RadioCard` | `<label class="atom-radio-card">` > `<span class="atom-radio atom-radio--align_top">` | Card 변형. `Radio` 와 같은 Props(+ `cardClassName`)를 받고, 카드에도 `data-state` · `data-disabled` 를 맞춥니다. |

---

## 5. Component tokens

| 대상 | 속성 | Token | Value |
|---|---|---|---|
| Control | radius | `{radius.full}` | 9999px |
| Control | background | `{color.bg.layer}` | |
| Control | border | `{color.border.default}` 1.5px inset | |
| Control (checked) | 채움 | `{color.bg.neutral-solid}` inset 6/7/8px | |
| 안쪽 점 | background | `{color.bg.layer}` | |
| Label | color | `{color.fg.neutral}` | 15px |
| 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 | |
| Card | padding · radius | `{space.x4}` · `{radius.r2}` | 16px · 8px |
| Card | border | `{color.border.subtle}` 1px inset | |
| Card (checked) | border | `{color.border.strong}` 2px inset | |
| Group | gap | `{space.x4}` / `{space.x5}` | 16px / 20px |
| transition | duration | `{duration.fast}` | 120ms |

```json
{
  "radio": {
    "control": {
      "radius": { "$type": "dimension", "$value": "{radius.full}" },
      "bg": { "$type": "color", "$value": "{color.bg.layer}" },
      "border": { "$type": "color", "$value": "{color.border.default}" },
      "checked-fill": { "$type": "color", "$value": "{color.bg.neutral-solid}" },
      "checked-inset": {
        "$type": "dimension",
        "small": { "$value": "6px" },
        "medium": { "$value": "7px" },
        "large": { "$value": "8px" }
      },
      "dot": { "$type": "color", "$value": "{color.bg.layer}" },
      "hover-border": { "$type": "color", "$value": "{color.fg.neutral-subtle}" },
      "invalid-border": { "$type": "color", "$value": "{color.fg.critical}" }
    },
    "label": { "$type": "color", "$value": "{color.fg.neutral}" },
    "description": { "$type": "color", "$value": "{color.fg.neutral-muted}" },
    "focus-ring": { "$type": "color", "$value": "{color.primary.600}" },
    "card": {
      "padding": { "$type": "dimension", "$value": "{space.x4}" },
      "radius": { "$type": "dimension", "$value": "{radius.r2}" },
      "border": { "$type": "color", "$value": "{color.border.subtle}" },
      "border-checked": { "$type": "color", "$value": "{color.border.strong}" }
    },
    "group": {
      "$type": "dimension",
      "gap-vertical": { "$value": "{space.x4}" },
      "gap-horizontal": { "$value": "{space.x5}" }
    },
    "transition": { "$type": "duration", "$value": "{duration.fast}" }
  }
}
```

---

## 6. 접근성

- **요소** — `<label>` 로 감싼 `<input type="radio">` 를 씁니다. 같은 `name` 을 공유하면
  브라우저가 배타 선택과 화살표 이동을 모두 처리합니다.
- **키보드** — 그룹 전체가 **하나의 탭 정거장**입니다. `Tab` 으로 그룹에 들어오면 선택된
  항목에 포커스가 가고, `↑` `↓` `←` `→` 로 이동하면서 **이동과 동시에 선택이 바뀝니다.**
  끝에 도달하면 처음으로 순환합니다.
- **Checkbox 와 다른 점** — 체크박스 그룹은 `Tab` 으로 항목 사이를 이동하고 순환하지
  않습니다. 라디오는 화살표로 이동하고 순환합니다.
- **그룹 라벨** — `role="radiogroup"` 에 `aria-label` 또는 `aria-labelledby` 로 "무엇을
  고르는 목록인지" 를 반드시 붙입니다. 스크린리더는 각 선택지 앞에 이 라벨을 읽어 줍니다.
  `<fieldset>` + `<legend>` 도 같은 역할을 합니다.
- **포커스 표시** — `.atom-radio__input:focus-visible + .atom-radio__control` 이
  `--atom-primary-600` 2px outline 을 그립니다.
- **Card 변형** — 카드 전체가 눌리게 만들되, 포커스 링은 여전히 Control 에 나타납니다.
  카드 자체에도 포커스 표시가 필요하면 `:focus-within` 규칙을 추가해야 합니다 (현재 없음).
- **터치 영역** — Control 은 18–26px 로 권장 최소 44×44px 에 못 미칩니다. `<label>` 로
  감싸 라벨까지 타깃에 포함시키는 것이 필수이고, 항목이 길면 Card 변형을 씁니다.
- **대비** — 기본 테두리 `--atom-border-default` 는 흰 배경 대비 **1.36:1** 로
  WCAG 1.4.11 의 3:1 에 미달합니다. Color 참조.
- **강제 색상 모드** — 테두리와 채움을 모두 `inset box-shadow` 로 그리므로 Windows
  고대비 모드에서 선택 상태가 보이지 않습니다.

---

## 7. 사용 가이드

### 기본값을 정해두기

가장 많이 선택되는 항목을 기본값으로 선택해 둡니다. 아무것도 선택하지 않은 상태는
'선택하지 않음' 으로 해석됩니다.

- ✅ **Do** 가장 흔한 선택지를 기본으로 켜둡니다.
- ❌ **Don't** 정답이 있는데도 비워 두지 않습니다.

> [!WARNING]
> '선택하지 않음' 자체가 유효한 답인 경우에만 비워 둡니다. 그때는 `해당 없음` 같은 선택지를
> 명시적으로 추가하는 편이 낫습니다.

### 선택지가 많아지면 Select 로

Radio 는 모든 선택지를 한 번에 보여줄 때 씁니다. 선택지가 **5개를 넘으면**
[Select](./select.md) 를 고려하세요.

- ✅ **Do** 2~5개는 Radio 로 모두 보여줍니다.
- ❌ **Don't** 긴 목록을 Radio 로 늘어놓지 않습니다.

### 가로 배치는 라벨이 짧을 때만

가로로 나열하면 라벨이 길어지거나 화면이 좁아질 때 어떤 컨트롤이 어떤 라벨에 속하는지
혼동됩니다. 세로가 기본이고, 가로는 세로 공간이 부족할 때의 예외입니다.

- ✅ **Do** 세로로 쌓고, 라벨이 2~3자일 때만 가로로 놓습니다.
- ❌ **Don't** 긴 라벨을 가로로 늘어놓지 않습니다.

### 다른 선택 컴포넌트와 구분하기

| 상황 | 쓸 컴포넌트 |
|---|---|
| 여러 개를 동시에 고를 수 있다 | [Checkbox](./checkbox.md) |
| 하나만 고르고, 선택지가 2~5개다 | **Radio** |
| 하나만 고르고, 선택지가 6개 이상이다 | [Select](./select.md) |
| 하나만 고르고, 화면을 즉시 전환한다 | Segmented Control (`segmented-control`) |

마지막 줄의 기준은 반영 시점입니다. **제출해야 반영되는 값이면 Radio, 지금 보고 있는 화면을
즉시 바꾸는 것이면 Segmented Control** 입니다. 필터·정렬·보기 전환은 후자입니다.

### 라벨은 선택지끼리 대구를 이루게

같은 그룹의 라벨은 같은 품사, 같은 길이로 씁니다. 하나만 문장이면 그 항목이 특별해 보입니다.

- ✅ **Do** "카드" · "계좌이체" · "휴대폰" 처럼 형태를 맞춥니다.
- ❌ **Don't** "카드" · "계좌로 직접 이체하기" 를 섞지 않습니다.

### 관련 컴포넌트

- [Checkbox](./checkbox.md) — 여러 개를 동시에 고를 때.
- [Select](./select.md) — 선택지가 많을 때.

---

## 8. 예시

```tsx
<RadioGroup aria-label="처리 방식" defaultValue="card">
  <Radio value="card" description="국내 모든 카드사">즉시 처리</Radio>
  <Radio value="transfer">예약 처리</Radio>
</RadioGroup>

<RadioGroup aria-label="거래 방식" value={value} onValueChange={setValue}>
  <RadioCard value="pickup" description="약속 장소에서 만나 거래해요">직접 가져가기</RadioCard>
  <RadioCard value="delivery">
    <Radio.Label>택배 거래</Radio.Label>
    <Radio.Description>상세한 설명을 하단에 작성</Radio.Description>
  </RadioCard>
</RadioGroup>
```

```html
<div class="atom-radio-group" role="radiogroup" aria-label="처리 방식">
  <label class="atom-radio">
    <input class="atom-radio__input" type="radio" name="pay" value="card" checked />
    <span class="atom-radio__control"></span>
    <span class="atom-radio__text">
      <span>즉시 처리</span>
      <span class="atom-radio__description">국내 모든 카드사</span>
    </span>
  </label>
  <label class="atom-radio">
    <input class="atom-radio__input" type="radio" name="pay" value="transfer" />
    <span class="atom-radio__control"></span>
    <span class="atom-radio__text"><span>예약 처리</span></span>
  </label>
</div>
```

---

## Radio Group

라디오를 묶는 블록입니다. `radio.css` 안에 함께 정의된 `atom-radio-group` 입니다 (`role: sibling`).

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

항상 `role="radiogroup"` 과 그룹 이름(`aria-label` / `aria-labelledby`)을 붙입니다.

## Radio Card

선택지를 테두리 있는 카드로 감싸는 블록입니다. `radio.css` 안에 함께 정의된 `atom-radio-card` 입니다 (`role: sibling`).
카드가 `<label>` 이 되고, 안쪽 `atom-radio` 는 `<span>` 으로 둡니다(`--align_top` 과 함께).

```html
<label class="atom-radio-card" data-state="checked">
  <span class="atom-radio atom-radio--align_top" data-state="checked">
    <span class="atom-radio__control"></span>
    <span class="atom-radio__text">
      <span>메인 텍스트</span>
      <span class="atom-radio__description">상세한 설명을 하단에 작성</span>
    </span>
  </span>
</label>
```

| 대상 | 속성 | 값 |
|---|---|---|
| 카드 | padding · radius | `--atom-x4` (16px) · `--atom-radius-r2` (8px) |
| 카드 | border | `--atom-border-subtle` 1px inset |
| 카드 `[data-state="checked"]` | border | `--atom-border-strong` 2px inset |
| 카드 `[data-disabled]` | opacity | `0.4` |
| 카드 안 `.atom-radio` | flex | `1` |