design-systems-slds-apply

套用 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

您可能也喜歡

fix

247Kfrontend

Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.

facebook

獲取

motion-advanced

237Kfrontend

Advanced motion patterns for React / Next.js — drag & drop, gestures, text animations, SVG path drawing, custom hooks, imperative sequences (useAnimate), loaders, and the full API decision tree. Requires motion-foundations.

affaan-m

獲取

next-cache-components-adoption

141Kfrontend

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

vercel

獲取

繼續探索

瀏覽 frontend 熱門 Skills 最近更新