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）。
Audit Lightning Web Components for SLDS compliance and produce a scored quality report. Runs the SLDS linter, analyzes CSS for theming hook usage and pairing, checks HTML for accessibility attributes, and scores findings across categories into an overall grade. Use when asked to \"score my component\", \"SLDS scorecard\", \"quality report\", \"audit SLDS compliance\", \"how good is my SLDS\", \"check component quality\", \"rate my component\", \"evaluate my component\", \"is this component ready to ship?\", \"look at my LWC for issues\", \"audit this before I submit\", \"review my component before code review\", or any time a user wants a quality assessment or production-readiness check on an LWC or SLDS component. Not for fixing violations (use design-systems-slds2-migrate) or building new components (use 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；在報告中註記脈絡 |
| 測試/示範元件 | 降低標準 — 在報告中註記，但不要因警告而阻斷 |
如果檢查產生誤判，請在報告中註記為「已抑制」並附理由，而非靜默忽略。
