designbase-wp-library

v0.10.0

Published

a month ago

Reusable CSS/JS kit for WordPress plugins (frontend/admin).

0High
0Medium
0Low

designbasekorea

DesignBase WordPress Library (DEWP)

워드프레스 플러그인 개발을 위한 재사용 가능한 프론트엔드 UI 라이브러리입니다.

DEWP = DesignBase WordPress Library

✨ 특징

🎨 THEME_GUIDE.md v0.1.16 기준 - 최신 디자인 토큰 시스템
🌙 자동 다크모드 - theme.css와 완벽 통합
📱 완전 반응형 - 모바일 우선 설계
♿ 접근성 준수 - WCAG 가이드라인 적용
🔧 TypeScript 지원 - 완전한 타입 정의
🚀 CDN 지원 - unpkg, jsDelivr

📦 설치

NPM

npm install designbase-wp-library

CDN (권장)

<!-- 통합 CDN (테마, 아이콘, 컴포넌트 모두 포함) -->
<link rel="stylesheet" href="https://unpkg.com/designbase-wp-library@latest/dist/css/dewp.min.css">
<script src="https://unpkg.com/designbase-wp-library@latest/dist/js/dewp.min.js"></script>

🚀 빠른 시작

기본 사용법

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>DEWP 라이브러리</title>
  
  <!-- 통합 CDN (테마, 아이콘, 컴포넌트 모두 포함) -->
  <link rel="stylesheet" href="https://unpkg.com/designbase-wp-library@latest/dist/css/dewp.min.css">
</head>
<body>
  <!-- 버튼 -->
  <button class="dewp-button dewp-button--primary">Primary Button</button>
  
  <!-- 카드 -->
  <div class="dewp-card">
    <div class="dewp-card-header">카드 제목</div>
    <div class="dewp-card-body">카드 내용</div>
  </div>
  
  <script src="https://unpkg.com/designbase-wp-library@latest/dist/js/dewp.min.js"></script>
</body>
</html>

🧩 주요 컴포넌트

1. 버튼 (Button)

<!-- 기본 버튼 -->
<button class="dewp-button dewp-button--primary">Primary</button>
<button class="dewp-button dewp-button--secondary">Secondary</button>
<button class="dewp-button dewp-button--tertiary">Tertiary</button>

<!-- 상태별 버튼 -->
<button class="dewp-button dewp-button--success">Success</button>
<button class="dewp-button dewp-button--warning">Warning</button>
<button class="dewp-button dewp-button--danger">Danger</button>

<!-- 크기 변형 -->
<button class="dewp-button dewp-button--primary dewp-button--sm">Small</button>
<button class="dewp-button dewp-button--primary dewp-button--lg">Large</button>

<!-- Outline 스타일 -->
<button class="dewp-button dewp-button--outline-primary">Outline</button>

2. 카드 (Card)

<!-- 기본 카드 -->
<div class="dewp-card">
  <div class="dewp-card-header">카드 제목</div>
  <div class="dewp-card-body">카드 내용입니다.</div>
  <div class="dewp-card-footer">푸터 영역</div>
</div>

<!-- 카드 변형 -->
<div class="dewp-card dewp-card--outlined">Outlined</div>
<div class="dewp-card dewp-card--elevated">Elevated</div>
<div class="dewp-card dewp-card--hover">Hover Effect</div>

3. 모달 (Modal)

// 기본 모달
window.DEWP.showModal({
  title: '모달 제목',
  content: '모달 내용입니다.',
  size: 'md' // sm, md, lg, xl
});

// 확인 모달
window.DEWP.showConfirmModal({
  title: '확인',
  message: '정말 삭제하시겠습니까?',
  confirmText: '삭제',
  cancelText: '취소',
  onConfirm: () => console.log('삭제됨')
});

3-1. 리스트 (List)

<!-- 기본/호버/구분선 리스트 -->
<ul class="dewp-list dewp-list--hover dewp-list--divided" style="max-width:560px;">
  <li class="dewp-list-item">
    <span class="dewp-list-item-icon">📄</span>
    <div>
      <div class="dewp-list-item-title">문서 1</div>
      <div class="dewp-list-item-subtitle">서브 텍스트</div>
    </div>
  </li>
