@uniai-fe/uds-foundation 0.4.6 → 0.4.7

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025 UNIAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project includes third-party software governed by additional licenses,
+including Apache License 2.0. Refer to `THIRD_PARTY_NOTICES.md` for the full
+text of those notices and any required attributions.

package/README.md

@@ -1,6 +1,6 @@
 # @uniai-fe/uds-foundation
 
-UNIAI 서비스 전반에서 공유하는 디자인 토큰과 폰트 자산을 CSS 변수 형태로 제공하는 패키지입니다. 색상·여백·레이아웃·타이포그래피·폰트 정의를 모두 포함하며, 다른 패키지(`@uniai-fe/uds-primitives`, `@uniai-fe/uds-templates`)의 기초가 됩니다.
+UNIAI 서비스 전반에서 공유하는 UDS token/runtime style foundation package입니다. 색상·여백·레이아웃·타이포그래피·폰트 정의를 CSS variables, Sass entry, TypeScript token object, helper/provider/font/type export로 제공하며, 다른 패키지(`@uniai-fe/uds-primitives`, `@uniai-fe/uds-templates`)의 기초가 됩니다.
 
 ## 설치
 
@@ -10,8 +10,89 @@ pnpm add @uniai-fe/uds-foundation
 
 ## 사용법 요약
 
+### Public import surface
+
+`@uniai-fe/uds-foundation`의 public import 기준은 package export map에 명시된 root와 subpath다. root import는 TS API entry이며 style load entry가 아니다.
+
+대표 안정 subpath:
+
+```ts
+import { ThemeProvider } from "@uniai-fe/uds-foundation/provider";
+import { themeTokens } from "@uniai-fe/uds-foundation/data/tokens";
+import { colorPrimitiveVar } from "@uniai-fe/uds-foundation/helpers";
+```
+
+- `@uniai-fe/uds-foundation`: provider, font, token snapshot, type surface를 모은 root TS API entry
+- `@uniai-fe/uds-foundation/data/tokens`: `themeTokens` snapshot
+- `@uniai-fe/uds-foundation/helpers`: token helper 함수
+- `@uniai-fe/uds-foundation/provider`: `ThemeProvider`
+- `@uniai-fe/uds-foundation/typography/fonts`: font option helpers
+- `@uniai-fe/uds-foundation/types/theme-tokens`: theme token type surface
+
+root에서 직접 export되는 token snapshot은 현재 API inventory로 취급한다. consumer guide에서는 style entry와 혼동을 줄이기 위해 `data/tokens`, `helpers`, `provider`, `typography/fonts`, `types/theme-tokens`처럼 명시 subpath를 우선 안내한다.
+
+## Foundation token/export contract
+
+foundation은 reset/document base style, CSS variables, SCSS/Sass entry, TypeScript token object, generated token snapshot, token helper, `ThemeProvider`, font options, public token types를 함께 제공한다.
+
+| 형식                    | 역할                                                                             |
+| ----------------------- | -------------------------------------------------------------------------------- |
+| CSS variables           | runtime style contract. 서비스와 design package style은 `var(--...)`를 소비한다. |
+| SCSS/Sass entry         | Sass consumer와 internal style composition을 위한 public style entry다.          |
+| TypeScript token object | `themeTokens`와 개별 token const가 제공하는 TS canonical snapshot이다.           |
+| JSON snapshot           | `docs/theme-tokens.json`에 있는 generated/reference snapshot이다.                |
+| Markdown token docs     | `docs/theme-tokens.md`에 있는 generated/reference documentation이다.             |
+| token map               | Figma token -> canonical token -> CSS variable mapping 기준이다.                 |
+| helper exports          | TS에서 token value 또는 CSS variable name 접근을 돕는다.                         |
+| provider export         | root DOM에 `.uds-theme-root` scope class를 부여한다.                             |
+| font exports            | `next/font/local` option과 font family contract를 제공한다.                      |
+| type exports            | 실제 token object에서 파생한 object-first token type contract다.                 |
+
+### `themeTokens` canonical snapshot
+
+`themeTokens`는 TS canonical token snapshot이다. public token type은 별도 수동 schema를 중복 선언하기보다 실제 token object에서 `typeof` 기반으로 파생한다. 이 object-first 구조는 token key와 public type의 drift를 줄이는 것이 목적이다.
+
+현재 구조는 단일 token pipeline이 아니다. SCSS runtime token과 TS canonical snapshot이 수동 병행되므로, 값 추가/변경 시 CSS variables, TS object, JSON/Markdown snapshot 사이 drift check는 후속 설계 대상이다.
+
+### Generated docs boundary
+
+`docs/theme-tokens.md`와 `docs/theme-tokens.json`은 token 이해를 돕는 generated/reference snapshot이다. source of truth 자체로 사용하지 않는다.
+
+- token source는 package-local `src/data/*.ts`의 TS canonical snapshot과 SCSS token files의 runtime CSS variable source로 나뉜다.
+- generated snapshot 재생성은 `tokens:doc` 등 별도 script/gate를 통해 수행한다.
+- 이 문서 보정 단계에서는 generated content를 재생성하지 않는다.
+- JSON/Markdown snapshot의 package publish 포함 여부는 별도 package contract gate에서 판단한다.
+
+### Source and mapping boundary
+
+`_context/design-system/sot/current/**`는 reference/SOT layer이며 package code나 package docs 산출물에서 import하지 않는다. 실제 implementation mapping은 package-local Figma token export와 `docs/theme-token-mapping-guide.md`를 기준으로 확인한다.
+
+역할 분리:
+
+- `_context/design-system/sot/current/**`: reference/SOT layer
+- package-local Figma token export: implementation mapping 근거
+- `docs/theme-token-mapping-guide.md`: Figma token -> canonical token -> CSS variable mapping guide
+- `src/data/*.ts`: TS canonical token source
+- SCSS token files: runtime CSS variable source
+- `docs/theme-tokens.{json,md}`: generated/reference snapshot
+
+### Helper / Provider / Font / Types boundary
+
+- Helpers: token key와 CSS variable/value 접근을 돕지만 token source를 대체하지 않는다. helper 예시가 실제 key와 맞지 않으면 문서 보정 후보로 본다.
+- Provider: CSS를 import하지 않고 root DOM에 `.uds-theme-root` scope class만 부여한다. foundation CSS가 로드되면 `.uds-theme-root`의 layout/style 책임도 함께 적용될 수 있다.
+- Fonts: `next/font/local` option과 font family contract를 제공한다. SCSS token layer의 `--font-family-*`와 `next/font/local` option의 `--theme-font-family-*`는 다른 변수 체계이며, `--theme-font-family-*`는 Next font class 적용을 전제로 한다.
+- Types: `ThemeTokens` 등 token type은 object-first `typeof` 파생 구조를 따른다. `ThemeColorSemanticSection`, `ThemeSpacingScale`, `ThemeLayoutSizes` 같은 broad compatibility type은 기존 소비자 보호용으로 유지한다.
+
+### Compatibility and Panda boundary
+
+compatibility alias와 deprecated token은 기존 소비자 보호 목적이므로 제거하거나 rename하지 않는다. `common_99/common_100`, `state.disabled/static_disabled`, `icon.disable/disabled` 같은 rename bridge와 CSS short alias는 compatibility layer로 유지한다. 제거 여부는 별도 compatibility gate가 필요하다.
+
+Panda Foundation PoC는 아직 시작하지 않는다. token source mapping, CSS variable compatibility, SCSS coexistence, alias/deprecated carry-over, validation-first 기준, package export stability가 먼저 고정되어야 한다.
+
 ## 제공 도구 목록
 
