@orioncactuscorp/ui 1.9.2 → 1.11.0

package/docs/responsive-foundation-profile.md

@@ -0,0 +1,230 @@
+# Responsive Foundation Profile
+
+`responsive.config`는 typography와 spacing foundation의 responsive 출력 방식을 정하는 SCSS compile-time profile이다. `typo`와 `space`는 같은 mode를 공유하며, 소비자는 token 값을 다시 작성하지 않고 공통 stop 또는 foundation별 stop range를 선택한다.
+
+이 profile은 `@orioncactuscorp/ui/foundations.css` 또는 `@orioncactuscorp/ui/styles.css` 같은 prebuilt CSS에는 적용되지 않는다. profile을 바꾸려면 SCSS source foundation을 직접 import해서 consumer build에서 컴파일해야 한다.
+
+## Config
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/responsive.config' with (
+  $oc-responsive-mode: fluid,
+  $oc-responsive-stops: (
+    min,
+    sm,
+    md,
+    lg,
+    xl,
+    hg,
+  ),
+  $oc-responsive-typo-stops: null,
+  $oc-responsive-space-stops: null,
+  $oc-responsive-space-profile: null,
+  $oc-responsive-static-stop: null
+);
+```
+
+### `$oc-responsive-mode`
+
+- `fluid`: 기본값. 기존 출력과 동일하게 stop 사이를 `fluidClamp()`로 보간한다.
+- `stepped`: `clamp()` 없이 stop 값이 breakpoint에서 계단식으로 바뀐다.
+- `static`: 선택한 stop 하나를 전체 viewport에 고정한다.
+
+### `$oc-responsive-stops`
+
+활성화할 기본 design stop 목록이다.
+
+- `fluid`: active range로 사용한다. range 밖은 가까운 active stop 값으로 고정된다.
+- `stepped`: 첫 stop은 base 값으로 출력하고, 이후 stop은 `respond-to(min, stop)` 기준 media에서 출력한다.
+- `static`: foundation별 stops가 없을 때 fallback active range로 사용한다.
+
+`sm`, `md`는 design stop 이름이다. 단일 `respond-to(sm/md)` mixin은 max-width 편의 API지만, `stepped` profile의 stop 전환은 `respond-to(min, stop)` 기준이다. 예를 들어 `md` 값은 `min-width: 769px`부터 적용된다.
+
+### `$oc-responsive-typo-stops`
+
+`typo` size/height token에만 적용할 design stop 목록이다. `null`이면 `$oc-responsive-stops`를 사용한다.
+
+### `$oc-responsive-space-stops`
+
+`space` token에만 적용할 design stop 목록이다. `null`이면 `$oc-responsive-stops`를 사용한다.
+
+### `$oc-responsive-space-profile`
+
+`space` token의 stepped 출력 방식을 바꾸는 profile이다. `null`이면 `$oc-responsive-mode: stepped`에서 active stops를 순서대로 출력한다.
+
+현재 지원하는 profile type:
+
+- `stepped-points`: named point별 target stop을 출력한다. `points.base`는 base `:root` 값이고, `min-md` 같은 point는 `respond-to(min, md)` 기준 media로 출력한다.
+
+`max-active-defined` target은 `$oc-responsive-space-stops` 안에서 해당 token에 실제 값이 있는 마지막 stop을 사용한다. `$oc-space-overrides`에서 stop 값을 `null`로 지정하면 그 stop은 정의되지 않은 것으로 취급한다.
+
+### `$oc-responsive-static-stop`
+
+`static` mode에서 전체 foundation에 공통으로 사용할 stop이다. 생략하면 각 foundation의 active stops 첫 번째 stop을 사용한다. foundation별 stops가 없으면 `$oc-responsive-stops`의 첫 번째 stop을 사용한다.
+
+## Examples
+
+### Default Fluid
+
+별도 설정 없이 `typo`와 `space`를 import하면 기본 fluid profile이 적용된다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/typo';
+@use '@orioncactuscorp/ui/scss/foundations/space';
+```
+
+### Stepped, sm~md Only
+
+`sm` 값을 base로 쓰고, `md` 값은 `769px`부터 적용한다. `lg` 이상 stop은 출력하지 않으므로 `md` 값이 이후 viewport에서도 유지된다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/responsive.config' with (
+  $oc-responsive-mode: stepped,
+  $oc-responsive-stops: (
+    sm,
+    md,
+  )
+);
+
+@use '@orioncactuscorp/ui/scss/foundations/typo';
+@use '@orioncactuscorp/ui/scss/foundations/space';
+```
+
+출력 형태:
+
+```css
+:root {
+  --oc-typo-size-body1: 1rem;
+}
+
+@media screen and (min-width: 769px) {
+  :root {
+    --oc-typo-size-body1: 1.0625rem;
+  }
+}
+```
+
+### Separate Typo and Space Stops
+
+mode는 `typo`와 `space`가 공유하되 active stop range만 다르게 지정할 수 있다. 아래 예시는 `typo`를 `sm` 값에 고정하고, `space`는 `sm` 값을 base로 쓰다가 `md` 이상에서 `md` 값으로 전환한다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/responsive.config' with (
+  $oc-responsive-mode: stepped,
+  $oc-responsive-typo-stops: (
+    sm,
+  ),
+  $oc-responsive-space-stops: (
+    sm,
+    md,
+  )
+);
+
+@use '@orioncactuscorp/ui/scss/foundations/typo';
+@use '@orioncactuscorp/ui/scss/foundations/space';
+```
+
+`$oc-responsive-typo-stops` 또는 `$oc-responsive-space-stops`를 생략하면 기존처럼 `$oc-responsive-stops`를 fallback으로 사용한다. `static` mode에서 `$oc-responsive-static-stop`을 생략한 경우에도 각 foundation의 첫 active stop을 고정값으로 사용한다.
+
+### Two-Mode Figma Viewport
+
+Figma `Viewport` collection이 `Mobile(md)`와 `Desktop(min, md)`처럼 두 mode만 갖고, `Desktop(min, md)`가 token별 desktop target 값을 가리킬 때는 `space`에 `stepped-points` profile을 사용한다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/responsive.config' with (
+  $oc-responsive-mode: stepped,
+  $oc-responsive-typo-stops: (
+    sm,
+  ),
+  $oc-responsive-space-stops: (
+    md,
+    lg,
+    xl,
+  ),
+  $oc-responsive-space-profile: (
+    type: stepped-points,
+    points: (
+      base: md,
+      min-md: max-active-defined,
+    ),
+  )
+);
+
+@use '@orioncactuscorp/ui/scss/foundations/space' with (
+  $oc-space-overrides: (
+    section-padding-viewport-x: (
+      md: 20,
+      xl: 32,
+    ),
+    section-padding-viewport-y: (
+      md: 16,
+      xl: 24,
+    ),
+    item-gap-small: (
+      xl: null,
+    ),
+  )
+);
+```
+
+이 profile은 `space`의 base 값을 각 token의 `md`로 출력하고, `769px+`부터 `$oc-responsive-space-stops` 안의 마지막 정의값으로 전환한다. 예를 들어 `item-padding-xsmall`은 `md -> xl`, `item-gap-tiny`는 `md -> lg`, `item-gap-small`은 `xl: null` 때문에 `md -> lg`로 출력된다.
+
+### Static md
+
+전체 viewport에서 `md` 값을 사용한다. 한 stop만 쓸 때 `fluid`나 `stepped`도 결과적으로 static처럼 출력되지만, 고정 의도를 드러내려면 `static` mode를 권장한다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/responsive.config' with (
+  $oc-responsive-mode: static,
+  $oc-responsive-static-stop: md
+);
+
+@use '@orioncactuscorp/ui/scss/foundations/typo';
+@use '@orioncactuscorp/ui/scss/foundations/space';
+```
+
+출력 형태:
+
+```css
+:root {
+  --oc-typo-size-body1: 1.0625rem;
+  --oc-space-section-padding-viewport-x: 2rem;
+}
+```
+
+## Full Foundation Rebuild
+
+`foundations.css`를 profile 적용 버전으로 대체하려면 consumer entry에서 foundation SCSS를 직접 import한다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/responsive.config' with (
+  $oc-responsive-mode: static,
+  $oc-responsive-static-stop: md
+);
+@use '@orioncactuscorp/ui/scss/foundations/color.global' as *;
+@use '@orioncactuscorp/ui/scss/foundations/color.theme.light' as *;
+@use '@orioncactuscorp/ui/scss/foundations/color.theme.dark' as *;
+@use '@orioncactuscorp/ui/scss/foundations/breakpoint' as *;
+@use '@orioncactuscorp/ui/scss/foundations/typo' as *;
+@use '@orioncactuscorp/ui/scss/foundations/space' as *;
+@use '@orioncactuscorp/ui/scss/foundations/atomic' as *;
+@use '@orioncactuscorp/ui/scss/foundations/focus' as *;
+@use '@orioncactuscorp/ui/scss/foundations/motion' as *;
+@use '@orioncactuscorp/ui/scss/foundations/zindex' as *;
+```
+
+이 consumer SCSS를 `@orioncactuscorp/ui/foundations.css` 대신 import한다.
+
+`reset.css`는 package prebuilt CSS를 그대로 import해도 된다.
+
+```tsx
+import '@orioncactuscorp/ui/reset.css';
+import './foundations.scss';
+```
+
+## Scope
+
+- responsive profile은 현재 `typo` size/height와 `space` token을 제어한다.
+- Typography letter spacing과 weight는 고정 token map을 유지한다.
+- `atomic` radius token은 `responsive.config` 대상이 아니며 기존 foundation 동작을 유지한다.
+- CSS variable runtime override와 SCSS compile-time profile은 서로 다른 customization 경로다.

package/docs/scss-helpers.md

@@ -0,0 +1,189 @@
+# SCSS Helpers
+
+`@orioncactuscorp/ui`가 SCSS source로 제공하는 consumer용 mixin/function입니다. 각 모듈은 `@orioncactuscorp/ui/scss/*` subpath로 import하고, `@use ... as *;` 형태를 사용합니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/mixins/element' as *;
+@use '@orioncactuscorp/ui/scss/mixins/breakpoint' as *;
+```
+
+> `@orioncactuscorp/ui/scss/index.scss` 통합 entry는 mixin뿐 아니라 **foundation CSS(토큰 + reset)를 함께 방출**합니다. `foundations.css`를 이미 import하고 있다면 토큰이 중복 방출되므로, mixin/function만 필요할 때는 위처럼 개별 mixin 모듈을 import하세요. 통합 entry는 prebuilt `foundations.css` 대신 SCSS foundation source를 직접 compile하는 경로에서만 사용합니다.
+
+이 문서에 있는 helper가 공개 계약입니다. 문서화되지 않은 export는 내부 구현이며 예고 없이 바뀔 수 있습니다([Stability Policy](./stability.md)).
+
+## oc-border — layout에 영향 없는 surface stroke
+
+`@orioncactuscorp/ui/scss/mixins/element`
+
+실제 CSS `border` 대신 `box-shadow`로 stroke를 그립니다. 요소의 content/padding/layout 크기를 바꾸지 않습니다.
+
+```scss
+@include oc-border($tokens...);
+```
+
+CSS `border` shorthand와 비슷하게 토큰을 순서 무관하게 나열합니다.
+
+| 토큰      | 값                                                  | 기본값         | 비고                                                                   |
+| --------- | --------------------------------------------------- | -------------- | ---------------------------------------------------------------------- |
+| width     | number (1개)                                        | `1px`          | `1.5px` 같은 half-pixel은 WebKit/DPR 보정 출력 포함                    |
+| color     | color, `var(...)` (1개)                             | `currentColor` |                                                                        |
+| side      | `top`, `right`, `bottom`, `left` (복수 가능), `all` | `all`          | 개별 side는 해당 방향 단일 stroke                                      |
+| placement | `inset`, `outer`                                    | `inset`        | `outer`는 요소 바깥에 그림 (역시 layout 무영향)                        |
+| style     | `solid`                                             | -              | CSS shorthand 익숙함을 위해 수용만 함 (box-shadow stroke는 항상 solid) |
+
+```scss
+.surface {
+  @include oc-border; // 1px currentColor inset
+}
+
+.surfaceAccent {
+  @include oc-border(var(--oc-color-theme-primary-normal));
+}
+
+.surfaceInvalid {
+  @include oc-border(1.5px, var(--oc-color-theme-status-negative));
+}
+
+.underline {
+  @include oc-border(bottom); // 아래쪽만
+}
+
+.focusRing {
+  @include oc-border(2px, var(--oc-color-theme-primary-normal), outer);
+}
+```
+
+`box-shadow` 한 채널을 사용하므로, 같은 요소에서 다른 `box-shadow`와 함께 쓸 때는 직접 shadow 목록을 조합해야 합니다.
+
+## oc-radius — 전역 radius factor 연동
+
+`@orioncactuscorp/ui/scss/mixins/radius`
+
+```scss
+oc-radius($radius, $factor-token: var(--oc-atomic-radius-factor))
+```
+
+`rem`/`em`/`px`/`clamp(...)` 기반 radius 값을 전역 radius factor에 연결합니다. `--oc-atomic-radius-factor`를 `0`으로 두면 이 helper를 거친 컴포넌트 로컬 radius도 함께 각지게 됩니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/mixins/radius' as *;
+
+.badge {
+  --oc-badge-radius: #{oc-radius(0.4em)};
+}
+```
+
+## oc-focus-ring — 키보드 포커스 ring
+
+`@orioncactuscorp/ui/scss/mixins/focus`
+
+```scss
+oc-focus-ring($color: var(--oc-color-theme-focus-ring), $width: var(--oc-focus-ring-width), $offset: var(--oc-focus-ring-offset))
+```
+
+`:focus-visible` ring을 foundation 토큰으로 그립니다. `outline` 기반이라 layout에 영향이 없고 요소의 border-radius를 그대로 따라가며 forced-colors 모드에서도 유지됩니다. reset 레이어가 `button`/`a[href]`/`summary`/`[tabindex]`에 같은 ring을 전역 기본값으로 제공하므로, 이 믹스인은 `all: unset`을 쓰는 요소나 ring을 다른 요소로 리다이렉트하는 경우(예: 선택 컨트롤의 wrapper)에 사용합니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/mixins/focus' as *;
+
+.trigger {
+  all: unset;
+
+  &:focus-visible {
+    @include oc-focus-ring;
+  }
+}
+```
+
+## oc-alpha — 토큰 기반 알파 색상
+
+`@orioncactuscorp/ui/scss/mixins/color`
+
+```scss
+oc-alpha($color, $opacity)
+```
+
+`color-mix(in srgb, ...)`로 알파가 적용된 색을 만듭니다. runtime CSS 변수 색상에도 알파를 적용할 수 있다는 점이 Sass `rgba()`와의 차이입니다.
+
+- `$color`: Sass color, `var(...)`, 또는 global color 토큰 suffix (`--oc-color-global-` 뒤 이름)
+- `$opacity`: `0`~`1` 숫자, 또는 global opacity 토큰 suffix (`--oc-color-global-opacity-` 뒤 이름)
+
+```scss
+@use '@orioncactuscorp/ui/scss/mixins/color' as *;
+
+.scrim {
+  background-color: oc-alpha(var(--oc-color-theme-primary-normal), 0.4);
+}
+```
+
+## typo — typography 토큰 조합
+
+`@orioncactuscorp/ui/scss/mixins/typo`
+
+```scss
+@include typo($variant, $weight: normal);
+```
+
+`font-size`, `line-height`, `letter-spacing`, `font-weight`를 `--oc-typo-*` 토큰에서 한 번에 출력합니다. raw `var(--oc-typo-size-*)` 직접 참조 대신 이 mixin을 사용하세요 — `--oc-typo-size-factor` runtime multiplier가 자동 반영됩니다.
+
+- `$variant`: foundation typo variant 이름 (`title1`, `body1` 등 — 전체 목록은 [Token Reference](./tokens.md))
+- `$weight`: `normal` | `medium` | `bold`
+
+variant별로 제공되는 weight는 [Token Reference](./tokens.md)의 `--oc-typo-weight-{variant}-*` 토큰 존재 여부를 기준으로 합니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/mixins/typo' as *;
+
+.heading {
+  @include typo(title2, bold);
+}
+```
+
+## respond-to — breakpoint media query
+
+`@orioncactuscorp/ui/scss/mixins/breakpoint`
+
+```scss
+@include respond-to($bp1, $bp2: null) { ... }
+```
+
+named breakpoint: `sm`(480px), `md`(768px), `lg`(1280px), `xl`(1600px), `hg`(1920px). `@use ... with ($breakpoint-md: 800px)`로 override할 수 있습니다.
+
+| 호출                                                 | 출력 media                                                    | 용도                                 |
+| ---------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------ |
+| `respond-to(sm)`, `respond-to(md)`                   | `(max-width: bp)`                                             | 좁은 viewport 예외 보정              |
+| `respond-to(lg)`, `respond-to(xl)`, `respond-to(hg)` | `(min-width: bp + 1px)`                                       | 넓은 viewport 확장                   |
+| `respond-to(min, $bp)`                               | `(min-width: bp + 1px)` (named) / `(min-width: 값)` (직접 값) | mobile-first progressive enhancement |
+| `respond-to(max, $bp)`                               | `(max-width: bp)`                                             | 상한                                 |
+| `respond-to($bp1, $bp2)`                             | `(min-width: 작은쪽 + 1px) and (max-width: 큰쪽)`             | 구간                                 |
+
+직접 숫자 값(`respond-to(min, 900px)`)도 받습니다. raw `@media (min-width: ...)` 대신 항상 이 mixin을 사용하세요.
+
+oc-ui SCSS는 mobile-first가 기본입니다: base rule은 narrow viewport 기준으로 쓰고, desktop 이상 차이는 `respond-to(min, md)`에서 더합니다. `respond-to(md)`(max-width)는 `Mobile(md)` 전용 예외 보정에만 사용합니다.
+
+## fluidClamp / toRem — fluid 값 유틸
+
+`@orioncactuscorp/ui/scss/mixins/utils`
+
+```scss
+fluidClamp($from, $bp, $anchor: to, $to)
+```
+
+`clamp($from, <viewport 비례식>, $to)`를 출력합니다. `$bp`는 기준 breakpoint(px), `$anchor`는 비례식이 어느 끝값에 정렬될지(`to` 기본, `from` 선택)입니다. foundation typo/space 토큰의 fluid 출력에 쓰이는 것과 같은 helper로, 커스텀 fluid 값을 만들 때 사용합니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/mixins/utils' as *;
+
+.hero {
+  padding-block: fluidClamp(toRem(24), 1280, to, toRem(64));
+}
+```
+
+`toRem($px)`는 `16px = 1rem` 기준으로 숫자를 rem으로 변환합니다.
+
+## Motion / Spring
+
+transition·animation helper(`oc-motion`, `oc-spring`)는 별도 가이드를 참조하세요.
+
+- [Semantic Motion](./motion.md) — intent/phase/pace 기반 motion 계약
+- [Spring Motion](./spring.md) — iOS perceptual duration 기반 spring transition