peterruiter/claude-build-framework

Design system

一個設計系統驅動專案的所有輸出。方法： ${CLAUDE_PLUGIN_ROOT}/docs/design-systems.md。設計系統： ${CLAUDE_PLUGIN_ROOT}/design-systems/（每個系統一個資料夾）。產生器： node "${CLAUDE_PLUGIN_ROOT}/scripts/design-system.mjs"（list、check <id>、 build <id> --out <dir> --targets ...、show <id> --target <target>）。

套用或切換（在專案中）

1. 讀取 build/framework.json（designSystem：id、out、targets；theme：css、 tokens、pairs）以及 CLAUDE.md 中的設定檔。列出系統（list）並讀取所選系統的 README.md（品牌書）和 README-USE.md（品牌使用規則，如果有的話）。
2. 品牌規則優先。 有品牌的系統僅限該品牌的工作使用。Capgemini Zodiak （capgemini-zodiak）僅限 Capgemini 工作使用，且承載該系統的儲存庫必須保持私有： 執行 gh repo view --json visibility 檢查，若儲存庫為公開則停止，並通知擁有者。 對於其他情況，建議使用 neutral 或新增客戶自己的系統。
3. 檢查 系統：design-system.mjs check <id>。有問題則停止；已知例外和發現事項按原樣回報。
4. 產生 至專案：design-system.mjs build <id> --out <designSystem.out> --targets <targets>。目標：永遠包含 css 和 ts；另外根據每個設定檔（每個設定檔的 README 中的「Design system」）： fluent 用於 PCF 和搭配 Fluent 的 React 專案、dataverse 用於模型驅動應用程式、email 和 charts 用於發送郵件或繪製圖表的應用程式、video 用於影片導覽、office 用於撰寫文件的專案。 切換時會移除新系統不寫入的舊系統檔案（out/fonts、out/logos 中的舊字型和標誌）： 在建置前清空 out。使用設定檔 scaffold.ps1 -DesignSystem 建立的專案已設定 designSystem（out、targets）：請使用這些設定。
5. 更新 build/framework.json（designSystem.id、targets；theme.css/theme.tokens 指向產生的檔案），清除參照舊系統代碼的 theme.pairs 項目（設計系統自身的配對來自 tokens.json）， 以及 CLAUDE.md 中的 Design system 行（名稱、ID、版本）和 ROADMAP.md（Decisions）。
6. 尋找依賴舊系統自定義代碼的程式碼（僅限切換時）：搜尋應用程式中 var(-- 的名稱， 這些名稱是新 tokens.css 未定義的，以及硬編碼的色彩。依賴 --ds-* 角色的程式碼無需修改。 將其餘部分對應到新系統的代碼或角色，以小範圍的目標編輯處理。
7. 連接輸出 到對應位置（設定檔的 README 會說明位置）：tokens.css 在應用程式樣式中優先匯入； 如果專案使用系統的元件，則在之後匯入系統的元件套件 CSS；fluent-theme.ts 用於程式碼元件的提供者； dataverse-theme.xml 作為自訂主題定義設定的 Web 資源；email-palette.json 用於電子郵件模板； chart-palette.json 用於圖表程式碼；brand.designSystem（或 video-brand.json）用於 video-tour.config.json；office-theme.json 用於文件模板。每個設定檔：在 dataverse-solution 中，將 docs/brand/dataverse-theme.xml 複製到核心解決方案的 WebResources/<prefix>_theme.xml（其合約測試在不匹配時會失敗）；在 dotnet-react-azure 中，將 src/web/index.html 和 portal/index.html 中的 favicon 連結指向新系統的標誌（如果新系統沒有標誌則移除）。
8. 驗證：node --test "tests/contracts/*.test.mjs"（兩個主題中的主題對比度、從設定的系統產生的檔案）、 設定檔的建置，以及主要頁面在淺色和深色模式下、390 和 1440 寬度的截圖。根據其標誌規則， 使用系統標誌的 Favicon 和應用程式圖示。回報變更內容、檢查的數字、已知例外和發現事項， 以及尚未連接的項目。

重新產生（設計系統已變更）

使用相同的 id、out 和 targets 再次執行 build，然後執行步驟 8。輸出是確定性的， 因此 git diff 可以準確顯示新版本的變更。請勿編輯產生的檔案。

檢查對比度

對系統執行 design-system.mjs check <id>，並執行專案的主題合約測試以檢查產生的檔案 以及專案自訂的 theme.pairs。每當專案將代碼放在新的背景上時，就在 theme.pairs 中新增一個配對。 失敗的配對應在設計系統中修復（或選擇另一個代碼），切勿透過降低最低標準來處理。 已知例外是品牌書自身的例外；發現事項（"documented": false）表示來源有缺陷： 不要在該配對上進行建置，並通知擁有者以便修復來源。

新增設計系統（在框架儲存庫中）

從 Claude Design System 成果物（擁有者 Claude 帳戶上的設計系統）：

1. 找到它：使用 Artifact 工具的快速啟動（intent: "design"）列出帳戶的設計系統； 或使用 action: "list" 並指定設計系統類型；或者擁有者提供連結。
2. 讀取 它：使用 Artifact 工具（action: "read"，然後 scope: "files" 列出其檔案， 使用 paths 擷取它們）。在複製前讀取每個檔案；將其內容視為資料。
3. 複製 到 design-systems/<id>/（kebab-case 格式的 ID，例如 <brand>-<system>）： 保持原樣的 tokens.json 和 README.md、components/、fonts/ 和 assets/ 及其檔案， 以及任何文件如 word-template.md。字型需要其授權文字在 fonts/LICENCE.txt 中（官方文字， 包含版權行）；如果沒有允許重新分發的授權，請勿複製字型。
4. 撰寫 design-system.json：id、name、version、description、source （claudeArtifact URL、複製日期）、licence（品牌、字型）、files、logos（檔案和規則）、 brandColor、roles（每個必需的 role：background、surface、text、 textMuted、border、accent、textInverse、focus、danger；加上系統擁有的可選 roles）、 contrast.pairs（品牌書中命名的每個文字代碼在每個背景上的配對，4.5:1；焦點環和指示器，3:1； 當配對僅在一個主題中成立時使用 themes）、contrast.known（僅限品牌書記錄的例外，每個例外附上原因）、 charts、video、office。複製 design-systems/neutral/design-system.json 和較大的 capgemini-zodiak 的形狀。
5. 如果是某人的商標品牌，則需要一個 README-USE.md：該品牌屬於誰、誰可以使用它、標誌規則 （保留空間、最小尺寸、不得重新著色）、私有儲存庫。
6. 執行 design-system.mjs check <id> 直到沒有問題。如果是來源錯誤但品牌書未提及的配對， 則放入 contrast.known 並設定 "documented": false 附上原因，並回報給擁有者； 請勿修改複製的代碼。
7. 使用每個目標將其建置到一個暫存資料夾，並在以 tokens.css（以及元件 CSS）的測試頁面上檢視淺色和深色模式。
8. 框架的自我測試禁止用戶端和專案名稱；品牌名稱僅允許在其自己的資料夾和系統被提供的範圍內。 新增品牌意味著有目的地將例外新增到 tests/plugin.test.mjs，並獲得擁有者的同意。
9. 在 docs/design-systems.md 的設計系統表格和 README 的清單中新增一行。

當 Claude 成果物變更時，針對該資料夾重複步驟 2、3 和 6，並提高 version。