【2026 最新】Astryx 教學：Claude Code 怎麼做繁中表單？CLI、Skill 與共用主題五步實作

你裝好元件庫，請 Claude 做報名頁，結果按鈕一種風格、輸入框另一種，錯誤訊息又自己長出第三套。這篇 Astryx 教學帶你解開這個結：讓 Agent 先找到手冊，再用同一套元件與主題，完成一頁可以填寫、確認、返回修改的繁中表單。

前半專為沒有設計系統背景的讀者寫；操作段需要能開啟終端機、已有 Node.js 與可用 Claude Code 的電腦。你不必先背 React API，但要知道每一步是在裝材料、查手冊，還是在驗收作品。練習使用虛構品牌「山間學堂」，只處理假資料，不連接報名後台。

先說結論：一致的表單＝元件＋文件入口＋共用主題＋行為驗收

Astryx 像一盒有規格書的積木；CLI 是查零件的櫃台，Skill 是提醒助手先查櫃台的工作守則。裝好積木，不代表助手已讀過規格；用了同一種顏色，也不代表按鈕真的能完成任務。今天把這四件事接起來。

截至 2026 年 11 月 13 日，官方 README將 Astryx 標為 Beta，核心使用 React 19 以上與 StyleX。本文的隔離專案實際安裝 Core、CLI、neutral 主題 0.7.15，使用 Node 24.15.0、React 19.3.1、Vite 8.3.8；這是本次跑通的組合，不是所有版本都已驗證的相容清單。

一、Astryx 教學先認五個零件：別把安裝都叫成 Skill

• ① 元件：「現成積木」。@astryxdesign/core 提供 TextInput、Button 等 React 元件，程式匯入後才能使用。
• ② 主題：「共用顏料與尺寸」。@astryxdesign/theme-neutral 提供視覺設定。Token 是有名字的設計數值，例如文字色、間距；比每個地方各填一個色碼容易維持一致。
• ③ CLI：「查文件的櫃台」。@astryxdesign/cli 是在終端機執行的工具，可搜尋、讀元件文件、產生頁面範本。
• ④ 專案指引與 Skill：「助手的工作守則」。它們是 Agent 讀取的文字指引。Claude Code 的 Skill 文件說明了 SKILL.md 的載入與呼叫方式；把元件套件裝進專案，與把指引交給 Agent，是不同動作。
• ⑤ Plugin：「把擴充包成一份」。Claude Code Plugin可包含 Skill、Agent、Hook 等元件。它的分發方式，與網站本身使用哪個版本的 UI 套件，應各自核對。

題目線索中的 11 月 10 日 RFC提出 Plugin 入口需求，作者也明說沒有使用頻率證據。查到的 11 月 13 日主分支已包含 官方 marketplace manifest 與 plugins/astryx；因此不能沿用「Plugin 還只是提案」的說法。本文採用專案內 CLI 與 init 路線，先把可重跑的作品做出來。

二、Astryx 教學實作：五步完成第一張繁中表單

第 1 步：「我的電腦能跑嗎？」先固定練習環境

打開終端機，先跑 node --version 與 npm --version。CLI 0.7.15 的套件宣告要求 Node ≥22.13.0；但 最低 Node 版本追蹤 issue在 11 月 11、12 日記載測試失敗。這只證明那些 CI 執行出了問題，不能推成每個人的 Node 22 都壞掉。想沿本文做，先用已具備的 Node 24 環境。

另開空資料夾，依序執行 npm create vite@9.3.4 astryx-form -- --template react-ts --no-interactive，再 cd astryx-form。Vite 是把開發頁面跑起來、最後打包的工具；官方入門文件也列出了建立專案的操作方式。這裡選 TypeScript，讓拼錯元件屬性能在建置時被找出來。

接著逐條完成：npm install --save-exact @astryxdesign/core@0.7.15 @astryxdesign/theme-neutral@0.7.15 @stylexjs/stylex@0.19.0；等它結束，再跑 npm install --save-dev --save-exact @astryxdesign/cli@0.7.15。用 npm ls --depth=0 留下版本，保留 package-lock.json。不要一邊安裝、一邊啟動 CLI。

第 2 步：「Agent 找得到嗎？」建立專案自己的文件入口

照 Core 官方起步說明，先執行 npx @astryxdesign/cli init。這個完整套件名稱很重要：尚未安裝 CLI 時，npx astryx 可能解析到另一個不相干套件。接著執行 npm pkg set "scripts.astryx=node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"，後面統一用 npm run astryx -- …。

