# @uniai-fe/uds-foundation

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

## 설치

```bash
pnpm add @uniai-fe/uds-foundation
```

## 사용법 요약

### 최근 업데이트

- `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 변수 주입

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

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

```ts
import "@uniai-fe/uds-foundation/css";
```

```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()`처럼 짧은 이름으로 접근할 수 있다.

```scss
@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)

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

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

### 3) 타입스크립트 헬퍼

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

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

### 4) Next.js `localFont`

```ts
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`: 토큰 스냅샷 생성
