@designbasekorea/ui

v0.16.1

Published

9 days ago

Designbase UI 컴포넌트 라이브러리 - 피그마 플러그인에 최적화된 React 컴포넌트

0High
0Medium
0Low

designbasekorea

@designbasekorea/ui

Designbase UI 컴포넌트 라이브러리 - 피그마 플러그인에 최적화된 React 컴포넌트입니다.

npm license

📦 설치

NPM

# UI 컴포넌트 + 필수 의존성
npm install @designbasekorea/ui @designbasekorea/tokens @designbasekorea/theme

Yarn

yarn add @designbasekorea/ui @designbasekorea/tokens @designbasekorea/theme

pnpm

pnpm add @designbasekorea/ui @designbasekorea/tokens @designbasekorea/theme

⚠️ 필수 의존성:

@designbasekorea/tokens - 디자인 토큰
@designbasekorea/theme - 테마 시스템

🚀 빠른 시작

React/Next.js에서

// 1. 토큰 CSS (필수 - 가장 먼저!)
import '@designbasekorea/tokens/dist/css/tokens.css';

// 2. 테마 CSS (필수)
import '@designbasekorea/theme/dist/css/theme.css';

// 3. UI 컴포넌트 import
import { Button, Card, Input, Accordion } from '@designbasekorea/ui';

function App() {
  return (
    <div>
      <Button variant="primary" size="l">
        클릭하세요
      </Button>
      
      <Card title="카드 제목" description="카드 설명입니다.">
        <Input placeholder="이름을 입력하세요" />
      </Card>
      
      <Accordion
        items={[
          { id: 'item-1', title: '제목 1', content: '내용 1' }
        ]}
      />
    </div>
  );
}

export default App;

CDN 사용

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    
    <!-- 1. 토큰 CSS (필수 - 가장 먼저!) -->
    <link rel="stylesheet" href="https://unpkg.com/@designbasekorea/tokens@latest/dist/css/tokens.css">
    
    <!-- 2. 테마 CSS (필수) -->
    <link rel="stylesheet" href="https://unpkg.com/@designbasekorea/theme@latest/dist/css/theme.css">
    
    <title>Designbase UI</title>
</head>
<body>
    <div id="root"></div>
    
    <!-- React & ReactDOM -->
    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
    
    <!-- Designbase UI -->
    <script src="https://unpkg.com/@designbasekorea/ui@latest/dist/index.umd.js"></script>
    
    <script>
        const { Button, Card, Input } = DesignbaseUI;
        
        const App = () => {
            return React.createElement('div', { style: { padding: '20px' } },
                React.createElement(Button, { 
                    variant: 'primary',
                    onClick: () => alert('클릭!')
                }, '클릭하세요'),
                
                React.createElement(Card, null,
                    React.createElement('h2', null, '카드 제목'),
                    React.createElement(Input, { placeholder: '입력하세요' })
                )
            );
        };
        
        ReactDOM.render(React.createElement(App), document.getElementById('root'));
    </script>
</body>
</html>

📚 컴포넌트 목록

Form 컴포넌트

Button - 버튼
Input - 텍스트 입력
Textarea - 여러 줄 텍스트 입력
Checkbox - 체크박스
Radio - 라디오 버튼
Toggle - 토글 스위치
Select - 선택 박스

Layout 컴포넌트

Card - 카드
Modal - 모달
Drawer - 드로어
Tabs - 탭
Accordion - 아코디언
Section - 섹션 (테두리 기본, 접기/펼치기 옵션)
Divider - 구분선

Feedback 컴포넌트

Alert - 알림
Toast - 토스트 알림
Tooltip - 툴팁
Badge - 뱃지
Spinner - 로딩 스피너
Progress - 진행 표시줄
Skeleton - 스켈레톤 로더

Navigation 컴포넌트

Breadcrumb - 브레드크럼
Pagination - 페이지네이션
Dropdown - 드롭다운

Data Display 컴포넌트

Table - 테이블
Chip - 칩
Avatar - 아바타

Date & Time 컴포넌트

