Uponati UI

Uponati UI는 일관된 디자인 시스템을 위한 React 컴포넌트 라이브러리입니다. 조직 내 프로젝트에서 통일된 사용자 경험을 제공하기 위해 설계되었습니다.

Uponati UI는 전체 라이브러리를 한 번에 설치하는 대신, 필요한 컴포넌트만 선택적으로 설치하는 방식을 채택했습니다. 이는 다음과 같은 장점이 있습니다:

• 번들 사이즈 최적화: 사용하지 않는 컴포넌트가 번들에 포함되지 않아 앱 크기가 최소화됩니다
• 유연한 사용: 프로젝트에 필요한 컴포넌트만 선택하여 설치할 수 있습니다
• 커스터마이징 용이성: 소스 코드 레벨에서 바로 컴포넌트를 수정할 수 있습니다
• 의존성 관리 간소화: 사용하지 않는 컴포넌트의 의존성을 관리할 필요가 없습니다

styleguide docs 확인하기

# 저장소 클론
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를 사용하기 위해서는 다음 의존성이 필요합니다:

# 필수 의존성 설치
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);
}

다크 모드 활성화하기

다크 모드를 활성화하려면 HTML의 최상위 요소에 dark 클래스를 추가하세요:

// 다크 모드 토글 구현 예시
import { useState, useEffect } from "react";

function ThemeToggle() {
  const [isDark, setIsDark] = useState(false);

  useEffect(() => {
    // 초기 테마 상태 설정
    const isDarkMode = document.documentElement.classList.contains("dark");
    setIsDark(isDarkMode);
  }, []);

  function toggleTheme() {
    const newDarkMode = !isDark;
    setIsDark(newDarkMode);

    // HTML 요소에 dark 클래스 토글
    if (newDarkMode) {
      document.documentElement.classList.add("dark");
      localStorage.setItem("theme", "dark");
    } else {
      document.documentElement.classList.remove("dark");
      localStorage.setItem("theme", "light");
    }
  }

  return (
    <button
      onClick={toggleTheme}
      className="rounded-md bg-gray-200 px-4 py-2 dark:bg-gray-700"
    >
      {isDark ? "라이트 모드로 전환" : "다크 모드로 전환"}
    </button>
  );
}

시스템 설정 기반 다크 모드

사용자의 시스템 설정에 따라 자동으로, 다크 모드를 활성화하려면 다음 스크립트를 _app.jsx 또는 layout.js에 추가하세요:

// 페이지 로드 시 다크 모드 설정
useEffect(() => {
  // localStorage에 저장된 테마가 있는지 확인
  const savedTheme = localStorage.getItem("theme");

  if (savedTheme === "dark") {
    document.documentElement.classList.add("dark");
  } else if (savedTheme === "light") {
    document.documentElement.classList.remove("dark");
  } else {
    // 시스템 설정 확인
    const prefersDark = window.matchMedia(
      "(prefers-color-scheme: dark)",
    ).matches;
    if (prefersDark) {
      document.documentElement.classList.add("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