@uniai-fe/uds-primitives

@uniai-fe/uds-foundation 토큰 위에 Radix UI 컴포넌트를 얇게 감싼 기초 UI 컴포넌트 컬렉션입니다. Next.js 등 React 런타임에서 바로 import해 버튼·입력·네비게이션 등 공통 요소를 일관된 스타일로 사용할 수 있습니다. Templates(@uniai-fe/uds-templates) 패키지에서 사용하는 Phone Input/Email Verification Input/OneTimeCode Input 등의 인증 시나리오 컴포넌트도 이곳에서 제공합니다.

설치

pnpm add @uniai-fe/uds-foundation @uniai-fe/util-functions @uniai-fe/uds-primitives

Peer Dependencies

@uniai-fe/uds-primitives는 디자인 토큰과 유틸리티 로직을 공유하기 위해 다음 패키지를 같이 설치해야 합니다.

• @uniai-fe/uds-foundation@^0.0.1
• @uniai-fe/util-functions@^0.2.3
• react@>=19, react-dom@>=19
• react-hook-form@>=7

peer dependency가 빠져 있을 경우 앱 번들 시점에 에러가 발생하니, 위 목록을 프로젝트 package.json에 명시해 주세요.

// next.config.ts
const nextConfig = {
  transpilePackages: ["@uniai-fe/uds-foundation", "@uniai-fe/uds-primitives"],
};
export default nextConfig;

앱 루트에서 foundation CSS를 1회 import 하면 모든 primitives가 토큰을 공유합니다.

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

사용 예시

import { Button } from "@uniai-fe/uds-primitives";

export default function Page() {
  return (
    <Button.Default fill="solid" size="medium" priority="primary">
      확인
    </Button.Default>
  );
}

Link/Anchor로 사용하기

import Link from "next/link";
import { Button } from "@uniai-fe/uds-primitives";

function LinkButton() {
  return (
    <Button.Default
      as={Link}
      href="/dashboard"
      fill="outlined"
      size="medium"
      priority="secondary"
    >
      대시보드로 이동
    </Button.Default>
  );
}

Button 역할 클래스 & Props 미리보기

• 기본 클래스: .button (padding/height/radius/타이포/커서 담당)
• 슬롯: button-label, button-icon, button-left, button-right, button-loading
• Modifier: button-scale-*, button-fill-*, button-priority-*, button-state-*, button-size-*, button-block, button-icon-left/right
• scale prop은 legacy 호환용이며 fill/size를 명시 사용하는 것이 권장된다.
• loading 상태는 readonly와 동일하게 잠기며 hover/pressed 반응을 막는다. anchor 등 커스텀 요소도 aria-disabled="true"를 통해 동일한 스타일을 적용받는다.

TextButton / RoundButton 템플릿

Button 객체는 템플릿별 컴포넌트를 포함한다.

import { Button } from "@uniai-fe/uds-primitives";

function Templates() {
  return (
    <>
      <Button.Text priority="secondary" size="medium">
        링크 스타일
      </Button.Text>

      <Button.Rounded aria-label="추가" size="small">
        <span aria-hidden="true">＋</span>
      </Button.Rounded>
    </>
  );
}

• TextButton(Button.Text)은 size="small|medium|large" + priority="secondary|tertiary"만 허용한다.
• RoundButton(Button.Rounded)은 size만 지정하면 되고 priority는 기본 Button과 동일하게 primary|secondary|tertiary를 사용한다.
• 템플릿별 클래스를 추가로 노출한다: .button-template-text, .button-template-text-size-*, .button-template-round, .button-template-round-size-*.
• 스토리북 primitives/Button Story에서 solid/outlined/텍스트/라운드 4가지 카테고리를 한 번에 확인할 수 있다.

SlotComponent (폴리모픽 as 래퍼)

