# 📚 Drama Ling 組件庫使用指南

## 🎯 組件庫架構說明

本組件庫採用 **HTML/CSS 即時預覽** 的方式，取代傳統的 Figma 設計工具。

## 📁 目錄結構

```
component-library/
├── index.html                 # 🏠 主頁面（組件總覽）
├── assets/                    # 🎨 共用資源
│   ├── styles/
│   │   ├── base.css          # 基礎樣式
│   │   ├── components.css    # 組件樣式
│   │   └── layout.css        # 布局樣式
│   └── scripts/
│       └── demo.js           # 展示功能腳本
├── components/                # 🧩 組件分類
│   ├── 01-interactive/       # 互動組件
│   ├── 02-input/             # 輸入組件
│   ├── 03-display/           # 展示組件
│   ├── 04-feedback/          # 反饋組件
│   ├── 05-navigation/        # 導航組件
│   └── 06-gamification/      # 遊戲化組件
└── pages/                     # 📄 完整頁面範例
    ├── login-page.html
    ├── dashboard.html
    └── learning-page.html
```

## 🔍 組件分類說明

### 1️⃣ 基礎組件（在 index.html 展示）
- **按鈕 Buttons** - 各種樣式和狀態
- **輸入框 Inputs** - 文字、密碼、搜尋
- **卡片 Cards** - 內容容器
- **警告 Alerts** - 提示訊息

### 2️⃣ 互動組件（01-interactive/）
- **模態框 Modals** - 彈出視窗
- **工具提示 Tooltips** - 懸浮提示
- **下拉選單 Dropdowns** - 選項列表

### 3️⃣ 輸入組件（02-input/）
- **表單 Forms** - 完整表單系統
- **選擇器 Selects** - 下拉選擇
- **開關 Switches** - 切換開關

### 4️⃣ 展示組件（03-display/）
- **表格 Tables** - 數據表格
- **列表 Lists** - 項目列表
- **統計卡片 Stats** - 數據展示

### 5️⃣ 導航組件（05-navigation/）
- **導航列 Navbar** - 頂部導航
- **側邊欄 Sidebar** - 側邊導航
- **分頁 Pagination** - 頁面切換

### 6️⃣ 遊戲化組件（06-gamification/）
- **成就 Achievements** - 成就系統
- **等級 Levels** - 等級進度
- **排行榜 Leaderboard** - 競爭排名

## 💻 使用方式

### 查看組件
1. 打開 `index.html` 查看基礎組件
2. 點擊左側導航進入特定組件頁面
3. 查看預覽效果和代碼示例

### 複製使用
1. 點擊「複製」按鈕獲取 HTML 代碼
2. 引入對應的 CSS 文件
3. 根據需求調整樣式

### 開發新組件
1. 在對應分類目錄創建 HTML 文件
2. 使用統一的展示模板結構
3. 在 index.html 添加導航連結

## 🎨 設計原則

### 一致性
- 統一的顏色系統（使用 CSS 變數）
- 統一的間距系統（8px 基準）
- 統一的圓角大小

### 響應式
- 所有組件支援手機、平板、桌面
- 使用 Flexbox 和 Grid 布局
- 觸控友好的交互區域

### 無障礙
- 語義化 HTML 標籤
- ARIA 屬性支援
- 鍵盤導航支援

## 📝 代碼規範

### HTML 結構
```html
<div class="component-showcase">
  <div class="showcase-preview">
    <!-- 組件預覽 -->
  </div>
  <div class="showcase-code">
    <button class="copy-button">複製</button>
    <pre><code>
      <!-- 可複製的代碼 -->
    </code></pre>
  </div>
</div>
```

### CSS 命名
- BEM 命名法：`block__element--modifier`
- 組件前綴：`dl-` (Drama Ling)
- 狀態類：`.is-active`, `.is-disabled`

### JavaScript
- 原生 JavaScript（無框架依賴）
- 事件委託優化性能
- 模組化組織代碼

## 🚀 快速開始

1. **查看組件庫**
   ```bash
   open docs/02_design/component-library/index.html
   ```

2. **複製基礎樣式**
   ```html
   <link rel="stylesheet" href="path/to/base.css">
   <link rel="stylesheet" href="path/to/components.css">
   ```

3. **使用組件**
   ```html
   <button class="btn btn-primary">開始學習</button>
   ```

## 📊 組件覆蓋率

| 分類 | 已完成 | 總數 | 完成度 |
|------|--------|------|--------|
| 基礎組件 | 8 | 10 | 80% |
| 互動組件 | 3 | 5 | 60% |
| 輸入組件 | 5 | 8 | 62% |
| 展示組件 | 6 | 8 | 75% |
| 導航組件 | 3 | 5 | 60% |
| 遊戲化組件 | 8 | 10 | 80% |
| **總計** | **33** | **46** | **72%** |

## 🔄 更新日誌

### v1.0.0 (2024-09-15)
- 初始版本發布
- 完成基礎組件系統
- 建立統一展示框架

## 📞 聯絡方式

如有問題或建議，請聯繫開發團隊。

---

**最後更新**: 2024-09-15