@uniai-fe/uds-foundation 0.3.0 → 0.4.0

package/README.md

@@ -10,6 +10,42 @@ pnpm add @uniai-fe/uds-foundation
 
 ## 사용법 요약
 
+## 제공 도구 목록
+
+- `ThemeProvider`
+- `ThemeProviderProps`
+- `themeTokens`
+- `@uniai-fe/uds-foundation/helpers`
+  - `colorPrimitiveHex`
+  - `colorPrimitiveVar`
+  - `spacingPaddingPx`
+  - `spacingPaddingVar`
+  - `spacingGapPx`
+  - `spacingGapVar`
+  - `layoutBreakpointPx`
+  - `layoutBreakpointVar`
+  - `layoutSizePx`
+  - `layoutSizeVar`
+  - `layoutRadiusSizePx`
+  - `layoutRadiusSizeVar`
+  - `layoutRadiusLevelPx`
+  - `layoutRadiusLevelVar`
+  - `typographyVariants`
+- `@uniai-fe/uds-foundation/typography/fonts`
+  - `pretendardFont`
+  - `pretendardLocalFont`
+  - `interFont`
+  - `interLocalFont`
+  - `createLocalFontOptions`
+- `@uniai-fe/uds-foundation/types/theme-tokens`
+  - `ThemeTokens`
+  - `ThemeColorPrimitive`
+  - `ThemeColorSemanticSection`
+  - `ThemeSpacingScale`
+  - `ThemeLayoutSizes`
+  - `ThemeTypographyVariant`
+  - `ThemeTypographyCategory`
+
 ### 최근 업데이트
 
 - `Light.tokens-v2` 기준으로 color semantic을 동기화했다. `label.standard=#3d3f43`, `border.standard.alternative=#e4e5e7`, `border.standard.assistive=#f2f2f3`로 교정했으며 `state.*`, `icon.*`, `surface.static.cool_gray_darker`를 추가했다.

package/dist/data/color.d.ts

@@ -1,10 +1,15 @@
 import { ThemeColorPrimitive, ThemeColorSemanticSection } from '../types/theme-tokens.js';
 
 /**
+ * Foundation Color Data; primitive color token snapshot
  * /_context/** 추출본을 참고해 수동으로 동기화한 컬러 토큰이다.
  * SCSS 값과 어긋나면 이 객체를 함께 수정해 문서/검증에 활용한다.
  */
 declare const color_primitive: ThemeColorPrimitive;
+/**
+ * Foundation Color Data; semantic color token snapshot
+ * canonical semantic 경로만 유지하며, CSS 하위호환 alias 변수는 SCSS 레이어에서만 함께 제공한다.
+ */
 declare const color_semantic: ThemeColorSemanticSection;
 
 export { color_primitive, color_semantic };

package/dist/data/layout.d.ts

@@ -1,7 +1,16 @@
 import { ThemeTokens } from '../types/theme-tokens.js';
 
+/**
+ * Foundation Layout Data; breakpoint token snapshot
+ */
 declare const layout_breakpoint: ThemeTokens["layout"]["breakpoint"];
+/**
+ * Foundation Layout Data; layout size token snapshot
+ */
 declare const layout_size: ThemeTokens["layout"]["size"];
