@orioncactuscorp/ui 1.10.0 → 1.11.0

package/docs/stability.md

@@ -0,0 +1,62 @@
+# 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

package/docs/tokens.md

@@ -0,0 +1,559 @@
+# Token Reference
+
+<!-- Generated by packages/ui/scripts/generate-token-reference.mjs. Do not edit manually. -->
+
+`@orioncactuscorp/ui/foundations.css`가 선언하는 `--oc-*` foundation 토큰 전체 목록입니다. `bun run build:css` 시 자동 재생성됩니다.
+
+토큰 값은 theme(`data-theme`)과 viewport(responsive mode)에 따라 달라질 수 있으므로 이 문서는 이름과 용도를 기준으로 제공합니다. 실제 값은 브라우저 devtools의 computed value 또는 [VS Code 자동완성 index](./editor-setup.md)로 확인하세요.
+
+값 커스터마이즈 방법은 README의 Foundation 섹션과 [Responsive Foundation Profile](./responsive-foundation-profile.md)을 참조하세요.
+
+## Color — theme semantic
+
+`:root`, `[data-theme="light"]`, `[data-theme="dark"]`에서 theme별 값으로 선언됩니다. consumer override는 theme selector 스코프에서 수행합니다.
+
+- `--oc-color-theme-accent-background-blue`
+- `--oc-color-theme-accent-background-cyan`
+- `--oc-color-theme-accent-background-green`
+- `--oc-color-theme-accent-background-lightBlue`
+- `--oc-color-theme-accent-background-lime`
+- `--oc-color-theme-accent-background-orange`
+- `--oc-color-theme-accent-background-pink`
+- `--oc-color-theme-accent-background-purple`
+- `--oc-color-theme-accent-background-red`
+- `--oc-color-theme-accent-background-redOrange`
+- `--oc-color-theme-accent-background-violet`
+- `--oc-color-theme-accent-foreground-blue`
+- `--oc-color-theme-accent-foreground-cyan`
+- `--oc-color-theme-accent-foreground-green`
+- `--oc-color-theme-accent-foreground-lightBlue`
+- `--oc-color-theme-accent-foreground-lime`
+- `--oc-color-theme-accent-foreground-orange`
+- `--oc-color-theme-accent-foreground-pink`
+- `--oc-color-theme-accent-foreground-purple`
+- `--oc-color-theme-accent-foreground-red`
+- `--oc-color-theme-accent-foreground-redOrange`
+- `--oc-color-theme-accent-foreground-violet`
+- `--oc-color-theme-background-elevated-alternative`
+- `--oc-color-theme-background-elevated-normal`
+- `--oc-color-theme-background-normal-alternative`
+- `--oc-color-theme-background-normal-normal`
+- `--oc-color-theme-fill-alternative`
+- `--oc-color-theme-fill-normal`
+- `--oc-color-theme-fill-strong`
+- `--oc-color-theme-focus-ring`
+- `--oc-color-theme-interaction-disable`
+- `--oc-color-theme-interaction-inactive`
+- `--oc-color-theme-inverse-background`
+- `--oc-color-theme-inverse-label`
+- `--oc-color-theme-inverse-primary`
+- `--oc-color-theme-label-alternative`
+- `--oc-color-theme-label-assistive`
+- `--oc-color-theme-label-disable`
+- `--oc-color-theme-label-neutral`
+- `--oc-color-theme-label-normal`
+- `--oc-color-theme-label-strong`
+- `--oc-color-theme-line-normal-alternative`
+- `--oc-color-theme-line-normal-neutral`
+- `--oc-color-theme-line-normal-normal`
+- `--oc-color-theme-line-normal-strong`
+- `--oc-color-theme-line-solid-alternative`
+- `--oc-color-theme-line-solid-neutral`
+- `--oc-color-theme-line-solid-normal`
+- `--oc-color-theme-line-solid-strong`
+- `--oc-color-theme-material-dimmer`
+- `--oc-color-theme-primary-normal`
+- `--oc-color-theme-static-black`
+- `--oc-color-theme-static-transparent`
+- `--oc-color-theme-static-white`
+- `--oc-color-theme-status-cautionary`
+- `--oc-color-theme-status-negative`
+- `--oc-color-theme-status-positive`
+
+## Color — global primitive
+
+theme와 무관한 primitive 값입니다. 컴포넌트에서는 theme semantic 토큰을 우선 사용하세요.
+
+- `--oc-color-global-blue-0`
+- `--oc-color-global-blue-10`
+- `--oc-color-global-blue-100`
+- `--oc-color-global-blue-20`
+- `--oc-color-global-blue-30`
+- `--oc-color-global-blue-40`
+- `--oc-color-global-blue-45`
+- `--oc-color-global-blue-50`
+- `--oc-color-global-blue-55`
+- `--oc-color-global-blue-60`
+- `--oc-color-global-blue-65`
+- `--oc-color-global-blue-70`
+- `--oc-color-global-blue-80`
+- `--oc-color-global-blue-90`
+- `--oc-color-global-blue-95`
+- `--oc-color-global-blue-99`
+- `--oc-color-global-common-0`
+- `--oc-color-global-common-100`
+- `--oc-color-global-common-transparent`
+- `--oc-color-global-coolNeutral-0`
+- `--oc-color-global-coolNeutral-10`
+- `--oc-color-global-coolNeutral-100`
+- `--oc-color-global-coolNeutral-15`
+- `--oc-color-global-coolNeutral-17`
+- `--oc-color-global-coolNeutral-20`
+- `--oc-color-global-coolNeutral-22`
+- `--oc-color-global-coolNeutral-23`
+- `--oc-color-global-coolNeutral-25`
+- `--oc-color-global-coolNeutral-30`
+- `--oc-color-global-coolNeutral-40`
+- `--oc-color-global-coolNeutral-5`
+- `--oc-color-global-coolNeutral-50`
+- `--oc-color-global-coolNeutral-60`
+- `--oc-color-global-coolNeutral-7`
+- `--oc-color-global-coolNeutral-70`
+- `--oc-color-global-coolNeutral-80`
+- `--oc-color-global-coolNeutral-90`
+- `--oc-color-global-coolNeutral-95`
+- `--oc-color-global-coolNeutral-96`
+- `--oc-color-global-coolNeutral-97`
+- `--oc-color-global-coolNeutral-98`
+- `--oc-color-global-coolNeutral-99`
+- `--oc-color-global-cyan-0`
+- `--oc-color-global-cyan-10`
+- `--oc-color-global-cyan-100`
+- `--oc-color-global-cyan-20`
+- `--oc-color-global-cyan-30`
+- `--oc-color-global-cyan-40`
+- `--oc-color-global-cyan-50`
+- `--oc-color-global-cyan-60`
+- `--oc-color-global-cyan-70`
+- `--oc-color-global-cyan-80`
+- `--oc-color-global-cyan-90`
+- `--oc-color-global-cyan-95`
+- `--oc-color-global-cyan-99`
+- `--oc-color-global-green-0`
+- `--oc-color-global-green-10`
+- `--oc-color-global-green-100`
+- `--oc-color-global-green-20`
+- `--oc-color-global-green-30`
+- `--oc-color-global-green-40`
+- `--oc-color-global-green-50`
+- `--oc-color-global-green-60`
+- `--oc-color-global-green-70`
+- `--oc-color-global-green-80`
+- `--oc-color-global-green-90`
+- `--oc-color-global-green-95`
+- `--oc-color-global-green-99`
+- `--oc-color-global-lightBlue-0`
+- `--oc-color-global-lightBlue-10`
+- `--oc-color-global-lightBlue-100`
+- `--oc-color-global-lightBlue-20`
+- `--oc-color-global-lightBlue-30`
+- `--oc-color-global-lightBlue-40`
+- `--oc-color-global-lightBlue-50`
+- `--oc-color-global-lightBlue-60`
+- `--oc-color-global-lightBlue-70`
+- `--oc-color-global-lightBlue-80`
+- `--oc-color-global-lightBlue-90`
+- `--oc-color-global-lightBlue-95`
+- `--oc-color-global-lightBlue-99`
+- `--oc-color-global-lime-0`
+- `--oc-color-global-lime-10`
+- `--oc-color-global-lime-100`
+- `--oc-color-global-lime-20`
+- `--oc-color-global-lime-30`
+- `--oc-color-global-lime-37`
+- `--oc-color-global-lime-40`
+- `--oc-color-global-lime-50`
+- `--oc-color-global-lime-60`
+- `--oc-color-global-lime-70`
+- `--oc-color-global-lime-80`
+- `--oc-color-global-lime-90`
+- `--oc-color-global-lime-95`
+- `--oc-color-global-lime-99`
+- `--oc-color-global-neutral-0`
+- `--oc-color-global-neutral-10`
+- `--oc-color-global-neutral-100`
+- `--oc-color-global-neutral-15`
+- `--oc-color-global-neutral-20`
+- `--oc-color-global-neutral-22`
+- `--oc-color-global-neutral-30`
+- `--oc-color-global-neutral-40`
+- `--oc-color-global-neutral-5`
+- `--oc-color-global-neutral-50`
+- `--oc-color-global-neutral-60`
+- `--oc-color-global-neutral-70`
+- `--oc-color-global-neutral-80`
+- `--oc-color-global-neutral-90`
+- `--oc-color-global-neutral-95`
+- `--oc-color-global-neutral-99`
+- `--oc-color-global-opacity-0`
+- `--oc-color-global-opacity-100`
+- `--oc-color-global-opacity-12`
+- `--oc-color-global-opacity-16`
+- `--oc-color-global-opacity-22`
+- `--oc-color-global-opacity-28`
+- `--oc-color-global-opacity-35`
+- `--oc-color-global-opacity-43`
+- `--oc-color-global-opacity-5`
+- `--oc-color-global-opacity-52`
+- `--oc-color-global-opacity-61`
+- `--oc-color-global-opacity-74`
+- `--oc-color-global-opacity-8`
+- `--oc-color-global-opacity-88`
+- `--oc-color-global-opacity-97`
+- `--oc-color-global-orange-0`
+- `--oc-color-global-orange-10`
+- `--oc-color-global-orange-100`
+- `--oc-color-global-orange-20`
+- `--oc-color-global-orange-30`
+- `--oc-color-global-orange-39`
+- `--oc-color-global-orange-40`
+- `--oc-color-global-orange-50`
+- `--oc-color-global-orange-60`
+- `--oc-color-global-orange-70`
+- `--oc-color-global-orange-80`
+- `--oc-color-global-orange-90`
+- `--oc-color-global-orange-95`
+- `--oc-color-global-orange-99`
+- `--oc-color-global-pink-0`
+- `--oc-color-global-pink-10`
+- `--oc-color-global-pink-100`
+- `--oc-color-global-pink-20`
+- `--oc-color-global-pink-30`
+- `--oc-color-global-pink-40`
+- `--oc-color-global-pink-46`
+- `--oc-color-global-pink-50`
+- `--oc-color-global-pink-60`
+- `--oc-color-global-pink-70`
+- `--oc-color-global-pink-80`
+- `--oc-color-global-pink-90`
+- `--oc-color-global-pink-95`
+- `--oc-color-global-pink-99`
+- `--oc-color-global-purple-0`
+- `--oc-color-global-purple-10`
+- `--oc-color-global-purple-100`
+- `--oc-color-global-purple-20`
+- `--oc-color-global-purple-30`
+- `--oc-color-global-purple-40`
+- `--oc-color-global-purple-50`
+- `--oc-color-global-purple-60`
+- `--oc-color-global-purple-70`
+- `--oc-color-global-purple-80`
+- `--oc-color-global-purple-90`
+- `--oc-color-global-purple-95`
+- `--oc-color-global-purple-99`
+- `--oc-color-global-red-0`
+- `--oc-color-global-red-10`
+- `--oc-color-global-red-100`
+- `--oc-color-global-red-20`
+- `--oc-color-global-red-30`
+- `--oc-color-global-red-40`
+- `--oc-color-global-red-50`
+- `--oc-color-global-red-60`
+- `--oc-color-global-red-70`
+- `--oc-color-global-red-80`
+- `--oc-color-global-red-90`
+- `--oc-color-global-red-95`
+- `--oc-color-global-red-99`
+- `--oc-color-global-redOrange-0`
+- `--oc-color-global-redOrange-10`
+- `--oc-color-global-redOrange-100`
+- `--oc-color-global-redOrange-20`
+- `--oc-color-global-redOrange-30`
+- `--oc-color-global-redOrange-40`
+- `--oc-color-global-redOrange-48`
+- `--oc-color-global-redOrange-50`
+- `--oc-color-global-redOrange-60`
+- `--oc-color-global-redOrange-70`
+- `--oc-color-global-redOrange-80`
+- `--oc-color-global-redOrange-90`
+- `--oc-color-global-redOrange-95`
+- `--oc-color-global-redOrange-99`
+- `--oc-color-global-violet-0`
+- `--oc-color-global-violet-10`
+- `--oc-color-global-violet-100`
+- `--oc-color-global-violet-20`
+- `--oc-color-global-violet-30`
+- `--oc-color-global-violet-40`
+- `--oc-color-global-violet-45`
+- `--oc-color-global-violet-50`
+- `--oc-color-global-violet-60`
+- `--oc-color-global-violet-70`
+- `--oc-color-global-violet-80`
+- `--oc-color-global-violet-90`
+- `--oc-color-global-violet-95`
+- `--oc-color-global-violet-99`
+
+## Typography
+
+size/height/spacing/weight는 `@include typo($variant, $weight)` 경유가 기본입니다. raw size 토큰 직접 참조는 피하세요.
+
+- `--oc-typo-font-family`
+- `--oc-typo-height-body1`
+- `--oc-typo-height-body1reading`
+- `--oc-typo-height-body2`
+- `--oc-typo-height-body2reading`
+- `--oc-typo-height-caption1`
+- `--oc-typo-height-caption2`
+- `--oc-typo-height-display1`
+- `--oc-typo-height-display2`
+- `--oc-typo-height-display3`
+- `--oc-typo-height-heading1`
+- `--oc-typo-height-heading2`
+- `--oc-typo-height-headline1`
+- `--oc-typo-height-headline2`
+- `--oc-typo-height-label1`
+- `--oc-typo-height-label1reading`
+- `--oc-typo-height-label2`
+- `--oc-typo-height-title1`
+- `--oc-typo-height-title2`
+- `--oc-typo-height-title3`
+- `--oc-typo-size-body1`
+- `--oc-typo-size-body1reading`
+- `--oc-typo-size-body2`
+- `--oc-typo-size-body2reading`
+- `--oc-typo-size-caption1`
+- `--oc-typo-size-caption2`
+- `--oc-typo-size-display1`
+- `--oc-typo-size-display2`
+- `--oc-typo-size-display3`
+- `--oc-typo-size-factor`
+- `--oc-typo-size-heading1`
+- `--oc-typo-size-heading2`
+- `--oc-typo-size-headline1`
+- `--oc-typo-size-headline2`
+- `--oc-typo-size-label1`
+- `--oc-typo-size-label1reading`
+- `--oc-typo-size-label2`
+- `--oc-typo-size-title1`
+- `--oc-typo-size-title2`
+- `--oc-typo-size-title3`
+- `--oc-typo-spacing-body1`
+- `--oc-typo-spacing-body1reading`
+- `--oc-typo-spacing-body2`
+- `--oc-typo-spacing-body2reading`
+- `--oc-typo-spacing-caption1`
+- `--oc-typo-spacing-caption2`
+- `--oc-typo-spacing-display1`
+- `--oc-typo-spacing-display2`
+- `--oc-typo-spacing-display3`
+- `--oc-typo-spacing-heading1`
+- `--oc-typo-spacing-heading2`
+- `--oc-typo-spacing-headline1`
+- `--oc-typo-spacing-headline2`
+- `--oc-typo-spacing-label1`
+- `--oc-typo-spacing-label1reading`
+- `--oc-typo-spacing-label2`
+- `--oc-typo-spacing-title1`
+- `--oc-typo-spacing-title2`
+- `--oc-typo-spacing-title3`
+- `--oc-typo-weight-body1-bold`
+- `--oc-typo-weight-body1-medium`
+- `--oc-typo-weight-body1-normal`
+- `--oc-typo-weight-body1reading-bold`
+- `--oc-typo-weight-body1reading-medium`
+- `--oc-typo-weight-body1reading-normal`
+- `--oc-typo-weight-body2-bold`
+- `--oc-typo-weight-body2-medium`
+- `--oc-typo-weight-body2-normal`
+- `--oc-typo-weight-body2reading-bold`
+- `--oc-typo-weight-body2reading-medium`
+- `--oc-typo-weight-body2reading-normal`
+- `--oc-typo-weight-caption1-bold`
+- `--oc-typo-weight-caption1-medium`
+- `--oc-typo-weight-caption1-normal`
+- `--oc-typo-weight-caption2-bold`
+- `--oc-typo-weight-caption2-medium`
+- `--oc-typo-weight-caption2-normal`
+- `--oc-typo-weight-display1-bold`
+- `--oc-typo-weight-display1-medium`
+- `--oc-typo-weight-display1-normal`
+- `--oc-typo-weight-display2-bold`
+- `--oc-typo-weight-display2-medium`
+- `--oc-typo-weight-display2-normal`
+- `--oc-typo-weight-display3-bold`
+- `--oc-typo-weight-display3-medium`
+- `--oc-typo-weight-display3-normal`
+- `--oc-typo-weight-heading1-bold`
+- `--oc-typo-weight-heading1-medium`
+- `--oc-typo-weight-heading1-normal`
+- `--oc-typo-weight-heading2-bold`
+- `--oc-typo-weight-heading2-medium`
+- `--oc-typo-weight-heading2-normal`
+- `--oc-typo-weight-headline1-bold`
+- `--oc-typo-weight-headline1-medium`
+- `--oc-typo-weight-headline1-normal`
+- `--oc-typo-weight-headline2-bold`
+- `--oc-typo-weight-headline2-medium`
+- `--oc-typo-weight-headline2-normal`
+- `--oc-typo-weight-label1-bold`
+- `--oc-typo-weight-label1-medium`
+- `--oc-typo-weight-label1-normal`
+- `--oc-typo-weight-label1reading-bold`
+- `--oc-typo-weight-label1reading-medium`
+- `--oc-typo-weight-label1reading-normal`
+- `--oc-typo-weight-label2-bold`
+- `--oc-typo-weight-label2-medium`
+- `--oc-typo-weight-label2-normal`
+- `--oc-typo-weight-title1-bold`
+- `--oc-typo-weight-title1-medium`
+- `--oc-typo-weight-title1-normal`
+- `--oc-typo-weight-title2-bold`
+- `--oc-typo-weight-title2-medium`
+- `--oc-typo-weight-title2-normal`
+- `--oc-typo-weight-title3-bold`
+- `--oc-typo-weight-title3-medium`
+- `--oc-typo-weight-title3-normal`
+
+## Space
+
+responsive mode(fluid/stepped/static)에 따라 viewport별 출력이 달라집니다.
+
+- `--oc-space-item-gap-atom`
+- `--oc-space-item-gap-huge`
+- `--oc-space-item-gap-large`
+- `--oc-space-item-gap-medium`
+- `--oc-space-item-gap-micro`
+- `--oc-space-item-gap-mini`
+- `--oc-space-item-gap-nano`
+- `--oc-space-item-gap-small`
+- `--oc-space-item-gap-tiny`
+- `--oc-space-item-gap-xlarge`
+- `--oc-space-item-gap-xsmall`
+- `--oc-space-item-padding-atom`
+- `--oc-space-item-padding-large`
+- `--oc-space-item-padding-medium`
+- `--oc-space-item-padding-micro`
+- `--oc-space-item-padding-mini`
+- `--oc-space-item-padding-nano`
+- `--oc-space-item-padding-small`
+- `--oc-space-item-padding-tiny`
+- `--oc-space-item-padding-xsmall`
+- `--oc-space-section-gap-large`
+- `--oc-space-section-gap-medium`
+- `--oc-space-section-gap-section`
+- `--oc-space-section-gap-xlarge`
+- `--oc-space-section-padding-viewport`
+- `--oc-space-section-padding-viewport-block-safe-end`
+- `--oc-space-section-padding-viewport-block-safe-start`
+- `--oc-space-section-padding-viewport-inline-safe-end`
+- `--oc-space-section-padding-viewport-inline-safe-start`
+- `--oc-space-section-padding-viewport-x`
+- `--oc-space-section-padding-viewport-y`
+
+## Atomic (radius/width/blur/shadow 등)
+
+`--oc-atomic-radius-factor`는 radius 전역 배율 runtime multiplier입니다.
+
+- `--oc-atomic-blur-compact`
+- `--oc-atomic-blur-normal`
+- `--oc-atomic-radius-factor`
+- `--oc-atomic-radius-huge`
+- `--oc-atomic-radius-large`
+- `--oc-atomic-radius-max`
+- `--oc-atomic-radius-medium`
+- `--oc-atomic-radius-micro`
+- `--oc-atomic-radius-mini`
+- `--oc-atomic-radius-small`
+- `--oc-atomic-radius-tiny`
+- `--oc-atomic-radius-xlarge`
+- `--oc-atomic-radius-xsmall`
+- `--oc-atomic-shadow-normal-large`
+- `--oc-atomic-shadow-normal-medium`
+- `--oc-atomic-shadow-normal-small`
+- `--oc-atomic-shadow-normal-xlarge`
+- `--oc-atomic-shadow-normal-xsmall`
+- `--oc-atomic-shadow-spread-small`
+- `--oc-atomic-shadow-spread-xlarge`
+- `--oc-atomic-width-content`
+- `--oc-atomic-width-section-large`
+- `--oc-atomic-width-section-medium`
+- `--oc-atomic-width-section-small`
+- `--oc-atomic-width-section-xsmall`
+
+## Focus ring
+
+키보드 포커스 링(`:focus-visible`)의 두께/offset입니다. 색상은 theme semantic 토큰 `--oc-color-theme-focus-ring`을 사용하며, 컴포넌트 적용은 `@include oc-focus-ring` 경유가 기본입니다.
+
+- `--oc-focus-ring-offset`
+- `--oc-focus-ring-width`
+
+## Motion
+
+duration/scale/distance factor는 unitless multiplier입니다. 자세한 정책은 [Semantic Motion](./motion.md)을 참조하세요.
+
+- `--oc-motion-distance-factor`
+- `--oc-motion-distance-factor-reject`
+- `--oc-motion-distance-factor-spatial`
+- `--oc-motion-duration-ambient`
+- `--oc-motion-duration-continuous`
+- `--oc-motion-duration-disclosure`
+- `--oc-motion-duration-disclosure-exit`
+- `--oc-motion-duration-expand`
+- `--oc-motion-duration-expand-exit`
+- `--oc-motion-duration-factor`
+- `--oc-motion-duration-factor-preserve`
+- `--oc-motion-duration-factor-reduced`
+- `--oc-motion-duration-fade`
+- `--oc-motion-duration-feedback`
+- `--oc-motion-duration-gesture`
+- `--oc-motion-duration-gesture-release`
+- `--oc-motion-duration-move`
+- `--oc-motion-duration-reject`
+- `--oc-motion-duration-sheet`
+- `--oc-motion-duration-sheet-exit`
+- `--oc-motion-duration-sheet-release`
+- `--oc-motion-duration-surface`
+- `--oc-motion-duration-surface-exit`
+- `--oc-motion-pace-normal`
+- `--oc-motion-pace-quick`
+- `--oc-motion-pace-slow`
+- `--oc-motion-scale-factor`
+- `--oc-motion-scale-factor-feedback`
+- `--oc-motion-scale-factor-spatial`
+- `--oc-motion-timing-ambient`
+- `--oc-motion-timing-continuous`
+- `--oc-motion-timing-disclosure`
+- `--oc-motion-timing-disclosure-exit`
+- `--oc-motion-timing-expand`
+- `--oc-motion-timing-expand-exit`
+- `--oc-motion-timing-fade`
+- `--oc-motion-timing-feedback`
+- `--oc-motion-timing-gesture`
+- `--oc-motion-timing-gesture-release`
+- `--oc-motion-timing-move`
+- `--oc-motion-timing-reject`
+- `--oc-motion-timing-sheet`
+- `--oc-motion-timing-sheet-exit`
+- `--oc-motion-timing-sheet-release`
+- `--oc-motion-timing-surface`
+- `--oc-motion-timing-surface-exit`
+
+## Spring
+
+spring preset의 timing/duration scale입니다. 자세한 사용법은 [Spring Motion](./spring.md)을 참조하세요.
+
+- `--oc-spring-bouncy-duration-scale`
+- `--oc-spring-bouncy-timing`
+- `--oc-spring-smooth-duration-scale`
+- `--oc-spring-smooth-timing`
+- `--oc-spring-snappy-duration-scale`
+- `--oc-spring-snappy-timing`
+
+## Z-index
+
+- `--oc-zindex-0`
+- `--oc-zindex-1`
+- `--oc-zindex-2`
+- `--oc-zindex-3`
+- `--oc-zindex-4`
+- `--oc-zindex-5`
+
+## Breakpoint
+
+SCSS에서는 `respond-to(...)` mixin 경유가 기본입니다. raw media query에 직접 사용하지 마세요.
+
+- `--oc-breakpoint-hg`
+- `--oc-breakpoint-lg`
+- `--oc-breakpoint-md`
+- `--oc-breakpoint-sm`
+- `--oc-breakpoint-xl`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orioncactuscorp/ui",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "orioncactus UI foundations and core primitives",
   "private": false,
   "type": "module",
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "src/scss",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -78,14 +79,18 @@
   },
   "packageManager": "bun@1.3.6",
   "scripts": {
-    "build": "bun run build:lib && bun run build:css && bun run check:exports && bun run check:dist-imports && bun run check:rsc-boundaries",
+    "build": "bun run build:lib && bun run build:css && bun run check:exports && bun run check:dist-imports && bun run check:css-injection && bun run check:rsc-boundaries",
     "build:lib": "vite build && node scripts/preserve-client-directives.mjs",
-    "build:css": "sass src/scss/foundations:dist/foundations --no-source-map --style=compressed && node scripts/fix-css-module-artifacts.mjs && node scripts/bundle-foundations.mjs && node scripts/generate-vscode-css-vars.mjs",
+    "build:css": "sass src/scss/foundations:dist/foundations --no-source-map --style=compressed && node scripts/fix-css-module-artifacts.mjs && node scripts/bundle-foundations.mjs && node scripts/generate-vscode-css-vars.mjs && node scripts/generate-token-reference.mjs",
+    "docs:tokens": "node scripts/generate-token-reference.mjs",
+    "docs:tokens:check": "node scripts/generate-token-reference.mjs --check",
     "check:exports": "node scripts/check-package-exports.mjs",
     "check:dist-imports": "node scripts/check-dist-imports.mjs",
+    "check:css-injection": "node scripts/check-css-injection.mjs",
     "check:rsc-boundaries": "node scripts/check-rsc-client-boundaries.mjs",
     "test": "vitest",
-    "test:run": "vitest run",
+    "test:run": "vitest run && node --test scripts/*.test.mjs",
+    "test:scripts": "node --test scripts/*.test.mjs",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "bun run --cwd ../.. build && bun run --cwd ../.. example:build && playwright test",
     "test:e2e:ci": "bun run --cwd ../.. example:build && playwright test",

package/src/scss/foundations/color-theme.test.ts

@@ -37,6 +37,20 @@ describe('color theme foundations', () => {
     expect(css).toContain('[data-theme=dark]');
   });
 
+  it('aliases the focus ring color to the primary semantic in both themes', () => {
+    const css = compileScss(`
+      @use 'foundations/color.theme.light' as light;
+      @use 'foundations/color.theme.dark' as dark;
+    `);
+
+    expect(css).toMatch(
+      /:root\{[^}]*--oc-color-theme-focus-ring:var\(--oc-color-theme-primary-normal\)/,
+    );
+    expect(css).toMatch(
+      /\[data-theme=dark\]\{[^}]*--oc-color-theme-focus-ring:var\(--oc-color-theme-primary-normal\)/,
+    );
+  });
+
   it('emits only light when $oc-color-themes is (light)', () => {
     const css = compileScss(`
       @use 'foundations/color.config' with ($oc-color-themes: (light,));

package/src/scss/foundations/color.theme.dark.scss

@@ -7,6 +7,7 @@
   --oc-color-theme-static-black: var(--oc-color-global-common-0);
   --oc-color-theme-static-transparent: var(--oc-color-global-common-transparent);
   --oc-color-theme-primary-normal: var(--oc-color-global-redOrange-60);
+  --oc-color-theme-focus-ring: var(--oc-color-theme-primary-normal);
   --oc-color-theme-label-strong: var(--oc-color-global-common-100);
   --oc-color-theme-label-normal: var(--oc-color-global-coolNeutral-99);
   --oc-color-theme-label-neutral: #{oc-alpha(coolNeutral-90, 88)};