Cals 설치 가이드

@vortex/ui-cals는 Cals 제품군을 위한 디자인 시스템입니다. Cals 전용 컴포넌트와 재사용 가능한 Foundation 컴포넌트를 같은 패키지에서 제공합니다.

요구사항

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

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

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

1. 패키지 설치

pnpm add @vortex/ui-cals

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

2. 스타일 import

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

import "@vortex/ui-cals/styles"

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

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

3. 컴포넌트 사용

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

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "@vortex/ui-cals"
 
export default function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>예약 정보</CardTitle>
      </CardHeader>
      <CardContent>
        <p>예약 정보를 확인하고 저장하세요.</p>
        <Button title="저장" />
      </CardContent>
    </Card>
  )
}

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

다크 모드

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

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

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

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

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

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

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

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

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

문제 해결

스타일이 적용되지 않음

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

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

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

다음 단계

• 빠른 시작
• 컴포넌트
• 디자인 토큰
• 디자이너 가이드