開發須知

本頁彙整專案開發與維護慣例，供貢獻者與維護者參考。

元件分類

新增元件分類時，依「主要互動方式」而非「效果作用對象」判斷：

• 跟隨滑鼠移動 → cursor-
• 包裹內容 → wrapper-
• 作用於靜態文字塊 → text-

即使效果作用在文字上，只要元件跟著滑鼠移動，就歸 cursor-。

元件文件

techKeywords

中文元件文件 frontmatter 的 techKeywords 每一項，必須精準對應 src/constants.ts 中 techKeywordList 的 name 欄位（例如用 Canvas 2D API 而非 Canvas 2D、粒子系統 而非 粒子動畫）。

對不上時，npm run docs:build 會印出 找不到技術關鍵字: xxx（僅警告、不中斷），且該關鍵字會從 <tech-keyword-table /> 表格中被濾掉。新增關鍵字須先加進 techKeywordList 才能使用。

英文文件（docs/en/…）慣例不放 techKeywords，也不引入 tech-keyword-table。

雙語同步

修改中文元件文件後，須同步更新對應英文版（docs/en/…），保持雙語一致。

範例元件

範例元件（如 docs/step-by-step/bg-starry-sea/examples/）中的說明文字，一律用 <span> 不用 <p>。<p> 自帶的 margin 會讓元件內部上下間距過大，影響排版。