designbase-wp-library

v0.11.2

Published

15 days 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-btn dewp-btn-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>

🔌 워드프레스 플러그인 전용 권장 사용법

DEWP는 워드프레스 플러그인(관리자/프론트 UI) 에서 사용하는 것을 기본 전제로 설계되어 있습니다.

1) 플러그인에서 자산 enqueue (권장)

<?php
/**
 * Plugin Name: My Plugin
 */

defined('ABSPATH') || exit;

function my_plugin_enqueue_dewp_assets($hook = '') {
    // 예: 특정 admin 페이지에서만 로드하고 싶다면 조건 추가
    // if ($hook !== 'toplevel_page_my-plugin') return;

    wp_enqueue_style(
        'dewp-css',
        'https://unpkg.com/[email protected]/dist/css/dewp.min.css',
        array(),
        '0.11.0'
    );

    wp_enqueue_script(
        'dewp-js',
        'https://unpkg.com/[email protected]/dist/js/dewp.min.js',
        array(),
        '0.11.0',
        true
    );
}

add_action('admin_enqueue_scripts', 'my_plugin_enqueue_dewp_assets');
// 필요 시 프론트에도 사용
// add_action('wp_enqueue_scripts', 'my_plugin_enqueue_dewp_assets');

2) 화면 렌더 후 명시적 초기화

<script>
document.addEventListener('DOMContentLoaded', function () {
  if (window.DEWP && typeof window.DEWP.init === 'function') {
    window.DEWP.init();
  }
});
</script>

3) 📖 공식 사용 가이드 (핵심)

전체 컴포넌트 마크업 예시와 CSS 변수 레퍼런스는 아래 가이드에서 확인하세요.

👉 DEWP 통합 사용 가이드 (DEWP-USAGE-GUIDE.md)

기타 상세 규칙:

docs/DEWP-WP-PLUGIN-PLAYBOOK.md: 워드프레스 플러그인 통합 규칙
docs/DEWP-AI-SPEC.md: AI가 잘못 생성하지 않도록 만든 정규 스펙
docs/dewp-ai-cheatsheet.json: 컴포넌트/API 치트시트(JSON)
docs/DEWP-GLOBAL-USABILITY-GUIDE.md: 글로벌 운영(다국어/RTL/A11y/성능) 가이드

4) JS 효율 사용 패턴

최초 렌더 시 DEWP.init()는 1회만 호출
동적 렌더 영역은 DEWP.init({ root: element })로 부분 초기화
동적으로 추가된 영역은 전체 재초기화 대신 컴포넌트별 API만 호출
- DEWP.autoInitializeDropdowns()
- DEWP.autoInitializeTabs()
- DEWP.autoInitializeAccordions()
- DEWP.autoInitializeDrawers()
- DEWP.autoInitializeCarousels()
- DEWP.autoInitializeLightbox()

🧩 주요 컴포넌트 (요약)

상세한 마크업은 사용 가이드를 참조하세요.

1. 버튼 (Button)

<button class="dewp-btn dewp-btn-primary">Primary</button>
<button class="dewp-btn dewp-btn-outline-primary">Outline</button>
<button class="dewp-btn dewp-btn-primary dewp-btn-s">Small</button>

2. 카드 (Card)

<div class="dewp-card">
  <div class="dewp-card-header">제목</div>
  <div class="dewp-card-body">내용...</div>
</div>

3. 모달 / 토스트 (Feedback)

DEWP.showModal({ title: '제목', content: '내용' });
DEWP.showSuccessToast('완료되었습니다.');

🎨 디자인 시스템

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
🌍 글로벌 사용성 가이드: docs/DEWP-GLOBAL-USABILITY-GUIDE.md
🤖 AI 스펙: docs/DEWP-AI-SPEC.md

🎯 전체 컴포넌트 목록

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.11.0 (최신)

패키지/번들 최신화 및 컴포넌트 문서 업데이트
사용 가이드(워드프레스/AI) 정비

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