# Stability Policy

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

## 공개 계약의 범위

**문서화된 표면이 계약입니다.** 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))과 문서화된 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 변수
- `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 안내)

patch에서 진행하는 변경:

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

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

## Deprecation 절차

1. 대체 경로가 준비된 minor 릴리스에서 deprecated로 선언하고 CHANGELOG Migration Notes에 대체 방법을 기록합니다.
2. deprecated 표면은 최소 한 번의 minor 주기 동안 동작을 유지합니다.
3. 제거는 다음 major 릴리스에서 Migration Notes와 함께 진행합니다.

## 의존성 고지

- `@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