# Stability Policy

`@orioncactuscorp/ui`가 무엇을 공개 계약으로 보고, 무엇을 breaking change로 취급하는지 정의합니다. 릴리스는 [Semantic Versioning](https://semver.org/lang/ko/)과 [Changesets](https://github.com/changesets/changesets)로 관리하며, consumer 영향이 있는 변경은 CHANGELOG의 Migration Notes에 기록합니다.

## 버전 라인

| 라인     | 공개 API 변경                                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------- |
| 1.x      | 공개 API를 다듬는 단계라 minor에서도 바뀔 수 있습니다. 모든 변경은 Migration Notes에 필요한 조치와 함께 기록합니다. |
| 2.0 이후 | 아래 [Breaking change 기준](#breaking-change-기준)과 [Deprecation 절차](#deprecation-절차)를 따릅니다.              |

1.x에서도 patch는 계약을 바꾸지 않습니다. minor 업그레이드 전에는 해당 버전의 Migration Notes를 확인하세요.

### 안정성 등급 (2.0 이후)

- **stable**: 표시가 없는 공개 API입니다. Breaking change 기준을 따릅니다.
- **experimental**: 문서에 experimental로 표시한 API입니다. 형태를 확정하기 전이라 minor에서도 바뀔 수 있으며, 변경은 Migration Notes에 기록합니다. 형태가 확정되면 stable로 전환합니다.

## 공개 계약의 범위

**문서화된 표면이 계약입니다.** README와 `docs/`(이 패키지에 동봉)에서 문서화한 것만 안정성을 보장합니다.

| 표면           | 계약 기준                                                                                                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 컴포넌트 props | 패키지 타입 정의 (`types.ts` 기반 공개 타입)                                                                                                                                                             |
| exports map    | `package.json` `exports`의 subpath 중 README Exports에 문서화된 것                                                                                                                                       |
| selector 계약  | [Selector Contract](./selector-contract.md)의 `data-oc-component` / `data-oc-part` / visual·state selector 표                                                                                            |
| CSS 변수       | foundation `--oc-*` 토큰 이름([Token Reference](./tokens.md))과 [CSS Variables](./css-variables.md)에 override·읽기 전용으로 표시된 component contract 변수(`--oc-{component}-*`)                        |
| SCSS API       | [SCSS Helpers](./scss-helpers.md), [Semantic Motion](./motion.md), [Spring Motion](./spring.md), [Responsive Foundation Profile](./responsive-foundation-profile.md)에 문서화된 mixin/function/설정 변수 |

다음은 계약이 **아니며** 예고 없이 바뀔 수 있습니다.

- CSS Module 클래스 이름 (해시 포함)
- selector 계약 표에 없는 내부 DOM 구조·wrapper 요소
- 문서화되지 않은 SCSS export, 내부 함수(`_` prefix), 내부 CSS 변수(`--_-*` 변수와 [CSS Variables](./css-variables.md#internal-변수)의 internal 목록)
- `dist/` 내부 파일 구조 (문서화된 exports subpath 경유가 아닌 직접 경로 import)

## Breaking change 기준

major 버전에서만 진행하는 변경:

- 문서화된 prop, export, mixin/function의 제거 또는 의미 변경
- `data-oc-*` selector 계약의 제거·이름 변경, selector 표에 있는 slot 구조 변경
- 문서화된 `--oc-*` 토큰·component contract 변수의 제거·이름 변경
- [Legacy 호환 attribute](./selector-contract.md#legacy-호환-출력)의 제거
- 지원 브라우저·React·Node 최소 버전 상향

minor에서 진행하는 변경:

- 새 컴포넌트, 새 prop, 새 토큰, 새 selector 계약의 추가
- deprecation 선언 (동작 유지 + Migration Notes 안내)
- internal component contract 변수를 override 또는 읽기 전용으로 승격

patch에서 진행하는 변경:

- 계약을 바꾸지 않는 버그 수정, 시각 결함 수정, 문서 수정

시각 스타일의 세부 값(색·간격·모션 수치)은 디자인 시스템 정책에 따라 minor에서 조정될 수 있습니다. 특정 픽셀 값 자체는 계약이 아니며, 토큰·selector를 통한 override 경로가 계약입니다.

## Deprecation 절차

1. 대체 경로가 준비된 minor 릴리스에서 deprecated로 선언하고 CHANGELOG Migration Notes에 대체 방법을 기록합니다.
2. deprecated 표면은 최소 한 번의 minor 주기 동안 동작을 유지합니다.
3. 제거는 deprecated 표면을 모아 다음 major 릴리스에서 한꺼번에 진행하고, Migration Notes에 기록합니다. 새 API는 현재 라인의 minor에 먼저 추가하므로, major 전에 대체 방법으로 옮겨 둘 수 있습니다.

## 프리릴리즈 채널

현재 정식 버전이 `X.Y.Z`일 때의 표기입니다.

| npm dist-tag | 용도                            | 버전 형식                                  |
| ------------ | ------------------------------- | ------------------------------------------ |
| `latest`     | 정식 버전                       | `X.Y.Z`                                    |
| `next`       | 현재 라인의 다음 정식 후보      | `X.Y.(Z+1)-next.N` 또는 `X.(Y+1).0-next.N` |
| `beta`, `rc` | 다음 major 후보 (2.0 이후 운영) | `(X+1).0.0-beta.N`, `(X+1).0.0-rc.N`       |

- dist-tag는 새 후보로 옮겨지므로 정확한 버전으로 고정해 설치합니다. 예: `npm install @orioncactuscorp/ui@<후보 버전> --save-exact`
- 다음 major 후보는 `^X.Y.Z`처럼 현재 major를 고정한 범위에 포함되지 않습니다.

## 의존성 고지

- `@base-ui-components/react`: 현재 `1.0.0-rc` 계열(release candidate)에 의존합니다. Base UI가 안정판을 릴리스하면 minor 버전에서 전환할 예정입니다. RC 기간 동안 Base UI 쪽 데이터 attribute(`data-starting-style` 등)나 내부 동작 변경이 전이될 수 있으며, 확인된 영향은 Migration Notes에 기록합니다.
- `@orioncactuscorp/icons`: 컴포넌트 내부 indicator용 dependency입니다. 앱 코드에서 아이콘을 직접 import하는 경우에만 직접 의존성으로 추가하세요.

## 지원 환경

- React 19+, React DOM 19+
- Node 22+
- 브라우저: **`color-mix()`를 지원하는 evergreen 브라우저** — Chrome/Edge 111+, Safari 16.2+, Firefox 113+ (2023년 상반기 이후)
  - `color-mix()`보다 지원 범위가 좁은 CSS 기능은 fallback 또는 `@supports` 가드와 함께 사용합니다. 기준선 미만 브라우저에서 시각 품질 저하는 있을 수 있으나, layout·접근성·상호작용이 깨지는 결함은 버그로 취급합니다.
- CSS Modules와 CSS `@layer`를 처리하는 bundler