Skip to Content
Getting StartediCignal 설치 가이드

iCignal 설치 가이드

@vortex/ui-icignal은 iCignal 제품군을 위한 디자인 시스템입니다. Foundation 컴포넌트와 iCignal 전용 컴포넌트를 단일 패키지에서 제공합니다.

요구사항

  • React / React DOM 19 앱
  • Node.js 20 이상, pnpm 9+ 권장
  • Vortex Private Registry 접근 및 필요한 인증

레지스트리가 아직 등록되지 않았다면 다음 명령을 한 번 실행하세요.

npm config set @vortex:registry http://repo.calsplatz.com:4873

1. 패키지 설치

pnpm add @vortex/ui-icignal

Foundation은 내부 의존성으로 자동 설치됩니다. @vortex/ui-foundation을 따로 설치할 필요가 없습니다.

2. 스타일 import

앱 진입점 또는 프레임워크의 전역 CSS 진입점에 한 번 추가하세요.

import "@vortex/ui-icignal/styles"

이 CSS에는 UI에 필요한 유틸리티, Foundation 기본 스타일, iCignal 디자인 토큰, 폰트, 다크 모드 스타일이 포함되어 있습니다. Foundation 스타일을 별도로 import하지 마세요.

패키지 컴포넌트 사용에는 Tailwind/PostCSS 설치, preset, content/@source 설정, TypeScript 경로 별칭이 필요하지 않습니다. Tailwind/PostCSS는 UI 패키지 내부 빌드에서 처리합니다.

3. 컴포넌트 사용

Button과 Card를 포함한 컴포넌트는 모두 @vortex/ui-icignal에서 import하세요.

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "@vortex/ui-icignal"
 
export default function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>분석 대시보드</CardTitle>
      </CardHeader>
      <CardContent>
        <p>분석 결과를 확인하세요.</p>
        <Button>새로고침</Button>
      </CardContent>
    </Card>
  )
}

컴포넌트별 props와 필요한 Provider/라우터/데이터 설정은 각 컴포넌트 문서를 확인하세요. 위 설치 흐름은 스타일 빌드 설정을 없애는 것이며 기능별 실행 환경을 대체하지 않습니다.

다크 모드

상위 요소(예: html)에 dark 클래스를 적용하면 포함된 다크 모드 토큰과 스타일이 사용됩니다. 테마 전환과 선택값 저장은 앱에서 처리하세요.

선택 사항: 앱 자체 Tailwind CSS v4 유틸리티

앱 화면에서 Tailwind 유틸리티를 직접 작성할 때만 앱의 Tailwind v4 환경을 구성하세요. 앱의 Tailwind CSS 진입점에서 다음 설정을 사용할 수 있습니다.

@import "tailwindcss";
@import "@vortex/ui-icignal/tailwind-config";

이 설정은 필수가 아니며 @vortex/ui-icignal/styles import를 대신하지 않습니다. Foundation의 tailwind-config를 별도로 import할 필요도 없습니다. 패키지 CSS는 UI에 필요한 유틸리티를 포함하지만 앱에서 임의로 작성하는 모든 Tailwind 클래스를 생성하지는 않습니다.

별도 흐름: CLI 템플릿과 소스 복사

새 앱을 만들 때는 CLI 템플릿을 사용할 수 있습니다.

npx @vortex/cli init my-icignal-app --template vite-icignal
cd my-icignal-app
pnpm install
pnpm dev

템플릿의 앱 개발 설정은 위 패키지 설치의 필수 조건이 아닙니다. npx @vortex/cli add로 컴포넌트 소스를 복사하는 경우에는 복사한 소스의 Tailwind 빌드, 경로 별칭, 의존성이 필요할 수 있으므로 CLI 가이드를 따르세요.

문제 해결

스타일이 적용되지 않음

@vortex/ui-icignal/styles가 전역 진입점에서 로드되는지 확인하세요. Foundation 스타일이나 다른 제품의 스타일을 추가하는 대신 iCignal 스타일 하나를 사용하세요. UI 자체에 Tailwind preset이나 Vite/PostCSS 플러그인을 추가할 필요는 없습니다.

앱의 Tailwind 클래스만 적용되지 않음

앱에서 직접 작성한 유틸리티는 앱의 Tailwind v4 빌드 대상입니다. 위 선택 사항을 확인하고, 컴포넌트 CSS용 styles import도 유지하세요.

다음 단계

Cals 설치 가이드Introduction