使用正確的藍圖、樣式鉤子、工具類別和圖示來套用符合 SLDS 的 UI。在建立任何需要 SLDS 的 UI、在 Lightning Base Components 與 SLDS Blueprints 之間做選擇、套用樣式鉤子進行主題化、使用工具類別進行版面配置與間距，或選擇圖示時使用。觸發詞包括「建立 modal」、「建立表單」、「資料表」、「SLDS 樣式」、「使用鉤子設定樣式」、「新增圖示」。
套用 SLDS
Salesforce Lightning Design System (SLDS) 是一個包含數千個元件的 CSS 框架。此技能教導代理程式如何尋找並正確使用它們。
版本： 此技能以 SLDS v2 為目標。舊版的
--lwc-*token 與slds-*--modifier語法已棄用。稽核範圍： 搭配的
design-systems-slds-validate技能分析器僅掃描.css、.html與.js檔案。請直接將其用於 LWC 及類似的 HTML/CSS/JS 元件；對於 JSX/TSX 或其他框架特定的範本格式，請將其視為部分訊號，並輔以人工審查。
什麼是 SLDS？
| 元件 | 數量 | 說明 |
|---|---|---|
| Lightning Base Components | ~70 | 預先建置的 LWC 元件（僅限 LWC） |
| SLDS Blueprints | 85 | 適用於任何框架的 CSS/HTML 模式 |
| Styling Hooks | 523 | 用於主題化的 CSS 自訂屬性（--slds-g-*） |
| Utility Classes | 1,147 | 用於間距、版面配置、可見性的快速樣式類別 |
| Icons | 1,732 | 涵蓋 5 個類別的 SVG 圖示 |
範圍
此技能涵蓋：
- 針對特定 UI 模式應使用哪個藍圖
- 如何使用鉤子設定樣式（顏色、間距、排版、陰影、邊框）
- 針對版面配置、間距、可見性應使用哪些工具類別
- 應使用哪個圖示以及來自哪個類別
- SLDS 命名慣例、類別結構、鉤子語法
此技能包含基本的無障礙提醒（圖示替代文字、焦點外框、顏色非唯一指示）於驗證檢查清單中。完整的 WCAG 合規需要專門的無障礙審查。
此技能不涵蓋（請使用搭配技能）：
- 設計決策 -- 視覺層級、組成、互動模式
- LWC 機制 -- 元件結構、@wire、@api、生命週期、事件（尚未提供）
- 完整無障礙 -- WCAG 符合性、ARIA 模式、鍵盤導覽、焦點管理、對比度（尚未提供）
元件選擇階層
永遠遵循此順序：
1. Lightning Base Components (LWC only) ← 先檢查
2. SLDS Blueprints (any framework) ← 使用精確的 SLDS 類別
3. Custom with Styling Hooks ← 使用 var(--slds-g-*)
4. Custom CSS (last resort) ← 仍使用鉤子作為值
若在 LWC 中建置，請先檢查是否有 LBC：Lightning Component Library
若沒有 LBC（或未使用 LWC），請選擇 SLDS Blueprint。請參閱 references/component-selection.md。
核心規則
應做
- 遵循選擇階層：LBC > Blueprint > Hooks > Custom CSS
- 對所有可主題化的值使用
var(--slds-g-*, fallback) - 建立自訂類別（
my-*、c-*）而非覆寫.slds-* - 在使用前驗證每個鉤子、類別與工具確實存在 — 執行搜尋腳本；切勿僅根據命名模式假設元件存在（請參閱 使用前驗證）
- 將表面顏色與表面上的文字顏色配對
- 在每個
<lightning-icon>上提供alternative-text
不應做
- 硬編碼顏色、間距或排版值
- 直接覆寫
.slds-*類別 - 使用已棄用的
--lwc-*token 作為主要值 - 使用
--slds-s-*（共用）鉤子 — 它們是私有的/內部的 - 重新指派鉤子值 — 僅使用
var()參考它們 - 僅使用顏色來傳達意義
- 透過從其他系列插值模式來發明鉤子名稱（請參閱下方的命名陷阱）
鉤子命名陷阱
SLDS 鉤子系列並非都遵循相同的命名模式。代理程式經常假設 {prefix}-{number} 普遍適用，而發明出不存在的鉤子。在使用前務必透過隨附的 search-hooks.cjs 腳本或 assets/hooks-index.json 驗證鉤子是否存在。
陷阱 1：字體大小鉤子並非編號
| 錯誤（不存在） | 正確 | 備註 |
|---|---|---|
--slds-g-font-size-3 |
--slds-g-font-scale-1 |
字體大小使用 font-scale-*，而非 font-size-* |
--slds-g-font-size-4 |
--slds-g-font-scale-2 |
僅存在 --slds-g-font-size-base（基礎大小） |
--slds-g-font-size-8 |
--slds-g-font-scale-6 |
刻度範圍：neg-4 到 10 |
規則： 對於字體大小，使用 --slds-g-font-size-base（唯一的基礎大小）或 --slds-g-font-scale-*（編號刻度）。切勿使用 --slds-g-font-size-N。
陷阱 2：顏色鉤子總是需要數字
| 錯誤（不存在） | 正確 | 備註 |
|---|---|---|
--slds-g-color-on-surface |
--slds-g-color-on-surface-2 |
所有顏色鉤子都需要數字 |
--slds-g-color-on-accent |
--slds-g-color-on-accent-1 |
根據強調程度選擇 1/2/3 |
--slds-g-color-surface |
--slds-g-color-surface-1 |
沒有未編號的基礎形式 |
規則： 每個 --slds-g-color-* 鉤子都以數字結尾。根據強調程度選擇：-1（低）、-2（中）、-3（高）。
陷阱 3：並非所有值都有對應的鉤子
某些 CSS 值（例如，標籤對齊的 min-width: 7rem）沒有 SLDS 鉤子。這是可接受的：
.c-field-label {
/* 此寬度沒有 SLDS 鉤子；有意的自訂值 */
min-width: 7rem;
}
規則： 當沒有鉤子時，直接使用該值並加上註解說明這是刻意的。盡可能偏好使用 SLDS 網格工具（slds-size_*）作為硬編碼寬度的替代方案。
使用前驗證
規則： 切勿在未先確認 SLDS 鉤子、工具類別、藍圖類別或圖示存在於中繼資料中時，就將其包含在產生的程式碼中。根據命名模式猜測是發明元件的主要來源。
在輸出任何 SLDS 元件之前執行適當的搜尋命令：
| 元件 | 驗證命令 | 真相來源 |
|---|---|---|
樣式鉤子（--slds-g-*） |
node scripts/search-hooks.cjs --prefix "<hook-name>" |
assets/hooks-index.json |
工具類別（slds-*） |
node scripts/search-utilities.cjs --search "<class-name>" |
assets/utilities-index.json |
| 藍圖 / CSS 類別 | node scripts/search-blueprints.cjs --search "<pattern>" 然後讀取 YAML |
assets/blueprints/components/*.yaml |
| 圖示 | node scripts/search-icons.cjs --query "<description>" |
assets/icon-metadata.json |
如果搜尋沒有結果：請勿使用該元件。 從搜尋結果中尋找替代方案，或使用已驗證的鉤子建立自訂樣式。
命名慣例
使用一致的前綴來命名自訂類別，以避免與 SLDS 衝突：
| 模式 | 使用案例 | 範例 |
|---|---|---|
my-* |
一般自訂樣式 | my-card-header |
c-* |
LWC 元件特定 | c-accountList-row |
[namespace]-* |
套件/應用程式命名空間 | acme-dashboard-widget |
避免： 通用名稱（container、wrapper）、類似 SLDS 的名稱（custom-slds-button）、在 SLDS 類別上使用 BEM（slds-card__custom-header）。
自訂鉤子命名空間：
:root {
--my-app-primary: var(--slds-g-color-accent-1);
--my-app-card-padding: var(--slds-g-spacing-4);
}
知識地圖
此技能捆綁了全面的 SLDS 知識。視需要讀取檔案 — 不要一次讀取所有內容。
決策指南（每個任務從這裡開始）
| 檔案 | 何時閱讀 |
|---|---|
| references/component-selection.md | 選擇元件或藍圖時 |
| references/styling-decision-guide.md | 套用顏色、間距、排版、陰影時 |
| references/icons-decision-guide.md | 選擇或實作圖示時 |
| references/utilities-quick-ref.md | 使用工具類別進行版面配置/間距時 |
搜尋腳本（尋找特定元件）
| 腳本 | 搜尋內容 | 範例 |
|---|---|---|
scripts/search-blueprints.cjs |
85 個藍圖 YAML | --search "dialog" |
scripts/search-hooks.cjs |
523 個樣式鉤子 | --prefix "--slds-g-color-accent-" |
scripts/search-icons.cjs |
1,732 個圖示與同義詞 | --query "save button" |
scripts/search-utilities.cjs |
1,147 個工具類別 | --category "grid" |
深入指南（閱讀以取得詳細規則）
| 資料夾 | 內容 | 索引 |
|---|---|---|
references/overviews/ |
基礎概念（顏色、間距、排版等） | references/README.md |
references/styling-hooks/ |
鉤子類別與詳細用法 | references/README.md |
references/utilities/ |
27 個工具類別類別 | references/README.md |
references/slds-development-guide.md |
完整的 SLDS 開發指南 | -- |
原始中繼資料（用於查詢的結構化資料）
請勿直接讀取中繼資料 JSON 檔案 — 它們對代理程式上下文來說太大（hooks-index.json 超過 6,000 行；icon-metadata.json 超過 38,000 行）。請使用上述搜尋腳本來查詢它們。
| 檔案 | 內容 | 行數 |
|---|---|---|
assets/blueprints/components/*.yaml |
85 個藍圖規格（類別、變體、a11y、HTML） | 每個約 50-200 |
assets/hooks-index.json |
523 個鉤子與值和 CSS 屬性 | 約 6,300 |
assets/icon-metadata.json |
1,732 個圖示與用於搜尋的同義詞 | 約 38,500 |
assets/utilities-index.json |
1,147 個工具類別與 CSS 規則 | 約 6,900 |
編寫工作流程
階段 1：了解需求
識別：
- 需要什麼 UI 模式？（表單、表格、modal、卡片等）
- 使用什麼框架？（LWC、React、Vue、Angular、原生）
- 它會顯示什麼資料？
- 它需要哪些狀態？（載入中、空白、錯誤、成功）
階段 2：選擇元件
- 如果是 LWC：檢查 Lightning Component Library 是否有 LBC
- 搜尋藍圖：
node scripts/search-blueprints.cjs --search "<pattern>" - 讀取藍圖 YAML：
assets/blueprints/components/<name>.yaml以取得精確的類別、修飾符、狀態與無障礙需求 - 沒有符合？ 使用鉤子建立自訂樣式（請參閱階段 3）
詳細資訊：references/component-selection.md
階段 3：套用樣式
- 閱讀：references/styling-decision-guide.md
- 顏色：分類角色（表面、強調、回饋、邊框）然後選擇鉤子
- 間距：使用工具類別（
slds-p-*、slds-m-*）或鉤子（--slds-g-spacing-*） - 版面配置：使用網格工具（
slds-grid、slds-col、slds-size_*） - 自訂 CSS：使用
var(--slds-g-*, fallback)，僅使用自訂類別前綴
階段 4：新增圖示
- 閱讀：references/icons-decision-guide.md
- 搜尋：
node scripts/search-icons.cjs --query "<description>" - 在 LWC 中：使用帶有
alternative-text的<lightning-icon> - 在非 LWC 中：使用帶有
slds-icon類別與slds-assistive-text的 SVG
階段 5：驗證（必做 — 請勿跳過）
步驟 1：執行 SLDS linter。 這是必要的。目標是零違規。
npx @salesforce-ux/slds-linter@latest lint <component-path>
Linter 會捕捉硬編碼值、類別覆寫與已棄用的 token。在繼續之前修正所有違規。 不要將違規合理化為可接受。
步驟 2：驗證沒有發明的鉤子。 確認輸出中的每個 --slds-g-* 鉤子都存在於 assets/hooks-index.json 中。與 checklists.md 中的 T051 檢查交叉比對。
步驟 3：執行 checklists.md 以進行 linter 無法自動化的檢查：
- 所有
var(--slds-g-*)都有 fallback 值（T002） - 表面/強調/回饋顏色鉤子已正確配對（T010–T013）
- 間距使用鉤子或工具類別 — 沒有神奇的
px值（T020–T021） - 字體大小使用
--slds-g-font-scale-*，而非--slds-g-font-size-N（T031） - 所有圖示都有無障礙文字（A004）
- 自訂類別使用
my-*或c-*前綴（Q010）
步驟 4（選用）：執行完整的品質稽核，使用 design-systems-slds-validate 技能在程式碼審查或部署前取得評分報告。請直接將其用於 LWC / HTML-CSS-JS 元件；對於 JSX/TSX 輸出，請將結果視為僅部分涵蓋。目標是在標記工作完成前達到 B 級（≥80）或更高。
快速參考
常見鉤子模式
/* 表面 + 文字配對（務必使用編號變體） */
background: var(--slds-g-color-surface-1, #ffffff);
color: var(--slds-g-color-on-surface-2, #181818);
/* 標準內距 */
padding: var(--slds-g-spacing-4, 1rem);
/* 卡片式容器 */
border-radius: var(--slds-g-radius-border-2, 0.25rem);
box-shadow: var(--slds-g-shadow-1, 0 2px 4px rgba(0,0,0,0.1));
/* 主要動作的強調色 */
background: var(--slds-g-color-accent-1, #0176d3);
color: var(--slds-g-color-on-accent-1, #ffffff);
/* 排版 -- 使用 font-scale-*，而非 font-size-*（僅存在 font-size-base） */
font-size: var(--slds-g-font-scale-2, 0.875rem);
常見工具模式
<!-- 響應式網格 -->
<div class="slds-grid slds-wrap slds-gutters">
<div class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2">...</div>
</div>
<!-- 間距 -->
<div class="slds-p-around_medium slds-m-bottom_small">...</div>
<!-- 截斷 -->
<p class="slds-truncate" title="Full text here">Full text here</p>
範例
請參閱 examples.md 以取得完整的範例，展示從意圖到 SLDS 元件選擇的完整工作流程。
驗證
請參閱 checklists.md 以取得與 design-systems-slds-validate 技能對齊的驗證檢查清單。
資源
| 資源 | URL |
|---|---|
| SLDS 網站 | https://www.lightningdesignsystem.com/ |
| Lightning Component Library | https://developer.salesforce.com/docs/component-library/overview/components |
| SLDS Linter | https://developer.salesforce.com/docs/platform/slds-linter/guide |
| Styling Hooks 參考 | https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks |
