@une-front/react-ui

UNE 디자인 시스템 기반의 React UI 컴포넌트 라이브러리입니다.

설치

npm install @une-front/react-ui @une-front/design-tokens

설정

CSS 진입점에서 디자인 토큰을 import 합니다:

@import "tailwindcss";
@import "@une-front/design-tokens";
@import "@une-front/react-ui/css";

html font-size 설정 (필수)

컴포넌트 내부 수치는 모두 rem 단위로 작성되어 있습니다. 호스트 프로젝트가 html의 font-size를 반드시 설정해야 합니다.

1. 고정 픽셀 (권장, 대부분 프로젝트)

html {
  font-size: 1px; /* 1rem = 1px, 컴포넌트 값이 px과 1:1 매핑 */
}
body {
  font-size: 16rem; /* 기본 텍스트 16px */
}

2. 뷰포트 반응형 (UI 전체 배율을 뷰포트에 맞게 조정)

@media (max-width: 1780px) {
  html { font-size: 0.0561797752808989vw; }
}

이 경우 뷰포트가 줄면 모든 컴포넌트가 비례해서 작아집니다.

3. 브라우저 기본값(16px) 유지 — 비권장 컴포넌트 값이 16배로 확대되어 의도와 다르게 보입니다. 접근성을 위해 사용자 폰트 설정을 존중하려면 별도 래퍼/스케일 전략을 추가 구현해야 합니다.

⚠️ 라이브러리는 html { font-size }를 직접 설정하지 않습니다. 호스트 프로젝트의 반응형/접근성 전략을 침해하지 않기 위함입니다.

흔한 함정: :root가 html을 덮는 경우

html { font-size: 1px }을 설정했어도 같은 CSS 파일 내의 :root 선언이 이를 덮을 수 있습니다.

html { font-size: 1px; }

:root {
  font: 16px/1.5 var(--sans);  /* ← 이게 위의 html 규칙을 덮어씀 */
}

:root(specificity 0,0,1,0)는 html(0,0,0,1)보다 우선합니다. 결과적으로 1rem = 16px이 되어 모든 컴포넌트가 16배 확대되어 렌더됩니다.

해결 방법

• :root의 font 단축 속성을 분해해 font-size 부분만 제거합니다.
• line-height, font-family는 body로 이동합니다.

html { font-size: 1px; }

:root {
  --sans: system-ui, sans-serif;
  color: var(--text);
}

body {
  font-family: var(--sans);
  line-height: 1.5;
  font-size: 16rem;
}

개발 환경에서는 라이브러리가 html의 computed font-size를 측정해 예상 범위(≈0.5px~2px)를 벗어나면 console.warn으로 한 번 경고합니다. 프로덕션 빌드에서는 이 검사 코드가 제거됩니다.

컴포넌트

Button

import { Button } from "@une-front/react-ui";

<Button>클릭</Button>

SegmentedControl

import { SegmentedControl } from "@une-front/react-ui";

const [value, setValue] = useState("day");

<SegmentedControl
  value={value}
  setValue={setValue}
  options={[
    { value: "day", label: "일" },
    { value: "month", label: "월" },
    { value: "year", label: "년" },
  ]}
  size="md"
  variant="button"
  color="primary"
/>

Switch

import { Switch } from "@une-front/react-ui";

const [checked, setChecked] = useState(false);

<Switch value={checked} setValue={setChecked} />

Tab

import { Tabs, TabList, TabButton, TabPanel } from "@une-front/react-ui";

const [tab, setTab] = useState("home");

<Tabs value={tab} setValue={setTab}>
  <TabList>
    <TabButton value="home" label="홈" />
    <TabButton value="profile" label="프로필" />
    <TabButton value="settings" label="설정" />
  </TabList>

  <TabPanel value="home">홈 컨텐츠</TabPanel>
  <TabPanel value="profile">프로필 컨텐츠</TabPanel>
  <TabPanel value="settings">설정 컨텐츠</TabPanel>
</Tabs>

마이그레이션 (Claude Code 플러그인)

기존 프로젝트를 @une-front/react-ui로 점진적 마이그레이션할 때 사용하는 Claude Code 슬래시 커맨드입니다.

설치

Claude Code에서:

/plugin marketplace add unecorp/designsystem
/plugin install migrate-une-front@une-front-designsystem
/reload-plugins

사용

마이그레이션할 프로젝트를 열고 다음을 실행:

/migrate-une-front:migrate

이 커맨드는 자동으로 단계를 판정하여 한 번에 하나씩 진행합니다:

1. 스캔 — 교체 가능한 컴포넌트를 찾아 migration/scan-result.md에 저장
2. 계획 — 교체 순서를 정해 migration/plan.md에 저장
3. 교체 — 파일을 하나씩 교체하고 체크박스 업데이트
4. 정리 — 불필요해진 UI 라이브러리 의존성 제거 안내

대화가 끊겨도 같은 커맨드를 다시 실행하면 migration/ 폴더의 체크박스를 보고 이어서 진행합니다.

승인 게이트를 모두 건너뛰고 단계 4까지 한 번에 완료하려면 force 플래그를 씁니다 — 호스트 파일과 package.json이 연쇄적으로 바뀌므로 커밋되지 않은 변경이 있을 때는 실행하지 마세요.

/migrate-une-front:migrate force

Peer Dependencies

• react ^18 || ^19
• react-dom ^18 || ^19

라이선스

ISC