FAQ

자주 묻는 질문

개요

Vortex UI에 대해 자주 묻는 질문과 답변을 모았습니다.

시작하기

Vortex UI는 무엇인가요?

Vortex UI는 전사 표준 프론트엔드 개발 플랫폼입니다. React 19, TypeScript 5, Tailwind CSS 4.0 기반의 컴포넌트 라이브러리와 개발 도구를 제공합니다.

주요 특징:

✅ shadcn/ui 기반 Foundation 컴포넌트
✅ iCignal/Cals 전용 컴포넌트
✅ CLI를 통한 간편한 설치
✅ 접근성 준수 (WCAG 2.1 AA)
✅ Dark mode 지원

shadcn/ui와 무엇이 다른가요?

Vortex UI는 shadcn/ui를 기반으로 하지만 다음과 같은 차별점이 있습니다:

특징	shadcn/ui	Vortex UI
기본 컴포넌트	✅	✅ (Foundation)
제품별 컴포넌트	❌	✅ (iCignal, Cals)
CLI 도구	✅	✅ (@vortex/cli)
프로젝트 템플릿	❌	✅ (init 명령어)
전사 표준	❌	✅
Private npm	❌	✅ (Verdaccio)

Vortex UI를 사용해야 하는 이유는?

전사 표준: 모든 프로젝트가 일관된 디자인과 코드 스타일 유지
생산성: CLI를 통한 빠른 프로젝트 생성 및 컴포넌트 추가
접근성: 모든 컴포넌트가 WCAG 2.1 AA 준수
제품별 최적화: iCignal, Cals 전용 컴포넌트 제공
검증된 품질: 테스트, Storybook, 문서 완비

설치 및 설정

새 프로젝트를 어떻게 시작하나요?


# 1. 프로젝트 생성
npx @vortex/cli init my-project --template vite-react
 
# 2. 프로젝트 디렉토리 이동
cd my-project
 
# 3. 개발 서버 실행
pnpm dev

자세한 내용은 Installation Guide를 참고하세요.

기존 프로젝트에 Vortex UI를 추가할 수 있나요?

네, 가능합니다!


# 1. 의존성 추가
pnpm add @vortex/ui
 
# 2. Tailwind CSS 설정
# tailwind.config.js에 Vortex UI 프리셋 추가
 
# 3. 컴포넌트 사용
import { Button } from "@vortex/ui"

주의: React 19, Tailwind CSS 4.0이 필요합니다.

TypeScript 없이 사용할 수 있나요?

JavaScript로도 사용 가능하지만 TypeScript 사용을 강력히 권장합니다:

✅ IntelliSense 자동완성
✅ 타입 안전성
✅ 에러 조기 발견
✅ 더 나은 개발 경험

컴포넌트

어떤 컴포넌트가 제공되나요?

Foundation (기본):

Button, Input, Select, Card, Table
Checkbox, Radio, Switch, Textarea
Tabs, Avatar, Breadcrumb
Dialog, Alert, Toast

iCignal (분석):

AnalyticsCard, MetricsDisplay
TrendIndicator, ChartContainer

Cals (예약):

BookingCard, ScheduleCard
CalendarView, TimeSlotPicker

전체 목록은 Components를 참고하세요.

컴포넌트를 어떻게 추가하나요?


# CLI 사용 (권장)
npx @vortex/cli add button
 
# 여러 컴포넌트 동시 추가
npx @vortex/cli add button input card

CLI가 자동으로:

컴포넌트 파일 복사
의존성 설치
TypeScript 설정 업데이트

컴포넌트를 커스터마이징할 수 있나요?

네! Vortex UI는 소스 코드를 직접 제공합니다.


# 컴포넌트는 프로젝트의 src/components/ui/ 에 복사됨
my-project/
└─ src/
   └─ components/
      └─ ui/
         └─ button.tsx  # 직접 수정 가능!

장점:

✅ 완전한 제어권
✅ 버전 충돌 없음
✅ 커스텀 수정 자유

주의: 업데이트 시 수동 병합 필요

Dark mode를 지원하나요?

네! 모든 컴포넌트가 Dark mode를 지원합니다.


// app/layout.tsx
<html className={theme === "dark" ? "dark" : ""}>
  <body>{children}</body>
</html>

CSS 변수로 테마 커스터마이징:


:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
}
 
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

스타일링

Tailwind CSS를 사용해야 하나요?

네, Vortex UI는 Tailwind CSS 4.0에 의존합니다.

이유:

✅ 유틸리티 기반 스타일링
✅ 빠른 개발 속도
✅ 작은 번들 사이즈
✅ Dark mode 내장
✅ 반응형 디자인

