Components.build 規範
關於建立現代化、可組合且無障礙 UI 元件的全面指導方針。包含 16 個規則類別,從核心原則到發佈策略,由 Hayden Bleasel 和 shadcn 共同撰寫。
何時套用
在以下情況參考這些指導方針:
- 建立新的 React 元件或元件庫
- 設計元件 API 和 prop 介面
- 實作無障礙功能(鍵盤、ARIA、焦點管理)
- 建構可組合的元件架構
- 使用 Tailwind CSS 和 CVA 進行元件樣式設計
- 將元件發佈至註冊表或 npm
依優先順序排列的規則類別
| 優先順序 | 類別 | 重點 | 前綴 |
|---|---|---|---|
| 1 | 概觀 | 規範範圍與目標 | overview |
| 2 | 原則 | 核心設計理念 | principles |
| 3 | 定義 | 常用術語 | definitions |
| 4 | 組合 | 分解複雜元件 | composition |
| 5 | 無障礙性 | 鍵盤、螢幕報讀軟體、ARIA | accessibility |
| 6 | 狀態 | 可控/非可控模式 | state |
| 7 | 型別 | TypeScript props 與介面 | types |
| 8 | 多型 | 使用 as prop 切換元素 | polymorphism |
| 9 | As-Child | Radix Slot 組合模式 | as-child |
| 10 | 資料屬性 | data-state 和 data-slot | data-attributes |
| 11 | 樣式設計 | Tailwind CSS、cn 工具、CVA | styling |
| 12 | 設計符記 | CSS 變數與主題設定 | design-tokens |
| 13 | 文件 | 元件文件 | documentation |
| 14 | 註冊表 | 元件註冊表 | registry |
| 15 | NPM | 發佈至 npm | npm |
| 16 | 市場平台 | 元件市場 | marketplaces |
快速參考
1. 概觀
overview- 規範範圍、目標與理念
2. 原則
principles- 可組合性、無障礙性、可自訂性、透明度
3. 定義
definitions- 常用術語(原始、複合、無頭等)
4. 組合
composition-root- 使用 Context 管理共享狀態的根元件composition-item- 項目包裝元件composition-trigger- 互動觸發元件composition-content- 內容顯示元件composition-export- 命名空間匯出模式
5. 無障礙性
accessibility-semantic-html- 使用適當的 HTML 元素accessibility-keyboard- 完善的鍵盤導覽支援accessibility-aria- 正確的 ARIA 角色、狀態與屬性accessibility-focus- 焦點管理與還原accessibility-live-regions- 螢幕報讀軟體提示accessibility-contrast- 顏色對比度要求
6. 狀態
state-uncontrolled- 內部狀態管理state-controlled- 外部狀態委派state-controllable- 使用 useControllableState 支援兩種模式
7. 型別
types-extend-html- 擴展原生 HTML 屬性types-export- 為消費者匯出 prop 型別types-single-element- 一個元件包裝一個元素
8. 多型
polymorphism-as-prop- 變更渲染的 HTML 元素類型polymorphism-typescript- 型別安全的多型元件polymorphism-defaults- 語意元素的預設值
9. As-Child
as-child-slot- 使用 Radix Slot 進行 prop 合併as-child-composition- 與子元件組合
10. 資料屬性
data-attributes-state- 使用data-state設定狀態樣式data-attributes-slot- 使用data-slot定位子元件
11. 樣式設計
styling-cn-utility- 合併 clsx 和 tailwind-mergestyling-order- 基礎 → 變體 → 條件式 → 使用者覆寫styling-cva- 使用 Class Variance Authority 定義變體styling-css-variables- 使用 CSS 變數實現動態值
12. 設計符記
design-tokens-css-variables- 將符記定義為 CSS 變數design-tokens-theming- 支援淺色/深色模式與主題
13. 文件
documentation-props- 使用 JSDoc 記錄所有 propsdocumentation-examples- 提供使用範例
14. 註冊表
registry-structure- 註冊表檔案結構registry-schema- 元件元資料架構
15. NPM
npm-package-json- 套件設定npm-exports- 模組匯出
16. 市場平台
marketplaces-distribution- 元件發佈策略
如何使用
閱讀個別的規則檔案以取得詳細說明和程式碼範例:
rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md
每個規則檔案包含:
- 為何重要的簡短說明
- 包含說明的錯誤程式碼範例
- 包含說明的正確程式碼範例
- 最佳實踐與常見陷阱
完整彙編文件
如需包含所有規則的完整指南,請參閱:AGENTS.md
關鍵原則
- 組合優先於設定 - 將元件分解為可組合的子元件
- 無障礙性為預設 - 這是必要條件,而非事後補救
- 單一元素包裝 - 每個元件包裝一個 HTML 元素
- 擴展 HTML 屬性 - 務必擴展原生元素 props
- 匯出型別 - 讓 prop 型別可供消費者使用
- 支援兩種狀態模式 - 可控與非可控
- 智慧型樣式合併 - 使用
cn()工具函數搭配 tailwind-merge
作者
共同撰寫:
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
改編為 AI 技能:
- Jordan Gilliam (@nolansym)
基於 components.build 規範。