ckm:design-system

概觀

什麼是 ckm:design-system？

ckm:design-system 是一個設計系統技能，將設計代幣（design tokens）架構、元件規格，以及簡報投影片產生流程，整合成一套可重複使用的工作流程。

它以三層代幣模型為核心（primitive → semantic → component），並附上對應的參考文件與 scripts，協助處理：

• CSS variable 系統
• 間距與字體尺度（spacing & typography scales）
• 元件狀態與變體（states & variants）
• Tailwind 主題設定
• 系統化的簡報與 pitch deck 版面

此技能內建具風格觀點的資料表與範本，涵蓋投影片背景、色彩邏輯、文案公式、版面與敘事策略，並提供用來產生與驗證設計代幣及投影片結構的 scripts。

適合哪些人使用？

ckm:design-system 適用於：

• 設計系統負責人與 UI/UX 設計師：需要清楚的代幣架構與元件規格參考。
• Frontend 與 React/Tailwind 開發者：需要穩定的代幣流程（CSS variables、驗證工具、Tailwind 整合提示）。
• 創辦人、PM 與行銷人員：常態性製作 pitch deck，希望有可重複、符合品牌一致性的投影片框架，而不是每次從零開始。

如果你想把類似 Figma 的設計思維，銜接到可直接實作的設計代幣與可重用的簡報系統，這個技能會非常合適。

它能解決哪些問題？

ckm:design-system 能幫助你：

• 標準化設計代幣，並以文件化的 primitive → semantic → component 分層管理。
• 從 JSON 產生 CSS tokens，並在程式碼庫中驗證其使用狀況。
• 規劃 Tailwind 主題，使用同一套代幣架構。
• 定義元件規格，包含狀態與變體，確保 UI 在不同畫面間維持一致性。
• 設計符合品牌的簡報，透過預先定義的投影片版型、圖表建議、顏色與情緒邏輯，以及文案公式來完成。

它提供一套有結構的方式，讓你把 UI 和投影片都視為「系統」，而不是一次性的成品。

什麼情況下特別適合使用 ckm:design-system？

在以下情境特別適合使用此技能：

• 你正在導入或重構 design system，並希望清楚定義代幣分層。
• 你需要與代幣架構緊密連結的 CSS variable 與 Tailwind 指引。
• 你希望 自動產生與驗證設計代幣，而不是手動管理。
• 你經常建立 pitch decks、銷售簡報或產品 demo，並希望有可重複的投影片結構。

如果你只需要單一次的靜態 UI mock，或完全沒有使用設計代幣和 CSS variables，這個技能的價值會相對有限。

使用方式

安裝與基本設定

1. 安裝 ckm:design-system 技能

將技能安裝到你的 Agent/skills 環境中：

npx skills add https://github.com/nextlevelbuilder/ui-ux-pro-max-skill --skill design-system

這會從 nextlevelbuilder/ui-ux-pro-max-skill repository 把 design-system skill 拉到你的本地 skills 目錄裡。

2. 探索核心檔案

安裝完成後，打開該技能資料夾，可以從以下檔案與資料夾開始：

• SKILL.md – 高層概觀、適用情境、代幣架構與快速上手指令。
• references/ – 關於代幣、元件、變體與 Tailwind 整合的概念性文件。
• data/ – 編碼投影片背景、色彩邏輯、文案公式、版面、字體與策略的 CSV 檔。
• scripts/ – 用來產生、嵌入與驗證代幣的工具 scripts，以及投影片搜尋輔助工具。
• templates/design-tokens-starter.json – 用來定義你自己代幣集的起始 JSON 範本。

這樣的結構讓你可以快速決定要採用哪些部分：只用代幣、只用簡報，或是整套系統一起用。

設計你的代幣架構

3. 了解三層代幣模型

SKILL.md 與 references/token-architecture.md 描述了一個三步驟架構：

Primitive (raw values)
       ↓
Semantic (purpose aliases)
       ↓
Component (component-specific)

使用這些參考檔案來設計每一層：

• references/primitive-tokens.md – 基礎色彩、間距、圓角、字體 primitives。
• references/semantic-tokens.md – 以用途為導向的代幣，例如 --color-primary、--surface-elevated、--text-muted。
• references/component-tokens.md – 元件層級的變數，例如 --button-bg、--card-border、--badge-pill-radius。

這樣分層的好處包括：

• 可以交換主題而不需要重寫元件。
• 讓實作細節（CSS variables、Tailwind 設定）與設計語言保持一致。

4. 建立或調整你的代幣 JSON

以 templates/design-tokens-starter.json 作為你自訂代幣檔案的基礎。

常見工作流程：

1. 將 templates/design-tokens-starter.json 複製到你的專案中，命名為 tokens.json。
2. 先填入 primitive 值（顏色、間距、字級大小）。
3. 將 primitives 對應到 semantic 角色（primary、secondary、surface、border 等）。
4. 再把 semantic tokens 映射到各個關鍵 UI 元件所需的 component tokens。

