@uniai-fe/uds-primitives

Foundation token 위의 기초 UI와 공통 interaction을 제공한다. 공통 책임과 convention은 ../DESIGN-SYSTEM-GUIDE.md를 따른다.

설치

현재 peer range는 package.json이 권위다.

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

Raw TypeScript package를 사용하는 Next.js 앱은 현재 package contract에 맞게 transpilePackages를 설정한다.

const nextConfig = {
  transpilePackages: ["@uniai-fe/uds-foundation", "@uniai-fe/uds-primitives"],
};

export default nextConfig;

Public entries

Component, type, hook과 utility는 root public entry에서 가져온다. 실제 공개 범위는 package.json exports와 public barrel이 권위다.

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

export const ConfirmButton = () => (
  <Button.Default fill="solid" size="medium" priority="primary">
    확인
  </Button.Default>
);

@uniai-fe/uds-primitives/src/**와 export map에 없는 category path는 public API가 아니다.

Button.Default의 priority는 primary, secondary, tertiary, green, yellow, orange, teal, pink, red, darkGray, lightGray를 지원한다. Text와 Rounded Button은 기존 priority 범위를 유지한다.

Input.Time.Template과 standalone TimePicker.Template, TimePickerUtils도 root public entry에서 제공한다.

Fab.Button은 아이콘 전용 주요 액션, Fab.Expand는 아이콘과 라벨을 표시한다. 필수 icon은 ReactNode이며 size는 small | medium | large다. Button과 같은 fill="solid" | "outlined"와 priority를 독립적으로 조합한다. 두 fill 모두 priority가 필수이며 Button.Default와 같은 primary, secondary, tertiary, green, yellow, orange, teal, pink, red, darkGray, lightGray를 지원한다. 색상과 상태별 배경은 Button 토큰을 재사용하며 outlined의 기본 면은 불투명 흰색이다. 아이콘 전용 Button에는 행동 이름인 aria-label도 필수다. 화면 고정 배치는 소비자가 정한다. Fab.Default, Fab.Extended, Fab.Label은 기존 사용처와의 호환을 유지한다.

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

<Fab.Button
  icon={<span aria-hidden="true">+</span>}
  aria-label="항목 추가"
  fill="solid"
  priority="primary"
  size="medium"
/>;

관련 액션을 원형 버튼으로 펼치는 구성은 Fab.Template으로 시작하거나 Fab.Root 안에 Fab.Trigger, Fab.Menu.List, Fab.Menu.Item을 직접 조립한다. Fab.Expand는 라벨 확장형이고, 메뉴를 펼치는 동작은 Fab.Trigger가 담당한다. Root는 hover·focus·click·keyboard, 메뉴 ID·ARIA 연결, 닫기와 focus 복귀를 소유한다. direction은 up | down | left | right이며 기본값은 up이다. 열림 상태는 open과 onOpenChange로 제어하거나 defaultOpen으로 초기화한다.

<Fab.Template
  triggerProps={{
    icon: <span aria-hidden="true">+</span>,
    "aria-label": "콘텐츠 추가 방법",
    fill: "solid",
    priority: "primary",
    size: "medium",
  }}
  items={[
    {
      id: "write",
      icon: <span aria-hidden="true">✎</span>,
      "aria-label": "새 글 작성",
      fill: "solid",
      priority: "secondary",
      size: "small",
      onClick: () => console.info("새 글 작성"),
    },
  ]}
/>

Root 하나에 Trigger 하나와 Menu.List 하나를 두고 그 안에 Menu.Item을 조립한다. 이 부품들은 Root 밖에서 사용하면 오류를 발생시킨다. Menu.Item의 aria-label은 행동 이름과 Tooltip 문구이며 persistentTooltips로 열린 메뉴의 문구를 계속 표시할 수 있다. 항목은 native onClick을 실행한 뒤 닫고 trigger로 focus를 돌려준다. 소비자가 event.preventDefault()를 호출하면 이 자동 처리를 막는다. Fab.Menu.Label은 기존 Tooltip.Text를 재사용하는 메뉴명 표현 부품이며 Tooltip의 스타일 문맥에서 사용한다. Speed Dial은 이 조합의 사용 사례 이름이며 별도 namespace가 아니다. Template 항목의 id는 DOM ID로도 쓰이므로 같은 화면에서 고유하게 지정한다. Template의 className, style, ref는 Root 하나에만 적용한다. 내부 버튼의 className은 입력에서 제외하며 런타임 입력도 무시한다. 내부 스타일은 최상위 className 아래 nested selector 또는 data attribute로 조정한다. 직접 조립하는 Trigger·Menu.Item의 className은 유지한다.

Hover로 열린 메뉴의 첫 포인터 클릭은 열림을 유지하고 이후 클릭·Enter·Space는 토글한다. 닫힌 Trigger에서는 모든 방향키로 첫 액션에 진입하며, 열린 메뉴의 반대 방향키는 Trigger에서 멈춘다.

Select와 Dropdown이 함께 사용하는 SelectedValue, toSelectedValueKey, isSameSelectedValue, isSameSelectedValueList, normalizeSingleSelectedValue, normalizeSelectedValuesByMode도 root public entry에서 제공한다.

Slot.Base는 as로 렌더링 요소를 교체하거나, asChild로 단일 React element에 className, style, event handler와 ref를 병합해 wrapper 없이 렌더링한다.

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

<Slot.Base asChild className="card-link">
  <a href="/docs">문서 보기</a>
</Slot.Base>;

asChild에서 anchor/button 같은 element 전용 prop은 child에 둔다.

Styles

CSS consumer는 Foundation 다음에 Primitives를 로드한다.

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

Sass consumer는 public style entry를 사용한다.

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

Storybook의 local Sass setup은 외부 consumer 계약을 대체하지 않는다.

Package-local docs

• docs/CONTEXT-INDEX.md: module별 append-only 작업 이력 routing
• docs/CONTEXT-GUIDELINES.md: 과거 전역 기록과 최신 priority delta
• docs/STORYBOOK.md: Primitives Story routing
• DESIGN-PRIMITIVES-SESSION-GUIDE.md: 작업 세션 입력과 실행 순서

Commands

pnpm format:check
pnpm lint
pnpm typecheck
pnpm check