• Button.Default는 SlotComponent를 통해 as prop으로 전달된 요소(예: Link, a, button)에 공통 속성/ref를 안전하게 전달한다.
• SlotComponentProps<C>는 React가 허용하는 모든 native props + data-* 속성을 그대로 포함하고, as/children/className만 재정의한다.
• 필요 시 import { SlotComponent } from "@uniai-fe/uds-primitives";로 직접 사용해 카드/배너 등의 래퍼를 구현할 수 있다.
• 자세한 도입 배경과 API는 docs/CONTEXT-SLOT.md에서 확인할 수 있다.

최근 업데이트

• TextInput Base 컴포넌트의 clear 버튼 로직을 pointer 이벤트 기반으로 재작성해 모바일 터치 환경에서도 안정적으로 입력값이 초기화되도록 했다.
• react-hook-form register와 연계된 값도 동일하게 초기화되며, focus가 빠지면 clear 버튼이 자동으로 숨겨진다.

스타일 내보내기

foundation CSS는 앱 루트에서 한 번만 직접 import해야 한다. primitives styles/css 엔트리는 컴포넌트 SCSS만 포함하며 foundation 토큰을 다시 로드하지 않는다.

@use "@uniai-fe/uds-foundation/css";
@use "@uniai-fe/uds-primitives/styles";

Next.js/webpack 환경에서 Sass를 사용하지 않는 경우에는 아래처럼 CSS를 순서대로 import한다.

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

컴포넌트 단위로 필요한 스타일만 선택해 불러오려면 각 경로(components/{name}/index.scss)를 직접 import하면 된다.

@use "@uniai-fe/uds-primitives/button/index.scss";
@use "@uniai-fe/uds-primitives/navigation/index.scss";

ThemeProvider는 CSS를 import하지 않으므로 foundation/primitives styles를 앱 루트에서 1회만 로드하면 중복 없이 토큰 매핑이 적용된다. Provider 자체는 foundation 패키지(@uniai-fe/uds-foundation/provider)에서만 export된다(one-source 규칙).

modules 레포 내부(Storybook 등)에서는 개발 편의를 위해 @uniai-fe/uds-primitives/src/index.scss를 직접 import하지만, 외부 서비스/패키지는 @uniai-fe/uds-primitives/css 엔트리만 사용한다.

토큰 스코프 & ThemeProvider

• primitives 소스 SCSS는 모든 디자인 토큰을 :root에 선언하고, 빌드 시 scripts/merge-theme-root.mjs가 이 토큰 블록을 하나의 :root { ... }로 합쳐 중복 선언을 제거한다.
• ThemeProvider가 루트 DOM에 .uds-theme-root 클래스를 주입하므로, 서비스 앱은 ThemeProvider를 layout 최상단에 배치한 뒤 @uniai-fe/uds-foundation/css → @uniai-fe/uds-primitives/css 순으로 import하면 된다.
• modules 레포(Storybook 등)는 SCSS 원본을 직접 import하지만 외부 소비자는 CSS 엔트리만 사용한다는 정책을 README/CODEX-RULES에 명시해둔다.

Next.js 통합 예시

Next.js 15(app router 기준)에서 primitives를 사용하는 최소 구성 예시는 다음과 같다.

// next.config.ts
const nextConfig = {
  transpilePackages: ["@uniai-fe/uds-foundation", "@uniai-fe/uds-primitives"],
  sassOptions: {
    // monorepo가 아니어도 node_modules 경로를 자동 탐색하지만,
    // 필요 시 디자인 토큰 경로를 명시해 두면 빌드 환경 차이를 줄일 수 있다.
    includePaths: ["./node_modules"],
  },
};
export default nextConfig;

/* app/globals.scss */
@use "@uniai-fe/uds-foundation/css";
@use "@uniai-fe/uds-primitives/styles";

// app/layout.tsx
import type { ReactNode } from "react";
import "@uniai-fe/uds-foundation/css";
import "@uniai-fe/uds-primitives/styles";
import { ThemeProvider } from "@uniai-fe/uds-foundation/provider";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="ko">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

