PingYang0717/frontend-design-skill

前端專案啟動（Frontend Project Bootstrap）

將 UI/UX 交付的 prototype 轉換為「團隊標準的前端專案 + 已填寫的文件 + 可開工的任務清單」，確保後續不同人員或不同 coding agent 所撰寫的程式碼風格一致。

版本：請見 CHANGELOG.md 中最上方記錄。

核心原則

1. prototype 是需求素材，不是要搬進專案的程式碼。 從中擷取畫面、資料、色票與互動邏輯，但不複製其實作方式；原始檔案與截圖應存放於 repo 中作為驗收標準。
2. 團隊規範原樣複製，專案內容依據 prototype 填寫。 兩類檔案的處理方式不同（請見下方「檔案索引」）。
3. 不確定就問，不要猜測。 問題應在停頓點分輪提出，每個問題附上建議答案；若使用者回答「是」即代表接受建議。
4. 不實作業務功能。 此 Skill 僅建立骨架、空白頁面與文件；業務功能後續將由 /implement 根據任務清單開發。
5. 驗證通過才算完成。 lint、typecheck、test、build 全部綠燈，無殘留 placeholder，每個畫面皆有截圖。

需要的輸入

• prototype（單一 HTML、多頁 HTML、設計工具連結或截圖）及其版本/交付日期
• 專案名稱與一句話說明
• 新專案的資料夾位置（必須是空資料夾或全新的 repo；若已有內容則先停止並確認）

其餘資訊（部署環境、後端現狀、語言、深色模式等）將在步驟 1 中詢問；詳細說明請見 references/workflow-detail.md。

事前準備（每台機器僅需執行一次）

cd <skill> && npm ci && npx playwright install chromium   # 用於 scripts/ 中的 Playwright 與 Prettier；不會納入專案骨架
# 若機器上已有 Chromium，可不下載，執行截圖腳本時改用環境變數 CHROMIUM_EXECUTABLE=<路徑>

流程

建立任務清單追蹤以下五個步驟，每完成一個步驟即標記為完成。

步驟 1：收件

首先確認專案資料夾不存在或是空的（若已有內容則停止並詢問）。接著確認 prototype 檔案、版本與團隊共享的存放位置，並詢問 references/workflow-detail.md 步驟 1 表格中訊息裡尚未提供的項目。

步驟 2：分析 prototype 並擷取截圖

閱讀 references/prototype-analysis.md，依照其方法進行分析，產出 docs/_bootstrap/prototype-analysis.md（格式：templates/prototype-analysis.md）。若 prototype 是 HTML，則將原始檔案放入 docs/prototype/，填寫 docs/prototype/screens.json（格式：templates/prototype-screens.json），執行截圖腳本產生每個畫面的 PNG。

⏸ 停頓點： 依據 references/prototype-analysis.md 的「停頓點」分輪提問：待確認問題、缺漏狀態的預設處理方式、路由模式（history/hash）、後端現狀。收到回答後記入分析文件的第 11、12 節，再繼續進行。

步驟 3：建立骨架

複製 assets/skeleton/（排除 node_modules），執行 npm ci，然後依照 references/workflow-detail.md 步驟 3 修改名稱、色票、路由模式、路由與選單、空白頁面、權限程式碼。保留 Item 範例功能直到第一個真實功能開發完成。

步驟 4：產出文件

依據 references/workflow-detail.md 步驟 4 的對照表複製並填寫文件。所有 <!-- FILL: --> 標記應依照指示填寫完畢後刪除該註解，所有 {{PLACEHOLDER}} 應替換為實際內容。若不清楚則填入「待確認」，不得編造內容。

步驟 5：驗證、提交與回報

npm run lint && npm run typecheck && npm test && npm run build
node <skill>/scripts/check-placeholders.mjs <project>

四項檢查全部綠燈（lint 無 warning）、檢查腳本回報 0 個 ERROR 才算完成；接著進行第一次 commit。 回報格式請見 references/workflow-detail.md 步驟 5。