Calendar - 캘린더
DatePicker - 날짜 선택기
TimePicker - 시간 선택기

기타

Rating - 별점
Stepper - 단계 표시
Popover - 팝오버
DatePicker - 날짜/기간 선택 (layout="panel" 듀얼 캘린더 + 프리셋)
AnimationBackground - 애니메이션 배경 (그라디언트, 파티클, 별, 눈/꽃/콘페티, 오로라, Lumina 셰이더 + 테마/그리드)
CursorFollower - 데스크탑 전용 커서 팔로워 라벨 (data-cursor-label)
Sidebar - 사이드 네비 (2depth, 하단 고정 메뉴, 커스텀 슬롯)
PageHeader - 페이지 헤더 (default 웹사이트용 / minimal 어드민용)

🎯 컴포넌트 사용 예시

Button

import { Button } from '@designbasekorea/ui';

<Button variant="primary" size="l" onPress={() => console.log('클릭!')}>
  Primary 버튼
</Button>

<Button variant="secondary" size="m" disabled>
  비활성 버튼
</Button>

<Button variant="tertiary" size="s" fullWidth>
  전체 너비 버튼
</Button>

Props:

variant: 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'danger'
size: 's' | 'm' | 'l'
fullWidth: boolean
disabled: boolean
onPress: () => void

Input

import { CloseIcon, SearchIcon } from '@designbasekorea/icons';
import { Input } from '@designbasekorea/ui';

<Input 
  placeholder="이름을 입력하세요"
  value={name}
  onChange={(e) => setName(e.target.value)}
/>

<Input 
  type="email"
  label="이메일"
  error
  errorMessage="올바른 이메일을 입력하세요"
/>

<Input 
  startIcon={SearchIcon}
  endIcon={CloseIcon}
/>

{/* 비밀번호 — 기본: 검증 UI 없음 */}
<Input
  type="password"
  label="비밀번호"
  placeholder="비밀번호를 입력하세요"
/>

{/* 비밀번호 강도 검증 — validate로 명시적으로 활성화 */}
<Input
  type="password"
  label="비밀번호"
  validate
  required
  validationVisibility="focus"
  passwordMinLength={8}
  onValidationChange={(result) => {
    if (result.type === 'password') {
      console.log(result.isValid, result.strength);
    }
  }}
/>

Props:

type: 'text' | 'email' | 'password' | 'number' | ...
label: string
placeholder: string
error: boolean
errorMessage: string
disabled: boolean
startIcon: React.ComponentType
endIcon: React.ComponentType
validate: boolean — 내장 검증 사용 (email 타입 기본 true, password 타입 기본 false)
validationVisibility: 'always' | 'focus' | 'never' — 비밀번호 강도/조건 패널 표시 시점
validateOnBlur: boolean — blur 후에만 에러 메시지 표시 (기본 true)
passwordMinLength: number — 비밀번호 최소 길이 (기본 8)
onValidationChange: 검증 상태 변경 콜백

Section

콘텐츠를 구역별로 나누는 레이아웃 컴포넌트입니다. 테두리(outlined) 스타일이 기본이며, collapsible로 접기/펼치기를 지원합니다.

import { Section } from '@designbasekorea/ui';

{/* 기본 — 테두리 + 헤더 구분선 */}
<Section title="섹션 제목" description="섹션 설명입니다.">
  <p>섹션 내용</p>
</Section>

{/* 헤더 액션 */}
<Section
  title="설정"
  description="변경 사항을 저장하세요."
  actions={<Button variant="primary">저장</Button>}
>
  <FormFields />
</Section>

{/* 접기/펼치기 — 헤더 클릭 또는 chevron으로 토글 */}
<Section
  title="상세 정보"
  description="클릭하여 펼치기"
  collapsible
  defaultExpanded={false}
>
  <DetailContent />
</Section>

{/* 제어형 접기/펼치기 */}
<Section
  title="고급 설정"
  collapsible
  expanded={isOpen}
  onExpandedChange={setIsOpen}
>
  <AdvancedSettings />
</Section>

Props:

