dramaling-vocab-learning/docs/02_design/component-library/COMPONENT_LIBRARY_GUIDE.md

📚 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 結構

<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. 查看組件庫

   open docs/02_design/component-library/index.html
   

2. 複製基礎樣式

   <link rel="stylesheet" href="path/to/base.css">
   <link rel="stylesheet" href="path/to/components.css">
   

3. 使用組件

   <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