@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;

CSS-only 프로젝트는 앱 루트에서 foundation CSS를 먼저 로드한 뒤 primitives CSS를 로드합니다. primitives CSS는 foundation token이 이미 로드되어 있다고 가정합니다.

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

사용 예시

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

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

Public import surface

@uniai-fe/uds-primitives의 공식 안정 public surface는 root namespace import다.

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

• component/type/hook 소비는 root namespace import를 기준으로 안내한다.
• @uniai-fe/uds-primitives/styles, @uniai-fe/uds-primitives/css, @uniai-fe/uds-primitives/init/dayjs, @uniai-fe/uds-primitives/init/mantine, @uniai-fe/uds-primitives/mantine-style는 package export map에 있는 style/init entry다.
• @uniai-fe/uds-primitives/button, @uniai-fe/uds-primitives/input 같은 short category subpath는 현재 안정 public surface로 안내하지 않는다.
• category subpath 공개 여부는 package contract gate 후보로 남긴다.

제공 도구 목록

아래 목록은 root namespace에서 확인하는 API inventory다. 카테고리 이름은 도구 탐색용이며, category subpath import 가능 여부의 SOT가 아니다.

• Alternate.EmptyData
• Alternate.LoadingDefault
• Alternate.LoadingIcon
• Alternate.Text
• Alternate.Layout.Container
• Alternate.Layout.Figure
• Alternate.Layout.Title
• Alternate.Layout.Contents
• Alternate.Layout.TextButton
• Alternate.Layout.Button
• AlternateEmptyDataProps
• AlternateLoadingDefaultProps
• AlternateLoadingIconProps
• AlternateTextProps
• AlternateLayoutContainerProps
• AlternateLayoutFigureProps
• AlternateLayoutTitleProps
• AlternateLayoutContentsProps
• AlternateLayoutTextButtonProps
• AlternateLayoutButtonProps
• Badge
• BadgeProps
• Chip.Default
• Chip.ClickableStyle
• Chip.InputStyle
• Chip.Label
• Chip.List
• ChipProps
• ChipListRootProps
• ChipListItemData
• Calendar.Root
• Calendar.Container
• Calendar.Header
• Calendar.Body
• Calendar.Footer
• Calendar.Core
• Calendar.Icon
• CalendarValue
• CalendarRootProps
• CalendarContainerProps
• CalendarGridProps
• CalendarDatePickerProps
• Carousel.Provider
• Carousel.Container
• Carousel.Control
• Carousel.Track
• Carousel.Button.Base
• Carousel.Button.Prev
• Carousel.Button.Next
• useCarousel
• useCarouselProviderController
• CarouselProviderProps
• CarouselTrackProps
• CarouselContainerProps
• CarouselControlProps
• CarouselPrevButtonProps
• CarouselNextButtonProps
• DrawerRoot
• DrawerTrigger
• DrawerPortal
• DrawerOverlay
• DrawerContent
• DrawerHeader
• DrawerBody
• DrawerFooter
• DrawerTitle
• DrawerDescription
• DrawerClose
• DrawerRootProps
• DrawerTriggerProps
• DrawerContentProps
• useDrawerDrag
• Form.Provider
• Form.Field.Container
• Form.Field.Header
• Form.Field.Body
• Form.Field.Footer
• Form.Field.Template
• FormFieldTemplateProps
• FormFieldContainerProps
• FormFieldHeaderProps
• FormFieldFooterProps
• FormFieldWidth
• FormFieldState
• getFormFieldWidthAttr
• getFormFieldWidthValue
• InfoBox
• InfoBoxIcon
• InfoBoxProps
• InfoBoxState
• BottomNavigation
• BottomNavigationProps
• NavigationItem
• NavigationItemKey
• NavigationHrefItem
• NavigationActionItem
• NavigationSitemapNode
• NavigationSitemapCollection
• NavigationSitemapOptions
• composeNavigationClassName
• isHrefNavigationItem
• Pagination
• PaginationCarousel
• PaginationCount
• PaginationProps
• PaginationCarouselProps
• PaginationCountProps
• PaginationCountSize
• PaginationCarouselPriority
• normalizePaginationState
• createPaginationPages
• composePaginationClassName
• Slot.Base
• Slot.Text
• SlotComponentProps
• SlotTextProps
• Switch
• SwitchProps
• SwitchSize
• TabRoot
• TabList
• TabTrigger
• TabContent
• TabRootProps
• TabListProps
• TabTriggerProps
• TabContentProps
• TabVariant
• TabScale
• TabContext
• useTabContext
• SegmentedControl
• SegmentedControlLabel
• SegmentedControlProps
• SegmentedControlOption
• SegmentedControlValue
• Divider
• DividerProps
• DividerDirection
• scrollbar (현재 public export 없음)
• spinner (현재 public export 없음)
• Table.Root
• Table.Head
• Table.Body
• Table.Foot
• Table.Row
• Table.Th
• Table.Td
• Table.Cell
• Table.Text
• Table.Container
• Table.Colgroup
• Table.Col
• TableColumnData
• TableRootProps
• TableContainerProps
• TableCellProps
• Toast.Host
• Toast.Item
• ToastIcon
• ToastItemData
• ToastHostProps
• ToastItemProps
• ToastState
• ToastHorizontal
• ToastVertical
• Button.Default
• Button.Text
• Button.Rounded
• Button.Label
• ButtonProps
• TextButtonProps
• RoundButtonProps
• Input.Base
• Input.TextArea
• Input.Text.Password
• Input.Text.Phone
• Input.Text.Email
• Input.Text.Search
• Input.Text.AuthCode
• Input.Date.Template
• Input.Address.Template
• Input.Address.Button
• Input.File.UploadButton
• Input.File.UploadedChip
• Input.File.List.*
• useInputFile
• useInputFileContext
• Select.Default
• Select.Multiple
• Select.Container
• Select.Trigger.Base
• Select.Selected.Base
• Select.Selected.Multiple
• SelectDropdownOption
• SelectMultipleTag
• Dropdown.Root
• Dropdown.Trigger
• Dropdown.Container
• Dropdown.Menu.Item
• Dropdown.Menu.List
• Dropdown.Template
• DropdownTemplateItem
• DropdownTemplateChangePayload
• Radio
• RadioField
• RadioCard
• RadioCardGroup
• RadioProps
• RadioFieldProps
• Checkbox
• CheckboxField
• CheckboxProps
• CheckboxFieldProps
• CheckboxSize
• Tooltip.Root
• Tooltip.Trigger
• Tooltip.Message
• Tooltip.Text
• Tooltip.Template
• TooltipMessageProps
• PopOver.Root
• PopOver.Trigger
• PopOver.Content
• PopOverRootProps
• PopOverTriggerProps
• PopOverContentProps

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가지 카테고리를 한 번에 확인할 수 있다.