title, subtitle, description: 헤더 텍스트
header: 커스텀 헤더 (chevron 포함 클릭 영역)
footer: 푸터 영역 (접기 시 콘텐츠와 함께 숨김)
actions: 헤더 우측 액션 (접기/펼치기와 독립 동작)
size: 's' | 'm' | 'l' | 'xl'
collapsible: boolean — 아코디언 활성화 (기본 false)
defaultExpanded: boolean — 비제어 모드 초기 펼침 (기본 true)
expanded: boolean — 제어 모드 펼침 상태
onExpandedChange: (expanded: boolean) => void
noPadding, fullWidth, fullHeight: 레이아웃 옵션

Breaking Change (v0.10.4):

variant prop 제거 (default / outlined / filled → outlined 스타일만 제공)
type="password" 검증 UI 기본 비활성 — validate prop으로 명시 활성화

DatePicker (Panel / Date Range Picker)

대시보드·분석 화면용 기간 선택 패널 — 왼쪽 프리셋, 2달 캘린더, 하단 입력 + 적용/취소.

import {
  DatePicker,
  DEFAULT_DATE_PICKER_PRESETS,
  createDefaultDatePickerPresets,
} from '@designbasekorea/ui';

<DatePicker
  layout="panel"
  mode="range"
  label="기간"
  value={range}
  onChange={setRange}
  calendarCount={2}
  presets={DEFAULT_DATE_PICKER_PRESETS}
  showPresets
  fullWidth
/>

// 커스텀 프리셋
<DatePicker
  layout="panel"
  presets={createDefaultDatePickerPresets({
    thisWeek: 'This week',
    custom: 'Custom',
  })}
/>

Panel 전용 Props:

layout: 'default' | 'panel' — panel 시 range 선택 UI (mode는 자동으로 range)
calendarCount: 1 | 2 — 표시할 달 수 (panel 기본 2)
presets: DatePickerPreset[] — 왼쪽 빠른 선택 목록
showPresets: boolean — 프리셋 사이드바 표시 (panel 기본 true)

동작 요약:

적용/취소 전까지 임시 값 유지 (onChange는 적용 시 호출)
2단 캘린더는 각 패널에 해당 월 날짜만 렌더 (인접 월 날짜 중복 없음)
하단 날짜는 텍스트로 표시 (input 아님)

프리셋 기본값: 오늘, 어제, 이번 주, 지난주, 이번 달, 지난달, 올해, 작년, 전체 기간, 사용자 지정

AnimationBackground

애니메이션 배경. 그라디언트·캔버스 파티클·Lumina 셰이더(plasma, mesh-flow, fluid, radiant, ethereal) 및 눈/꽃/콘페티를 지원합니다.

import { AnimationBackground } from '@designbasekorea/ui';

// Lumina fluid + 프리셋
<AnimationBackground type="fluid" preset="neon_dream" zoom={1.6} blur={90} />

// 파티클
<AnimationBackground type="snow" particleCount={60} particleSize={3} />
<AnimationBackground type="flowers" wind={0.6} />
<AnimationBackground type="confetti" speed={2000} />

// 오로라 + 그리드
<AnimationBackground
  type="aurora"
  theme="light"
  colors={['#c084fc', '#f472b6', '#38bdf8']}
  intensity="medium"
  showGrid
  gridOpacity={0.12}
/>

CursorFollower

데스크탑(마우스·769px 이상)에서만 동작하는 커서 팔로워 라벨입니다. 기본 커서는 유지되고, 클릭 가능 요소 위에서 pill이 옆을 따라다닙니다.

import { CursorFollower } from '@designbasekorea/ui';

<CursorFollower defaultLabel="See the project" smoothness={0.14}>
  <a href="/work" data-cursor-label="See the project">Portfolio</a>
  <button data-cursor-label="Open contact">Contact</button>
</CursorFollower>

라벨 지정: data-cursor-label 또는 data-cursor 속성
Props: smoothness, offset, selector, hideNativeCursor(기본 false), showIcon

Sidebar

