不知不覺，30 天的鐵人賽已經來到 Day 29。
回頭看看，我們從一開始只有 Button 的小專案，逐漸建立了：
CUI
│
├── Design Tokens
├── React Components
├── Component Contract
├── Accessibility Rules
├── Storybook
├── Accessibility Testing
└── CDN Build
└── Legacy HTML Integration
前面幾天，我們也陸續完成了不同的使用入口。
React 開發者可以使用 CUI Components。
既有網站可以透過 CDN CSS 與 HTML Contract 導入 CUI。
而 Storybook 則讓開發者可以直接查看元件的 Props、Variants、States 與使用範例。
但今天，我想再處理另一種使用情境。
如果使用 CUI 的不是人，而是 AI 呢？
例如現在開發時，我們可能會直接請 AI Coding Assistant：
幫我建立一個包含姓名、電子郵件與送出按鈕的表單。
AI 確實可以很快產生程式碼。
但如果它不知道專案裡已經有 CUI，可能就會自行寫出：
export function SubmitButton() {
return (
<button className="rounded bg-blue-600 px-4 py-2 text-white">
送出
</button>
)
}
乍看之下沒有什麼問題。
但我們明明已經有：
<Button variant="primary">
送出
</Button>
而且 Button 的顏色、尺寸、Focus Indicator，都已經有統一規範。
AI 卻又重新建立了一套。
如果每次產生新頁面，都發生同樣的情況，那我們花了這麼多天建立的 Design System，就很難真正發揮效果。
因此今天的目標是：
讓 AI 知道 CUI 的存在，並且在產生程式碼時遵守 CUI 的 Component Contract 與 Accessibility Rules。
人類開發者使用 UI Kit 時，可以閱讀：
README
Storybook
Component Source
Usage Examples
但 AI 不一定會主動閱讀所有文件。
即使它能存取整個 Repository，也不代表它每次產生程式碼時，都會正確理解：
有哪些 Components？
有哪些 Variants？
哪些 Props 是公開 API？
哪些組合方式才是正確的？
哪些 Accessibility Rules 必須遵守？
例如我們的 Button 已經定義：
variant
├── primary
├── secondary
├── outline
├── ghost
├── destructive
└── link
但 AI 可能自行產生：
<Button variant="success">
儲存成功
</Button>
問題是：
CUI Button 根本沒有 success 這個 Variant。
如果 AI 沒有先確認 Component Contract，就很容易產生看似合理、實際卻無法使用的程式碼。
這正是今天想解決的問題。
這裡所說的 AI Skill，可以理解成：
一組提供給 AI Coding Assistant 的專案知識、工作指引與使用規範。
它通常包含：
When to Use
Available Components
Component Contract
Accessibility Rules
Code Examples
Validation Steps
當 AI 接到與 CUI 有關的開發任務時，就可以依照這些規範完成工作。
例如：
User Request
│
↓
AI Coding Assistant
│
↓
Read CUI Skill
│
↓
Check Component Contract
│
↓
Generate Code
│
↓
Validate Accessibility
不過要先說明：
Skill 不是所有 AI 工具都會自動辨識的通用執行標準。
不同 AI Coding Assistant，可能有不同的 Skill 載入機制、目錄慣例與支援能力。
所以今天會先建立一份以 Markdown 為核心、方便閱讀與維護的 Skill，再依實際使用的 AI 工具進行整合。
我們在 Day 25 建立了 Storybook。
現在又要建立 AI Skill，會不會重複？
我認為兩者的定位不同。
| Storybook | AI Skill | |
|---|---|---|
| 主要使用者 | 開發者 | AI Coding Assistant |
| 主要目的 | 探索、展示與測試元件 | 引導 AI 正確產生程式碼 |
| 內容 | Stories、Controls、Docs | 規則、使用流程、範例 |
| 互動方式 | 開啟介面操作 | AI 讀取指引並執行任務 |
例如 Storybook 可以讓我們看到：
Button
├── Primary
├── Secondary
└── Disabled
而 AI Skill 則應該告訴 AI：
需要主要操作按鈕時：
→ 優先使用 CUI Button
→ 使用 variant="primary"
→ 不要自行建立另一套 Button
→ 確認 Accessible Name
所以兩者並不是互相取代。
而是：
CUI
│
Component Contract
│
┌────────┴────────┐
↓ ↓
Storybook AI Skill
│ │
↓ ↓
Developers AI
這也是 Day 1 規劃的文件架構。
今天先採用容易管理的目錄結構。
例如：
skills/
└── cui/
├── SKILL.md
├── references/
│ ├── components.md
│ ├── accessibility.md
│ └── legacy.md
└── examples/
├── form.tsx
└── legacy-form.html
其中：
SKILL.md
→ AI 使用 CUI 的入口
references/components.md
→ Component API 與使用規範
references/accessibility.md
→ Accessibility Requirements
references/legacy.md
→ 傳統 HTML 使用方式
examples/
→ 正確的實作範例
這裡先把它當作專案內的 Skill Source。
如果使用的 AI 工具要求特定目錄，例如 .agents/skills/，可以再依工具的規範放置或連結。
不要只因為建立了 skills/cui/SKILL.md，就假設所有 AI 工具都會自動載入。
因為 CUI 已經有不少元件。
例如：
Button
Input
Textarea
Checkbox
Radio
Switch
Select
Badge
Alert
Table
Pagination
Tooltip
Dialog
如果把所有 Props、Variants、Examples 和 Accessibility Rules 都塞進 SKILL.md，很容易變成一份又長又難維護的文件。
所以我想採用：
入口精簡，細節分離。
例如：
SKILL.md
│
├── What is CUI?
├── When to use?
├── General rules
└── Reference links
│
├── Components
├── Accessibility
└── Legacy
AI 可以先閱讀最重要的規則。
再依照任務需要，查看對應的詳細文件。
SKILL.md先新增：
skills/cui/SKILL.md
內容可以從這樣開始：
---
name: cui
description: Use CUI components and accessibility
conventions when building React interfaces
or integrating CUI into traditional HTML pages.
---
# CUI UI Kit
CUI is an accessible UI kit built with React,
TypeScript, Tailwind CSS and Base UI.
## When to Use
Use this skill when:
- Building UI with CUI components
- Creating forms, tables or dialogs
- Updating existing CUI components
- Integrating CUI styles into HTML pages
- Reviewing CUI accessibility requirements
## Core Rules
1. Reuse existing CUI components.
2. Do not invent unsupported variants or props.
3. Prefer semantic HTML.
4. Preserve accessible names and keyboard behavior.
5. Use CUI design tokens.
6. Follow the component contract.
7. Validate changes before completion.
## References
- [Components](references/components.md)
- [Accessibility](references/accessibility.md)
- [Legacy HTML](references/legacy.md)
這裡使用 YAML Frontmatter，方便支援這種格式的 Skill Loader 讀取名稱與描述。
但 Frontmatter 的實際欄位要求，仍然要依目標工具的規範確認。
When to Use 為什麼重要？這一段是在告訴 AI：
什麼情況下應該參考 CUI Skill？
例如：
Create a form using CUI.
當然應該使用。
但使用者可能只說：
幫我建立一個資料編輯表單。
如果目前專案已經採用 CUI，AI 也應該優先檢查是否有現成元件。
所以我們可以把觸發情境寫得更貼近實際開發任務：
Creating or updating UI components
Building forms and validation flows
Implementing dialogs and tooltips
Creating data tables and pagination
Working on accessibility improvements
不過 Skill 的 Description 也不能寫得太廣泛。
否則 AI 可能在不相關的任務裡，也一直載入 CUI 的規範。
所以應該清楚界定：
這份 Skill 是為使用 CUI 的專案與任務而設計。
我想把這條放在很前面。
## Component Reuse
Before creating a new UI component:
1. Check whether CUI already provides it.
2. Prefer existing public component APIs.
3. Do not duplicate existing components.
4. Do not introduce unsupported variants.
5. Do not bypass accessibility behavior.
例如使用者要求：
建立一個有取消與儲存按鈕的表單。
AI 不應該直接寫：
<button className="bg-blue-600">
儲存
</button>
而是先確認 CUI 是否提供 Button。
如果有，就使用：
<Button variant="primary">
儲存
</Button>
但這裡也不能要求 AI 無條件使用某個元件。
如果 CUI 沒有適合的 API，AI 應該先檢查專案實作，而不是硬塞不存在的 Props。
接著新增：
skills/cui/references/components.md
這份文件負責整理 CUI 的公開 Component API。
例如 Button：
# CUI Components
## Button
Import:
`@/components/ui/button`
Supported variants:
- primary
- secondary
- outline
- ghost
- destructive
- link
Supported sizes:
- sm
- md
- lg
- icon-sm
- icon-md
- icon-lg
Rules:
- Use a native button for actions.
- Icon-only buttons require an accessible name.
- Do not invent unsupported variants.
- Preserve native disabled behavior.
這些內容應該直接對照目前的 button.tsx。
因為我們不希望 Skill 寫：
Button 支援 success
但原始碼其實沒有。
因此 Component Reference 必須和實際程式碼保持一致。
Day 22 我們已經整理過 Component Contract。
包含：
Semantic HTML
Public Props
Variants
Sizes
States
Data Attributes
Design Tokens
現在這些規則就能成為 AI 產生程式碼時的邊界。
例如：
## Component Contract
- Use documented public props only.
- Do not depend on internal implementation details.
- Preserve semantic HTML.
- Use documented data-cui-* attributes for HTML integration.
- Do not add redundant ARIA attributes.
- Do not hardcode colors that have CUI tokens.
這樣可以減少 AI 自行推測元件 API 的情況。
不過也要記得：
文件不是 TypeScript Compiler。
即使 Skill 寫得很清楚，AI 還是可能犯錯。
因此最後仍然需要：
Type Check
Build
Lint
Tests
來驗證結果。
接著新增：
skills/cui/references/accessibility.md
這份文件我想整理成幾個核心原則。
# CUI Accessibility Rules
## Semantic HTML
- Prefer native HTML elements.
- Do not use div as a replacement for button.
- Use proper table semantics for tabular data.
## Accessible Name
- Interactive controls must have an accessible name.
- Icon-only buttons need aria-label or hidden text.
- Do not rely on placeholder as an input label.
## Forms
- Associate labels with controls.
- Associate error messages with invalid fields.
- Use aria-invalid when appropriate.
- Do not rely on color alone to indicate errors.
## Keyboard
- Preserve native keyboard interactions.
- Provide visible keyboard focus.
- Do not create keyboard traps.
## Dialog
- Provide an accessible title.
- Manage initial focus.
- Contain focus in modal dialogs.
- Restore focus appropriately.
- Handle dismissal according to the task.
這些規則都不是今天才新增的。
而是前面 28 天已經逐步建立的 Accessibility Requirements。
今天只是把它們整理成 AI 也能直接使用的文件。
這裡有個我覺得很重要的問題。
AI 有時候會認為：
加越多 ARIA，就越符合無障礙。
例如：
<button
role="button"
aria-label="儲存"
>
儲存
</button>
但原生 <button> 已經具有 Button Role。
而且可見文字「儲存」本身就能提供 Accessible Name。
因此這裡的：
role="button"
aria-label="儲存"
通常都是不必要的。
所以我想在 Skill 裡明確加入：
## ARIA Rules
- Prefer native semantics before ARIA.
- Do not add redundant roles.
- Do not duplicate accessible names unnecessarily.
- Use ARIA only when it serves a clear purpose.
- ARIA does not replace keyboard behavior.
這樣 AI 才不會為了看起來符合 Accessibility，而產生一堆沒有必要的 Attributes。
比起只有一條：
Input must have a label.
我覺得 AI 更需要看到正確的組合範例。
例如：
<Field>
<FieldLabel htmlFor="email">
電子郵件
</FieldLabel>
<Input
id="email"
name="email"
type="email"
/>
<FieldDescription>
請輸入常用的電子郵件地址。
</FieldDescription>
</Field>
這樣 AI 才能理解：
Field
├── FieldLabel
├── Input
└── FieldDescription
而不是自己發明：
<Input label="電子郵件" />
因為 CUI 的 Input 不一定提供 label 這個 Prop。
所以 Skill 的 Example 應該展示：
實際存在的 Component API 與正確的組合方式。
例如：
<Field data-invalid="true">
<FieldLabel htmlFor="email">
電子郵件
</FieldLabel>
<Input
id="email"
name="email"
aria-invalid="true"
aria-describedby="email-error"
/>
<FieldError id="email-error">
請輸入有效的電子郵件地址。
</FieldError>
</Field>
這裡 AI 需要理解：
Visual Error
+
ARIA Invalid
+
Error Association
而不是只做：
<Input className="border-red-500" />
這就是我們前面建立 Accessibility Contract 的價值。
Day 24 我們討論過 Dialog 的 Focus Management。
如果 Skill 只有：
Use Dialog for modal content.
其實不夠。
因為 AI 可能會寫出一個視覺上正常，但鍵盤操作不完整的 Dialog。
所以至少要補充：
## Dialog Rules
- Use the existing CUI Dialog component.
- Do not create a custom focus trap unnecessarily.
- Provide DialogTitle.
- Use DialogDescription when appropriate.
- Keep modal focus behavior intact.
- Do not remove keyboard dismissal without a reason.
- Consider unsaved changes before allowing dismissal.
另外，AI 應該使用 CUI 實際提供的 Dialog API。
例如目前採用 Base UI 的 Composition Pattern，就不應該直接套用其他 Primitive Library 的 API。
這也是為什麼 Skill 必須依據專案實際原始碼撰寫。
接著新增：
skills/cui/references/legacy.md
因為 React 和一般 HTML 的使用方式不同。
例如 React：
<Button variant="primary">
儲存
</Button>
Legacy HTML：
<button
type="button"
data-cui-slot="button"
data-cui-variant="primary"
data-cui-size="md"
>
儲存
</button>
所以我們要明確告訴 AI：
# CUI HTML Integration
Use this reference when working with traditional HTML pages.
## Rules
- Do not introduce React into an existing HTML page.
- Load the published CUI CSS.
- Use documented data-cui-* attributes.
- Preserve native HTML semantics.
- Do not assume CSS provides interactive behavior.
- Use native browser APIs when appropriate.
- Follow the accessibility requirements.
這樣 AI 才不會在傳統 HTML 頁面裡，突然產生一堆 JSX。
這點和 Day 27、Day 28 很有關係。
例如：
<button
data-cui-slot="button"
data-cui-variant="primary"
>
儲存
</button>
CSS 可以提供樣式。
但不會自動完成：
Save Data
Validation
Dialog Open
Tooltip Dismissal
所以 Skill 必須清楚說明：
## CSS and Behavior
CUI CSS provides visual styling.
It does not automatically implement application logic.
Interactive components may require native browser
behavior or an explicitly supported JavaScript adapter.
Do not assume an adapter exists unless it is present
in the project.
這樣 AI 就不會因為看到：
cui.min.css
便自行假設：
cui.js
已經存在。
這是我覺得很容易忽略的地方。
假設我們目前完成：
CDN CSS
但還沒有完整實作：
Tooltip Adapter
Dialog Adapter
那 Skill 不應該寫：
CUI provides all interactive components for Legacy.
因為這不符合實際狀態。
比較好的方式是：
## Current Support
- CSS-only components: use documented HTML contracts.
- Interactive components: check implementation status.
- Do not invent missing JavaScript APIs.
這讓 AI 知道：
文件必須反映實際能力，而不是理想中的架構。
前面我們已經有：
Build
Lint
Contrast Check
Storybook
Accessibility Testing
所以 AI 在完成任務後，也應該執行適當檢查。
例如：
## Validation
After changing CUI components:
1. Run the project build.
2. Run lint.
3. Run contrast checks when styles or tokens change.
4. Review relevant Storybook stories.
5. Run available accessibility and interaction tests.
6. Report checks that could not be executed.
這裡我不想要求 AI 每次修改一個字，就把所有測試全部跑完。
而是根據修改範圍選擇適當檢查。
例如：
Button Styling Change
→ Build
→ Lint
→ Contrast
→ Button Stories
而：
Dialog Behavior Change
→ Build
→ Lint
→ Dialog Interaction Tests
→ Keyboard / Focus Review
這樣比較合理。
即使文件已經整理得很完整，我還是想加入一條：
## Source Verification
Before using or modifying a component:
- Inspect its current public API.
- Check the corresponding Storybook stories.
- Verify supported variants and props.
- Do not assume documentation is newer than source code.
原因很簡單。
我們可能會修改：
Button Variant
Field API
Dialog Composition
但忘記同步更新 Skill。
如果 AI 完全相信過期文件，就可能產生錯誤程式碼。
因此：
Skill 是開發指引，不應該取代對實際程式碼的確認。
文件寫完後，還不能直接宣布成功。
我們需要測試：
AI 真的會依照規範使用 CUI 嗎？
我想先設計幾個測試情境。
Prompt：
請使用 CUI 建立一個包含姓名、電子郵件與送出按鈕的表單，並提供必要的欄位說明。
預期：
Use Field
Use FieldLabel
Use Input
Use Button
Preserve Accessible Name
不應該：
Create another Button
Use Placeholder as Label
Hardcode Button Colors
Prompt：
請在電子郵件格式錯誤時，顯示驗證訊息。
預期：
aria-invalid
aria-describedby
FieldError
不應該只有：
Red Border
Prompt：
請建立一個可以編輯資料的 Dialog。
預期：
Use CUI Dialog
Provide Accessible Title
Preserve Focus Management
Use Existing Button
不應該：
Custom div Modal
Unnecessary Focus Trap
Unsupported Dialog Props
這次換成：
請在一個不使用 React 的 HTML 頁面中，加入 CUI 的主要操作按鈕與表單欄位。
預期 AI 產生：
<label for="name">
姓名
</label>
<input
id="name"
name="name"
data-cui-slot="input"
>
<button
type="submit"
data-cui-slot="button"
data-cui-variant="primary"
data-cui-size="md"
>
送出
</button>
而不是：
import { Button } from "@/components/ui/button"
因為這個情境明確不使用 React。
這個測試可以確認 AI 是否理解：
Same Contract
Different Environment
我想先建立一個簡單的檢查表。
| 檢查項目 | 預期結果 |
|---|---|
| Component Reuse | 優先使用現有 CUI 元件 |
| API Accuracy | 不產生不存在的 Props |
| Semantic HTML | 使用正確 HTML 元素 |
| Accessibility | 保留 Label、Name、Keyboard 規則 |
| Design Tokens | 不任意硬編碼顏色 |
| React / Legacy | 能區分不同環境 |
| Validation | 會執行適當檢查 |
測試時可以記錄：
Prompt
Generated Code
Problems Found
Skill Changes
Retest Result
這樣就不只是憑感覺認為：
AI 好像變聰明了
而是能觀察 Skill 是否真的改善程式碼品質。
如果想進一步驗證，可以使用相同的任務做比較。
例如：
Task
→ Create Accessible Form
第一組：
Without CUI Skill
第二組：
With CUI Skill
比較：
是否使用 CUI Components？
是否產生不存在的 API？
是否正確處理 Label？
是否遵守 Error Pattern？
是否通過 Build？
不過要注意，AI 產生結果可能受到模型、上下文、工具與隨機性的影響。
所以單次測試只能當作初步觀察。
如果要更有說服力，可以用相同條件重複測試幾次。
這是今天最後一個重要觀念。
假設未來我們新增：
Button Loading State
或修改：
Dialog API
那麼：
Component Source
Storybook
AI Skill
都可能需要同步更新。
因此我希望未來的 Pull Request Checklist 可以包含：
Component Changed?
│
├── Update Stories
├── Update Component Docs
├── Review Accessibility
└── Update AI Skill if needed
這樣 Skill 才不會慢慢變成過期文件。
這也是我今天開始想到的下一步。
目前：
Storybook
→ Human Documentation
AI Skill
→ AI Instructions
但兩邊都需要知道：
Component Names
Variants
Sizes
Props
Usage Rules
如果全部手動維護，就可能產生差異。
所以未來可以考慮：
Component Contract
│
├── Storybook Docs
│
└── AI Skill Reference
例如把公開 API 與部分 Metadata 整理成結構化資料，再由不同工具產生對應文件。
不過今天先不實作這套自動化。
因為目前更重要的是確認：
AI Skill 的內容是否正確、實用，而且能真正改善 AI 產生的程式碼。
今天的工作可以整理成：
Skill Structure
SKILL.md
Contract
AI Testing
今天主要修改的是文件，但還是可以執行：
npm run build
npm run lint
如果修改了元件樣式或 Tokens，再執行：
npm run check:contrast
如果有新增或調整 CDN 相關範例，也可以執行：
npm run build:cdn
不過這些指令只能驗證專案的部分品質。
它們不會自動驗證 Skill 是否能被 AI 正確載入，也不會驗證 AI 是否遵守文件。
所以今天最重要的測試，仍然是實際使用支援 Skill 的 AI Coding Assistant，確認它能讀取文件並完成指定任務。
最後檢查：
git status
git diff
今天的 Branch：
git switch -c feat/ai-skill
完成後：
git add .
git diff --staged
git commit -m "docs: add CUI AI skill and usage guidelines"
今天我們讓 CUI 多了一個新的使用入口。
原本：
CUI
│
Shared Contract
│
┌──────────┴──────────┐
↓ ↓
React Legacy
│ │
Components HTML / CSS
現在再加入：
CUI
│
Shared Contract
│
┌────────────┼────────────┐
↓ ↓ ↓
React Legacy AI Skill
│ │ │
↓ ↓ ↓
Developers Developers AI
這讓 CUI 不只是提供可以重複使用的元件。
也開始提供：
How to Use
What to Reuse
What Not to Do
How to Validate
而這些規則，正是我們前面 28 天不斷累積的成果。
但今天最重要的收穫不是多了一份 SKILL.md。
而是重新理解：
Design System 的價值，不只在於提供元件，也在於讓不同的使用者能夠正確、一致地使用這些元件。
人類開發者需要文件與範例。
AI Coding Assistant 也需要明確的規則與邊界。
當兩者都能依照同一份 Component Contract 工作時，CUI 才更有機會維持長期的一致性。
當然，AI Skill 不能保證 AI 永遠不會犯錯。
我們仍然需要：
Code Review
Type Check
Build
Accessibility Testing
但至少現在，我們不再只是期待 AI 自己猜對。
而是開始主動提供它應該遵守的規範。
明天，就是最後一天了！
30 天前，我們從一個簡單的想法開始：
打造一套能兼顧 Accessibility、React、Legacy 與 AI 的 UI Kit。
現在已經逐步完成：
Design Tokens
React Components
Accessibility Patterns
Component Contract
Storybook
Accessibility Testing
CDN Build
Legacy Integration
AI Skill
Day 30，我想回頭整理整個專案的架構、這 30 天遇到的問題，以及哪些目標已經完成、哪些仍然需要繼續努力。
也會重新檢視：
CUI 到底只是一套 Component Library，還是已經開始具備 Design System 的雛形？
Day 30：
30 天打造 Accessible UI Kit：從一顆 Button 到 Design System 的起點。
iThome鐵人賽
看影片追技術