Astryx 怎麼讓 AI 生成前端接入設計系統：React 元件、主題與驗收約束

讓 AI 生成一個頁面不難；難的是第二、第三個頁面仍沿用正確顏色、間距、元件狀態、無障礙屬性與互動邊界。Astryx 是 Meta 開源的 React 設計系統，官方稱其仍在 Beta，提供 150 多個可存取元件、主題、深色模式、範本與 CLI，並可用 CSS 自訂屬性覆寫主題。官方儲存庫

把 Astryx 接給 Agent 的目的不是讓模型自由設計，而是讓人與 Agent 使用同一套元件與文件。

先判斷是否適合引入

適合的專案通常具備：

React 專案已有多個後台頁，AI 生成 UI 開始風格漂移；
團隊需要統一按鈕、表單、彈窗、空狀態與深色模式；
希望 Agent 優先組合既有元件，而非每次手寫 CSS；
可在隔離環境驗證並鎖定 Beta 依賴版本。

若不是 React，或已有成熟內部元件庫，不必為追熱點重構。可將元件優先、token 優先、截圖驗收的方法移入既有系統。

安裝與最小主題

官方範例套件：

1
2


npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

先在獨立分支或小頁面驗證建置、樣式載入與深色模式，再擴展到應用入口。不要讓 Agent 直接替換全域樣式、路由殼或既有 token 檔案。

主題應表達品牌約束，而不是讓每頁任意覆寫。把可調整的顏色、圓角、字型與間距寫進專案規則，讓 Agent 知道應復用什麼。

先做小頁面，不要替換應用外殼

從設定頁、篩選側欄或資料詳情卡等單一路由開始。列出目前字型、間距、色彩 token、互動狀態與元件，再讓 Agent 用 Astryx 重建一個區塊。保留路由、資料請求、權限判斷與全域樣式入口；設計系統只負責元件與主題，不承擔業務遷移。

固定本地驗證順序：安裝後啟動開發伺服器；查看淺色與深色模式；用 Tab 走完表單、彈窗和按鈕；縮窄到行動寬度；最後跑既有測試或建置。每一步問題都記在該元件改動中，避免多頁接入後才發現 token 覆寫、CSS 優先序或焦點衝突。

小頁面穩定後，把它作為參考實作，記錄允許套件、主題入口、元件匯入方式與不可改的全域檔案。後續 Agent 任務引用這份參考即可。

給 Agent 的專案級約束

把以下規則放入 AGENTS.md、CLAUDE.md 或 Skill：

1
2
3
4
5


- 新页面优先使用 @astryxdesign 现有组件；新增自定义组件前先说明原因。
- 不新增全局 CSS reset，不修改既有主题 token。
- 所有表单字段必须有可见 label、错误态和禁用态。
- 完成后提供桌面和窄屏截图，并列出新增组件与交互状态。
- 不以截图相似为唯一验收；保留键盘操作和语义结构。

這比「用設計系統做儀表板」更可執行：Agent 有禁止項、復用路徑與交付物，審查者也能看出是否繞過元件庫。

將輸入、輸出與禁止項寫進任務單

任務應列出頁面範圍、可用資料、允許修改的檔案與驗收截圖。例如只改 src/features/orders/FilterPanel.tsx；復用既有查詢參數；不新增依賴、不改路由與 theme.ts；提供桌面與窄屏截圖，並列出 Button、Select、Dialog 狀態。這可避免 Agent 為達成視覺效果順手改全域 reset、狀態管理或 API 層。

複雜元件先要求結構草案：有哪些區塊、各自對應哪個 Astryx 元件、需要哪些 loading/error/empty 狀態。人工確認結構再寫程式。若設計稿超出元件庫，應調整設計或指定新元件維護者，而非塞入不可復用的臨時 CSS。

用四層驗收減少 UI 漂移

層級	檢查內容
元件	是否復用 Button、Input、Dialog 等既有元件，狀態是否完整
主題	是否只用允許的 token 或 CSS 變數改變視覺
互動	鍵盤焦點、載入、錯誤、空狀態是否可用
交付	建置是否通過、截圖是否覆蓋關鍵頁、是否有元件清單

視覺一致不是複製像素；真正應穩定的是可存取語義、狀態機、主題來源與可維護的元件邊界。

可重複的驗收流程

合入前先看 diff：是否新增繞過元件庫的全域樣式、寫死品牌色、修改無關檔案。瀏覽器中驗證正常資料、載入、空資料、API 失敗；表單另測必填、格式錯誤、禁用與送出中。只截正常態會掩蓋大多數回歸。

最後以鍵盤完成一次關鍵流程：Tab 順序是否合理、焦點能否進出 Dialog、錯誤訊息是否關聯欄位、顏色對比是否足夠。將這些檢查放入 PR 範本，Agent 生成頁面也會受同一標準約束。

常見誤區

把 Beta 當成全站重構理由：先鎖版，在單一功能域驗證升級成本。
讓 Agent 直接改元件內部：優先組合與主題覆寫；確有需要才匯出或接管原始碼。
每頁寫一套臨時 CSS：設計系統只剩套件名稱，無法約束後續 Agent。
只驗截圖不驗互動：截圖看不出 tab 順序、錯誤回饋與不能點擊的按鈕。

小結

Astryx 可建立人與 Agent 共用的前端語言。先在少量頁面驗證元件、主題與驗收流程，再把規則沉澱到專案檔案；不要讓新設計系統成為另一層無人維護的抽象。