섹션 네비, 2depth 아코디언, 하단 고정 메뉴, 커스텀 슬롯을 지원합니다.

import { Sidebar } from '@designbasekorea/ui';

<Sidebar
  sections={[
    {
      id: 'main',
      title: '일반',
      items: [
        { id: 'dashboard', label: '대시보드', href: '/', icon: PhoneIcon, active: true },
        {
          id: 'users',
          label: '사용자 관리',
          icon: UsersIcon,
          children: [
            { id: 'user-list', label: '사용자 목록', href: '/users' },
            { id: 'roles', label: '권한 관리', href: '/users/roles' },
          ],
        },
      ],
    },
    { id: 'tools', title: '도구', items: [{ id: 'analytics', label: '분석', href: '/analytics', icon: BarChartIcon }] },
  ]}
  navTop={<Button fullWidth size="s">+ 새 프로젝트</Button>}
  bottomItems={[
    { id: 'settings', label: '설정', href: '/settings', icon: SettingsIcon },
    { id: 'support', label: '고객센터', href: '/support', icon: CustomerSupportIcon },
  ]}
  defaultExpandedIds={['users']}
  userProfile={{ name: '김철수', email: '[email protected]' }}
  footerExtra="v2.4.0 · Designbase Admin"
/>

| Prop | 설명 | |------|------| | sections | 섹션 제목 + 메뉴 (title 레이블은 작게 표시) | | children | 2depth 하위 메뉴 (chevron + 아코디언) | | navTop / navBottom | 네비 상·하단 커스텀 영역 | | bottomItems | 푸터 위 고정 메뉴 (설정, 고객센터 등) | | footerExtra | 계정 카드 아래 (버전 표기 등) | | defaultExpandedIds | 초기 펼침 메뉴 ID |

PageHeader

웹사이트용 default와 어드민/대시보드용 minimal variant를 지원합니다.

import { PageHeader, Button } from '@designbasekorea/ui';

// minimal — 타이틀 우측 CTA + 하단 탭
<PageHeader
  variant="minimal"
  title="사용자 관리"
  description="팀 멤버를 초대하고 권한을 관리합니다."
  tabs={[
    { id: 'overview', label: '개요' },
    { id: 'users', label: '사용자' },
    { id: 'billing', label: '결제' },
  ]}
  selectedTabId={activeTab}
  onTabChange={setActiveTab}
  actions={
    <>
      <Button variant="secondary" size="m">보내기</Button>
      <Button variant="primary" size="m">사용자 초대</Button>
    </>
  }
/>

// minimal — 상세 뎁스 (뒤로가기)
<PageHeader
  variant="minimal"
  showBackButton
  title="김철수"
  description="사용자 상세 정보"
  backFallbackHref="/users"
  onBack={() => navigate('/users')}
/>

// default — 웹사이트 랜딩용 (중앙 정렬)
<PageHeader
  title="페이지 타이틀"
  description="설명 텍스트"
  actions={<Button variant="primary">시작하기</Button>}
/>

| Prop | 설명 | |------|------| | variant | 'default' | 'minimal' | | tabs | minimal 하단 좌측 탭 | | actions | minimal: 타이틀 우측 CTA (size="m" 권장) | | showBackButton | minimal 타이틀 좌측 뒤로가기 (tertiary 버튼) | | onBack / backFallbackHref | 뒤로가기 커스텀 / 히스토리 없을 때 이동 경로 | | selectedTabId / onTabChange | 탭 제어 |

Card

import { Card } from '@designbasekorea/ui';

<Card
  title="카드 제목"
  description="카드 내용입니다."
  actions={[
    { label: '취소', variant: 'secondary' },
    { label: '확인', variant: 'primary' }
  ]}
/>

<Card image={{ src: '/image.jpg', alt: '썸네일' }} layout="horizontal">
  <p>커스텀 콘텐츠</p>
</Card>

Modal

import { Button, Modal, ModalBody, ModalFooter } from '@designbasekorea/ui';

