355 lines
8.2 KiB
Markdown
355 lines
8.2 KiB
Markdown
# 📚 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 |