design-system

Design System

Token 架構、元件規格、系統化設計、投影片生成。

使用時機

• 設計 Token 建立
• 元件狀態定義
• CSS 變數系統
• 間距/字型級別
• 設計轉程式碼交接
• Tailwind 主題設定
• 投影片/簡報生成

Token 架構

載入：references/token-architecture.md

三層結構

原始層（原始值）
       ↓
語意層（用途別名）
       ↓
元件層（元件專用）

範例：

/* 原始層 */
--color-blue-600: #2563EB;

/* 語意層 */
--color-primary: var(--color-blue-600);

/* 元件層 */
--button-bg: var(--color-primary);

快速開始

產生 Token：

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

驗證使用：

node scripts/validate-tokens.cjs --dir src/

參考資料

主題	檔案
Token 架構	references/token-architecture.md
原始 Token	references/primitive-tokens.md
語意 Token	references/semantic-tokens.md
元件 Token	references/component-tokens.md
元件規格	references/component-specs.md
狀態與變體	references/states-and-variants.md
Tailwind 整合	references/tailwind-integration.md

元件規格範例

屬性	預設	懸停	啟用	停用
背景	primary	primary-dark	primary-darker	muted
文字	white	white	white	muted-fg
邊框	none	none	none	muted-border
陰影	sm	md	none	none

腳本

腳本	用途
generate-tokens.cjs	從 JSON Token 設定產生 CSS
validate-tokens.cjs	檢查程式碼中是否有硬編碼值
search-slides.py	BM25 搜尋 + 情境推薦
slide-token-validator.py	驗證投影片 HTML 是否符合 Token 規範
fetch-background.py	從 Pexels/Unsplash 擷取圖片

範本

範本	用途
design-tokens-starter.json	包含三層結構的入門 JSON

整合

與品牌整合： 從品牌色彩/字型提取原始值
與 ui-styling 整合： 元件 Token → Tailwind 設定

技能依賴： brand, ui-styling
主要代理人： ui-ux-designer, frontend-developer

投影片系統

使用設計 Token + Chart.js + 情境決策系統，製作符合品牌規範的簡報。

資料來源

檔案	用途
docs/brand-guidelines.md	品牌識別、語調、色彩
assets/design-tokens.json	Token 定義（原始→語意→元件）
assets/design-tokens.css	CSS 變數（在投影片中匯入）
assets/css/slide-animations.css	CSS 動畫庫

投影片搜尋（BM25）

# 基本搜尋（自動偵測領域）
python scripts/search-slides.py "投資人簡報"

# 領域特定搜尋
python scripts/search-slides.py "問題激發" -d copy
python scripts/search-slides.py "營收成長" -d chart

# 情境搜尋（進階系統）
python scripts/search-slides.py "問題投影片" --context --position 2 --total 9
python scripts/search-slides.py "行動呼籲" --context --position 9 --prev-emotion frustration

決策系統 CSV

檔案	用途
data/slide-strategies.csv	15 種簡報結構 + 情緒曲線 + 重點節奏
data/slide-layouts.csv	25 種版面 + 元件變體 + 動畫
data/slide-layout-logic.csv	目標 → 版面 + 打破模式標記
data/slide-typography.csv	內容類型 → 字型級別
data/slide-color-logic.csv	情緒 → 色彩處理
data/slide-backgrounds.csv	投影片類型 → 圖片類別（Pexels/Unsplash）
data/slide-copy.csv	25 種文案公式（PAS、AIDA、FAB）
data/slide-charts.csv	25 種圖表類型與 Chart.js 設定

情境決策流程

1. 解析目標/情境
        ↓
2. 搜尋 slide-strategies.csv → 取得策略 + 情緒節奏
        ↓
3. 針對每張投影片：
   a. 查詢 slide-layout-logic.csv → 版面 + 打破模式
   b. 查詢 slide-typography.csv → 字型級別
   c. 查詢 slide-color-logic.csv → 色彩處理
   d. 查詢 slide-backgrounds.csv → 圖片（若需要）
   e. 套用 slide-animations.css 中的動畫類別
        ↓
4. 使用設計 Token 產生 HTML
        ↓
5. 使用 slide-token-validator.py 驗證

模式打破（Duarte Sparkline）

進階簡報在情緒之間交替以維持參與度：

「現狀」（挫折） ↔ 「可能的情境」（希望）

系統會在 1/3 和 2/3 位置計算模式打破。

投影片需求

所有投影片必須：

1. 匯入 assets/design-tokens.css - 單一事實來源
2. 使用 CSS 變數：var(--color-primary)、var(--slide-bg) 等
3. 使用 Chart.js 製作圖表（非僅 CSS 長條圖）
4. 包含導覽（鍵盤方向鍵、點擊、進度條）
5. 內容置中對齊
6. 著重說服/轉換

Chart.js 整合

<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>

<canvas id="revenueChart"></canvas>
<script>
new Chart(document.getElementById('revenueChart'), {
    type: 'line',
    data: {
        labels: ['9月', '10月', '11月', '12月'],
        datasets: [{
            data: [5, 12, 28, 45],
            borderColor: '#FF6B6B',  // 使用品牌珊瑚色
            backgroundColor: 'rgba(255, 107, 107, 0.1)',
            fill: true,
            tension: 0.4
        }]
    }
});
</script>

Token 合規

/* 正確 - 使用 Token */
background: var(--slide-bg);
color: var(--color-primary);
font-family: var(--typography-font-heading);

/* 錯誤 - 硬編碼 */
background: #0D0D0D;
color: #FF6B6B;
font-family: 'Space Grotesk';

參考實作

包含所有功能的運作範例：

assets/designs/slides/claudekit-pitch-251223.html

指令

/slides:create "10 張投影片的 ClaudeKit Marketing 投資人簡報"

最佳實務

1. 絕不在元件中使用原始十六進位色碼 - 一律參考 Token
2. 語意層可實現主題切換（淺色/深色）
3. 元件 Token 可實現每個元件的自訂
4. 使用 HSL 格式以便控制透明度
5. 記錄每個 Token 的用途
6. 投影片必須匯入 design-tokens.css 並僅使用 var()