Components

Vortex Design System의 모든 컴포넌트를 확인하세요

개요

Vortex는 3가지 제품 테마를 지원하는 포괄적인 컴포넌트 시스템을 제공합니다.

제품별 컴포넌트

• Foundation: 모든 제품의 기반이 되는 기본 컴포넌트
• iCignal: iCignal 제품 전용 테마 컴포넌트
• Cals: Cals 제품 전용 테마 컴포넌트

Foundation 컴포넌트

모든 Vortex 제품의 기반이 되는 핵심 컴포넌트입니다.

Form 컴포넌트

사용자 입력을 받는 폼 관련 컴포넌트입니다.

Display 컴포넌트

정보를 표시하는 디스플레이 컴포넌트입니다.

iCignal 컴포넌트

iCignal 제품 전용 브랜드 컬러와 디자인이 적용된 컴포넌트입니다.

모든 Foundation 컴포넌트가 iCignal 테마로 제공됩니다.

특징

• iCignal 브랜드 컬러 자동 적용
• iCignal Preset을 통한 일관된 디자인
• Foundation 컴포넌트와 동일한 API

Cals 컴포넌트

Cals 제품 전용 브랜드 컬러와 디자인이 적용된 컴포넌트입니다.

모든 Foundation 컴포넌트가 Cals 테마로 제공됩니다.

특징

• Cals 브랜드 컬러 자동 적용
• Cals Preset을 통한 일관된 디자인
• Foundation 컴포넌트와 동일한 API

컴포넌트 추가 방법

CLI로 컴포넌트 추가

# 단일 컴포넌트 추가
npx @vortex/cli add button
 
# 여러 컴포넌트 동시 추가
npx @vortex/cli add button input select
 
# 사용 가능한 컴포넌트 목록 확인
npx @vortex/cli list

수동 설치

패키지를 직접 설치하여 사용할 수도 있습니다:

# Foundation
pnpm add @vortex/ui-foundation
 
# iCignal
pnpm add @vortex/ui-icignal
 
# Cals
pnpm add @vortex/ui-cals

제품 패키지 하나만 선택하세요. Cals/iCignal의 Foundation 의존성은 자동 설치되므로 별도 설치나 import가 필요하지 않습니다. 앱 전역 진입점에서 선택한 제품의 styles를 한 번 import하고 컴포넌트도 같은 제품 패키지에서 가져옵니다. 예를 들어 Cals는 다음과 같습니다.

import "@vortex/ui-cals/styles"

React 19 앱과 Private Registry 접근이 전제이며, 패키지 UI에 Tailwind/PostCSS나 TypeScript 별칭 설정은 필요하지 않습니다. 앱 자체 Tailwind v4 유틸리티는 선택적 앱 빌드 설정을 사용하세요. CLI add의 소스 복사는 별도 흐름으로 Tailwind/경로 설정이 필요할 수 있습니다. 자세한 내용은 설치 가이드를 참고하세요.

컴포넌트 사용 패턴

Foundation 컴포넌트 사용

import { Button, Input, Select } from "@vortex/ui-foundation";
 
export default function MyForm() {
  return (
    <form>
      <Input type="email" placeholder="이메일" />
      <Select>
        <option>옵션 1</option>
        <option>옵션 2</option>
      </Select>
      <Button type="submit">제출</Button>
    </form>
  );
}

iCignal 테마 사용

import "@vortex/ui-icignal/styles"
import { Button } from "@vortex/ui-icignal"
 
export default function IcignalApp() {
  return <Button>저장</Button>
}

Cals 테마 사용

import "@vortex/ui-cals/styles"
import { Button } from "@vortex/ui-cals"
 
export default function CalsApp() {
  return <Button title="저장" />
}

디자인 원칙

Vortex 컴포넌트는 다음 원칙을 따릅니다:

1. 접근성 우선 (Accessibility First)

모든 컴포넌트는 WCAG 2.1 AA 기준을 준수합니다:

• 시맨틱 HTML 사용
• ARIA 속성 자동 적용
• 키보드 네비게이션 완벽 지원
• 스크린 리더 호환성
• 충분한 색상 대비 (4.5:1 이상)

2. 타입 안정성 (Type Safety)

모든 컴포넌트는 TypeScript로 작성되어 완벽한 타입 지원을 제공합니다:

• Props 타입 정의
• 제네릭 타입 지원
• 자동 완성 지원
• 컴파일 타임 에러 검출

3. 컴포지션 (Composition)

Radix UI Slot을 통한 유연한 컴포지션 지원:

// Button 스타일을 Link에 적용
<Button asChild>
  <Link href="/dashboard">대시보드</Link>
</Button>

4. 커스터마이징 (Customization)

Tailwind CSS를 통한 쉬운 커스터마이징:

// className으로 스타일 확장
<Button className="w-full bg-gradient-to-r from-purple-500 to-pink-500">
  커스텀 버튼
</Button>

5. 일관성 (Consistency)

모든 컴포넌트는 일관된 API와 명명 규칙을 따릅니다:

• Variants: variant="default" | "secondary" | "destructive" | ...
• Sizes: size="default" | "sm" | "lg" | ...
• States: disabled, loading, error, etc.

성능 최적화

Vortex 컴포넌트는 다음과 같은 성능 최적화가 적용되어 있습니다:

번들 크기 최적화

• Tree-shakeable: 사용하는 컴포넌트만 번들에 포함
• Zero Runtime Overhead: CVA를 통한 컴파일 타임 variant 생성
• Minimal Dependencies: 필수 의존성만 포함

렌더링 최적화

• React.memo: 불필요한 리렌더링 방지
• useCallback/useMemo: 이벤트 핸들러 및 값 메모이제이션
• Code Splitting: 컴포넌트별 lazy loading 지원

품질 보증

모든 Vortex 컴포넌트는 엄격한 품질 기준을 충족합니다:

테스트 커버리지

• ✅ 단위 테스트 (Vitest)
• ✅ 접근성 테스트 (axe-core)
• ✅ E2E 테스트 (Playwright)

문서화

• ✅ MDX 사용 가이드
• ✅ TypeScript 타입 정의
• ✅ 코드 예제

CI/CD

• ✅ 자동 빌드 및 배포
• ✅ 타입 체크
• ✅ Lint 및 Format
• ✅ 자동 버전 관리

다음 단계

지원 및 피드백

문제가 발생하거나 개선 제안이 있으신가요?

• GitLab Issues: vortex/platform/issues 
• Slack: #vortex-design-system