Meta 開源 Astryx 設計系統：174 個元件與 AI 代理實測

一句話結論：Astryx 是 Meta 開源、在內部養了八年的設計系統（MIT、Beta），出貨 174 個無障礙 React 元件、7 套主題與一支把元件文件變成 JSON 的 CLI；astryx init 會把元件索引寫進 AGENTS.md，讓 AI 編碼代理直接讀規格、不必猜 API。

這是什麼：一個在 Meta 內部活過八年的設計系統

Astryx 不是某個工程師的週末專案。根據官方 README，它「在 Meta 內部成長了八年，成為公司內使用最廣、規模最大的設計系統，支撐 13,000 個以上的應用」。2026 年 1 月開源（meta/astryx，MIT），以 @astryxdesign/* 系列套件發佈到 npm；截至 2026-11-12 的查證：26,343 顆星、2,040 個 fork、622 個 open issue，最新版 0.7.15 於當天下午發佈。

它的定位寫得很清楚，而且不太像一般設計系統的行銷詞：

一個完全可客製、為「現在這種開發方式」而生的開源設計系統：由人，以及和他們一起工作的代理共同建構。

換句話說，它把「AI 代理是一等公民」寫進了架構，而不是事後補一個 MCP server。

一表看懂

為什麼 2026 年值得看：四個「代理友善」的具體設計

很多專案會說自己「AI-ready」，Astryx 的做法是可以逐條檢查的：

1. init 會寫 agent 文件。 astryx init 在專案根目錄產生 AGENTS.md（並在需要時建 GEMINI.md 指向它），把版本、元件數、CSS 匯入順序、工作流程、以及「不要用 <div>」這類規則寫進去。本次實測產出的 AGENTS.md 是 2,214 bytes。
2. CLI 有機器可讀的 manifest。 astryx manifest --json 回一份自描述清單：每個指令的參數、型別、預設值、回應型別、退出碼。實測輸出 165,540 bytes、涵蓋 17 個指令。
3. 錯誤碼是穩定的 API。 錯誤回傳 code（如 ERR_UNKNOWN_COMPONENT）而不是只有人看的字串，官方承諾錯誤碼只增不改。實測打錯字 astryx component Buttn 會回：

{"apiVersion": 1, "error": "No component named \"Buttn\"",
 "code": "ERR_UNKNOWN_COMPONENT",
 "suggestions": [{"name": "Button", "reason": "similar name (distance 1)"}]}

4. 有給代理省 token 的輸出模式。 --dense 與 --brief 讓同一個元件的文件從 10 KB 降到 833 bytes；--zh 提供簡中翻譯（沒有翻譯的元件會回英文）。

這四件事合起來，才讓「讓代理寫前端」從抽卡變成人可以審核的流程——因為規格是一份可以被 diff 的檔案。

安裝與啟動：三個套件、三行 CSS

官方建議的安裝（本次實測直接照抄執行）：

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

實測結果：安裝完 92 個頂層套件目錄、151 個 package.json，@astryxdesign/core 佔 45 MB（含 src、dist、型別與 locales）。值得注意的依賴結構——core 的執行期依賴只有 1 個（intl-messageformat），其餘全是 peer dependency：

"dependencies": {"intl-messageformat": "^11.2.9"},
"peerDependencies": {"@stylexjs/stylex": "^0.19.0", "react": ">=19.0.0", "react-dom": ">=19.0.0"}

接著只要三行 CSS 加一個 Provider，不需要 PostCSS、Babel 或任何建置外掛：

// app/providers.tsx
'use client';
import {Theme} from '@astryxdesign/core/theme';
import {LinkProvider} from '@astryxdesign/core/Link';
import {neutralTheme} from '@astryxdesign/theme-neutral/built';

export function Providers({children}) {
  return <Theme theme={neutralTheme}><LinkProvider component={Link}>{children}</LinkProvider></Theme>;
}

/* 順序不能換，因為它對應 CSS layer 的疊法 */
@import '@astryxdesign/core/reset.css';        /* @layer reset */
@import '@astryxdesign/core/astryx.css';        /* @layer astryx-base */
@import '@astryxdesign/theme-neutral/theme.css';/* @layer astryx-theme */

