Components

Components

說明

AI Playbook 的 Components 不是一般設計系統元件庫的完整實作清單，而是定義「文件網站中可重複使用的內容與介面模式」。

第一版元件應優先服務三件事：

讓文件更容易掃讀。
讓 AI Agent 更容易辨識規則、範例與限制。
讓未來自訂 UI 有明確來源，不從單次頁面需求長出來。

Why

AI Playbook 會持續新增 Brand、Design、Prompt、Workflow、Examples 等內容。如果每一頁都用不同方式表達 Do / Don’t、Checklist、Prompt Example 或 Decision，讀者與 Agent 都會增加判讀成本。

Components 文件的目的，是把重複出現的內容模式穩定下來。

Component Principles

第一版元件原則：

先使用 Markdown 與 Starlight 內建能力。
同一種資訊只用一種呈現方式。
元件必須有明確語意，不為裝飾而存在。
文字內容必須保留在 Markdown / MDX 中。
自訂元件出現前，先有對應規範文件。

Content Components

這些是第一版最重要的元件類型。

Decision Record

用於記錄技術或內容決策。

必要欄位：

Decision
Context
Options Considered
Reason
Consequences
Review Trigger

適用情境：

技術選型
部署策略
內容架構調整
AI Agent 工作規則

Do / Don’t

用於明確定義可做與不可做的行為。

規則：

Do 要可執行。
Don’t 要可判斷。
不寫空泛價值觀。
不把偏好寫成絕對規則，除非它是專案硬限制。

Checklist

用於驗收文件、流程或工作成果。

規則：

每個項目要能被勾選。
避免「確認內容良好」這類不可驗證文字。
已完成項目可使用 [x]，待辦使用 [ ]。

Prompt Example

用於給 Agent 可直接使用或改寫的提示詞。

規則：

要包含任務、輸入、限制與輸出格式。
不放入私密資料。
不依賴沒有寫在文件裡的隱性上下文。

Workflow Step

用於描述可重複執行的工作步驟。

必要欄位：

Input
Action
Output
Verification
Owner

UI Components

第一版不急著自製 UI component library。若需要 UI 元件，先採 Starlight 預設樣式與 Markdown。

可接受的後續 UI 元件：

Callout
Card
Badge
Step List
Command Block
Prompt Block

尚不建議的元件：

複雜 Dashboard chrome
自訂圖表系統
大型互動 Hero
與文件理解無關的動畫元件

Naming

元件文件命名使用小寫 kebab-case。

範例：

decision-record.md
prompt-example.md
workflow-step.md
do-dont.md

舊 PRD 提到的 marketing 元件，例如 pricing.md、hero.md、faq.md，要等實際內容需求出現後再補，不先做空規格。

Do

每個元件文件都要說明使用情境。
元件內容應可由 Markdown 或 MDX 驅動。
元件狀態與限制要明確。
優先定義內容元件，再定義視覺元件。
讓每個元件都能支援 Agent 判讀。
先寫規範，再做 UI 實作。

Don’t

不要只描述視覺外觀而不說用途。
不要建立無法重用的單次元件。
不要把元件文案硬寫在程式碼。
不要為了看起來像設計系統而建立空元件。
不要讓圖片承載元件的核心文字。
不要在沒有重複需求前建立複雜互動元件。

Checklist

Prompt Example

請依 AI Playbook 的 Components 規範，建立一份新的內容元件文件。

元件名稱：
使用情境：
必要欄位：
Do：
Don't：
Checklist：
Prompt Example：

限制：
- 先定義語意與使用規則
- 不先寫 UI 程式
- 內容必須可由 Markdown / MDX 驅動