Slot (폴리모픽 as 래퍼)

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

최근 업데이트

• TextInput Base 컴포넌트의 clear 버튼 로직을 pointer 이벤트 기반으로 재작성해 모바일 터치 환경에서도 안정적으로 입력값이 초기화되도록 했다.
• react-hook-form register와 연계된 값도 동일하게 초기화되며, focus가 빠지면 clear 버튼이 자동으로 숨겨진다.
• Input.TextArea를 추가했다.
  • height?: number | string으로 높이를 직접 제어한다. (기본 128px)
  • length?: number을 주면 0 / n자 카운터가 우측 하단에 노출된다.
  • 기본 resize는 비활성(none)이며, size 축은 Input 기본 size token(--input-default-*)을 재사용한다.
• Select/Dropdown 계약을 items 중심으로 정렬했다.
  • Select: items, onSelectChange, dropdownOptions, open/defaultOpen/onOpen
  • Dropdown.Template: items[].selected + onChange(payload)

스타일 내보내기

primitives styles/css 엔트리는 primitives component styles만 제공하며 foundation 토큰을 다시 로드하지 않는다. Foundation style은 service app root 또는 global stylesheet에서 먼저 로드해야 한다.

CSS-only consumer setup

Sass를 사용하지 않는 Next.js/webpack 소비자는 CSS entry를 순서대로 import한다.

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

Sass consumer setup

Sass 소비자는 foundation Sass public entry를 먼저 로드하고 primitives aggregate entry를 이어서 로드한다.

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

Storybook/local render setup

modules repo 내부 Storybook은 source style 변경을 빠르게 확인하기 위해 Preview에서 @uniai-fe/uds-foundation/css 이후 @uniai-fe/uds-primitives/styles를 로드한다. 이 설정은 Storybook local render setup이며 외부 consumer setup의 SOT가 아니다.

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

Mantine CSS 포함 책임은 이번 문서 보정에서 확정하지 않는다. @uniai-fe/uds-primitives/css, @uniai-fe/uds-primitives/styles, root init, mantine-style 중 어느 entry가 공식 책임을 갖는지는 별도 package/style contract gate에서 정리한다.

토큰 스코프 & ThemeProvider

• primitives styles는 foundation token이 이미 로드되어 있다고 가정한다.
• ThemeProvider는 루트 DOM에 .uds-theme-root 클래스를 주입하지만 CSS를 import하지 않는다. 서비스 앱은 ThemeProvider를 layout 최상단에 배치하더라도 style entry를 별도로 로드해야 한다.
• CSS-only 소비자는 @uniai-fe/uds-foundation/css -> @uniai-fe/uds-primitives/css 순서를 사용한다.
• Sass 소비자는 @uniai-fe/uds-foundation/scss -> @uniai-fe/uds-primitives/styles 순서를 사용한다.

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;

아래 두 style load 방식 중 하나만 선택한다.

Sass 방식:

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

CSS-only 방식:

// app/layout.tsx
import type { ReactNode } from "react";
import "@uniai-fe/uds-foundation/css";
import "@uniai-fe/uds-primitives/css";
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/scss"; @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|unit|layout/  // 컴포넌트 구현
  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해 사용하면 됩니다.