function MyComponent() {
  const [isOpen, setIsOpen] = useState(false);
  
  return (
    <>
      <Button onPress={() => setIsOpen(true)}>
        모달 열기
      </Button>
      
      <Modal 
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        title="모달 제목"
      >
        <ModalBody>
          <p>모달 내용입니다.</p>
        </ModalBody>
        <ModalFooter>
          <Button onPress={() => setIsOpen(false)}>닫기</Button>
          <Button variant="primary">확인</Button>
        </ModalFooter>
      </Modal>
    </>
  );
}

Accordion

import { Accordion } from '@designbasekorea/ui';

<Accordion
  items={[
    { id: 'item-1', title: '제목 1', content: '내용 1' }
  ]}
/>

Toast

import { toast } from '@designbasekorea/ui';

// 성공 토스트
toast.success('저장되었습니다!');

// 에러 토스트
toast.error('오류가 발생했습니다.');

// 경고 토스트
toast.warning('주의하세요!');

// 정보 토스트
toast.info('새로운 알림이 있습니다.');

// 커스텀 토스트
toast({
  title: '제목',
  description: '설명',
  duration: 5000,
  variant: 'success'
});

🎨 테마 커스터마이징

CSS 변수 오버라이드

:root {
  /* 버튼 색상 변경 */
  --db-color-primary: #ff6b6b;
  --db-color-primary-hover: #ff5252;
  
  /* 모서리 둥글기 변경 */
  --db-radius-button: 16px;
  --db-radius-card-m: 20px;
  
  /* 간격 변경 */
  --db-padding-m: 20px;
}

컴포넌트별 스타일 오버라이드