可搭配以下文件參考：

• references/component-specs.md – 協助思考元件如何使用代幣。
• references/states-and-variants.md – 涵蓋 hover、focus、disabled、error 等狀態與變體。

產生與驗證設計代幣

5. 從代幣產生 CSS variables

使用 SKILL.md 中說明的代幣產生 script：

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

• --config 指向你的代幣 JSON（例如 tokens.json）。
• -o 指定輸出的 CSS 檔案（例如 tokens.css）。

產出的 CSS 檔會以 --custom-properties 定義你的代幣集合，可直接匯入前端專案中使用。

6. 驗證代幣在程式碼中的使用

為了確保程式碼只使用核准的代幣，可以執行代幣驗證工具：

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

這會檢查指定目錄（例如 src/）中代幣的使用模式，幫助你：

• 找出應該使用代幣卻被硬編（hard-coded）的值。
• 找出已棄用或未定義的代幣。

scripts/ 目錄中另外還有：

• html-token-validator.py – 掃描 HTML 中代幣使用模式。
• slide-token-validator.py – 驗證與投影片相關情境中的代幣使用。

用這些工具來維持 UI 與投影片都與你的設計系統對齊。

7. 在需要的地方嵌入代幣

如果你的環境需要將代幣直接嵌入文件或 HTML，可以使用：

• scripts/embed-tokens.cjs – 將代幣嵌入到目標檔案中。

請查看 script 內的註解及 SKILL.md，取得與你環境相符的使用說明。

Tailwind 與實作考量

8. 規劃 Tailwind 整合

此技能包含專門的 Tailwind 參考文件：

• references/tailwind-integration.md – 指引你如何將代幣名稱與尺度對應到 Tailwind 主題設定。

可以用來：

• 將 primitive/semantic tokens 映射到 Tailwind 的 colors、spacing 與 fontSize scales。
• 讓 Tailwind utility classes 與你的代幣設計保持一致（例如從 primitives 衍生出 primary 調色盤）。

即使目前尚未使用 Tailwind，這份參考也能幫助你思考，未來如何將代幣系統擴展到 utility-first CSS。

建立系統化的 pitch decks

雖然此技能的主要分類是設計系統，ckm:design-system 同時也支援結構化的簡報設計。

9. 使用投影片資料表來規劃版面與視覺

data/ 資料夾中包含多個 CSV 檔，用來描述最佳實務的投影片模式：

• data/slide-backgrounds.csv – 依投影片類型（hero、vision、team、testimonial、CTA、problem、solution 等）建議背景圖種類、遮罩與配置方式。
• data/slide-color-logic.csv – 情緒（frustration、hope、fear、relief、trust、urgency、curiosity 等）如何對應到背景風格、文字顏色與強調色使用方式。
• data/slide-typography.csv – 依投影片類型提供字體編排建議（階層、強調等）。
• data/slide-layout-logic.csv – 由敘事目標與情緒驅動的版面模式（hook、problem、solution、proof、traction、CTA、timeline、features 等）。
• data/slide-layouts.csv – 具體的版面模式與 CSS 結構提示（例如 grids、split layouts、hero 結構、動畫建議）。

你可以把這些資料表導入自己的流程（scripts、試算表或 deck generator），用敘事與情緒驅動來建立一致性的投影片，而非憑感覺臨時設計。

10. 用實證有效的公式結構化投影片文案

data/slide-copy.csv 提供針對不同投影片類型設計的文案公式，包括：

• AIDA（Attention → Interest → Desire → Action）
• PAS（Problem → Agitate → Solution）
• 4Ps（Promise → Picture → Proof → Push）
• Before-After-Bridge
• QUEST
• Star-Story-Solution

每一列包含：

• formula_name 與 keywords
• 結構化的 components
• use_case 與 example_template
• emotion_trigger 和 slide_type

你可以利用這些資料來：

• 引導 agent 依指定公式撰寫投影片文案。
• 讓 pitch deck 與銷售簡報的文案風格更一致。

11. 挑選適合的簡報策略來組成完整 deck

data/slide-strategies.csv 定義了不同類型的完整 deck 模式，例如：

• YC Seed Deck
• Guy Kawasaki 10/20/30
• Series A Deck

每個策略包含：

• 建議投影片數量
• 投影片順序（title、problem、solution、traction、market 等）
• 目標、受眾與語氣
• 敘事與情緒的起承轉合

這能讓你：

• 依照選定策略，一次產生整套投影片大綱。
• 同步管理設計系統與敘事結構，維持整體一致性。

12. 使用與投影片相關的 scripts

scripts/ 資料夾中包含多個與投影片流程相關的工具：