</ul>

<!-- 액션 영역 리스트 -->
<ul class="dewp-list dewp-list--divided" style="max-width:720px;">
  <li class="dewp-list-item">
    <div class="dewp-list-item-content">
      <div class="dewp-list-item-title">회원 가입 요청</div>
      <div class="dewp-list-item-subtitle">신규 요청 · 2분 전</div>
    </div>
    <div class="dewp-list-item-actions">
      <button class="dewp-btn dewp-btn-tertiary dewp-btn-sm">자세히</button>
      <button class="dewp-btn dewp-btn-primary dewp-btn-sm">승인</button>
    </div>
  </li>
</ul>

<!-- 분리형 리스트 -->
<ul class="dewp-list dewp-list--divided dewp-list--split" style="max-width:720px;">
  <li class="dewp-list-item">
    <div class="dewp-list-item-label">사이트 제목</div>
    <div class="dewp-list-item-value">
      <strong>Designbase Library</strong>
      <p class="dewp-list-item-description">워드프레스 상단에 표시될 이름입니다.</p>
    </div>
  </li>
</ul>

4. 토스트 (Toast)

// 타입별 토스트
window.DEWP.showSuccessToast('성공 메시지', 3000);
window.DEWP.showErrorToast('오류 메시지', 3000);
window.DEWP.showWarningToast('경고 메시지', 3000);
window.DEWP.showInfoToast('정보 메시지', 3000);

// 커스텀 토스트
window.DEWP.showToast('메시지', 'success', 3000, 'lg');

5. 드롭다운 (Dropdown)

<div class="dewp-dropdown">
  <button class="dewp-dropdown-toggle">선택하세요</button>
  <div class="dewp-dropdown-menu">
    <div class="dewp-dropdown-item" data-value="1">옵션 1</div>
    <div class="dewp-dropdown-item" data-value="2">옵션 2</div>
  </div>
</div>

<script>
  window.DEWP.autoInitializeDropdowns();
</script>

6. 탭 (Tabs)

<div class="dewp-tabs">
  <button class="dewp-tab-btn active" data-tab="tab1">탭 1</button>
  <button class="dewp-tab-btn" data-tab="tab2">탭 2</button>
</div>

<div class="dewp-tab-content">
  <div class="dewp-tab-pane active" data-tab="tab1">탭 1 내용</div>
  <div class="dewp-tab-pane" data-tab="tab2">탭 2 내용</div>
</div>

<script>
  window.DEWP.initTabs();
</script>

7. 아코디언 (Accordion)

<div class="dewp-accordion">
  <div class="dewp-accordion-item">
    <div class="dewp-accordion-header">
      <span class="dewp-accordion-title">아코디언 제목 1</span>
      <span class="dewp-accordion-icon">▼</span>
    </div>
    <div class="dewp-accordion-content">아코디언 내용 1</div>
  </div>
</div>

<script>
  window.DEWP.initAccordions();
</script>

8. Drawer

<div class="dewp-drawer" id="my-drawer">
  <div class="dewp-drawer-header">
    <h3 class="dewp-drawer-title">Drawer 제목</h3>
    <button class="dewp-drawer-close">×</button>
  </div>
  <div class="dewp-drawer-content">
    Drawer 내용
  </div>
</div>

<script>
  const drawer = window.DEWP.createDrawer({
    target: '#my-drawer',
    overlay: true,
    closeOnEscape: true
  });
  
  window.DEWP.openDrawer(drawer);
</script>

8-1. 캐러셀 (Carousel)

<div class="dewp-carousel dewp-carousel--image" data-dewp-carousel data-carousel-indicators="true">
  <div class="dewp-carousel__viewport">
    <div class="dewp-carousel__track">
      <div class="dewp-carousel__slide">
        <img src="image-1.jpg" alt="첫 번째 슬라이드">
        <div class="dewp-carousel__slide-caption">슬라이드 설명</div>
      </div>
      <div class="dewp-carousel__slide">
        <img src="image-2.jpg" alt="두 번째 슬라이드">
      </div>
    </div>
  </div>