+아래 목록은 현재 API inventory다. 실제 import 가능 경로는 package export map의 root와 명시 subpath를 기준으로 확인한다.
+
 - `ThemeProvider`
 - `ThemeProviderProps`
 - `themeTokens`
@@ -53,27 +134,31 @@ pnpm add @uniai-fe/uds-foundation
 - Figma 토큰 매핑 기준은 `docs/theme-token-mapping-guide.md`를 단일 참조로 사용한다.
 - `Sementic.Button.*`은 foundation이 아닌 `@uniai-fe/uds-primitives` 버튼 변수 토큰(`components/button/styles/variables.scss`)에서 운영한다.
 - `Sementic.Opacity.*`은 foundation semantic 토큰으로 별도 편입하지 않고, Figma node `{opacity}` source value를 `opacity` 속성에 직접 적용한다. (예: `30%`/`0.3` -> `opacity: 0.3;`)
-- Sass 소비자는 `@use "@uniai-fe/uds-foundation/css.scss";` 경로를 사용해야 하며, CSS-only 프로젝트는 기존대로 `import "@uniai-fe/uds-foundation/css";`로 토큰을 주입한다.
+- Sass 소비자는 public entry인 `@use "@uniai-fe/uds-foundation/scss";`를 사용한다. package root의 `css.scss` 파일은 해당 entry가 가리키는 내부 forward 파일이며, consumer-facing 사용 예시에서는 직접 경로로 안내하지 않는다.
 