• scripts/generate-slide.py – 核心投影片產生邏輯（你可以改寫後整合到自己的 deck generator 或自動化流程）。
• scripts/search-slides.py 與 scripts/slide_search_core.py – 搜尋工具，協助你依關鍵字與情境找到合適的投影片模式或策略。
• scripts/fetch-background.py – 依 data/slide-backgrounds.csv 的指引，幫助從 Pexels/Unsplash 等來源抓取背景圖。

這些 scripts 是組裝積木，你可以視環境與自動化需求選擇直接執行或改寫整合。

善用參考文件與說明

13. 把 references 當作實作清單

references/ 資料夾不只是說明文件，也可當作你建立設計系統時的 checklist：

• references/token-architecture.md – 檢查 primitive/semantic/component 分層是否合理。
• references/primitive-tokens.md – 確認基礎代幣是否充分。
• references/semantic-tokens.md – 確保每個 semantic token 都有清楚用途。
• references/component-tokens.md – 把代幣映射到實際元件。
• references/component-specs.md – 紀錄狀態、變體、互動與無障礙考量。
• references/states-and-variants.md – 避免遺漏 hover、focus、active、disabled、error、success 等狀態。

在設計審查與交接時使用這些檔案，可讓設計與開發團隊保持對齊。

讓技能適配你的技術堆疊

14. 逐步整合

你不需要一次採用整個技能。常見的漸進整合方式包括：

• 只導入代幣 – 先用 templates/design-tokens-starter.json、generate-tokens.cjs 與 validate-tokens.cjs 建立代幣流程。
• 只導入投影片系統 – 使用 data/ 底下的 CSV 與 scripts/generate-slide.py，在保留既有設計系統的前提下，讓簡報更一致。
• 完整導入 – 同時整合代幣、元件與投影片結構，建立橫跨產品 UI 與 pitch decks 的統一品牌系統。

先專注解決當前最迫切的問題，再逐步擴展使用範圍。

常見問題（FAQ）

ckm:design-system 是 UI kit 還是設計代幣引擎？

它主要是一個 設計系統與代幣架構技能，同時內建結構化的簡報系統。它不附帶 Figma UI kit，但提供：

• 三層代幣架構
• 用來產生與驗證代幣的 scripts
• 元件規格與狀態的參考文件

你可以在 Figma 或其他設計工具中輕鬆鏡射相同的代幣與元件。

一定要搭配 Tailwind 或 React 才能用 ckm:design-system 嗎？

不需要。references/tailwind-integration.md 中有 Tailwind 整合說明，但完全是選擇性的。代幣會以標準 CSS variables 產生，因此可以搭配任何技術堆疊：

• Vanilla CSS 或 CSS Modules
• Styled-components 或其他 CSS-in-JS 解法
• Web Components 或其他框架的 design tokens

ckm:design-system 是怎麼幫助簡報製作的？

這個技能把投影片 deck 視為一個 設計系統問題 來處理：

• data/slide-layouts.csv 與 data/slide-layout-logic.csv 定義版面模式與 CSS 結構。
• data/slide-backgrounds.csv 與 data/slide-color-logic.csv 建立投影片類型與情緒到視覺元素的對應關係。
• data/slide-copy.csv 與 data/slide-strategies.csv 提供文案公式與完整 deck 結構。
• generate-slide.py 與 search-slides.py 等 scripts 協助自動產生與搜尋合適的版型。

因此你可以建立可重複、符合品牌的一致性 decks，而不是每次重新發明版面。

一定要照原樣使用提供的 CSV 資料嗎？

不用。這些 CSV 是 有明確觀點的預設值，你可以：

• 直接使用，快速產出 pitch deck。
• fork 後依照品牌語氣與視覺風格調整。
• 完全改成自己的資料，只保留相同的 script 操作模式。

如果我只在意設計代幣，應該怎麼開始？

若你主要聚焦在設計代幣與 UI 實作，可以這樣開始：

1. 閱讀 SKILL.md，特別是「When to Use」與「Token Architecture」段落。

2. 打開 references/token-architecture.md 及 primitive/semantic/component 相關參考文件。

3. 複製 templates/design-tokens-starter.json，建立自己的 tokens.json。

4. 執行：

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

這樣就有一條可運作的代幣流程，不必先碰到簡報系統部分。

ckm:design-system 適合小型專案嗎？

可以使用，但它的優勢在於：

• 有多個人同時貢獻 UI 或簡報內容
• 需要高度一致性與可擴充性
• 預期會持續調整品牌或產品

對於只做一次的一頁式 landing page 或單次內部簡報，完整系統可能稍嫌過度結構化。不過你仍然可以輕量地借用代幣架構或投影片文案公式作為參考。

要如何快速了解這個技能到底包含哪些內容？

在 skills 瀏覽器或檔案總管中，查看 design-system 技能的完整目錄結構，特別是：

• SKILL.md
• data/
• references/
• scripts/
• templates/design-tokens-starter.json

這會一目了然顯示所有參考文件與輔助 scripts，方便你決定要把哪些部分整合進自己的工作流程。