若使用者不在場時：對於有建議答案的項目，採用建議並標記「採用建議（暫定）」；沒有建議答案的項目則寫「待確認」，繼續進行流程；兩者都需列在回報中。唯一需要停止的情況是專案資料夾已有內容。

檔案索引

原樣複製（僅可替換名稱，不得改寫內容）

路徑	複製到	內容
assets/skeleton/	專案根目錄	可執行骨架：設定檔、api 層、資料 hook、DataBoundary、權限、i18n、theme、MSW、測試、CI（Azure DevOps）、PR 範本、Item 範例功能
references/standards/	docs/conventions/	18 份團隊開發規範 + 索引
references/adr-baseline/	docs/adr/	ADR 0001–0016 + 索引
templates/agents/	docs/agents/	mattpocock skills 的 tracker 與 domain docs 設定（local markdown、single-context）

依據 prototype 填寫

範本	產出
templates/prototype-analysis.md	docs/_bootstrap/prototype-analysis.md
templates/prototype-screens.json	docs/prototype/screens.json（截圖腳本輸入）
templates/README.md、AGENTS.md、ARCHITECTURE.md、GLOSSARY.md	專案根目錄
templates/CLAUDE.md	專案根目錄（Claude Code 的轉接檔：一行說明註解加上 @AGENTS.md，原樣複製）
templates/prototype-README.md	docs/prototype/README.md
templates/adr-router-mode.md	docs/adr/0017-router-mode.md
templates/api-interface-auth.md、api-interface.md、api-checklist.md	docs/api/
templates/feature-spec.md	docs/specs/<feature>.md
templates/task.md、tasks-README.md、task-remove-example.md	docs/tasks/
templates/adr.md、bug-report.md 等	另存一份到 docs/templates/ 供後續使用

說明文件與工具

路徑	使用時機
references/workflow-detail.md	每一步的具體做法、指令與檔案對照
references/prototype-analysis.md	步驟 2
scripts/screenshot-prototype.mjs	步驟 2（prototype 改版時也需重新執行）
scripts/check-placeholders.mjs	步驟 5

整合 mattpocock skills

此 Skill 的產出即為 mattpocock/skills 的輸入；專案不需要再執行 /setup-matt-pocock-skills（即使執行，也只會原地更新 AGENTS.md 的 ## Agent skills 與 docs/agents/，請勿讓它寫入 CLAUDE.md）。

該 skill	對應到這裡
/grill-with-docs、grilling	步驟 2 的停頓點即為同一種訪談；後續如需修改設計，可直接使用它，名詞定義記在 GLOSSARY.md、決策記錄在 docs/adr/0018+
domain-modeling	讀寫 GLOSSARY.md（格式相同）與 docs/adr/（團隊格式，請見 docs/agents/domain.md）
/to-spec、/to-tickets	無需使用。規格已存放在 docs/specs/（Gherkin 編號），任務已存放在 docs/tasks/（包含分層檔案路徑與可重用元件）
/implement	第一版的實作方式：一次只處理一份 docs/tasks/<ID>-*.md，從 main 開分支進行；它會自動呼叫 tdd 與 code-review
tdd	seam（測試接縫）已寫在 AGENTS.md 的「測試 seam」段落，無需再討論
/implement-spec	可使用但尚未測試過：每個 worktree 都需執行 npm ci（husky prepare），Azure DevOps 未支援 draft PR 整合

Agent 工具相容性

AGENTS.md 是唯一的規則來源。opencode 與 Kimi Code CLI 直接讀取專案根目錄的 AGENTS.md；Claude Code 則讀取 CLAUDE.md，因此骨架中附帶一個僅包含 @AGENTS.md 的轉接檔。請勿在轉接檔中另行撰寫規則。

更新此 Skill

若團隊規範需要修改，請直接更新此 Skill（standards、adr-baseline、skeleton 一併更新），並在 CHANGELOG.md 中記錄並升級版本；請勿僅在個別專案中修改。個別專案的偏離應撰寫為該專案的 ADR（從 0017 開始）。 修改 skeleton 後，務必在 assets/skeleton/ 目錄下執行 lint、typecheck、test、build；修改 Markdown 後請執行 npm run format。