本次 init 寫入 AGENTS.md 與 GEMINI.md。請打開看實際生成了什麼；若這個新專案沒有 CLAUDE.md，建立它，放一行 @AGENTS.md，讓 Claude Code 匯入同一份內容。已有 CLAUDE.md 的專案，保留原文再加入匯入；官方專案記憶文件說明了這種匯入語法。

全域 CLI 是另一條方便路徑：官方提供 npm i -g @astryxdesign/cli，讓不同資料夾能找到命令。本文不以全域版本作為作品依賴；新電腦要重跑的是專案內套件與 lockfile。雲端環境也應確認它實際讀到了哪份專案指引，而非假設你電腦上的個人 Skill 已跟著過去。

第 3 步：「用什麼積木？」先查，再產生範本

依序執行 npm run astryx -- build "one page workshop registration form"、npm run astryx -- search form。本次 build 回傳最接近的 contact-form 頁面範本；這是推薦起點，還不是完成品。再跑 npm run astryx -- template contact-form --type page src/Registration.tsx，讓檔案真的落地。

把 npm run astryx -- component TextInput、npm run astryx -- component Button、npm run astryx -- component FormLayout 的結果交給 Agent。官方 TextInput API定義的 onChange 第一個參數就是字串，因此可寫 onChange={setName}，別從其他元件庫照抄 event.target.value。

另一個容易猜錯的地方：FormLayout 負責排列，提交行為仍放在原生 <form>；TextInput 本身已有 label 與 status 介面，這次直接使用。Button 的文字用 label="確認資料"，提交按鈕加 type="submit"。先核對屬性，比生成後逐個修錯省事。

第 4 步：「為什麼還是不同風格？」把根節點接到同一主題

執行 npm run astryx -- theme add neutral。本次產生 src/astryx-themes.ts，其中已匯入主題 CSS 與字型 CSS。請 Claude 修改 src/main.tsx：先依序匯入 @astryxdesign/core/reset.css、@astryxdesign/core/astryx.css，再載入生成的 themes 模組。

從 @astryxdesign/core/theme 匯入 Theme，從 ./astryx-themes 匯入 themes、defaultThemeSlug；把 App 包成 <Theme theme={themes[defaultThemeSlug]} mode="light"><App /></Theme>。先固定亮色，方便比對；之後要跟系統明暗，再單獨改 mode 並重驗。刪除 Vite 範例對 App 的舊 CSS 引用，避免舊樣式干擾。

繁中也有兩層：index.html 設 lang="zh-Hant"，自己的標題、按鈕、錯誤全部寫繁中；元件內建字串則使用 InternationalizationProvider，從 @astryxdesign/core/i18n 匯入，並載入 @astryxdesign/core/locales/zh-TW.generated.js。設定 locale="zh-TW" 與 messages={{"zh-TW": zhTW}}。本次畫面中的「必填」，就是需要一併驗收的內建文案。

第 5 步：「怎樣才叫完成？」交一份能被測試的需求

在此專案啟動 Claude Code，貼上下面這份需求。先讓它讀文件、列計畫，再在同一專案實作；登入與使用成本沿用你現有的 Claude Code 帳戶，這個練習不要求另外購買模型 API。

• 讀取 CLAUDE.md 與 AGENTS.md，使用專案的 npm run astryx -- 查 API。以剛生成的 contact-form 為起點，保留 Center → VStack → Section 的頁面框架；Section 設 width=”100%”、maxWidth={800}、padding={6}、paddingBlock={10}。
• 把 src/App.tsx 改為虛構「山間學堂」單頁練習，只留「稱呼」與「Email」兩個 TextInput，以及「確認資料」Button；移除未使用的範例檔與匯入。標題用 Heading level={1}，欄位用 FormLayout 排列。
• 用 React state 保存兩個欄位。第一次確認前不顯示錯誤；確認時稱呼需有非空白文字，Email 用簡單格式檢查。這只檢查字串形狀，不驗證信箱存在。錯誤透過 TextInput 的 status={{type: 'error', message: '請填寫稱呼。'}} 顯示，並把焦點移到第一個錯誤欄位。
• 用原生 form 處理提交並 preventDefault；中文組字期間保留 composition 狀態，避免尚在選字時切換確認畫面。確認成功後顯示姓名與 Email，標題為「已完成資料確認」，把鍵盤焦點移到該區域；「返回修改」保留原值。
• 在確認畫面清楚顯示「這是本機練習，尚未送出正式報名」。資料只留在 React state；不加入 API 提交、付款或追蹤。main.tsx 使用前一步的共用 Theme 與繁中語系；body 字型沿用主題 token 並保留繁中字型 fallback。
• 最後執行 npm run build，修完型別與匯入錯誤，再以 npm run dev -- --host 127.0.0.1 啟動；回報修改檔案、實際版本與測試證據。