三個檔案的實際重量（本次量測）：

也就是說全站樣式基底約 53 KB gzip，這對「一次載入 150+ 元件的樣式」來說是合理的數字，而且沒有 runtime CSS-in-JS 的計算成本。

實測一：SSR 渲染出來的 HTML 長什麼樣

用 react-dom/server 渲染一個「帳單摘要」卡片（Card + VStack + Heading + Text + Badge + 兩個 Button），輸出 3,454 bytes，關鍵特徵直接看得到：

• 根節點帶 data-astryx-theme="neutral"，主題切換是靠這個屬性 + CSS 變數，不是重新渲染。
• 每個元件保留語意屬性：data-variant="primary"、data-size="md"、data-direction="vertical"、data-gap="3"——這對 E2E 測試與主題覆寫非常好用，不必靠 class 名稱。
• 按鈕內建 <span role="status" aria-live="polite"> 的即時區域，載入狀態會唸出來。
• class 是 StyleX 的原子類別（x1k57tk5 這種），共 15 個 class 屬性；風格覆寫建議走 className 與 CSS 變數，而不是去改這些雜湊。

換句話說，你拿到的是一個「有語意、可測試、可主題化」的 DOM，而不是一堆 div 疊出來的結果。

實測二：六個真的會天天用的 CLI 指令

CLI 有 17 個指令，但 90% 的日常只需要這六個（以下輸出都是本次實跑）：

其中 build 這個指令值得單獨講。它做的事不是「生成一個頁面」，而是先幫你選對模板：

TEMPLATE
The closest template; none is exactly this page.
name: settings  package: @astryxdesign/core
command: npx astryx template settings --type page <path>
Install missing dependencies: npm install @heroicons/react@"^2.2.0"

接著實際 scaffold：

astryx template settings --type page app/settings.tsx
# Copied template to app/settings.tsx

產出 230 行、7,777 bytes 的完整頁面原始碼，裡面已經用了 Layout／LayoutHeader／LayoutPanel、Grid、List、TabList、Typeahead、TextInput、CheckboxInput，並在檔頭標了 'use client'。這比自己從空白檔案拼版面快得多，也是官方 AGENTS.md 裡寫的規矩：「先模板、再區塊、最後才是元件」。

注意一個小坑：模板路徑必須是相對專案根目錄，餵絕對路徑會直接被拒：

Error: Invalid template target path "/tmp/...": absolute paths are not allowed.

實測三：init 寫進 AGENTS.md 的到底是什麼

這是整個系統最有趣的一環。執行 astryx init --json 之後回傳的收據：

{"type": "init.run", "data": {"features": ["agents"],
 "docsWritten": ["AGENTS.md", "GEMINI.md"], "docsError": null}}

而寫進 AGENTS.md 的內容不是空泛的「請遵守風格」，而是操作規格：

• 版本與規模：Astryx v0.7.15 · 174 components
• 必做設定：兩個 CSS import，並註明「沒有這些，元件會渲染成無樣式」
• 工作流程三步：build 挑模板 → template scaffold → component 讀 props
• 硬性規則：不要用 <div>、密集資料用 Table/List 而不是 Card 列表、Badge 只放數量、先用元件 props 再用 token（var(--color-*)）、不要寫死 hex/px
• 自我檢查：交付前把 <div>／<span>／寫死的顏色與 px 換掉，並跑 astryx doctor --built <dir>，檢查失敗就不要交付

這段話的價值在於它是可被 commit、可被 review、可被 diff 的。比起在 prompt 裡貼一段風格指南，這種放在 repo 裡的做法，換一個代理接手也不會走鐘。

實測四：doctor 的 31 項檢查與 CI gate