</div>

const carouselEl = document.querySelector('.dewp-carousel');
const carouselId = DEWP.initCarousel(carouselEl, {
  loop: true,
  autoplay: true,
  interval: 4000,
  indicators: true,
});

DEWP.goToCarousel(carouselEl, 1);
DEWP.nextCarousel(carouselEl);
DEWP.prevCarousel(carouselEl);
DEWP.startCarouselAutoplay(carouselEl, 4500);
DEWP.stopCarouselAutoplay(carouselEl);

캐러셀은 활성 슬라이드의 콘텐츠 높이에 맞춰 자동으로 뷰포트 높이를 조절합니다.

8-2. 라이트박스 (Lightbox)

<div class="dewp-lightbox-gallery">
  <button type="button"
          data-dewp-lightbox="gallery-a"
          data-lightbox-src="large-1.jpg"
          data-lightbox-caption="이미지 설명 1">
    <img src="thumb-1.jpg" alt="이미지 1 썸네일">
  </button>
  <button type="button"
          data-dewp-lightbox="gallery-a"
          data-lightbox-src="large-2.jpg"
          data-lightbox-caption="이미지 설명 2">
    <img src="thumb-2.jpg" alt="이미지 2 썸네일">
  </button>
</div>

DEWP.registerLightbox('.dewp-lightbox-gallery', {
  loop: true,
  swipe: true,
  showCaption: true,
});

DEWP.openLightbox('gallery-a', 0);
DEWP.nextLightbox();
DEWP.closeLightbox();

9. 폼 요소 (Forms)

<!-- 입력 필드 -->
<div class="dewp-form-group">
  <label class="dewp-form-label">이름</label>
  <input type="text" class="dewp-form-input" placeholder="이름 입력">
</div>

<!-- 체크박스 -->
<div class="dewp-form-check dewp-form-checkbox">
  <input type="checkbox" class="dewp-form-check-input" id="check1">
  <label class="dewp-form-check-label" for="check1">동의합니다</label>
</div>

<!-- 라디오 버튼 -->
<div class="dewp-form-check dewp-form-radio">
  <input type="radio" class="dewp-form-check-input" name="radio" id="radio1">
  <label class="dewp-form-check-label" for="radio1">옵션 1</label>
</div>

<!-- 토글 스위치 -->
<label class="dewp-toggle-label">
  <input type="checkbox" class="dewp-toggle-input">
  <span class="dewp-toggle-slider"></span>
  <span class="dewp-toggle-text">알림 받기</span>
</label>

10. 테이블 (Table)

<table class="dewp-table">
  <thead>
    <tr>
      <th>제목</th>
      <th>작성자</th>
      <th>날짜</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>게시글 1</td>
      <td>홍길동</td>
      <td>2025-01-01</td>
    </tr>
  </tbody>
</table>

🎨 디자인 시스템

CSS 변수 (THEME_GUIDE.md v0.1.16 기준)

Surface (배경)

--db-surface-base           /* 기본 배경 */
--db-surface-layer-1        /* 1단계 높이 */
--db-surface-layer-2        /* 2단계 높이 */

Text (텍스트)

--db-text-primary           /* 주요 텍스트 */
--db-text-secondary         /* 보조 텍스트 */
--db-text-tertiary          /* 부가 텍스트 */
--db-text-link              /* 링크 텍스트 */
--db-text-inverse-primary   /* 반전 텍스트 */

Border (테두리)

--db-border-base            /* 기본 테두리 */
--db-border-layer-1         /* 1단계 테두리 */
--db-border-layer-2         /* 2단계 테두리 */

Feedback (상태)

--db-feedback-success-fg/bg /* 성공 */
--db-feedback-warning-fg/bg /* 경고 */
--db-feedback-error-fg/bg   /* 에러 */
--db-feedback-info-fg/bg    /* 정보 */

Brand (브랜드)

--db-brand-primary          /* 주요 브랜드 색상 */
--db-brand-secondary        /* 보조 브랜드 색상 */

다크 모드

다크 모드는 자동으로 적용됩니다:

<!-- 다크 모드 활성화 -->
<body data-theme="dark">
  <!-- 모든 컴포넌트가 자동으로 다크 모드로 전환됩니다 -->
</body>

<script>
  // JavaScript로 다크 모드 토글
  const toggleDarkMode = () => {
    const currentTheme = document.body.getAttribute('data-theme');
    const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
    document.body.setAttribute('data-theme', newTheme);
  };
</script>

📱 반응형 브레이크포인트

| 사이즈 | 최소 너비 | |--------|-----------| | xs | 0px | | sm | 576px | | md | 768px | | lg | 992px | | xl | 1200px | | xxl | 1400px |

🔧 개발

빌드

# CSS + JS 빌드
npm run build

# CSS만 빌드
npm run build:css

# JS만 빌드
npm run build:js

개발 모드 (Watch)

# CSS + JS 동시 감시
npm run dev

# CSS만 감시
npm run dev:css

# JS만 감시
npm run dev:js

로컬 테스트

# 1. 빌드
npm run build

# 2. 서버 실행 (프로젝트 루트에서)
python3 -m http.server 8001

# 3. 브라우저에서 접속
# http://localhost:8001/test/local-test.html

📂 빌드 출력

dist/
├── css/
│   └── dewp.min.css        # 압축된 CSS (152.8 kB)
└── js/
    └── dewp.min.js         # 압축된 JavaScript (40.7 kB)

🌐 CDN 링크

unpkg

https://unpkg.com/designbase-wp-library@latest/dist/css/dewp.min.css
https://unpkg.com/designbase-wp-library@latest/dist/js/dewp.min.js

jsDelivr

https://cdn.jsdelivr.net/npm/designbase-wp-library@latest/dist/css/dewp.min.css
https://cdn.jsdelivr.net/npm/designbase-wp-library@latest/dist/js/dewp.min.js

📚 문서

자세한 사용법과 예제는 다음 링크에서 확인하세요:

📖 공식 문서: https://designbasekorea.github.io/designbase-wp-library/
🎨 라이브 데모: https://designbasekorea.github.io/designbase-wp-library/
📦 NPM: https://www.npmjs.com/package/designbase-wp-library

🎯 전체 컴포넌트 목록

Layout

Header
Section
Sidebar
Card
List

Navigation

Tabs
Breadcrumb
Pagination
Dropdown

Forms

Input
Textarea
Select
Checkbox
Radio
Toggle
Stepper
Range Slider

Feedback

Toast
Modal
Notice
Badge
Spinner
Progress
Progress Step
Empty State

Interactive

Accordion
Drawer
Popover
Tooltip

Display

Table
Stat
Chip
Divider

🔄 버전 히스토리

v0.9.3 (최신)

🧱 dewp-list-item-content / actions / label / value 구조를 추가해 리스트 액션/분리형 패턴 지원
📚 문서(docs/dewp-list.html, docs/dewp-modal.html, docs/dewp-popover.html)에 HTML 구조 및 JS 예제 보강
🛠 README를 최신 컴포넌트 사용 예로 갱신

v0.9.2

🎨 THEME_GUIDE.md v0.1.16 기준 전체 변수 시스템 통일
✨ 새로운 변수 시스템 적용 (Surface, Border, Feedback, Interactive, Brand)
🗑️ 하드코딩된 색상 및 수동 다크모드 제거
♿ 접근성 개선

v0.6.0

🎨 THEME_GUIDE.md v0.1.16 기준 전체 변수 시스템 통일
✨ 새로운 변수 시스템 적용 (Surface, Border, Feedback, Interactive, Brand)
🗑️ 하드코딩된 색상 및 수동 다크모드 제거
♿ 접근성 개선

v0.5.6

이전 안정 버전

전체 변경 이력은 CHANGELOG.md를 참조하세요.

🤝 기여

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 라이선스

이 프로젝트는 MIT License를 따릅니다.

📞 지원

이메일: [email protected]
Issues: GitHub Issues

🔗 관련 프로젝트

@designbasekorea/theme - 디자인 토큰 시스템 (통합됨)
@designbasekorea/icons-webfont - 아이콘 시스템 (통합됨)

Made with ❤️ by DesignBase Korea