# 📚 Drama Ling HTML/CSS 元件庫使用指南

**建立日期**: 2025-09-14
**版本**: v1.0
**目的**: 提供完整的元件使用說明和最佳實踐

## 🎯 為什麼選擇 HTML/CSS 元件庫？

### 優勢比較

| 特性 | Figma | HTML/CSS 元件庫 |
|------|-------|----------------|
| **版本控制** | ❌ 需要額外工具 | ✅ Git 原生支援 |
| **即時預覽** | ⚠️ 靜態預覽 | ✅ 瀏覽器實時互動 |
| **代碼複用** | ❌ 需要重新實現 | ✅ 直接複製使用 |
| **團隊協作** | 💰 需要付費授權 | ✅ 免費開源 |
| **修改速度** | ⚠️ 需要導出更新 | ✅ 即時修改生效 |
| **響應式測試** | ⚠️ 有限支援 | ✅ 完整測試 |

## 🚀 快速開始

### 1. 查看元件庫
```bash
# 在瀏覽器中打開
open docs/02_design/component-library/index.html
```

### 2. 複製元件代碼
1. 瀏覽到需要的元件區塊
2. 點擊「複製」按鈕
3. 貼上到你的專案中

### 3. 引入樣式文件
```html
<!-- 在你的 HTML 頭部引入 -->
<link rel="stylesheet" href="path/to/design-tokens.css">
<link rel="stylesheet" href="path/to/base.css">
<link rel="stylesheet" href="path/to/components.css">
```

## 📖 元件分類說明

### 🎯 核心元件 (Core Components)

#### 按鈕 (Buttons)
- **用途**: 觸發操作或導航
- **變體**: primary, secondary, success, danger, text
- **尺寸**: sm, 標準, lg
- **狀態**: normal, hover, active, disabled

```html
<!-- 基礎用法 -->
<button class="btn btn-primary">主要按鈕</button>

<!-- 尺寸變化 -->
<button class="btn btn-primary btn-lg">大按鈕</button>

<!-- 圖標按鈕 -->
<button class="btn btn-icon btn-primary">🎮</button>
```

#### 輸入框 (Input Fields)
- **類型**: text, email, password, textarea
- **狀態**: normal, focus, error, success
- **配件**: label, hint, error message

```html
<!-- 完整輸入組 -->
<div class="input-group">
  <label class="input-label required">電子郵件</label>
  <input type="email" class="input-field" placeholder="example@email.com">
  <span class="input-hint">我們不會分享你的電子郵件</span>
</div>
```

#### 卡片 (Cards)
- **類型**: 基礎卡片, 學習卡片, 成就卡片
- **結構**: header, body, footer
- **互動**: hover效果, 點擊反饋

```html
<!-- 基礎卡片 -->
<div class="card">
  <div class="card-header">
    <h3 class="card-title">標題</h3>
  </div>
  <div class="card-body">內容</div>
  <div class="card-footer">
    <button class="btn btn-primary btn-sm">操作</button>
  </div>
</div>
```

#### 警告 (Alerts)
- **類型**: success, error, warning, info
- **功能**: 可關閉, 自動消失
- **動畫**: 滑入效果

```html
<!-- 成功警告 -->
<div class="alert alert-success">
  <span class="alert-icon">✓</span>
  <div class="alert-content">
    <div class="alert-title">成功！</div>
    <div class="alert-message">操作已完成</div>
  </div>
  <button class="alert-close">✕</button>
</div>
```

### 🎮 遊戲化元件 (Gamification)

#### 生命值 (Life Bar)
```html
<div class="life-bar">
  <span class="life-heart">❤️</span>
  <span class="life-heart">❤️</span>
  <span class="life-heart empty">❤️</span>
</div>
```

#### 星級評分 (Star Rating)
```html
<div class="star-rating">
  <span class="star active">⭐</span>
  <span class="star active">⭐</span>
  <span class="star">⭐</span>
</div>
```

#### 進度條 (Progress Bar)
```html
<div class="progress">
  <div class="progress-bar" style="width: 60%"></div>
</div>
```

## 🎨 設計系統整合

### 色彩系統
使用 CSS 變數管理所有顏色：
```css
/* 主要色彩 */
var(--primary-teal)      /* #00E5CC - 主品牌色 */
var(--secondary-purple)  /* #8E44AD - 輔助色 */
var(--accent-violet)     /* #9B59B6 - 強調色 */

/* 功能色彩 */
var(--success-green)     /* #4CAF50 - 成功 */
var(--error-red)         /* #E74C3C - 錯誤 */
var(--warning-yellow)    /* #F39C12 - 警告 */
var(--info-cyan)         /* #3498DB - 資訊 */
```

### 間距系統
基於 8px 網格系統：
```css
var(--space-1)  /* 4px */
var(--space-2)  /* 8px */
var(--space-3)  /* 12px */
var(--space-4)  /* 16px */
var(--space-6)  /* 24px */
var(--space-8)  /* 32px */
```

