# Components

`foundation/` 토큰을 조합해 만든 ATOM UI 컴포넌트 정의입니다. 내용은 `03_ASSET_GUIDE` 원본을 그대로 옮긴 것입니다.
원본은 다음 세 곳입니다.

- `catalog/<slug>.js`: 문서, Props, 데모
- `styles/elements/<slug>.css`: 실제 CSS와 헤더 계약
- `registry.json` `assets.<slug>`: 기계가 읽는 형식

> **문서에 없는 것은 정해지지 않은 것입니다.** 원본에 없는 상태나 variant 를 만들지 않습니다.

각 문서는 아래 순서로 구성됩니다.

1. 구성 (Anatomy): 부품과 각 부품의 클래스 (`atom-<slug>__<part>`)
2. 종류 / 크기 (Properties): 원본 Properties 의 축마다 표 하나. px 값은 원본 그대로입니다.
   **클래스 계약** 소절은 Props 값과 CSS modifier 의 대응표입니다.
3. 상태 (State)
4. Props: 원본 Specification 의 Props 표와, 구현이 쓰는 compound **Parts** 표
5. Component tokens: 원본 Design Tokens 표. foundation 토큰을 `{...}` 로 참조하며, DTCG JSON 을 함께 둡니다.
6. 접근성
7. 사용 가이드: 원본 Guidelines 의 ✅ Do / ❌ Don't / ⚠️ Caution
8. 예시: tsx, 그리고 원본 Markup html

각 문서 첫 문단은 원본 `meta.description` 입니다. registry 와 docs 사이트가 이 문단을 설명으로 다시 씁니다.

## 목록

분류(kind)와 category 는 원본 `catalog/_index.js` 기준입니다.

### Elements (9) — 단일 컨트롤 · 표시

| 컴포넌트 | category | specSource | 비고 |
|---|---|---|---|
| [Badge](badge.md) | feedback | measured | |
| [Button](button.md) | action-input | measured | sub-asset: Icon Button |
| [Checkbox](checkbox.md) | action-input | measured | |
| [Chip](chip.md) | display | measured | |
| [Input Button](input-button.md) | action-input | **없음** | 원본 `hidden`. Specification 미완성 |
| [Radio](radio.md) | action-input | measured | |
| [Select](select.md) | selection | measured | |
| [Switch](switch.md) | action-input | measured | |
| [Text Input](text-input.md) | action-input | measured | sub-asset: Textarea |

### Components (19) — 여러 요소의 조합

| 컴포넌트 | category | specSource | 비고 |
|---|---|---|---|
| [Accordion](accordion.md) | display | measured | |
| [Autocomplete](autocomplete.md) | selection | measured | |
| [Chart](chart.md) | display | measured | |
| [Date Input](date-input.md) | action-input | measured | |
| [Dialog](dialog.md) | overlay | measured | |
| [Field](field.md) | display | measured | sub-asset: Label |
| [Grid](grid.md) | display | measured | |
| [Multi Select](multi-select.md) | selection | measured | |
| [Pagination](pagination.md) | navigation | measured | |
| [Section Title](section-title.md) | display | measured | |
| [Shape Map](shape-map.md) | display | measured | |
| [Splitter](splitter.md) | display | measured | |
| [Statistic](statistic.md) | display | measured | |
| [Tabs](tabs.md) | navigation | measured | |
| [Time Chip](time-chip.md) | selection | measured | |
| [Time Input](time-input.md) | action-input | measured | |
| [Toast](toast.md) | overlay | measured | |
| [Tooltip](tooltip.md) | overlay | measured | |
| [Tree](tree.md) | display | measured | |

`specSource` 등급:

| 등급 | 뜻 |
|---|---|
| `measured` | 코드에서 실측한 값 |
| `derived` | 토큰과 프리뷰 마크업에서 계산한 값 |
| `proposed` | 참조 기반 제안이며 아직 구현되지 않은 값 |

**이 등급을 확인하지 않고 수치를 확정 스펙으로 쓰면 안 됩니다.**

---

## 공통 규칙

모든 컴포넌트에 같은 규칙이 적용됩니다. 각 문서에는 이 규칙과 다른 점만 적습니다.

### 클래스 이름 규칙

```
atom-{block}__{element}--{axis}_{value}
```

| 자리 | 형식 | 예 |
|---|---|---|
| block | `atom-<slug>` | `atom-button` |
| element | `atom-<slug>__<part>` | `atom-button__label` |
| modifier | `atom-<slug>--<axis>_<kebab-value>` | `atom-button--variant_brand-solid` |