-### 1) CSS 변수 주입
+### 1) 스타일 엔트리
 
-```ts
-import "@uniai-fe/uds-foundation";
-```
+`@uniai-fe/uds-foundation` root import는 TS API, token data, helpers, provider, font, type surface를 소비하기 위한 entry다. CSS variable 주입 방법으로 안내하지 않는다.
 
-CSS 파일만 직접 사용하려면:
+CSS-only 소비자는 앱 루트 또는 global stylesheet에서 foundation CSS를 먼저 로드한다.
 
 ```ts
 import "@uniai-fe/uds-foundation/css";
 ```
 
+Sass 소비자는 foundation Sass public entry를 사용한다.
+
+```scss
+@use "@uniai-fe/uds-foundation/scss";
+```
+
 ```css
 .button-primary {
   color: var(--color-primary-default);
   padding: var(--spacing-padding-6);
   border-radius: var(--theme-radius-medium-1);
   font: var(--font-body-medium-weight) var(--font-body-medium-size) /
-    var(--font-body-medium-line-height) var(--theme-font-family-pretendard);
+    var(--font-body-medium-line-height) var(--font-family-pretendard);
 }
 ```
 
@@ -98,7 +183,13 @@ Sass 소비자는 `@use "@uniai-fe/uds-foundation/scss";`로 전체 토큰을, `
 }
 ```
 
-### 2) 토큰 데이터(JSON)
+### ThemeProvider와 CSS load 책임
+
+`ThemeProvider`는 CSS를 import하지 않는다. Provider는 루트 DOM에 `.uds-theme-root` scope class를 부여하고, CSS load 책임은 service app root, global stylesheet, 또는 consumer setup이 가진다.
+
+foundation CSS가 로드된 상태에서는 `.uds-theme-root`에 연결된 foundation scope/layout 스타일도 함께 적용되므로, Provider 책임을 CSS load 책임으로 축소해 설명하지 않는다.
+
+### 2) 토큰 데이터(TS object)
 
 ```ts
 import { themeTokens } from "@uniai-fe/uds-foundation/data/tokens";

package/dist/index.d.ts

@@ -8,7 +8,6 @@ export { spacing_gap, spacing_padding } from './data/spacing.js';
 export { layout_breakpoint, layout_radius, layout_size } from './data/layout.js';
 export { typography_tokens } from './data/typography.js';
 export { ThemeColorPrimitive, ThemeColorSemantic, ThemeColorSemanticSection, ThemeLayoutBreakpoint, ThemeLayoutRadius, ThemeLayoutSize, ThemeLayoutSizes, ThemeSpacingGap, ThemeSpacingPadding, ThemeSpacingScale, ThemeTokens, ThemeTypography, ThemeTypographyCategory, ThemeTypographyVariant } from './types/theme-tokens.js';
-import 'react/jsx-runtime';
 import 'react';
 
 /**

package/dist/provider/ThemeProvider.d.ts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { PropsWithChildren } from 'react';
 
 /**
@@ -20,6 +20,6 @@ type FoundationThemeProviderProps = {
  * @example
  * <ThemeProvider><App /></ThemeProvider>
  */
-declare function ThemeProvider({ children, className, }: PropsWithChildren<FoundationThemeProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ThemeProvider({ children, className, }: PropsWithChildren<FoundationThemeProviderProps>): react.JSX.Element;
 
 export { type FoundationThemeProviderProps, ThemeProvider };

package/dist/provider/index.d.ts

@@ -1,3 +1,2 @@
 export { ThemeProvider, FoundationThemeProviderProps as ThemeProviderProps } from './ThemeProvider.js';
-import 'react/jsx-runtime';
 import 'react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-foundation",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "UNIAI Design System; Design Foundation Package",
   "type": "module",
   "private": false,
@@ -104,14 +104,14 @@
   },
   "devDependencies": {
     "@types/node": "^24.12.3",
-    "@types/react": "^19.2.14",
-    "react": "^19.2.6",
+    "@types/react": "^19.2.16",
+    "react": "^19.2.7",
     "@uniai-fe/tsconfig": "workspace:*",
     "autoprefixer": "^10.5.0",
-    "postcss": "^8.5.14",
+    "postcss": "^8.5.15",
     "postcss-cli": "^11.0.1",
     "prettier": "^3.8.3",
-    "sass": "^1.99.0",
+    "sass": "^1.100.0",
     "tsup": "^8.5.1",
     "typescript": "5.9.3"
   }