astryx doctor 不是印個「一切正常」的吉祥物。本次實測回 31 項檢查，分佈是 16 pass、11 info、2 warn、2 fail，涵蓋：

其中兩個 fail 值得誠實寫出來：本次刻意寫了一支只 import 主題模組、沒有 import theme.css 的測試腳本，doctor 直接抓出來：

theme-stylesheet-imports  [fail]
render_test.mjs imports neutral without @astryxdesign/theme-neutral/theme.css

也就是說「元件長得怪」這種最常見的症狀，它會指到具體檔案而不是叫你通靈。加上 --json 與 --built <dir>，這條檢查可以直接掛進 CI：交付前建置、跑 doctor、失敗就擋 PR。

主題系統：7 套主題、198 個變數、279 個可覆寫點

Astryx 的主題不是「換一份 CSS」，而是三層：

1. 主題包（@astryxdesign/theme-*）：7 套現成主題，astryx theme list 顯示 7 套可用，本次 theme add neutral 後產生一份 astryx-themes.js：

/** @generated by `astryx theme` — do not edit manually. */
import {neutralTheme as _astryxTheme0} from "@astryxdesign/theme-neutral/built";
import "@astryxdesign/theme-neutral/theme.css";
export const themes = {"neutral": _astryxTheme0};
export const defaultThemeSlug = "neutral";

2. 設計 token：theme.css 內定義 198 個 CSS 自訂屬性，官方文件把它分成 color／data（圖表）／syntax（程式碼高亮）／spacing／size／border／focus／radius／shadow／duration／typography 共 11 類。
3. 元件級覆寫：astryx theme targets 列出 279 個 theming target、涵蓋 98 個元件，每一筆標明元件、可覆寫的 props、狀態與對應的 className。

要更細還能 defineTheme() 寫自訂主題（theme template 會產生帶註解的樣板），或 theme eject 把主題原始碼 fork 出來自己改——但官方提醒 eject 只該用在「要完全接管」的情況，日常換色用 palette 就夠。

模板與區塊：58 + 723 是真的能省時間

58 個頁面模板對應的是常見頁型（settings、table-tree、dashboard、detail、wizard、AI Chat…），723 個區塊是可插進頁面的段落。這套「頁面模板 vs 區塊」的分工很重要：

• 頁面模板只給骨架（Layout + header／content／panel 三個 slot），不含導覽；導覽要自己包 AppShell／TopNav／SideNav。
• 區塊模板是內容片段（banner、表單段、列表段），用來補模板缺的部分。
• 元件才是最後的原子。

這個順序寫在 AGENTS.md 裡，也是 astryx build 的預設引導。實務上它的效果是：代理不會一開口就開始 <div> 排版。

跟 shadcn/ui、Tailwind 怎麼比？

先說清楚方法論：這一節是文件與機制層的比較，不是跑分。本次沒有在同一個專案裡把 shadcn/ui 與 Astryx 各建一版做 bundle 與 Lighthouse 對照，所以下面沒有性能數字。

如果你的團隊偏好「程式碼在我 repo 裡、想改什麼就改什麼」，shadcn/ui 的模式更直接；如果你要的是「150+ 元件的行為與無障礙都有人負責、而且換主題不用改元件」，Astryx 的模型省事得多。混合用法也存在：Astryx 官方明說可以用 Tailwind 的 className 覆寫，不強迫你放棄現有工具鏈。

已知限制與沒做的事（重要）

產品文最該寫的就是這一段：