위 예시는 ThemeProvider가 foundation 패키지에서만 export되고 CSS를 재import하지 않는 현재 구조를 기준으로 하므로, globals.scss 또는 루트에서 foundation/primitives styles를 반드시 각각 한 번 로드해야 한다. Sass 기반 프로젝트는 @use "@uniai-fe/uds-foundation/css"; @use "@uniai-fe/uds-primitives/styles";, CSS-only 프로젝트는 import "@uniai-fe/uds-foundation/css"; import "@uniai-fe/uds-primitives/css";를 사용한다.

모든 컴포넌트는 .component 클래스 + CSS 변수 기반으로 override가 가능하며, 버튼처럼 Slot(left/right/icon 등)을 제공하는 항목은 CONTEXT-*.md 문서에 상세 API를 기록했습니다. 불필요한 data-* attribute는 제거했고, 상태 표시는 :disabled, [aria-busy="true"] 같은 표준 attribute만 사용합니다.

구조

src/components/{category}/
  markup/   // 컴포넌트 구현
  types/    // 외부 노출 타입
  styles/   // SCSS (foundation 토큰 기반)
  hooks/    // 카테고리 전용 훅

• 배럴(components/{category}/index.tsx)은 항상 import "./index.scss"를 포함합니다.
• 스타일은 foundation CSS 변수만 사용하며, .button.button-priority-* / .button.button-fill-* 클래스 조합으로 상태를 분기합니다.

스크립트

• pnpm module:lint
• pnpm module:typecheck
• pnpm module:build

루트에서는 pnpm --filter @uniai-fe/uds-primitives <command>로 실행할 수 있습니다.

문서

• CONTEXT.md 및 CONTEXT-*.md: 각 컴포넌트의 상태/진행/디자인 근거
• CONTEXT-INPUT.md: Phone/Email/OneTimeCode 등 인증 입력 시나리오 규칙을 포함하며, templates CONTEXT-SIGNUP*.md와 항상 동기화해야 한다.
• RADIX-SIZE-GUIDE.md: primitives 사이즈 체계와 Radix 매핑 규칙

Signup 인증 입력 컴포넌트

• PhoneInput: 기본은 마스킹된 전화번호 입력만 제공한다. onRequestCode(optional)를 주입하면 인증요청 버튼이 우측 right 슬롯에 노출된다. 인증코드 입력 섹션은 templates 레이어(Auth.AuthCode.Phone)에서 code.visible, code.inputProps로 제어한다.
• EmailInput: 이메일 입력과 인증요청 버튼까지만 제공한다. 인증코드 UI와 countdown/state 관리는 @uniai-fe/uds-templates의 Auth.AuthCode.Email 템플릿에서 처리하며, code.visible, code.helper, code.inputProps.length 등의 옵션으로 Step2 Verify & Agreement 상태를 맞춘다.
• AuthCodeInput: length 지정형 OneTimeCode grid. EmailInput 내부에서 사용하지만 서비스 앱도 직접 import할 수 있다.
• 변경 시에는 다음 문서를 함께 업데이트한다: packages/design/primitives/docs/CONTEXT-INPUT.md, packages/design/templates/docs/CONTEXT-SIGNUP.md, CONTEXT-SIGNUP-FLOW.md, packages/design/templates/docs/STORYBOOK.md, apps/design-storybook/src/stories/templates/auth/AuthSignup.stories.tsx.

• 컨벤션: 모든 컴포넌트/스토리/문서는 slot/prefix/suffix 용어를 사용하지 않고, 레이아웃 기준(header/body/footer, 2단 구조는 upper/lower)과 util* 키워드를 사용한다. 인터랙션 함수는 on* 접두사를 사용하고, JSDoc @param은 depth 전체를 풀어 쓴다.

필요한 컨텍스트를 확인한 뒤 컴포넌트를 import해 사용하면 됩니다.