Skip to Content
ResourcesFAQ

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/uiVortex UI
기본 컴포넌트✅✅ (Foundation)
제품별 컴포넌트❌✅ (iCignal, Cals)
CLI 도구✅✅ (@vortex/cli)
프로젝트 템플릿❌✅ (init 명령어)
전사 표준❌✅
Private npm❌✅ (Verdaccio)

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

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

설치 및 설정

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

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

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

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

React / React DOM 19 앱과 Vortex Private Registry 접근이 준비되어 있다면 사용할 제품 패키지 하나를 설치하세요. Foundation 예시는 다음과 같습니다.

pnpm add @vortex/ui-foundation

앱 전역 진입점에서 스타일을 한 번 import하고 같은 패키지의 컴포넌트를 사용합니다.

import "@vortex/ui-foundation/styles"
import { Button } from "@vortex/ui-foundation"

Cals/iCignal은 해당 제품 패키지와 styles를 사용하며 Foundation은 자동 설치되므로 별도 설치나 import가 필요하지 않습니다. UI CSS가 컴파일되어 제공되므로 Tailwind/PostCSS, preset, TypeScript 별칭 설정은 필수가 아닙니다. 앱 자체 Tailwind v4 유틸리티를 작성할 때만 앱의 Tailwind 빌드와 선택적 제품 tailwind-config를 구성하세요. 자세한 내용은 설치 가이드를 참고하세요.

CLI add는 소스 복사 방식이라 별도의 Tailwind/경로 설정이 필요할 수 있습니다. 컴포넌트별 Provider 요구사항도 해당 문서를 따르세요.

TypeScript 없이 사용할 수 있나요?

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

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

컴포넌트

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

Foundation (기본):

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

iCignal (분석):

  • DataTable, Switch, Slider
  • DatePicker, ComboBox

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를 사용해야 하나요?

아니요. 배포 패키지는 UI 유틸리티, 토큰, 폰트, 다크 모드 스타일이 포함된 컴파일된 CSS를 제공합니다. 해당 제품의 styles만 import하면 되며 Tailwind/PostCSS는 패키지 내부 빌드에서 처리합니다.

앱에서 Tailwind 유틸리티를 직접 작성하는 경우에만 앱의 Tailwind v4 빌드와 선택적 제품 tailwind-config를 사용하세요. styles import는 계속 유지합니다. CLI 소스 복사 방식의 빌드 요구사항과는 구분해야 합니다.

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

네. 앱은 일반 CSS, CSS Modules, CSS-in-JS 등 원하는 스타일링 방식을 사용할 수 있습니다. Vortex UI 패키지 때문에 Tailwind를 함께 설치할 필요는 없습니다.

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

패키지 styles 다음에 앱 CSS를 로드하고 필요한 토큰만 재정의하세요. 다음 값은 사용자 지정 예시입니다.

:root {
  --background: #ffffff;
  --foreground: #111827;
  --primary: #2563eb;
}

기본 스타일 사용에는 이 재정의도 필요하지 않습니다. 설치와 선택적 Tailwind 통합은 설치 가이드를 참고하세요.

개발 도구

@vortex/cli는 무엇인가요?

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

주요 기능:

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

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();
});

도구:

배포

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” 에러가 발생해요

패키지 import 방식이라면 제품 패키지가 설치되어 있는지, import 경로가 같은 제품을 가리키는지, Private Registry에 접근할 수 있는지 확인하세요. 배포 패키지 사용에는 앱의 @/ 경로 별칭이 필요하지 않습니다.

CLI add로 소스를 복사한 경우에만 복사된 파일과 앱의 경로 별칭/의존성을 CLI 가이드에 따라 확인하세요.

스타일이 적용되지 않아요

  1. 선택한 제품의 styles가 앱의 전역 진입점에서 로드되는지 확인하세요. Cals라면 import "@vortex/ui-cals/styles"를 사용합니다.
  2. Cals/iCignal의 경우 Foundation이나 다른 제품의 스타일을 중복 import하지 않았는지 확인하세요.
  3. 앱 CSS가 패키지 토큰이나 스타일을 덮어쓰는지 확인하세요.
  4. UI가 아니라 직접 작성한 Tailwind 클래스만 빠진 경우, 선택적 앱 Tailwind v4 빌드와 제품 tailwind-config를 확인하세요. 패키지 자체에 Tailwind 설정을 추가할 필요는 없습니다.

TypeScript 에러가 발생해요

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

일반적인 문제:

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

기여

버그를 발견했어요

  1. Issue 생성

  2. 재현 단계 포함

    • 환경 정보 (OS, Browser, Version)
    • 코드 예제
    • 스크린샷

  3. PR 생성 (선택)

새로운 기능을 제안하고 싶어요

  1. Discussion 시작

    • 아이디어 공유 및 피드백 수집

  2. Feature Request Issue

    • 구체적인 사용 사례 설명
    • 디자인 제안 (mockup)

  3. 구현 및 PR

지원

도움이 필요해요

커뮤니티:

  • GitLab Issues: 버그 리포트
  • Discussions: 질문, 아이디어
  • Slack: 실시간 채팅 (내부 팀)

문서:

상용 지원이 있나요?

내부 팀을 위한 지원:

다음 단계

Installation

설치 가이드

Components

컴포넌트 문서

Contributing

기여 가이드

Support

지원 채널

Last updated on
CustomizationMigration Guide