1. 還是 Beta。 0.7.x 代表 API 仍可能變動，官方也把 @astryxdesign/lab 保留在內部、charts 與 vega 只發在 @canary（charts 在 npm 上的 latest 甚至是「佔位用，請勿安裝」的 0.0.0-bootstrap.0）。要圖表得先接受 canary 風險。
2. 沒有實跑完整框架建置。 本文的驗證是「安裝 + SSR 渲染 + CLI + 模板 scaffold」，沒有跑 Next.js 或 Vite 的 production build、沒有跑 ESLint／StyleX 編譯器路徑、沒有做 Lighthouse 或 bundle 分析。你如果用的是 Next.js + Tailwind 的組合，請照官方 docs 的對應章節走一遍再決定。
3. 部分模板需要 StyleX 編譯器。 AGENTS.md 自己寫了：「No StyleX/Tailwind compiler here」，但同時註明「有些模板用 StyleX，需要編譯器外掛」。這兩句話放在一起要小心讀：元件本身不用編譯器，複製出來的模板原始碼可能要用。
4. 依賴沒有全部自動安裝。 template settings 會提示 npm install @heroicons/react@"^2.2.0"，但不會替你裝。加上 @stylexjs/stylex 是 peer dependency，套件管理員沒處理好就會在執行期炸。
5. 文件與實測數字有小落差。 README 寫「150+ 元件」，CLI 實際回報 174；swizzle 在 manifest 裡標記為「專案外呼叫會被拒絕（refuse）」，實測在專案外執行的錯誤訊息是找不到 @astryxdesign/core（不是 ERR_PROJECT_REQUIRED）。這類落差在 Beta 階段屬於正常，但寫自動化腳本時別把 manifest 的字面當唯一真理。
6. 簡中翻譯不完整。 實測 component Button --zh 回的是英文（該元件尚無翻譯），不是錯誤，但別期待全站都有中文文件。

誰適合、誰不需要

適合：React 19 專案、需要大量表單／表格／設定頁的 B 端產品、團隊已經在用 coding agent 寫前端而苦於「每次產出的風格都不一樣」、需要無障礙規格有明確依據（Astryx 的元件文件會寫清楚對比度要求，例如按鈕文字 4.5:1、圖示 3:1、Badge 14 種顏色 × 3 狀態 × 2 模式共 336 組）。

不需要：只做 landing page（Tailwind 更快）、想完全擁有元件原始碼（shadcn/ui 更合適）、需要圖表而無法接受 canary（等 stable）、或團隊不在 React 生態（目前只有 React 與一個 native 套件在建置清單裡）。

五分鐘上手的最小路徑

# 1. 安裝（core + 一套主題 + CLI）
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli

# 2. 讓代理（和你自己）知道規則
npx @astryxdesign/cli init          # 寫 AGENTS.md / GEMINI.md
npx @astryxdesign/cli doctor        # 31 項檢查，先修再開工

# 3. 從模板開始，不要從空白檔案開始
npx @astryxdesign/cli build "settings page for API keys"
npx @astryxdesign/cli template settings --type page app/settings.tsx

# 4. 查規格再改
npx @astryxdesign/cli search button
npx @astryxdesign/cli component Button --detail compact

唯一必須自己記得的一件事：在 app 入口匯入 reset.css 與 astryx.css，否則你會得到一堆沒有樣式的正確 DOM，然後花半小時懷疑人生。

站內延伸閱讀

• Penpot 完整教學 2026：開源 Figma 替代品，Design Tokens 到 MCP — 設計端要自架時的另一半：設計檔與 token 怎麼留在自己手上。
• Agent Skills 完整教學：讓 Claude Code、Cursor 自動遵循工程紀律 — AGENTS.md 這類「把規矩寫進 repo」的做法，背後的方法論。
• Tailwind CSS：以工具優先的 CSS 框架實現快速 UI 開發 — 如果你的專案已經在 Tailwind 上，Astryx 的共存方式與取捨。

原始來源

• GitHub：meta/astryx（MIT）
• 官方文件 ／ Storybook ／ Sandbox
• npm：@astryxdesign/core ／ @astryxdesign/cli
• 套件內文件：packages/cli/README.md（CLI 完整規格、錯誤碼表、capability manifest）

本文數字除特別註明外，皆為 2026-11-12 在本機（Node v26.7.0、npm 11.19.0、Astryx 0.7.15）實際安裝與執行所得；GitHub 星數、issue 數以當日 API 查詢為準，會隨時間變動。