+/**
+ * Foundation Layout Data; radius-by-size와 radius-by-level token snapshot
+ */
 declare const layout_radius: {
     readonly size: {
         readonly size_4x4: 1;

package/dist/data/spacing.d.ts

@@ -1,6 +1,12 @@
 import { ThemeSpacingScale } from '../types/theme-tokens.js';
 
+/**
+ * Foundation Spacing Data; padding token snapshot
+ */
 declare const spacing_padding: ThemeSpacingScale;
+/**
+ * Foundation Spacing Data; gap token snapshot
+ */
 declare const spacing_gap: ThemeSpacingScale;
 
 export { spacing_gap, spacing_padding };

package/dist/data/tokens.d.ts

@@ -1,5 +1,8 @@
 import { ThemeTokens } from '../types/theme-tokens.js';
 
+/**
+ * Foundation Data; theme token snapshot 집계 객체
+ */
 declare const themeTokens: ThemeTokens;
 
 export { themeTokens };

package/dist/data/typography.d.ts

@@ -1,5 +1,8 @@
 import { ThemeTokens } from '../types/theme-tokens.js';
 
+/**
+ * Foundation Typography Data; typography token snapshot
+ */
 declare const typography_tokens: ThemeTokens["typography"];
 
 export { typography_tokens };

package/dist/data/typography.js

@@ -57,7 +57,7 @@ const typography_tokens = {
       font_weight: 600
     }
   },
-  // Body scale follows the latest Figma Light tokens including xxsmall.
+  // 변경: body scale은 최신 Figma Light tokens와 xxsmall 축을 그대로 따른다.
   body: {
     large: {
       size: 19,

package/dist/helpers/index.d.ts

@@ -1,28 +1,157 @@
 import { ThemeTokens, ThemeTypographyCategory } from '../types/theme-tokens.js';
 
 declare const tokens: ThemeTokens;
+/**
+ * Foundation Helper Types; color primitive key
+ */
 type ThemeColorPrimitiveKey = keyof typeof tokens.color.primitive;
+/**
+ * Foundation Helpers; primitive color hex 조회
+ * @param {ThemeColorPrimitiveKey} key primitive color token key
+ * @returns {string} hex 색상값
+ * @example
+ * colorPrimitiveHex("blue_55");
+ */
 declare function colorPrimitiveHex(key: ThemeColorPrimitiveKey): string;
+/**
+ * Foundation Helpers; primitive color CSS variable 조회
+ * @param {ThemeColorPrimitiveKey} key primitive color token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * colorPrimitiveVar("blue_55");
+ */
 declare function colorPrimitiveVar(key: ThemeColorPrimitiveKey): string;
+/**
+ * Foundation Helper Types; spacing padding key
+ */
 type ThemeSpacingPaddingKey = keyof typeof tokens.spacing.padding;
+/**
+ * Foundation Helper Types; spacing gap key
+ */
 type ThemeSpacingGapKey = keyof typeof tokens.spacing.gap;
+/**
+ * Foundation Helpers; spacing padding px 조회
+ * @param {ThemeSpacingPaddingKey} key spacing padding token key
+ * @returns {number} px 값
+ * @example
+ * spacingPaddingPx("padding_6");
+ */
 declare function spacingPaddingPx(key: ThemeSpacingPaddingKey): number;
+/**
+ * Foundation Helpers; spacing padding CSS variable 조회
+ * @param {ThemeSpacingPaddingKey} key spacing padding token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * spacingPaddingVar("padding_6");
+ */
 declare function spacingPaddingVar(key: ThemeSpacingPaddingKey): string;
+/**
+ * Foundation Helpers; spacing gap px 조회
+ * @param {ThemeSpacingGapKey} key spacing gap token key
+ * @returns {number} px 값
+ * @example
+ * spacingGapPx("gap_6");
+ */
 declare function spacingGapPx(key: ThemeSpacingGapKey): number;
+/**
+ * Foundation Helpers; spacing gap CSS variable 조회
+ * @param {ThemeSpacingGapKey} key spacing gap token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * spacingGapVar("gap_6");
+ */
 declare function spacingGapVar(key: ThemeSpacingGapKey): string;
+/**
+ * Foundation Helper Types; layout breakpoint key
+ */
 type ThemeLayoutBreakpointKey = keyof typeof tokens.layout.breakpoint;
+/**
+ * Foundation Helper Types; layout size key
+ */
 type ThemeLayoutSizeKey = keyof typeof tokens.layout.size;
+/**
+ * Foundation Helper Types; layout radius size key
+ */
 type ThemeLayoutRadiusSizeKey = keyof typeof tokens.layout.radius.size;
+/**
+ * Foundation Helper Types; layout radius level key
+ */
 type ThemeLayoutRadiusLevelKey = keyof typeof tokens.layout.radius.level;
+/**
+ * Foundation Helpers; layout breakpoint px 조회
+ * @param {ThemeLayoutBreakpointKey} key breakpoint token key
+ * @returns {number} px 값
+ * @example
+ * layoutBreakpointPx("medium");
+ */
 declare function layoutBreakpointPx(key: ThemeLayoutBreakpointKey): number;
+/**
+ * Foundation Helpers; layout breakpoint CSS variable 조회
+ * @param {ThemeLayoutBreakpointKey} key breakpoint token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutBreakpointVar("medium");
+ */
 declare function layoutBreakpointVar(key: ThemeLayoutBreakpointKey): string;
+/**
+ * Foundation Helpers; layout size px 조회
+ * @param {ThemeLayoutSizeKey} key size token key
+ * @returns {number} px 값
+ * @example
+ * layoutSizePx("pc_large");
+ */
 declare function layoutSizePx(key: ThemeLayoutSizeKey): number;
+/**
+ * Foundation Helpers; layout size CSS variable 조회
+ * @param {ThemeLayoutSizeKey} key size token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutSizeVar("pc_large");
+ */
 declare function layoutSizeVar(key: ThemeLayoutSizeKey): string;
+/**
+ * Foundation Helpers; layout radius size px 조회
+ * @param {ThemeLayoutRadiusSizeKey} key radius size token key
+ * @returns {number} px 값
+ * @example
+ * layoutRadiusSizePx("size_medium");
+ */
 declare function layoutRadiusSizePx(key: ThemeLayoutRadiusSizeKey): number;
+/**
+ * Foundation Helpers; layout radius size CSS variable 조회
+ * @param {ThemeLayoutRadiusSizeKey} key radius size token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutRadiusSizeVar("size_medium");
+ */
 declare function layoutRadiusSizeVar(key: ThemeLayoutRadiusSizeKey): string;
+/**
+ * Foundation Helpers; layout radius level px 조회
+ * @param {ThemeLayoutRadiusLevelKey} key radius level token key
+ * @returns {number} px 값
+ * @example
+ * layoutRadiusLevelPx("medium_1");
+ */
 declare function layoutRadiusLevelPx(key: ThemeLayoutRadiusLevelKey): number;
+/**
+ * Foundation Helpers; layout radius level CSS variable 조회
+ * @param {ThemeLayoutRadiusLevelKey} key radius level token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutRadiusLevelVar("medium_1");
+ */
 declare function layoutRadiusLevelVar(key: ThemeLayoutRadiusLevelKey): string;
+/**
+ * Foundation Helper Types; typography category key
+ */
 type ThemeTypographyCategoryKey = keyof typeof tokens.typography;
+/**
+ * Foundation Helpers; typography category variant 목록 조회
+ * @param {ThemeTypographyCategoryKey} category typography category key
+ * @returns {typeof tokens.typography[ThemeTypographyCategoryKey]} variant map
+ * @example
+ * typographyVariants("body");
+ */
 declare function typographyVariants(category: ThemeTypographyCategoryKey): ThemeTypographyCategory;
 
 export { type ThemeColorPrimitiveKey, type ThemeLayoutBreakpointKey, type ThemeLayoutRadiusLevelKey, type ThemeLayoutRadiusSizeKey, type ThemeLayoutSizeKey, type ThemeSpacingGapKey, type ThemeSpacingPaddingKey, type ThemeTypographyCategoryKey, colorPrimitiveHex, colorPrimitiveVar, layoutBreakpointPx, layoutBreakpointVar, layoutRadiusLevelPx, layoutRadiusLevelVar, layoutRadiusSizePx, layoutRadiusSizeVar, layoutSizePx, layoutSizeVar, spacingGapPx, spacingGapVar, spacingPaddingPx, spacingPaddingVar, typographyVariants };

package/dist/index.css

@@ -523,6 +523,7 @@
     --color-label-alternative: var(--color-cool-gray-70);
     --color-label-assistive: var(--color-cool-gray-80);
     --color-label-disabled: var(--color-cool-gray-80);
+    --color-border-standard: var(--color-cool-gray-90);
     --color-border-standard-cool-gray: var(--color-cool-gray-90);
     --color-border-standard-blue: var(--color-blue-90);
     --color-border-strong: var(--color-cool-gray-75);

package/dist/provider/ThemeProvider.d.ts

@@ -1,12 +1,24 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
+/**
+ * ThemeProvider Props; foundation theme provider 속성
+ * @property {string} [className] `.uds-theme-root`와 함께 병합할 루트 className
+ */
 type FoundationThemeProviderProps = {
+    /**
+     * `.uds-theme-root`와 함께 병합할 루트 className
+     */
     className?: string;
 };
 /**
- * Foundation Theme Provider — `.uds-theme-root` 클래스를 부여해
- * CSS 변수 토큰이 적용될 루트를 명시한다.
+ * Foundation Theme Provider; CSS 변수 토큰 적용 루트 provider
+ * @component
+ * @param {PropsWithChildren<FoundationThemeProviderProps>} props
+ * @param {string} [props.className] `.uds-theme-root`와 함께 병합할 루트 className
+ * @param {React.ReactNode} props.children provider 하위 렌더 노드
+ * @example
+ * <ThemeProvider><App /></ThemeProvider>
  */
 declare function ThemeProvider({ children, className, }: PropsWithChildren<FoundationThemeProviderProps>): react_jsx_runtime.JSX.Element;
 

package/dist/types/theme-tokens.d.ts

@@ -1,16 +1,58 @@
+/**
+ * ThemeTypographyVariant; typography variant token 구조
+ * @property {number} size font-size px 값
+ * @property {string} line_height line-height 값
+ * @property {number} letter_spacing letter-spacing 값
+ * @property {number} font_weight font-weight 값
+ */
 interface ThemeTypographyVariant {
+    /**
+     * font-size px 값
+     */
     readonly size: number;
+    /**
+     * line-height 값
+     */
     readonly line_height: string;
+    /**
+     * letter-spacing 값
+     */
     readonly letter_spacing: number;
+    /**
+     * font-weight 값
+     */
     readonly font_weight: number;
 }
+/**
+ * ThemeColorPrimitive; primitive color token map
+ */
 type ThemeColorPrimitive = Record<string, string>;
+/**
+ * ThemeColorSemanticSection; semantic color nested token map
+ * @property {string | ThemeColorSemanticSection} [token] semantic color value 또는 하위 section
+ */
 interface ThemeColorSemanticSection {
     readonly [token: string]: string | ThemeColorSemanticSection;
 }
+/**
+ * ThemeSpacingScale; spacing scale token map
+ */
 type ThemeSpacingScale = Record<string, number>;
+/**
+ * ThemeLayoutSizes; layout size token map
+ */
 type ThemeLayoutSizes = Record<string, number>;
+/**
+ * ThemeTypographyCategory; typography category token map
+ */
 type ThemeTypographyCategory = Record<string, ThemeTypographyVariant>;
+/**
+ * ThemeTokens; foundation token snapshot 전체 구조
+ * @property {{ primitive: ThemeColorPrimitive; semantic: ThemeColorSemanticSection }} color color token 집합
+ * @property {{ padding: ThemeSpacingScale; gap: ThemeSpacingScale }} spacing spacing token 집합
+ * @property {{ breakpoint: Record<"xsmall" | "small" | "medium" | "large", number>; size: ThemeLayoutSizes; radius: { size: ThemeLayoutSizes; level: ThemeLayoutSizes } }} layout layout token 집합
+ * @property {{ [category: string]: ThemeTypographyCategory }} typography typography token 집합
+ */
 interface ThemeTokens {
     readonly color: {
         readonly primitive: ThemeColorPrimitive;

package/dist/typography/fonts/types.d.ts

@@ -1,30 +1,115 @@
+/**
+ * ThemeFontStyle; font style 축
+ * @typedef {"normal" | "italic"} ThemeFontStyle
+ */
 type ThemeFontStyle = "normal" | "italic";
+/**
+ * ThemeFontDisplay; next/font display 축
+ * @typedef {"auto" | "block" | "swap" | "fallback" | "optional"} ThemeFontDisplay
+ */
 type ThemeFontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
+/**
+ * ThemeFontSource; font file source 정의
+ * @property {string} filename 폰트 파일명
+ * @property {string} weight font-weight 문자열
+ * @property {ThemeFontStyle} style font-style 값
+ */
 interface ThemeFontSource {
+    /**
+     * 폰트 파일명
+     */
     filename: string;
+    /**
+     * font-weight 문자열
+     */
     weight: string;
+    /**
+     * font-style 값
+     */
     style: ThemeFontStyle;
 }
+/**
+ * ThemeFontDefinition; foundation font definition 구조
+ * @property {string} name 폰트 식별자
+ * @property {string} family CSS font-family 이름
+ * @property {string} cssVariable CSS variable 이름
+ * @property {string[]} fallbacks fallback font-family 목록
+ * @property {ThemeFontDisplay} [display] next/font display 정책
+ * @property {boolean} [preload] preload 여부
+ * @property {readonly ThemeFontSource[]} sources 폰트 소스 목록
+ */
 interface ThemeFontDefinition {
+    /**
+     * 폰트 식별자
+     */
     name: string;
+    /**
+     * CSS font-family 이름
+     */
     family: string;
+    /**
+     * CSS variable 이름
+     */
     cssVariable: string;
+    /**
+     * fallback font-family 목록
+     */
     fallbacks: string[];
+    /**
+     * next/font display 정책
+     */
     display?: ThemeFontDisplay;
+    /**
+     * preload 여부
+     */
     preload?: boolean;
+    /**
+     * 폰트 소스 목록
+     */
     sources: readonly ThemeFontSource[];
 }
+/**
+ * NextLocalFontOptions; next/font/local 입력 옵션 구조
+ * @property {string} variable CSS variable 이름
+ * @property {ThemeFontDisplay} [display] next/font display 정책
+ * @property {string[]} fallback fallback font-family 목록
+ * @property {boolean} [preload] preload 여부
+ * @property {ReadonlyArray<{ path: string; weight: string; style: ThemeFontStyle }>} src 폰트 소스 목록
+ */
 interface NextLocalFontOptions {
+    /**
+     * CSS variable 이름
+     */
     variable: string;
+    /**
+     * next/font display 정책
+     */
     display?: ThemeFontDisplay;
+    /**
+     * fallback font-family 목록
+     */
     fallback: string[];
+    /**
+     * preload 여부
+     */
     preload?: boolean;
+    /**
+     * 폰트 소스 목록
+     */
     src: ReadonlyArray<{
         path: string;
         weight: string;
         style: ThemeFontStyle;
     }>;
 }
+/**
+ * Foundation Fonts; localFont options 변환 유틸
+ * @param {ThemeFontDefinition} font foundation font definition
+ * @param {string} metaUrl import.meta.url
+ * @returns {NextLocalFontOptions} next/font/local 옵션 객체
+ * @example
+ * createLocalFontOptions(pretendardFont, import.meta.url);
+ */
 declare function createLocalFontOptions(font: ThemeFontDefinition, metaUrl: string): NextLocalFontOptions;
 
 export { type NextLocalFontOptions, type ThemeFontDefinition, type ThemeFontDisplay, type ThemeFontSource, type ThemeFontStyle, createLocalFontOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-foundation",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "UNIAI Design System; Design Foundation Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.28.2",
+  "packageManager": "pnpm@10.32.0",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -99,15 +99,16 @@
     "module:build": "pnpm build",
     "module:dev": "pnpm dev",
     "foundation:build": "pnpm run build",
-    "foundation:dev": "pnpm run dev"
+    "foundation:dev": "pnpm run dev",
+    "publish:public": "bash ../../../scripts/npm-publish.sh"
   },
   "devDependencies": {
     "@types/node": "^24.10.2",
-    "@types/react": "^19.2.11",
+    "@types/react": "^19.2.14",
     "react": "^19.2.4",
     "@uniai-fe/tsconfig": "workspace:*",
-    "autoprefixer": "^10.4.24",
-    "postcss": "^8.5.6",
+    "autoprefixer": "^10.4.27",
+    "postcss": "^8.5.8",
     "postcss-cli": "^11.0.1",
     "prettier": "^3.8.1",
     "sass": "^1.97.3",

package/src/color/semantic/border.scss

@@ -1,5 +1,6 @@
 // 테마 경계선 토큰
 @mixin foundation-color-border() {
+  --color-border-standard: var(--color-cool-gray-90); // #e4e5e7;
   --color-border-standard-cool-gray: var(--color-cool-gray-90); // #e4e5e7;
   --color-border-standard-blue: var(--color-blue-90); // #ccdeff;
   --color-border-strong: var(--color-cool-gray-75); // #bcbec2;

package/src/data/color.ts

@@ -240,6 +240,7 @@ const color_cyan: ThemeColorPrimitive = {
 } as const;
 
 /**
+ * Foundation Color Data; primitive color token snapshot
  * /_context/** 추출본을 참고해 수동으로 동기화한 컬러 토큰이다.
  * SCSS 값과 어긋나면 이 객체를 함께 수정해 문서/검증에 활용한다.
  */
@@ -261,6 +262,10 @@ export const color_primitive: ThemeColorPrimitive = {
   ...color_cyan,
 };
 
+/**
+ * Foundation Color Data; semantic color token snapshot
+ * canonical semantic 경로만 유지하며, CSS 하위호환 alias 변수는 SCSS 레이어에서만 함께 제공한다.
+ */
 export const color_semantic: ThemeColorSemanticSection = {
   primary: {
     default: color_primitive.blue_55,

package/src/data/layout.ts

@@ -1,5 +1,8 @@
 import type { ThemeTokens } from "../types/theme-tokens";
 
+/**
+ * Foundation Layout Data; breakpoint token snapshot
+ */
 export const layout_breakpoint: ThemeTokens["layout"]["breakpoint"] = {
   xsmall: 0,
   small: 768,
@@ -7,6 +10,9 @@ export const layout_breakpoint: ThemeTokens["layout"]["breakpoint"] = {
   large: 1200,
 };
 
+/**
+ * Foundation Layout Data; layout size token snapshot
+ */
 export const layout_size: ThemeTokens["layout"]["size"] = {
   xxsmall: 4,
   xsmall_1: 8,
@@ -25,6 +31,9 @@ export const layout_size: ThemeTokens["layout"]["size"] = {
   xlarge_2: 120,
 };
 
+/**
+ * Foundation Layout Data; radius-by-size와 radius-by-level token snapshot
+ */
 export const layout_radius = {
   size: {
     size_4x4: 1,

package/src/data/spacing.ts

@@ -1,5 +1,8 @@
 import type { ThemeSpacingScale } from "../types/theme-tokens";
 
+/**
+ * Foundation Spacing Data; padding token snapshot
+ */
 export const spacing_padding: ThemeSpacingScale = {
   padding_1: 2,
   padding_2: 4,
@@ -14,6 +17,9 @@ export const spacing_padding: ThemeSpacingScale = {
   padding_11: 40,
 };
 
+/**
+ * Foundation Spacing Data; gap token snapshot
+ */
 export const spacing_gap: ThemeSpacingScale = {
   gap_1: 2,
   gap_2: 4,

package/src/data/tokens.ts

@@ -4,6 +4,9 @@ import { spacing_gap, spacing_padding } from "./spacing.js";
 import { layout_breakpoint, layout_radius, layout_size } from "./layout.js";
 import { typography_tokens } from "./typography.js";
 
+/**
+ * Foundation Data; theme token snapshot 집계 객체
+ */
 export const themeTokens: ThemeTokens = {
   color: {
     primitive: color_primitive,

package/src/data/typography.ts

@@ -1,5 +1,8 @@
 import type { ThemeTokens } from "../types/theme-tokens";
 
+/**
+ * Foundation Typography Data; typography token snapshot
+ */
 export const typography_tokens: ThemeTokens["typography"] = {
   display: {
     large: {
@@ -59,7 +62,7 @@ export const typography_tokens: ThemeTokens["typography"] = {
       font_weight: 600,
     },
   },
-  // Body scale follows the latest Figma Light tokens including xxsmall.
+  // 변경: body scale은 최신 Figma Light tokens와 xxsmall 축을 그대로 따른다.
   body: {
     large: {
       size: 19,

package/src/helpers/index.ts

@@ -7,77 +7,206 @@ const kebab = (value: string) => value.replace(/_/g, "-");
 const dropPrefix = (value: string, prefix: string) =>
   value.startsWith(`${prefix}_`) ? value.slice(prefix.length + 1) : value;
 
+/**
+ * Foundation Helper Types; color primitive key
+ */
 export type ThemeColorPrimitiveKey = keyof typeof tokens.color.primitive;
 
+/**
+ * Foundation Helpers; primitive color hex 조회
+ * @param {ThemeColorPrimitiveKey} key primitive color token key
+ * @returns {string} hex 색상값
+ * @example
+ * colorPrimitiveHex("blue_55");
+ */
 export function colorPrimitiveHex(key: ThemeColorPrimitiveKey): string {
   return tokens.color.primitive[key];
 }
 
+/**
+ * Foundation Helpers; primitive color CSS variable 조회
+ * @param {ThemeColorPrimitiveKey} key primitive color token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * colorPrimitiveVar("blue_55");
+ */
 export function colorPrimitiveVar(key: ThemeColorPrimitiveKey): string {
   return cssVar(`color-${kebab(key)}`);
 }
 
+/**
+ * Foundation Helper Types; spacing padding key
+ */
 export type ThemeSpacingPaddingKey = keyof typeof tokens.spacing.padding;
+/**
+ * Foundation Helper Types; spacing gap key
+ */
 export type ThemeSpacingGapKey = keyof typeof tokens.spacing.gap;
 
+/**
+ * Foundation Helpers; spacing padding px 조회
+ * @param {ThemeSpacingPaddingKey} key spacing padding token key
+ * @returns {number} px 값
+ * @example
+ * spacingPaddingPx("padding_6");
+ */
 export function spacingPaddingPx(key: ThemeSpacingPaddingKey): number {
   return tokens.spacing.padding[key];
 }
 
+/**
+ * Foundation Helpers; spacing padding CSS variable 조회
+ * @param {ThemeSpacingPaddingKey} key spacing padding token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * spacingPaddingVar("padding_6");
+ */
 export function spacingPaddingVar(key: ThemeSpacingPaddingKey): string {
   const suffix = kebab(dropPrefix(key, "padding"));
   return cssVar(`spacing-padding-${suffix}`);
 }
 
+/**
+ * Foundation Helpers; spacing gap px 조회
+ * @param {ThemeSpacingGapKey} key spacing gap token key
+ * @returns {number} px 값
+ * @example
+ * spacingGapPx("gap_6");
+ */
 export function spacingGapPx(key: ThemeSpacingGapKey): number {
   return tokens.spacing.gap[key];
 }
 
+/**
+ * Foundation Helpers; spacing gap CSS variable 조회
+ * @param {ThemeSpacingGapKey} key spacing gap token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * spacingGapVar("gap_6");
+ */
 export function spacingGapVar(key: ThemeSpacingGapKey): string {
   const suffix = kebab(dropPrefix(key, "gap"));
   return cssVar(`spacing-gap-${suffix}`);
 }
 
+/**
+ * Foundation Helper Types; layout breakpoint key
+ */
 export type ThemeLayoutBreakpointKey = keyof typeof tokens.layout.breakpoint;
+/**
+ * Foundation Helper Types; layout size key
+ */
 export type ThemeLayoutSizeKey = keyof typeof tokens.layout.size;
+/**
+ * Foundation Helper Types; layout radius size key
+ */
 export type ThemeLayoutRadiusSizeKey = keyof typeof tokens.layout.radius.size;
+/**
+ * Foundation Helper Types; layout radius level key
+ */
 export type ThemeLayoutRadiusLevelKey = keyof typeof tokens.layout.radius.level;
 
+/**
+ * Foundation Helpers; layout breakpoint px 조회
+ * @param {ThemeLayoutBreakpointKey} key breakpoint token key
+ * @returns {number} px 값
+ * @example
+ * layoutBreakpointPx("medium");
+ */
 export function layoutBreakpointPx(key: ThemeLayoutBreakpointKey): number {
   return tokens.layout.breakpoint[key];
 }
 
+/**
+ * Foundation Helpers; layout breakpoint CSS variable 조회
+ * @param {ThemeLayoutBreakpointKey} key breakpoint token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutBreakpointVar("medium");
+ */
 export function layoutBreakpointVar(key: ThemeLayoutBreakpointKey): string {
   return cssVar(`theme-breakpoint-${kebab(key)}-start`);
 }
 
+/**
+ * Foundation Helpers; layout size px 조회
+ * @param {ThemeLayoutSizeKey} key size token key
+ * @returns {number} px 값
+ * @example
+ * layoutSizePx("pc_large");
+ */
 export function layoutSizePx(key: ThemeLayoutSizeKey): number {
   return tokens.layout.size[key];
 }
 
+/**
+ * Foundation Helpers; layout size CSS variable 조회
+ * @param {ThemeLayoutSizeKey} key size token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutSizeVar("pc_large");
+ */
 export function layoutSizeVar(key: ThemeLayoutSizeKey): string {
   return cssVar(`theme-size-${kebab(key)}`);
 }
 
+/**
+ * Foundation Helpers; layout radius size px 조회
+ * @param {ThemeLayoutRadiusSizeKey} key radius size token key
+ * @returns {number} px 값
+ * @example
+ * layoutRadiusSizePx("size_medium");
+ */
 export function layoutRadiusSizePx(key: ThemeLayoutRadiusSizeKey): number {
   return tokens.layout.radius.size[key];
 }
 
+/**
+ * Foundation Helpers; layout radius size CSS variable 조회
+ * @param {ThemeLayoutRadiusSizeKey} key radius size token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutRadiusSizeVar("size_medium");
+ */
 export function layoutRadiusSizeVar(key: ThemeLayoutRadiusSizeKey): string {
   const suffix = kebab(dropPrefix(key, "size"));
   return cssVar(`theme-radius-${suffix}`);
 }
 
+/**
+ * Foundation Helpers; layout radius level px 조회
+ * @param {ThemeLayoutRadiusLevelKey} key radius level token key
+ * @returns {number} px 값
+ * @example
+ * layoutRadiusLevelPx("medium_1");
+ */
 export function layoutRadiusLevelPx(key: ThemeLayoutRadiusLevelKey): number {
   return tokens.layout.radius.level[key];
 }
 
+/**
+ * Foundation Helpers; layout radius level CSS variable 조회
+ * @param {ThemeLayoutRadiusLevelKey} key radius level token key
+ * @returns {string} CSS variable 문자열
+ * @example
+ * layoutRadiusLevelVar("medium_1");
+ */
 export function layoutRadiusLevelVar(key: ThemeLayoutRadiusLevelKey): string {
   return cssVar(`theme-radius-${kebab(key)}`);
 }
 
+/**
+ * Foundation Helper Types; typography category key
+ */
 export type ThemeTypographyCategoryKey = keyof typeof tokens.typography;
 
+/**
+ * Foundation Helpers; typography category variant 목록 조회
+ * @param {ThemeTypographyCategoryKey} category typography category key
+ * @returns {typeof tokens.typography[ThemeTypographyCategoryKey]} variant map
+ * @example
+ * typographyVariants("body");
+ */
 export function typographyVariants(category: ThemeTypographyCategoryKey) {
   return tokens.typography[category];
 }

package/src/index.ts

@@ -1,5 +1,8 @@
 import "./index.scss";
 
+/**
+ * Foundation; 토큰 CSS, 폰트, provider, 타입 엔트리 집계 배럴
+ */
 export * from "./typography/fonts";
 export * from "./provider";
 export type * from "./types";

package/src/provider/ThemeProvider.tsx

@@ -1,12 +1,24 @@
 import type { PropsWithChildren } from "react";
 
+/**
+ * ThemeProvider Props; foundation theme provider 속성
+ * @property {string} [className] `.uds-theme-root`와 함께 병합할 루트 className
+ */
 export type FoundationThemeProviderProps = {
+  /**
+   * `.uds-theme-root`와 함께 병합할 루트 className
+   */
   className?: string;
 };
 
 /**
- * Foundation Theme Provider — `.uds-theme-root` 클래스를 부여해
- * CSS 변수 토큰이 적용될 루트를 명시한다.
+ * Foundation Theme Provider; CSS 변수 토큰 적용 루트 provider
+ * @component
+ * @param {PropsWithChildren<FoundationThemeProviderProps>} props
+ * @param {string} [props.className] `.uds-theme-root`와 함께 병합할 루트 className
+ * @param {React.ReactNode} props.children provider 하위 렌더 노드
+ * @example
+ * <ThemeProvider><App /></ThemeProvider>
  */
 function ThemeProvider({
   children,
@@ -17,6 +29,7 @@ function ThemeProvider({
     classNames.push(className);
   }
 
+  // 변경: foundation token scope를 한 곳에서 고정한다.
   return <div className={classNames.join(" ")}>{children}</div>;
 }
 

package/src/provider/index.ts

@@ -1,2 +1,5 @@
+/**
+ * Foundation Provider; theme root provider 엔트리
+ */
 export { ThemeProvider } from "./ThemeProvider";
 export type { FoundationThemeProviderProps as ThemeProviderProps } from "./ThemeProvider";

package/src/types/index.ts

@@ -1,2 +1,5 @@
+/**
+ * Foundation Types; style option, theme tokens 엔트리
+ */
 export type * from "./style-option";
 export type * from "./theme-tokens";

package/src/types/theme-tokens.ts

@@ -1,18 +1,60 @@
+/**
+ * ThemeTypographyVariant; typography variant token 구조
+ * @property {number} size font-size px 값
+ * @property {string} line_height line-height 값
+ * @property {number} letter_spacing letter-spacing 값
+ * @property {number} font_weight font-weight 값
+ */
 export interface ThemeTypographyVariant {
+  /**
+   * font-size px 값
+   */
   readonly size: number;
+  /**
+   * line-height 값
+   */
   readonly line_height: string;
+  /**
+   * letter-spacing 값
+   */
   readonly letter_spacing: number;
+  /**
+   * font-weight 값
+   */
   readonly font_weight: number;
 }
 
+/**
+ * ThemeColorPrimitive; primitive color token map
+ */
 export type ThemeColorPrimitive = Record<string, string>;
+/**
+ * ThemeColorSemanticSection; semantic color nested token map
+ * @property {string | ThemeColorSemanticSection} [token] semantic color value 또는 하위 section
+ */
 export interface ThemeColorSemanticSection {
   readonly [token: string]: string | ThemeColorSemanticSection;
 }
+/**
+ * ThemeSpacingScale; spacing scale token map
+ */
 export type ThemeSpacingScale = Record<string, number>;
+/**
+ * ThemeLayoutSizes; layout size token map
+ */
 export type ThemeLayoutSizes = Record<string, number>;
+/**
+ * ThemeTypographyCategory; typography category token map
+ */
 export type ThemeTypographyCategory = Record<string, ThemeTypographyVariant>;
 
+/**
+ * ThemeTokens; foundation token snapshot 전체 구조
+ * @property {{ primitive: ThemeColorPrimitive; semantic: ThemeColorSemanticSection }} color color token 집합
+ * @property {{ padding: ThemeSpacingScale; gap: ThemeSpacingScale }} spacing spacing token 집합
+ * @property {{ breakpoint: Record<"xsmall" | "small" | "medium" | "large", number>; size: ThemeLayoutSizes; radius: { size: ThemeLayoutSizes; level: ThemeLayoutSizes } }} layout layout token 집합
+ * @property {{ [category: string]: ThemeTypographyCategory }} typography typography token 집합
+ */
 export interface ThemeTokens {
   readonly color: {
     readonly primitive: ThemeColorPrimitive;

package/src/typography/fonts/index.ts

@@ -1,3 +1,6 @@
+/**
+ * Foundation Fonts; localFont helper 및 font definition 엔트리
+ */
 export * from "./types";
 export * from "./pretendard";
 export * from "./inter";

package/src/typography/fonts/types.ts

@@ -1,5 +1,13 @@
+/**
+ * ThemeFontStyle; font style 축
+ * @typedef {"normal" | "italic"} ThemeFontStyle
+ */
 export type ThemeFontStyle = "normal" | "italic";
 
+/**
+ * ThemeFontDisplay; next/font display 축
+ * @typedef {"auto" | "block" | "swap" | "fallback" | "optional"} ThemeFontDisplay
+ */
 export type ThemeFontDisplay =
   | "auto"
   | "block"
@@ -7,27 +15,96 @@ export type ThemeFontDisplay =
   | "fallback"
   | "optional";
 
+/**
+ * ThemeFontSource; font file source 정의
+ * @property {string} filename 폰트 파일명
+ * @property {string} weight font-weight 문자열
+ * @property {ThemeFontStyle} style font-style 값
+ */
 export interface ThemeFontSource {
+  /**
+   * 폰트 파일명
+   */
   filename: string;
+  /**
+   * font-weight 문자열
+   */
   weight: string;
+  /**
+   * font-style 값
+   */
   style: ThemeFontStyle;
 }
 
+/**
+ * ThemeFontDefinition; foundation font definition 구조
+ * @property {string} name 폰트 식별자
+ * @property {string} family CSS font-family 이름
+ * @property {string} cssVariable CSS variable 이름
+ * @property {string[]} fallbacks fallback font-family 목록
+ * @property {ThemeFontDisplay} [display] next/font display 정책
+ * @property {boolean} [preload] preload 여부
+ * @property {readonly ThemeFontSource[]} sources 폰트 소스 목록
+ */
 export interface ThemeFontDefinition {
+  /**
+   * 폰트 식별자
+   */
   name: string;
+  /**
+   * CSS font-family 이름
+   */
   family: string;
+  /**
+   * CSS variable 이름
+   */
   cssVariable: string;
+  /**
+   * fallback font-family 목록
+   */
   fallbacks: string[];
+  /**
+   * next/font display 정책
+   */
   display?: ThemeFontDisplay;
+  /**
+   * preload 여부
+   */
   preload?: boolean;
+  /**
+   * 폰트 소스 목록
+   */
   sources: readonly ThemeFontSource[];
 }
 
+/**
+ * NextLocalFontOptions; next/font/local 입력 옵션 구조
+ * @property {string} variable CSS variable 이름
+ * @property {ThemeFontDisplay} [display] next/font display 정책
+ * @property {string[]} fallback fallback font-family 목록
+ * @property {boolean} [preload] preload 여부
+ * @property {ReadonlyArray<{ path: string; weight: string; style: ThemeFontStyle }>} src 폰트 소스 목록
+ */
 export interface NextLocalFontOptions {
+  /**
+   * CSS variable 이름
+   */
   variable: string;
+  /**
+   * next/font display 정책
+   */
   display?: ThemeFontDisplay;
+  /**
+   * fallback font-family 목록
+   */
   fallback: string[];
+  /**
+   * preload 여부
+   */
   preload?: boolean;
+  /**
+   * 폰트 소스 목록
+   */
   src: ReadonlyArray<{
     path: string;
     weight: string;
@@ -35,6 +112,14 @@ export interface NextLocalFontOptions {
   }>;
 }
 
+/**
+ * Foundation Fonts; localFont options 변환 유틸
+ * @param {ThemeFontDefinition} font foundation font definition
+ * @param {string} metaUrl import.meta.url
+ * @returns {NextLocalFontOptions} next/font/local 옵션 객체
+ * @example
+ * createLocalFontOptions(pretendardFont, import.meta.url);
+ */
 export function createLocalFontOptions(
   font: ThemeFontDefinition,
   metaUrl: string,