design-systems-slds-validate
熱門稽核 Lightning Web Components 是否符合 SLDS 規範，並產生評分品質報告。執行 SLDS linter，分析 CSS 的 theming hook 使用與配對，檢查 HTML 的無障礙屬性，並將各類別的發現評分為整體等級。當使用者要求「為我的元件評分」、「SLDS 評分卡」、「品質報告」、「稽核 SLDS 合規性」、「我的 SLDS 有多好」、「檢查元件品質」、「為我的元件評級」、「評估我的元件」、「這個元件可以出貨了嗎？」、「檢查我的 LWC 是否有問題」、「提交前稽核這個」、「程式碼審查前檢視我的元件」，或任何時候使用者想要對 LWC 或 SLDS 元件進行品質評估或生產就緒檢查時使用。不適用於修正違規（請使用 design-systems-slds2-migrate）或建立新元件（請使用 design-systems-slds-apply）。
稽核 Lightning Web Components 是否符合 SLDS 規範，並產生評分品質報告。執行 SLDS linter，分析 CSS 的 theming hook 使用與配對，檢查 HTML 的無障礙屬性，並將各類別的發現評分為整體等級。當使用者要求「為我的元件評分」、「SLDS 評分卡」、「品質報告」、「稽核 SLDS 合規性」、「我的 SLDS 有多好」、「檢查元件品質」、「為我的元件評級」、「評估我的元件」、「這個元件可以出貨了嗎？」、「檢查我的 LWC 是否有問題」、「提交前稽核這個」、「程式碼審查前檢視我的元件」，或任何時候使用者想要對 LWC 或 SLDS 元件進行品質評估或生產就緒檢查時使用。不適用於修正違規（請使用 design-systems-slds2-migrate）或建立新元件（請使用 design-systems-slds-apply）。
SLDS 品質稽核
稽核 Lightning Web Components 是否符合 SLDS 規範，並產生自動化評分卡，加上必要的人工審查關卡。結合 SLDS linter 輸出與補充的靜態分析，以捕捉 linter 遺漏的問題。
適用範圍
也適用於：稽核整個專案或元件集的 SLDS 合規性，以及在修改前後進行品質比較。
不適用於：
- 修正 linter 違規 — 請改用
design-systems-slds2-migrate - 建立新元件 — 請改用
design-systems-slds-apply - 僅執行 linter — 直接執行
npx @salesforce-ux/slds-linter@latest lint . - 完整的 WCAG 無障礙稽核 — 此技能僅檢查屬性是否存在（標籤、替代文字、焦點指示），不檢查對比度、鍵盤流程或螢幕閱讀器行為
- 超出
.css、.html和.js檔案的框架特定範本稽核 — JSX/TSX/Vue/Svelte 輸出需要額外的人工審查
品質驗證流程
1. 執行 SLDS Linter → 收集違規計數（linter 的工作）
2. 執行分析腳本 → 檢查 linter 未涵蓋的項目（補充）
3. 代理人工審查 → 必要的人工審查關卡
4. 評分與等級 → 計算自動化分數與最終建議
5. 產生報告 → 產生格式化評分卡
步驟 1：執行 SLDS Linter
執行 linter 以收集基準違規資料：
npx @salesforce-ux/slds-linter@latest lint <component-path> 2>&1
依規則計算違規數。這些直接計入 Linter 合規性 分數：
| 規則 | 影響 |
|---|---|
slds/class-override |
破壞主題化、深色模式 |
slds/lwc-token-to-slds-hook |
SLDS 1 技術債 |
slds/no-hardcoded-values |
破壞主題化、無障礙性 |
Linter 合規性分數 = 100 - (total_violations × 10)，最低 0。
如果 linter 無法使用（沒有 Node.js、沒有網路存取、CI 沙箱限制）：跳過此步驟，在報告標頭註記「Linter 未執行」，將 Linter 合規性標記為 N/A，並使用其餘 4 個類別重新正規化為 100% 來計算整體分數：
整體（linter 無法使用） = (主題化 × 0.29) + (無障礙性 × 0.29)
+ (程式碼品質 × 0.21) + (元件使用 × 0.21)
步驟 2：執行補充分析
執行分析腳本以捕捉 linter 未涵蓋的問題。隨附的分析器僅掃描 .css、.html 和 .js 檔案：
node scripts/analyze-quality.cjs <component-path>
腳本會輸出 JSON，依嚴重性分類發現。它檢查：
CSS 檢查（linter 互補）
| 檢查 | 捕捉內容 | 嚴重性 |
|---|---|---|
| 缺少後備值 | var(--slds-g-*) 沒有後備值 |
嚴重 |
| 發明 hook（T051） | --slds-g-* token 未在 hooks-index.json 中找到（需要 --hooks-index） |
嚴重 |
| Hook 配對 | 背景 hook 沒有對應的前景 hook | 警告 |
!important |
特異性覆寫 | 警告 |
| 魔術像素值 | 硬編碼的 px 未使用間距 hook |
警告 |
| 高 z-index | z-index 值 > 99 | 警告 |
| 移除輪廓 | outline: none 沒有替代的焦點樣式 |
警告 |
JS 檢查
| 檢查 | 捕捉內容 | 嚴重性 |
|---|---|---|
| 內聯樣式指派 | .style.*= 直接屬性指派 |
警告 |
| SLDS 類別操作 | 動態 .classList.add('slds-*') 操作 |
警告 |
HTML 檢查
| 檢查 | 捕捉內容 | 嚴重性 |
|---|---|---|
| LBC 輸入標籤 | <lightning-input> 沒有 label 屬性 |
嚴重 |
| 圖示替代文字 | <lightning-icon> 沒有 alternative-text |
嚴重 |
| 圖片替代文字 | <img> 沒有 alt |
嚴重 |
| 標題階層 | 跳過標題層級（h2 到 h4） | 警告 |
| 正數 tabindex | tabindex 值不是 0 或 -1 |
警告 |
| 可點擊的 div | <div onclick> 而非 <button> |
警告 |
| 內聯樣式 | style="..." 屬性 |
警告 |
| 原生元素 | <input>、<button>、<select> 但有 LBC 替代方案 |
警告 |
Hook 配對驗證
腳本檢查背景/前景 hook 是否在語意上配對：
surface-* 背景 → on-surface-* 文字
surface-container-* 背景 → on-surface-* 文字
accent-* 背景 → on-accent-* 文字
accent-container-* 背景 → on-accent-* 文字
限制： Hook 配對是在檔案層級檢查，而非每個選擇器。一個在
.classA有surface-1、在.classB有on-accent-1的檔案會通過，因為 surface 和 accent 系列都存在。請在人工審查（步驟 3）中逐選擇器檢查配對正確性。
發明 Hook 偵測（T051）
腳本將 CSS 中的每個 --slds-g-* token 與 hooks-index.json 交叉比對。任何未在 metadata 中找到的 hook 都會被標記為嚴重 — 這能捕捉最常見的代理錯誤，即從命名模式發明 hook。
步驟 3：代理人工審查
這些檢查需要理解元件的用途，無法可靠地自動化。審查每個項目，並將發現分類為：
- 阻斷 — 藍圖結構不正確、缺少必要狀態，或語意/互動問題，使元件無法生產就緒
- 建議 — 值得改進但不單獨阻斷出貨的項目
| 審查區域 | 尋找內容 |
|---|---|
| 載入狀態 | 元件在擷取資料時是否顯示 spinner 或 skeleton？ |
| 錯誤狀態 | 錯誤是否以可操作的訊息呈現給使用者？ |
| 空狀態 | 沒有資料時是否有有意義的空狀態？ |
| 停用狀態 | 互動元素是否在視覺和功能上處理停用狀態？ |
| 語意 HTML | 是否在適當處使用 <nav>、<article>、<section>？ |
| SLDS 藍圖合規性 | 卡片、彈窗、表單是否遵循 SLDS 藍圖結構？ |
人工審查發現不會自動化，但會影響最終建議。不要只報告自動化等級作為唯一結論。
步驟 4：計算自動化分數與最終建議
元件複雜度
在評分前，先分類元件以提供分數脈絡：
| 複雜度 | 標準 | 報告註記 |
|---|---|---|
| 小型 | 1-2 個檔案，< 100 行總數 | 分數是高信賴度（表面積小） |
| 中型 | 3-6 個檔案，100-500 行總數 | 分數反映典型元件 |
| 大型 | 7+ 個檔案，500+ 行總數 | 分數反映絕對問題數 — 即使建構良好的大型元件也可能分數較低 |
在報告標頭包含複雜度分類。這可防止將 1000 行元件的「B」誤讀為 20 行元件的「B」。
自動化評分公式
類別分數 = 100 - (嚴重問題 × 10) - (警告 × 3) - (資訊 × 1)
最低分數：0
類別與權重
| 類別 | 權重 | 來源 |
|---|---|---|
| Linter 合規性 | 30% | SLDS linter 輸出（步驟 1） |
| 主題化 | 20% | 腳本：後備值、hook 配對（步驟 2） |
| 無障礙性 | 20% | 腳本：標籤、替代文字、焦點（步驟 2） |
| 程式碼品質 | 15% | 腳本：!important、內聯樣式、z-index（步驟 2） |
| 元件使用 | 15% | 腳本：原生元素（步驟 2）加上人工語意/藍圖審查（步驟 3） |
自動化整體分數
整體 = (Linter × 0.30) + (主題化 × 0.20) + (無障礙性 × 0.20)
+ (程式碼品質 × 0.15) + (元件使用 × 0.15)
自動化等級門檻
| 分數 | 等級 | 意義 |
|---|---|---|
| 90-100 | A | 優異的自動化分數 |
| 80-89 | B | 良好的自動化分數 |
| 70-79 | C | 可接受的自動化分數 |
| 60-69 | D | 薄弱的自動化分數 |
| 0-59 | F | 不及格的自動化分數 |
人工審查關卡
計算自動化分數後，套用人工審查結果：
| 關卡 | 使用時機 | 對最終建議的影響 |
|---|---|---|
| 通過 | 沒有人工發現 | 最終建議可遵循自動化分數 |
| 建議 | 僅有非阻斷的人工發現 | 最終建議最多為「可出貨，但有後續事項」 |
| 阻斷 | 一個或多個阻斷性人工發現 | 最終建議為不適合生產，無論自動化等級為何 |
最終建議規則
同時使用自動化分數與人工審查關卡：
| 最終建議 | 條件 |
|---|---|
| 可出貨 | 自動化等級 A/B，無嚴重發現，人工關卡 = 通過 |
| 可出貨，但有後續事項 | 自動化等級 A/B，無嚴重發現，人工關卡 = 建議 |
| 需要改進 | 有任何嚴重發現，自動化等級 C/D，或人工關卡 = 阻斷 |
| 不及格 | 自動化等級 F |
步驟 5：產生品質報告
使用 report-format.md 中的範本產生最終報告。預設使用精簡格式作為初始輸出，並依要求展開各節。
報告包含：
- 執行摘要，含自動化等級與最終建議
- 人工審查關卡結果（
Pass、Advisory或Blocking） - 各類別分數，含視覺指標
- 依嚴重性分類的詳細發現
- 特定程式碼位置與建議
- 必要行動的檢查清單
快速驗證模式
用於快速品質檢查，不需完整分析：
- 執行 linter：
npx @salesforce-ux/slds-linter@latest lint <path> - 依類型計算違規數
- 僅報告摘要
快速品質檢查：<component-name>
─────────────────────────────────────
Linter 違規：
• 類別覆寫： 0
• 已棄用 Token： 3
• 硬編碼值： 5
快速自動化等級：C（估計）
執行完整驗證以取得詳細報告。
邊緣案例與誤判
| 情況 | 指引 |
|---|---|
| 無頭元件（僅 JS，無 HTML） | 跳過 HTML 檢查；僅評分 CSS + linter 類別 |
| 包裝器/容器元件 | 可能合理只有最少 CSS；不要因低 hook 使用而扣分 |
| 刻意使用原生元素 | 在自訂 SLDS 藍圖內使用 <button> 是正確的；若在 slds-* 藍圖結構內則抑制 C002 |
| LEX 之外的元件 | LWR/Experience Cloud 元件可能不使用 Lightning Base Components；在報告中註記脈絡 |
| 測試/示範元件 | 降低標準 — 在報告中註記，但不要因警告而阻斷 |
如果檢查產生誤判，請在報告中註記為「已抑制」並附理由，而非靜默忽略。
