啟動一個 React 網頁專案
請先閱讀 web-craft；其規則同樣適用於此。專案中已有的決定優先於以下所有預設值。
1. 需求收集
讀取已給定的內容：產品描述、現有儲存庫、頁面、設計系統、STACK.md、DESIGN.md、API 合約。然後使用 references/intake.md 補足空白項目：介面類型（登陸頁、編輯型、目錄型、消費者應用、管理後台、客戶入口或混合型）、主要使用者與操作、內容或操作密度、裝置、SEO 需求、當前與未來的語言、從右至左書寫支援、認證方式、後端（Node.js、第三方 API、CMS、模擬或靜態）。
僅詢問會改變產品或架構決策的問題。其餘皆陳述為假設。
2. 決定技術設定檔
每項決定附上一行理由。在方向確定之前，不要生成任何畫面。
| 決策項目 | 預設值與決策依據文件 |
|---|---|
| 框架與渲染 | 公開、SEO 或 CMS 為主、多語言 → Next.js App Router。需登入且高度互動 → React + Vite 或現有的 Next.js。簡單靜態介面 → 最簡單可行的方案。references/framework-choice.md |
| UI 套件 | 有獨特風格的品牌產品 → shadcn/ui。表格/表單繁重的管理後台 → Ant Design。Material 風格產品或已使用 MUI → Material UI。現有系統 → 保留原樣。每個應用介面只使用一個主要套件。references/kit-choice.md |
| 樣式 | 跟隨套件：shadcn → Tailwind（shadcn 要求）；Ant Design 或 MUI → 套件的主題，加上自定義部分的 CSS Modules；自定義或編輯型 → CSS Modules。切勿在同一個介面上混合使用 Tailwind 與 CSS Modules 作為同等系統。references/styling-choice.md |
| 國際化 | Next.js → next-intl；Vite → i18next + react-i18next。語言環境註冊表、後備語言、URL 策略與目錄載入方式均在第一天決定。references/i18n-setup.md |
| 動畫 | 簡單狀態使用 CSS 過渡；當需要元件掛載/卸載、佈局或編排動畫時使用 Motion for React。持續時間與緩動標記；減少動畫偏好在一處處理。references/motion-setup.md |
| 表單與資料 | react-hook-form + Zod；TanStack Query 或框架的資料模型；保留現有方案。 |
| 主題 | 互動性產品提供淺色/深色/系統主題；品牌行銷網站可僅使用單一主題作為產品決策。 |
| 測試 | 型別檢查、Lint（使用 eslint-plugin-web-craft 和 eslint-plugin-jsx-a11y）、在行為邏輯處撰寫單元/元件測試、關鍵流程使用 Playwright。 |
| 語言與工具 | 嚴格 TypeScript，每個專案固定使用 Yarn，單一 lockfile。 |
從官方來源驗證每個所選套件的當前穩定版本，鎖定可共同運作的版本，並將其記錄在 STACK.md 中。切勿從記憶或此技能中複製版本號。
3. 撰寫專案文件
STACK.md：框架、渲染、套件、樣式、國際化引擎、資料與表單工具、版本、環境、腳本。 範本：references/stack-template.md。DESIGN.md：產品特性、取自參考資料的原則、版面、標記（顏色、字體、間距、圓角、層級、動畫）、文案規則、動畫矩陣、國際化注意事項。範本：references/design-template.md。- 語言環境列表與型別來自程式碼配置。文件僅描述它們，並非第二個真相來源。
- 不要為每個小改動創建四個新文件。
4. 佈局專案
採用基於功能（feature-based）的結構，伺服器/客戶端邊界清晰，單一 API 層，單一位置存放標記與 Provider：
references/structure.md。
5. 驗證骨架
在構建更多畫面之前，必須先讓一個小型流程完整運作：
- 語言環境在首次渲染時正確解析（無語言閃爍），切換時保持路由。
- 主題遵循使用者選擇與系統設定，載入時無閃爍。
- 表單在失焦時驗證，提交時滾動至第一個錯誤，將伺服器錯誤對應到對應欄位。
- 對話框有進出動畫、焦點侷限並在關閉時歸還焦點；減少動畫偏好移除大幅移動。
- 列表或圖表顯示骨架屏、空白狀態與含重試功能的錯誤狀態。
- 純鍵盤操作正常；無控制台或水合錯誤。
然後構建一個代表性的垂直切片（包含真實內容、第二語言、載入與錯誤狀態），在瀏覽器中以行動裝置與桌面兩種寬度檢查，然後再擴展到其他畫面。
6. 腳本
dev、build、start（Next.js）、typecheck、lint、test、test:e2e。當打包大小預算重要時，新增 analyze。
來源
這些預設值所使用的官方連結，以及審查日期：references/sources.md。請在安裝對應版本時重新檢查它們。