# Component API Naming Conventions

`@orioncactuscorp/ui`는 컴포넌트의 시각적 선택지를 `variant`,
`appearance`, `size`로 일관되게 표현합니다. 이 규칙은 처음 사용하는
컴포넌트에서도 prop의 역할을 예측할 수 있게 하는 공개 API 계약입니다.

## 역할은 계약, 시각 값은 기본값

prop 이름과 TypeScript에 선언된 선택지는 버전 관리되는 계약입니다. 반면 각
선택지가 사용하는 색, 간격, 크기 같은 구체적인 시각 값은 디자인 시스템의
기본값입니다. 지원되는 token, component contract 변수, selector 계약을 통해
consumer가 조정할 수 있으며, 디자인 시스템 정책에 따라 변경될 수 있습니다.

지원되는 선택지의 정확한 목록은 각 컴포넌트의 TypeScript 선언을 기준으로
확인하세요. 모든 컴포넌트가 아래 축을 전부 제공하지는 않습니다.

## `variant`: 하나의 시각·표현 축

컴포넌트에 열거형 시각 또는 표현 축이 하나라면 `variant`를 사용합니다.
`variant`가 나타내는 구체적인 역할은 컴포넌트에 따라 의미·색, 강조 강도,
형태, surface 표현, layout 표현, slot content 종류 등이 될 수 있습니다.

상태, 간격, 동작처럼 독립된 개념은 `variant`에 합치지 않고 별도 prop으로
표현합니다.

## `appearance` + `variant`: 독립된 두 축

형태 또는 surface와 의미 또는 색을 각각 선택해야 하는 컴포넌트는 두 축을
분리합니다.

- `appearance`: 형태 또는 surface 처리
- `variant`: 의미 또는 색 의도

`Button`이 대표적인 예입니다. `appearance`는 `solid | outlined`, `variant`는
`default | primary | secondary | assistive`를 제공합니다.

```tsx
<Button appearance='solid' variant='primary'>
  저장
</Button>

<Button appearance='outlined' variant='assistive'>
  도움말
</Button>
```

이 분리는 형태와 의미를 하나의 조합 이름으로 합치지 않고 각 역할을 독립적으로
읽고 선택할 수 있게 합니다.

## `size`: 표준 크기 순서의 부분집합

named size의 표준 순서는 다음과 같습니다.

```text
xsmall < small < medium < large
```

각 컴포넌트는 실제로 지원하는 크기만 부분집합으로 제공합니다. 예를 들어 어떤
컴포넌트가 `small | medium`만 제공하더라도 사용하지 않는 `xsmall`이나 `large`를
대칭성을 위해 추가하지 않습니다. TypeScript union의 선언 순서는 별도 계약이
아니며, 크기 비교에는 위 순서를 사용합니다.

### Named size 밖의 예외

named preset이 아니라 외부 문맥이나 직접 지정한 치수로 크기를 정해야 할 때만
다음과 같은 값을 허용합니다.

- `inherit`: owner의 typography·크기를 상속
- `custom`: component CSS가 치수를 결정
- 숫자 또는 자유 형식 값: primitive나 icon-sized control에 직접 치수를 전달

`TextButton`은 owner 안에서 자연스럽게 조합할 수 있도록 `size='inherit'`을
제공합니다. 색을 상속하는 `variant='inherit'`은 size가 아닌 variant 축의
선택지입니다.

```tsx
<TextButton variant='inherit' size='inherit'>
  자세히 보기
</TextButton>
```

새 named size가 필요할 때 `tiny`, `mini` 같은 별도 척도를 만들지 않습니다.
직접·custom·상속 크기가 필요한 경우에는 해당 예외의 목적을 컴포넌트 API에
문서화합니다.

`Badge`의 작은 preset도 `size='xsmall'`을 사용하므로 모든 named size가 이
표준 순서를 따릅니다.