Uponati UI는 일관된 디자인 시스템을 위한 React 컴포넌트 라이브러리입니다. 조직 내 프로젝트에서 통일된 사용자 경험을 제공하기 위해 설계되었습니다.
Uponati UI는 전체 라이브러리를 한 번에 설치하는 대신, 필요한 컴포넌트만 선택적으로 설치하는 방식을 채택했습니다. 이는 다음과 같은 장점이 있습니다:
- 번들 사이즈 최적화: 사용하지 않는 컴포넌트가 번들에 포함되지 않아 앱 크기가 최소화됩니다
- 유연한 사용: 프로젝트에 필요한 컴포넌트만 선택하여 설치할 수 있습니다
- 커스터마이징 용이성: 소스 코드 레벨에서 바로 컴포넌트를 수정할 수 있습니다
- 의존성 관리 간소화: 사용하지 않는 컴포넌트의 의존성을 관리할 필요가 없습니다
# 저장소 클론
git clone [저장소 URL]
cd styleguide
# 의존성 설치
yarn install
# 문서 서버 실행
yarn dev브라우저에서 http://localhost:{PORT} 으로 접속하면 컴포넌트 가이드, 코드 예제 및 디자인 시스템 문서를 확인할 수 있습니다.
-
테마 초기화 필수: 컴포넌트를 사용하기 전에 반드시
npx @uponati/ui init-theme명령을 실행하여 테마를 초기화해야 합니다. 이 과정이 누락되면 컴포넌트 스타일이 제대로 적용되지 않습니다. -
기존 globals.css 파일이 있는 경우: 이미 프로젝트에 globals.css 내부에 @theme가 정의되어 있다면, 먼저 해당 파일을 백업해두세요.
# 기존 파일 백업 mv src/app/globals.css src/app/globals.backup.css # 테마 초기화 실행 npx @uponati/ui init-theme
백업 후 필요한 스타일을 새로 생성된 globals.css에 병합할 수 있습니다.
-
색상 커스터마이징:
globals.css에 추가된 색상 변수는 프로젝트의 디자인 요구사항에 맞게 자유롭게 수정할 수 있습니다. 기본 색상 값을 변경하여 컴포넌트의 전체적인 테마를 조정할 수 있습니다.
# 컴포넌트 설치
npx @uponati/ui add [컴포넌트명]
# 예: Input 컴포넌트 설치
npx @uponati/ui add input
# 여러 컴포넌트 동시 설치
npx @uponati/ui add button card tabs
# 설치 경로 지정 (기본값: src/components/ui)
npx @uponati/ui add input --path src/components/custom
# 테마 설치 (컴포넌트 스타일링을 위해 필요)
npx @uponati/ui init-theme테마는 기본적으로 src/app/globals.css 파일에 추가됩니다. 다른 위치에 설치하려면:
npx @uponati/ui init-theme --path src/styles/globals.css| 컴포넌트 | 설명 | 명령어 |
|---|---|---|
| Alert | 알림 컴포넌트 | npx @uponati/ui add alert |
| Button | 버튼 컴포넌트 | npx @uponati/ui add button |
| Card | 카드 컴포넌트 | npx @uponati/ui add card |
| Input | 입력 컴포넌트 | npx @uponati/ui add input |
| LinkButton | 링크 버튼 컴포넌트 | npx @uponati/ui add linkbutton |
| Tabs | 탭 컴포넌트 | npx @uponati/ui add tabs |
Uponati UI는 Tailwind CSS 4의 테마 시스템을 사용합니다. 테마를 설정하고 관리하는 방법은 다음과 같습니다:
# 테마 설치 (컴포넌트 스타일링을 위해 필요)
npx @uponati/ui init-theme
# 다른 경로에 설치
npx @uponati/ui init-theme --path src/styles/globals.css테마는 기본적으로 src/app/globals.css 파일에 추가됩니다.
다크 모드를 쉽게 관리할 수 있는 React 컨텍스트와 훅을 추가할 수 있습니다:
# 테마 컨텍스트 및 useTheme 훅 설치
npx @uponati/ui useTheme
# 다른 경로에 설치
npx @uponati/ui useTheme --path src/contexts이 명령어는 ThemeContext.tsx 파일을 src/context 디렉토리에 추가합니다. 이 파일에는 테마 상태 관리를 위한 컨텍스트 프로바이더와 useTheme 훅이 포함되어 있습니다.
useTheme 훅은 다음과 같은 값을 제공합니다:
-
theme: 현재 테마 상태 ('light' 또는 'dark') -
toggleTheme: 라이트/다크 모드를 전환하는 함수
설치가 완료되면 다음과 같이 사용할 수 있습니다:
import { useTheme } from "@/context/ThemeContext";
function ThemeToggle() {
const { theme, toggleTheme } = useTheme();
return (
<button
onClick={toggleTheme}
className="rounded-md bg-gray-200 px-4 py-2 dark:bg-gray-700"
>
{theme === "dark" ? "라이트 모드로 전환" : "다크 모드로 전환"}
</button>
);
}프로젝트의 루트 레이아웃에 ThemeProvider를 추가하세요:
import { ThemeProvider } from "@/context/ThemeContext";
// layout.tsx 또는 최상위 컴포넌트
export default function RootLayout({ children }) {
return <ThemeProvider>{children}</ThemeProvider>;
}ThemeProvider는 자동으로 다음과 같은 기능을 제공합니다:
- 로컬 스토리지에 테마 설정 저장
- 페이지 로드 시 저장된 테마 복원
- HTML 루트 요소에 'dark' 클래스 자동 추가/제거
Uponati UI를 사용하기 위해서는 다음 의존성이 필요합니다:
# 필수 의존성 설치
npm install tailwind-merge
# 또는
yarn add tailwind-merge또한 프로젝트에 다음 패키지들이 설치되어 있어야 합니다:
- React (18 이상)
- React DOM (18 이상)
- TailwindCSS (4 이상) - 강력히 권장
TailwindCSS 4가 설치되어 있지 않다면:
# Tailwind CSS 4 설치 (최신 버전)
npm install -D tailwindcss@latest중요: Uponati UI는 Tailwind CSS 4의 새로운 테마 시스템(
@theme지시어)을 사용합니다. 이 테마 시스템은npx @uponati/ui init-theme명령어로 설정되며, 컴포넌트 스타일링에 필수적입니다.
Uponati UI는 Tailwind CSS 4의 새로운 다크 모드 시스템을 활용합니다. init-theme 명령으로 생성된 globals.css에는 이미 다크 모드 변형이 정의되어 있습니다:
@custom-variant dark (&:is(.dark *));
@theme {
/* 색상 변수들 */
}
body {
background-color: var(--color-gray-50);
color: var(--color-gray-900);
}
.dark body {
background-color: var(--color-gray-900);
color: var(--color-gray-50);
}다크 모드는 npx @uponati/ui useTheme 명령어로 설치한 ThemeContext를 통해 간편하게 관리할 수 있습니다. 이 컨텍스트는 HTML의 최상위 요소에 dark 클래스를 자동으로 추가/제거하는 기능을 제공합니다:
import { useTheme } from "@/context/ThemeContext";
function ThemeToggle() {
const { theme, toggleTheme } = useTheme();
return (
<button
onClick={toggleTheme}
className="rounded-md bg-gray-200 px-4 py-2 dark:bg-gray-700"
>
{theme === "dark" ? "라이트 모드로 전환" : "다크 모드로 전환"}
</button>
);
}ThemeProvider를 사용하지 않는 경우에는 직접 HTML 요소에 dark 클래스를 추가/제거할 수 있습니다:
// 다크 모드 활성화
document.documentElement.classList.add("dark");
// 다크 모드 비활성화
document.documentElement.classList.remove("dark");다크 모드의 색상을 커스터마이징하려면 globals.css의 .dark body 부분을 수정하세요:
.dark body {
/* 배경 및 텍스트 색상 조정 */
background-color: var(--color-gray-900);
color: var(--color-gray-50);
}
/* 특정 컴포넌트의 다크 모드 스타일 조정 */
.dark .my-component {
background-color: var(--color-primary-900);
border-color: var(--color-primary-700);
}Uponati UI 컴포넌트들은 이미 다크 모드에 최적화되어 있으며, dark: 접두사를 사용한 Tailwind 클래스로 필요한 경우 추가적인 스타일링이 가능합니다.
설치 후 React 컴포넌트에서 다음과 같이 사용할 수 있습니다:
자세한 내용은 상단의 styleguide docs를 참조해주세요.
import Button from "@/components/ui/Button";
import Input from "@/components/ui/Input";
export default function MyForm() {
return (
<div>
<Input placeholder="이메일을 입력하세요" type="email" />
<Button>제출하기</Button>
</div>
);
}- 라이선스: MIT
- 개발자: Uponati Team