- **기본값에는 클래스가 없습니다.** 예를 들어 Button `size="medium"` 은 modifier 없이 `atom-button` 만 씁니다.
  기본값은 빠진 값이 아니라 실제 값입니다.
- **Props 값은 camelCase, modifier 값은 kebab-case** 입니다(`brandSolid` → `brand-solid`). 둘은 관련이 있지만 1:1 대응은 아닙니다.
  - 기본값에는 클래스가 없습니다.
  - 여러 props 는 속성으로 표현됩니다.
  - 일부 props 는 화면에 드러나지 않습니다.

  그래서 각 문서의 **클래스 계약** 표만 기준으로 삼습니다.
- **상태는 클래스가 아니라 속성으로 표현합니다.**
  - 데이터 속성: `[data-state="open"]` · `[data-pressed]` · `[data-loading]`
  - 네이티브 속성: `:checked` · `[disabled]`
  - aria 속성: `[aria-selected]` · `[aria-invalid]`

  예외는 Text Input 과 Date Input 입니다. 이 둘은 `--focused` · `--invalid` · `--disabled` · `--readonly` 클래스를 씁니다.

### 프리뷰 수치를 실제 치수로 쓰지 않습니다

원본 카드 프리뷰는 400×225 고정 캔버스에 맞춰 그린 뒤 축소한 것입니다. 실제 치수는 다음 두 곳에 있습니다.

- 각 문서의 **2. 종류 / 크기** 표
- `styles/elements/<slug>.css`

### 데모 전용 클래스는 배포하지 않습니다

다음 클래스는 문서 사이트를 위한 것이라 화면에 쓰지 않습니다.

- `atom-demo-row` · `atom-demo-cell` · `atom-demo-label`
- 원본 registry `conventions.nonAssetClasses` 에 있는 클래스 169개(`atom-icon-button` 포함)

### 컨트롤 표면 (Control surface)

Field 의 Control 슬롯에 들어가는 상자들은 높이와 테두리를 공유합니다. 해당 컴포넌트는 Text Input · Textarea · Select · Multi Select · Date Input · Time Input · Input Button 입니다.

| 항목 | 토큰 | 값 |
|---|---|---|
| 높이 (`medium` / `small` / `large`) | `--atom-control-h` / `-small` / `-large` | 48 / 40 / 56px |
| 테두리 | `--atom-control-border` | `inset 0 0 0 1px var(--atom-border-default)` |
| hover | `--atom-control-border-hover` | `inset 0 0 0 1px var(--atom-fg-neutral-subtle)` |
| focus | `--atom-control-border-focus` | `inset 0 0 0 2px var(--atom-primary-600)` |
| invalid | `--atom-control-border-invalid` | `inset 0 0 0 2px var(--atom-fg-critical)` |

Button 은 자체 높이를 갖습니다. 조합에 들어갈 때 `field.css` 가 행 높이에 맞춰 늘립니다.
자세한 내용은 [Spacing](../foundation/spacing.md#레이아웃-고정값) 과 [Color](../foundation/color.md#컨트롤-테두리-control-surface) 에 있습니다.

### 접근성 기본

- **포커스 링** — `base.css` 의 `:focus-visible` 이 `--atom-primary-600` 2px outline 을 2px 띄워 그립니다.
- **움직임 줄이기** — `prefers-reduced-motion` 은 `base.css` 에서 전역으로 처리합니다([Motion](../foundation/motion.md)).
- **색만으로 의미를 전하지 않습니다** — 아이콘과 문구를 함께 씁니다([Color](../foundation/color.md)).
- **스크린리더 전용 텍스트** — `.atom-sr-only` 를 씁니다.
- **한국어 문장** — `.atom-break-keep` 을 붙여 단어 중간에서 줄바꿈하지 않게 합니다.

### 스타일시트 의존

원본 `requiresStylesheets` 기준입니다. 이 컴포넌트를 쓸 때는 아래 엘리먼트 CSS 도 함께 불러와야 합니다(`implement` 의 `styles.css` 는 전부 불러옵니다).

| 컴포넌트 | 함께 필요한 CSS |
|---|---|
| autocomplete · date-input · multi-select · select · time-input · input-button | field |
| chart · shape-map | chip |
| dialog · tooltip | button |
| field | button · text-input |
| grid | button · multi-select · pagination · select · text-input |
| pagination | grid · select |
| section-title | button · grid |
| statistic | chart |
| switch | button · checkbox |
| text-input | button · checkbox · field · select |
| time-chip | button · chip |