CSS Modules나 Styled Components를 사용할 수 있나요?

Tailwind CSS와 함께 사용 가능하지만 권장하지 않습니다:

Tailwind CSS 권장 이유:

Vortex UI가 Tailwind에 최적화됨
일관된 디자인 시스템
더 작은 번들 사이즈
더 빠른 개발 속도

글로벌 스타일을 어떻게 변경하나요?


/* src/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    /* ... */
  }
}

자세한 내용은 Customization Guide를 참고하세요.

개발 도구

@vortex/cli는 무엇인가요?

Vortex CLI는 프로젝트 생성 및 컴포넌트 추가를 자동화하는 도구입니다.

주요 기능:


# 프로젝트 생성
npx @vortex/cli init my-project
 
# 컴포넌트 추가
npx @vortex/cli add button
 
# 컴포넌트 업데이트
npx @vortex/cli update button

Storybook은 어떻게 사용하나요?

Storybook에서 모든 컴포넌트를 확인할 수 있습니다:

🔗 https://storybook.vortex.dev

✅ 모든 variants 확인
✅ 인터랙티브 Controls
✅ 코드 예제
✅ 사용 가이드

VSCode 확장은 무엇을 설치해야 하나요?

필수:

ESLint
Prettier
Tailwind CSS IntelliSense

권장:

TypeScript Import Sorter
Path Intellisense
GitLens

성능

번들 사이즈는 얼마나 되나요?

Foundation 컴포넌트:

Button: ~2KB (gzipped)
Input: ~3KB (gzipped)
Select: ~8KB (gzipped with Radix UI)
전체: ~50KB (모든 Foundation 컴포넌트)

최적화 팁:

Tree-shaking 자동 지원
사용하는 컴포넌트만 번들링됨
Dynamic import로 코드 스플리팅

성능을 최적화하려면?


// 1. Dynamic Import
const HeavyComponent = dynamic(() => import("./HeavyComponent"));
 
// 2. Lazy Loading
const LazyComponent = lazy(() => import("./LazyComponent"));
 
// 3. Memoization
const MemoizedComponent = memo(Component);
 
// 4. Virtual Scrolling (큰 리스트)
import { useVirtualizer } from "@tanstack/react-virtual";

자세한 내용은 Performance Guide를 참고하세요.

접근성

WCAG 준수 수준은?

모든 컴포넌트가 WCAG 2.1 AA 준수:

✅ 키보드 네비게이션
✅ 스크린 리더 지원
✅ 적절한 ARIA 속성
✅ 색상 대비 충족
✅ Focus 관리

접근성 테스트는 어떻게 하나요?


// jest-axe 사용
import { axe } from "jest-axe";
 
it("has no accessibility violations", async () => {
  const { container } = render(<Component />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

도구:

axe DevTools (Chrome Extension)
Lighthouse
WAVE

배포

Vercel에 배포할 수 있나요?

네! Vortex UI는 모든 호스팅 플랫폼에서 작동합니다:

✅ Vercel
✅ Netlify
✅ AWS (S3, CloudFront)
✅ 자체 서버


# 프로덕션 빌드
pnpm build
 
# 빌드 결과물: dist/ 또는 .next/

환경 변수는 어떻게 설정하나요?


# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=GA-XXXXXXXXX


// 사용
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

주의: NEXT_PUBLIC_ 접두사 필수 (클라이언트 노출)

문제 해결

”Module not found” 에러가 발생해요

원인 1: 컴포넌트 미설치


npx @vortex/cli add button

원인 2: Path alias 미설정


// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

스타일이 적용되지 않아요

체크리스트:

✅ globals.css import 확인


// app/layout.tsx
import "@/globals.css";

✅ Tailwind 설정 확인


// tailwind.config.js
module.exports = {
  content: ["./src/**/*.{ts,tsx}"],
};

✅ CSS 변수 확인


/* globals.css */
@layer base {
  :root {
    --background: 0 0% 100%;
  }
}

TypeScript 에러가 발생해요


# 타입 체크
pnpm type-check
 
# 자동 수정
pnpm lint --fix

일반적인 문제:

의존성 버전 불일치 → pnpm install 재실행
타입 정의 누락 → @types/* 패키지 설치

기여

버그를 발견했어요

Issue 생성
- GitLab Issues: repo.calsplatz.com/vortex/platform
- Bug template 사용
재현 단계 포함
- 환경 정보 (OS, Browser, Version)
- 코드 예제
- 스크린샷
PR 생성 (선택)
- Contributing Guide 참고