這個流程最值得留下的 trace（一步步的狀態紀錄）是：空表單 → 確認 → 欄位錯誤 → 填入假資料 → 確認畫面 → 返回原值。你能逐格說明發生什麼，才知道作品的狀態由誰管理。元件提供外觀與互動基礎，業務規則仍是 App 的工作。

三、先驗行為，再調顏色：手機、中文與鍵盤四張考卷

• 手機：把瀏覽器縮到 390px，另加 320px 人工檢查。長 Email、錯誤訊息與按鈕都要完整；檢查是否橫向捲動。這次自動驗了 390px，沒有橫向溢出；320px 列為讀者可加做的條件。
• 錯誤：空白確認應出現兩個欄位錯誤；填錯 Email 再修正，觀察訊息是否跟著更新。不要只把邊框變紅，要有可以照做的文字。
• 鍵盤：從稱呼用 Tab 到 Email、再到確認按鈕；送出成功後，焦點應進入確認區。返回修改要看到原值，不能只看到空白的漂亮頁面。
• 中文組字：用你平常的輸入法輸入稱呼，按 Enter 選字，確認不會誤送出，再按按鈕確認。這次只跑了合成 composition 事件的程式測試，未操作實體中文輸入法；兩者不能畫等號。

本次還核對了建置成功、錯誤欄位的 aria-invalid、確認區焦點，以及返回後兩個欄位保留；這些結果只涵蓋保存的樣本與 Chromium 設定。要交給真實使用者，再照 跨瀏覽器驗收教學補上目標瀏覽器與裝置。

四、四個常見坑：先找缺的是哪一層

• 命令找不到：先確認在含 package.json 的資料夾，跑 npm ls @astryxdesign/cli 與 npm run astryx -- --version。專案命令跑通後，再排全域 PATH；別先重裝所有工具。
• 元件像沒穿衣服：查 reset、astryx 元件 CSS、主題 CSS 與 Theme 包覆。這篇採預編譯輸出；不要把貢獻者建置 StyleX 原始碼的設定，直接塞進新手使用路徑。
• Agent 憑印象寫屬性：拿錯誤訊息回查 component TextInput，讓它說明每個 prop 的來源。Skill 提醒查手冊，TypeScript 與瀏覽器才告訴你這次是否寫對。
• 看見成功就以為已報名：本例只切換 React state，重新整理會回到起點。真正接上後台時，還要另做伺服器驗證、儲存、失敗處理與重複提交控制；那是下一個功能範圍。

把成果保存成一個小型專案：保留 src、index.html、package.json、package-lock.json、AGENTS.md 與 CLAUDE.md，再留 build 與測試紀錄。重建時執行 npm ci、npm run build。主分支 README、npm 發布版、你專案內的 CLI 可能不同步；排錯先報這三個版本位置，別只說「我用最新版」。

常見問題：八個先講答案的判斷

1. 裝好 Astryx，Claude 就會自動使用嗎？

還要確認指引與入口。讓它讀專案檔並實際執行一次 search，再核對產物匯入了什麼。

2. 一定要全域安裝 CLI 嗎？

本篇路徑用專案內 CLI 就能完成。全域安裝可方便跨專案找到命令，作品仍保留本地依賴版本。

3. 現在能說 Plugin 只是提案嗎？

不能沿用舊結論。11 月 13 日查到的主分支已有 marketplace 與 Plugin 目錄；是否採用該入口，還要核對當下文件與環境。

4. Theme 會替我翻譯整張頁面嗎？

文案要另外處理。自己的 label 與錯誤寫繁中，元件內建字串用語系 provider 與 catalog；主題處理視覺。

5. TextInput 的 onChange 要讀 event.target.value 嗎？

這份 API 的第一個參數就是字串。用 onChange={setName}；需要事件時再讀第二個參數。

6. 顯示「已完成資料確認」代表報名成功嗎？

本例只完成本機確認。正式報名要有後台儲存與回應，畫面用語必須說清楚目前做到哪一步。

7. 自動測試通過，中文輸入就驗完了嗎？

還要用實際輸入法操作。合成事件只驗程式分支，不能替不同系統的選字與送出行為背書。

8. 今天做到哪裡算入門？

把空白錯誤、有效確認、返回保留與手機版都走過，並能用 lockfile 重建，就是一個可檢查的第一頁。

給新手的三個重點

第一，先讓 Agent 找得到文件，再要求它寫元件。第二，整頁共用一套主題與語系，別每個欄位各自補樣式。第三，用狀態與操作證明完成，別只交一張截圖。一致的表單＝元件＋文件入口＋共用主題＋行為驗收。