### 圓角系統
```css
var(--radius-sm)   /* 8px */
var(--radius-md)   /* 12px */
var(--radius-lg)   /* 16px */
var(--radius-xl)   /* 24px */
var(--radius-full) /* 50% */
```

## 📱 響應式設計

### 斷點系統
```css
/* Mobile First 設計 */
@media (min-width: 576px)  { /* Small */ }
@media (min-width: 768px)  { /* Medium */ }
@media (min-width: 992px)  { /* Large */ }
@media (min-width: 1200px) { /* Extra Large */ }
@media (min-width: 1400px) { /* Extra Extra Large */ }
```

### 響應式工具類
```html
<!-- 在不同螢幕尺寸顯示/隱藏 -->
<div class="hidden-mobile">桌面顯示</div>
<div class="hidden-desktop">手機顯示</div>
```

## ♿ 無障礙設計

### 必要屬性
```html
<!-- 標籤關聯 -->
<label for="email">電子郵件</label>
<input id="email" type="email">

<!-- ARIA 屬性 -->
<button aria-label="關閉對話框">✕</button>

<!-- 必填標記 -->
<label class="input-label required">必填欄位</label>
```

### 鍵盤導航
- 所有互動元件支援 Tab 導航
- 焦點狀態明顯可見
- 支援 Esc 關閉彈窗

### 螢幕閱讀器
```html
<!-- 僅供螢幕閱讀器 -->
<span class="sr-only">載入中...</span>
```

## 🔧 與框架整合

### Vue.js 整合
```vue
<template>
  <button :class="['btn', `btn-${type}`, { 'btn-lg': large }]">
    <slot></slot>
  </button>
</template>

<script>
export default {
  props: {
    type: {
      type: String,
      default: 'primary'
    },
    large: Boolean
  }
}
</script>
```

### React 整合
```jsx
const Button = ({ type = 'primary', size, children, ...props }) => {
  const classNames = ['btn', `btn-${type}`];
  if (size) classNames.push(`btn-${size}`);

  return (
    <button className={classNames.join(' ')} {...props}>
      {children}
    </button>
  );
};
```

## 🌙 主題切換

### 實作暗色/亮色主題
```javascript
// 主題切換邏輯
function toggleTheme() {
  document.body.classList.toggle('light-theme');
  localStorage.setItem('theme',
    document.body.classList.contains('light-theme') ? 'light' : 'dark'
  );
}

// 載入儲存的主題
const savedTheme = localStorage.getItem('theme');
if (savedTheme === 'light') {
  document.body.classList.add('light-theme');
}
```

## 📋 最佳實踐

### DO ✅
1. **使用語義化 HTML**: 選擇正確的標籤 (button, nav, header)
2. **保持一致性**: 使用預定義的設計變數
3. **測試響應式**: 在不同裝置上測試
4. **優化效能**: 只引入需要的樣式
5. **註解代碼**: 為複雜元件添加說明

### DON'T ❌
1. **避免內聯樣式**: 使用 class 而非 style 屬性
2. **不要覆蓋變數**: 使用擴展而非修改
3. **避免深層嵌套**: 保持 HTML 結構簡潔
4. **不要忽略無障礙**: 確保所有人都能使用
5. **避免硬編碼值**: 使用設計系統變數

## 🔄 更新和維護

### 版本控制
```bash
# 查看變更
git diff docs/02_design/component-library/

# 提交更新
git add .
git commit -m "feat: 新增下拉選單元件"
```

### 元件新增流程
1. 在 `components.css` 中定義樣式
2. 在 `index.html` 中添加展示
3. 更新本指南文檔
4. 提交並通知團隊

## 🆘 常見問題

### Q: 如何自定義元件顏色？
A: 覆蓋 CSS 變數即可：
```css
.my-custom-button {
  --primary-teal: #your-color;
}
```

### Q: 元件在 IE 瀏覽器不正常？
A: 本元件庫不支援 IE，建議使用現代瀏覽器。

### Q: 如何添加動畫效果？
A: 使用 CSS transition 或 animation：
```css
.btn {
  transition: all 0.3s ease;
}
```

### Q: 可以用於商業專案嗎？
A: 是的，本元件庫採用開源授權。

## 📚 相關資源

- [設計系統總覽](../design-system/README.md)
- [色彩系統](../design-system/colors.md)
- [字體系統](../design-system/typography.md)
- [響應式設計規範](../specifications/responsive-design.md)
- [無障礙設計規範](../specifications/accessibility.md)

## 🤝 貢獻指南

歡迎貢獻新元件或改進現有元件：

1. Fork 專案
2. 建立 feature 分支
3. 提交變更
4. 發起 Pull Request

---

**維護團隊**: Drama Ling 開發團隊
**最後更新**: 2025-09-14
**版本**: v1.0