@uniai-fe/uds-foundation

UNIAI 서비스 전반에서 공유하는 디자인 토큰과 폰트 자산을 CSS 변수 형태로 제공하는 패키지입니다. 색상·여백·레이아웃·타이포그래피·폰트 정의를 모두 포함하며, 다른 패키지(@uniai-fe/uds-primitives, @uniai-fe/uds-templates)의 기초가 됩니다.

설치

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를 추가했다.
• 하위호환 정책으로 common_99/common_100, icon.disable/icon.disabled, state.disabled/state.static_disabled를 함께 유지한다.
• 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";로 토큰을 주입한다.

1) CSS 변수 주입

import "@uniai-fe/uds-foundation";

CSS 파일만 직접 사용하려면:

import "@uniai-fe/uds-foundation/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);
}

Sass 유틸리티

Sass 소비자는 @use "@uniai-fe/uds-foundation/scss";로 전체 토큰을, @use "@uniai-fe/uds-foundation/scss/functions" as style;로 스타일 계산 함수를, @use "@uniai-fe/uds-foundation/scss/responsive" as responsive;로 반응형 rem 믹스인을 사용할 수 있다. alias(as style)를 지정하면 style.padding()처럼 짧은 이름으로 접근할 수 있다.

@use "@uniai-fe/uds-foundation/scss" as foundation;
@use "@uniai-fe/uds-foundation/scss/functions" as style;
@use "@uniai-fe/uds-foundation/scss/responsive" as responsive;

:root {
  @include foundation.foundation-layout-radius();
  @include responsive.base();
}

@include responsive.queries();

.panel {
  @include style.padding("rem", 16);
}

2) 토큰 데이터(JSON)

import { themeTokens } from "@uniai-fe/uds-foundation/data/tokens";

console.log(themeTokens.color.primitive.blue_55);

3) 타입스크립트 헬퍼

import {
  colorPrimitiveVar,
  spacingPaddingPx,
} from "@uniai-fe/uds-foundation/helpers";

const primaryBg = colorPrimitiveVar("blue_55");
const mediumGap = spacingPaddingPx("padding_6");

4) Next.js localFont

import localFont from "next/font/local";
import {
  pretendardLocalFont,
  interLocalFont,
} from "@uniai-fe/uds-foundation/typography/fonts";

export const pretendard = localFont(pretendardLocalFont);
export const inter = localFont(interLocalFont);

5) 패키지 스크립트

• pnpm build: 타입 검사 + CSS/폰트 산출
• pnpm dev: watch 모드
• pnpm tokens:doc: 토큰 스냅샷 생성