/* Button 커스터마이징 */
.db-button {
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

/* Card 커스터마이징 */
.db-card {
  border-width: 2px;
}

📦 Export 형식

| 형식 | 경로 | 설명 | |------|------|------| | ESM | dist/index.esm.js | ES Module (React) | | CJS | dist/index.js | CommonJS | | UMD | dist/index.umd.js | Universal (CDN) | | CSS | dist/index.css | 컴포넌트 스타일 | | Types | dist/index.d.ts | TypeScript 타입 |

🔧 고급 사용법

Tree Shaking

// 개별 import로 번들 크기 최적화
import Button from '@designbasekorea/ui/dist/components/Button';
import Card from '@designbasekorea/ui/dist/components/Card';

TypeScript

import { ButtonProps, CardProps } from '@designbasekorea/ui';

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

접근성 (a11y)

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

키보드 네비게이션 지원
ARIA 속성 포함
스크린 리더 호환
포커스 관리

<Button aria-label="검색">
  <SearchIcon />
</Button>

<Input 
  aria-describedby="email-error"
  aria-invalid={!!error}
/>

🔗 관련 패키지

@designbasekorea/tokens - 디자인 토큰 (필수)
@designbasekorea/theme - 테마 시스템 (필수)
@designbasekorea/icons - 아이콘 컴포넌트
@designbasekorea/icons-webfont - 아이콘 웹폰트

📖 문서 및 예제

Storybook

모든 컴포넌트의 라이브 예제를 확인하세요:

npm run storybook

브라우저에서 http://localhost:6006 접속

온라인 문서

Storybook (배포됨) - 모든 컴포넌트 예제
GitHub Repository - 소스 코드

🔄 버전 히스토리

0.15.0 (Latest)

✅ PageHeader: showBackButton 뒤로가기 + navigatePageHeaderBack export
✅ Dropdown: 닫힌 메뉴 클릭 차단 수정, 커스텀 trigger onPress 연동

0.14.0

✅ PageHeader: variant="minimal" — 타이틀 우측 CTA, 하단 좌측 탭, 컨테이너 패딩·배경

0.13.0

✅ Sidebar: navTop / navBottom / footerExtra 슬롯, bottomItems 하단 고정 메뉴
✅ Sidebar: children 2depth 아코디언 + chevron, 섹션 레이블 축소
✅ AnimationBackground: Lumina 그라데이션 + snow / flowers / confetti
✅ CursorFollower: 데스크탑 커서 팔로워 (data-cursor-label)

0.12.0

✅ AnimationBackground: Lumina 그라데이션 (plasma, mesh-flow, fluid, radiant, ethereal) + preset, zoom, noise
✅ AnimationBackground: 파티클 snow, flowers, confetti + wind
✅ CursorFollower: 데스크탑 커서 팔로워 라벨 (data-cursor-label, 기본 커서 유지)

0.11.0

✅ DatePicker: layout="panel" Panel Date Range Picker (프리셋 + 2달 캘린더 + 적용/취소)
✅ DatePicker: 2단 캘린더 월별 격리, 하단 날짜 텍스트 표시, 프리셋 스타일 정리
✅ DatePicker: DEFAULT_DATE_PICKER_PRESETS, createDefaultDatePickerPresets export

0.10.4

✅ Input: type="password" 검증 UI 기본 비활성 — validate prop으로 명시 활성화
✅ Section: outlined 스타일 기본 적용, variant prop 제거
✅ Section: collapsible / defaultExpanded / expanded / onExpandedChange 접기·펼치기 지원
✅ Section: 접힌 상태에서 헤더 하단 구분선 제거

0.10.3

✅ Toggle: 네이티브 button 기본 스타일(padding, border, background) 제거

0.5.1

✅ AnimationBackground: 레이어 구조(CanvasLayer, CSSGradientLayer, MeshAuroraLayer, GridOverlay)
✅ theme(light/dark), showGrid, gridSize, gridColor, gridOpacity 지원
✅ Light Aurora Mesh / Blueprint 스타일 및 그리드 라인 전 영역 표시
✅ 타입 정리: gradient, pulse, wave, particles, stars, aurora (레인보우·파이어·오션·선셋 제거)

0.5.0

✅ Select 모바일 바텀시트 지원 (useMobileBottomSheet)

0.1.0

✅ 20+ React 컴포넌트 제공
✅ 테마 시스템 통합
✅ TypeScript 지원
✅ 접근성 준수

⚠️ 주의사항

1. CSS 로드 순서

반드시 이 순서대로 CSS를 로드하세요:

// 1. 토큰 (필수 - 가장 먼저!)
import '@designbasekorea/tokens/dist/css/tokens.css';

// 2. 테마 (필수)
import '@designbasekorea/theme/dist/css/theme.css';

// 3. UI 컴포넌트 (자동으로 테마 CSS 포함)
import { Button } from '@designbasekorea/ui';

2. 버전 호환성

| UI | Tokens | Theme | |----|--------|-------| | 0.11.0+ | 0.2.x | 0.2.x |

호환되는 버전을 함께 사용하세요.

3. React 버전

React 19.0.0+ 필요 (peerDependencies)
React DOM 19.0.0+ 필요

🤝 기여

버그 리포트나 기능 제안은 GitHub Issues로 부탁드립니다.

📄 라이선스

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@designbasekorea/ui

📦 설치

NPM

Yarn

pnpm

🚀 빠른 시작

React/Next.js에서

CDN 사용

📚 컴포넌트 목록

Form 컴포넌트

Layout 컴포넌트

Feedback 컴포넌트

Navigation 컴포넌트

Data Display 컴포넌트

Date & Time 컴포넌트

기타

🎯 컴포넌트 사용 예시

Button

Input

Section

DatePicker (Panel / Date Range Picker)

AnimationBackground

CursorFollower

Sidebar

PageHeader

Card

Modal

Accordion

Toast

🎨 테마 커스터마이징

CSS 변수 오버라이드

컴포넌트별 스타일 오버라이드

📦 Export 형식

🔧 고급 사용법

Tree Shaking

TypeScript

접근성 (a11y)

🔗 관련 패키지

📖 문서 및 예제

Storybook

온라인 문서

🔄 버전 히스토리

0.15.0 (Latest)

0.14.0

0.13.0

0.12.0

0.11.0

0.10.4

0.10.3

0.5.1

0.5.0

0.1.0

⚠️ 주의사항

1. CSS 로드 순서

2. 버전 호환성

3. React 버전

🤝 기여

📄 라이선스