8.2 KiB

Raw Blame History

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

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

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

優勢比較

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

🚀 快速開始

1. 查看元件庫

# 在瀏覽器中打開
open docs/02_design/component-library/index.html

2. 複製元件代碼

瀏覽到需要的元件區塊
點擊「複製」按鈕
貼上到你的專案中

3. 引入樣式文件

<!-- 在你的 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

<!-- 基礎用法 -->
<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

<!-- 完整輸入組 -->
<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效果, 點擊反饋

<!-- 基礎卡片 -->
<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
功能: 可關閉, 自動消失
動畫: 滑入效果

<!-- 成功警告 -->
<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)

<div class="life-bar">
  <span class="life-heart">❤️</span>
  <span class="life-heart">❤️</span>
  <span class="life-heart empty">❤️</span>
</div>

星級評分 (Star Rating)

<div class="star-rating">
  <span class="star active">⭐</span>
  <span class="star active">⭐</span>
  <span class="star">⭐</span>
</div>

進度條 (Progress Bar)

<div class="progress">
  <div class="progress-bar" style="width: 60%"></div>
</div>

🎨 設計系統整合

色彩系統

使用 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 網格系統：

var(--space-1)  /* 4px */
var(--space-2)  /* 8px */
var(--space-3)  /* 12px */
var(--space-4)  /* 16px */
var(--space-6)  /* 24px */
var(--space-8)  /* 32px */

圓角系統

var(--radius-sm)   /* 8px */
var(--radius-md)   /* 12px */
var(--radius-lg)   /* 16px */
var(--radius-xl)   /* 24px */
var(--radius-full) /* 50% */

📱 響應式設計

斷點系統

/* 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 */ }

響應式工具類

<!-- 在不同螢幕尺寸顯示/隱藏 -->
<div class="hidden-mobile">桌面顯示</div>
<div class="hidden-desktop">手機顯示</div>

♿ 無障礙設計

必要屬性

<!-- 標籤關聯 -->
<label for="email">電子郵件</label>
<input id="email" type="email">

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

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

鍵盤導航

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

螢幕閱讀器

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

🔧 與框架整合

Vue.js 整合

<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 整合

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>
  );
};

🌙 主題切換

實作暗色/亮色主題

// 主題切換邏輯
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 ✅

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

DON'T ❌

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

🔄 更新和維護

版本控制

# 查看變更
git diff docs/02_design/component-library/

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

元件新增流程

在 components.css 中定義樣式
在 index.html 中添加展示
更新本指南文檔
提交並通知團隊

🆘 常見問題

Q: 如何自定義元件顏色？

A: 覆蓋 CSS 變數即可：

.my-custom-button {
  --primary-teal: #your-color;
}

Q: 元件在 IE 瀏覽器不正常？

A: 本元件庫不支援 IE，建議使用現代瀏覽器。

Q: 如何添加動畫效果？

A: 使用 CSS transition 或 animation：

.btn {
  transition: all 0.3s ease;
}

Q: 可以用於商業專案嗎？

A: 是的，本元件庫採用開源授權。

📚 相關資源

🤝 貢獻指南

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

Fork 專案
建立 feature 分支
提交變更
發起 Pull Request

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

8.2 KiB Raw Blame History Unescape Escape