applying-slds
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseApplying SLDS
应用SLDS
The Salesforce Lightning Design System (SLDS) is a CSS framework with thousands of artifacts. This skill teaches agents how to find and correctly use them.
Version: This skill targets SLDS v2. Legacytokens and--lwc-*syntax are deprecated.slds-*--modifierAudit scope: The companionskill analyzer only scansvalidating-slds,.css, and.htmlfiles. Use it directly for LWC and similar HTML/CSS/JS components; treat it as a partial signal for JSX/TSX or other framework-specific template formats and supplement with manual review..js
**Salesforce Lightning设计系统(SLDS)**是一个包含数千种资源的CSS框架。本技能指导开发者如何查找并正确使用这些资源。
版本说明: 本技能针对SLDS v2。旧版令牌和--lwc-*语法已被弃用。slds-*--modifier审计范围: 配套的技能分析器仅扫描validating-slds、.css和.html文件。可直接用于LWC及类似的HTML/CSS/JS组件;对于JSX/TSX或其他框架特定的模板格式,仅作为部分参考信号,需辅以人工审查。.js
What is SLDS?
什么是SLDS?
| Artifact | Count | Description |
|---|---|---|
| Lightning Base Components | ~70 | Pre-built LWC components (LWC only) |
| SLDS Blueprints | 85 | CSS/HTML patterns for any framework |
| Styling Hooks | 523 | CSS custom properties ( |
| Utility Classes | 1,147 | Rapid styling classes for spacing, layout, visibility |
| Icons | 1,732 | SVG icons across 5 categories |
| 资源类型 | 数量 | 描述 |
|---|---|---|
| Lightning Base Components | ~70 | 预构建的LWC组件(仅适用于LWC) |
| SLDS Blueprints | 85 | 适用于任何框架的CSS/HTML模式 |
| Styling Hooks | 523 | 用于主题定制的CSS自定义属性( |
| Utility Classes | 1,147 | 用于快速设置间距、布局、可见性的样式类 |
| Icons | 1,732 | 涵盖5个类别的SVG图标 |
Scope
适用范围
This skill covers:
- Which blueprint to use for a given UI pattern
- How to style with hooks (color, spacing, typography, shadows, borders)
- Which utility classes to use for layout, spacing, visibility
- Which icon to use and from which category
- SLDS naming conventions, class structure, hook syntax
This skill includes basic accessibility reminders (icon alt text, focus outlines, color-not-sole-indicator) in the validation checklists. Full WCAG compliance requires a dedicated accessibility review.
This skill does NOT cover (use companion skills):
- Design decisions -- visual hierarchy, composition, interaction patterns
- LWC mechanics -- component structure, @wire, @api, lifecycle, events (not yet available)
- Full accessibility -- WCAG conformance, ARIA patterns, keyboard navigation, focus management, contrast ratios (not yet available)
本技能涵盖:
- 针对特定UI模式选择合适的蓝图
- 如何使用hooks设置样式(颜色、间距、排版、阴影、边框)
- 选择哪些实用工具类用于布局、间距、可见性设置
- 选择合适的图标及其所属类别
- SLDS命名规范、类结构、hook语法
本技能包含基础可访问性提示(图标替代文本、焦点轮廓、不单独依赖颜色传达信息),并纳入验证检查清单。完整的WCAG合规性需要专门的可访问性审查。
本技能不涵盖(请使用配套技能):
- 设计决策——视觉层级、布局、交互模式
- LWC机制——组件结构、@wire、@api、生命周期、事件(暂未提供)
- 完整可访问性——WCAG合规、ARIA模式、键盘导航、焦点管理、对比度(暂未提供)
Component Selection Hierarchy
组件选择优先级
Always follow this order:
1. Lightning Base Components (LWC only) ← Check first
2. SLDS Blueprints (any framework) ← Use exact SLDS classes
3. Custom with Styling Hooks ← Use var(--slds-g-*)
4. Custom CSS (last resort) ← Still use hooks for valuesIf building in LWC, check for an LBC first: Lightning Component Library
If no LBC exists (or not using LWC), select an SLDS Blueprint. See references/component-selection.md.
请始终遵循以下顺序:
1. Lightning Base Components(仅LWC) ← 优先检查
2. SLDS Blueprints(任何框架) ← 使用精确的SLDS类
3. 结合Styling Hooks自定义 ← 使用var(--slds-g-*)
4. 自定义CSS(最后手段) ← 仍需使用hooks获取值如果基于LWC开发,请先查看是否有对应的LBC:Lightning组件库
如果没有对应的LBC(或不使用LWC),请选择SLDS Blueprint。详情请见references/component-selection.md。
Core Rules
核心规则
Do
应该做
- Follow the selection hierarchy: LBC > Blueprint > Hooks > Custom CSS
- Use for all themeable values
var(--slds-g-*, fallback) - Create custom classes (,
my-*) instead of overridingc-*.slds-* - Verify every hook, class, and utility exists before using it — run the search scripts; never assume an artifact exists based on naming patterns (see Verify Before You Use)
- Pair surface colors with on-surface colors for text
- Provide on every
alternative-text<lightning-icon>
- 遵循选择优先级:LBC > Blueprint > Hooks > 自定义CSS
- 对所有可主题化的值使用
var(--slds-g-*, fallback) - 创建自定义类(、
my-*)而非覆盖c-*.slds-* - 使用前务必验证每个hook、类和工具类是否存在——运行搜索脚本;切勿根据命名模式假设资源存在(请查看「使用前验证」章节)
- 将表面颜色与对应文本颜色配对使用
- 为每个提供
<lightning-icon>alternative-text
Don't
不应该做
- Hard-code colors, spacing, or typography values
- Override classes directly
.slds-* - Use deprecated tokens as primary values
--lwc-* - Use (shared) hooks -- they are private/internal
--slds-s-* - Reassign hook values -- only reference them with
var() - Use color alone to convey meaning
- Invent hook names by interpolating patterns from other families (see Naming Traps below)
- 硬编码颜色、间距或排版值
- 直接覆盖类
.slds-* - 将已弃用的令牌作为主要值使用
--lwc-* - 使用(共享)hooks——它们是私有/内部资源
--slds-s-* - 重新分配hook值——仅通过引用它们
var() - 仅使用颜色传达信息
- 通过其他系列的模式推断hook名称(请查看下方命名陷阱)
Hook Naming Traps
Hook命名陷阱
SLDS hook families do NOT all follow the same naming pattern. Agents frequently invent hooks that don't exist by assuming works universally. Always verify a hook exists via the bundled script or before using it.
{prefix}-{number}search-hooks.cjsmetadata/hooks-index.jsonSLDS的hook系列并非都遵循相同的命名模式。开发者常因假设通用而发明不存在的hook。使用前务必通过捆绑的脚本或验证hook是否存在。
{prefix}-{number}search-hooks.cjsmetadata/hooks-index.jsonTrap 1: Font size hooks are NOT numbered
陷阱1:字体大小hook不使用编号
| Wrong (does not exist) | Correct | Notes |
|---|---|---|
| | Font sizes use |
| | Only |
| | Scale goes: neg-4 through 10 |
Rule: For font sizes, use (the one base size) or (the numbered scale). Never .
--slds-g-font-size-base--slds-g-font-scale-*--slds-g-font-size-N| 错误(不存在) | 正确写法 | 说明 |
|---|---|---|
| | 字体大小使用 |
| | 仅存在 |
| | 缩放范围:neg-4到10 |
规则: 字体大小请使用(唯一基础大小)或(编号缩放)。切勿使用。
--slds-g-font-size-base--slds-g-font-scale-*--slds-g-font-size-NTrap 2: Color hooks always require a number
陷阱2:颜色hook必须包含编号
| Wrong (does not exist) | Correct | Notes |
|---|---|---|
| | All color hooks need a number |
| | Pick 1/2/3 by emphasis level |
| | No unnumbered base form |
Rule: Every hook ends in a number. Pick by emphasis: (low), (medium), (high).
--slds-g-color-*-1-2-3| 错误(不存在) | 正确写法 | 说明 |
|---|---|---|
| | 所有颜色hook都需要编号 |
| | 根据强调级别选择1/2/3 |
| | 无未编号的基础形式 |
规则: 每个hook都以编号结尾。根据强调级别选择:(低)、(中)、(高)。
--slds-g-color-*-1-2-3Trap 3: Not all values have hook equivalents
陷阱3:并非所有值都有对应的hook
Some CSS values (e.g., for label alignment) have no SLDS hook. This is acceptable:
min-width: 7remcss
.c-field-label {
/* No SLDS hook exists for this width; intentional custom value */
min-width: 7rem;
}Rule: When no hook exists, use the value directly with a comment explaining it's intentional. Prefer SLDS grid utilities () as alternatives to hardcoded widths where possible.
slds-size_*部分CSS值(例如标签对齐的)没有对应的SLDS hook。这种情况是可接受的:
min-width: 7remcss
.c-field-label {
/* 该宽度无对应的SLDS hook;为有意设置的自定义值 */
min-width: 7rem;
}规则: 当没有对应的hook时,直接使用值并添加注释说明是有意设置的。尽可能优先使用SLDS网格工具类()替代硬编码宽度。
slds-size_*Verify Before You Use
使用前验证
Rule: Never include an SLDS hook, utility class, blueprint class, or icon in generated code without first confirming it exists in the metadata. Guessing based on naming patterns is the primary source of invented artifacts.
Run the appropriate search command before emitting any SLDS artifact:
| Artifact | Verification command | Source of truth |
|---|---|---|
Styling hook ( | | |
Utility class ( | | |
| Blueprint / CSS class | | |
| Icon | | |
If the search returns no match: do not use the artifact. Find an alternative from the search results or build custom with verified hooks.
规则: 在生成的代码中加入SLDS hook、实用工具类、蓝图类或图标之前,务必先确认它们存在于元数据中。基于命名模式猜测是导致无效资源的主要原因。
在输出任何SLDS资源之前,运行相应的搜索命令:
| 资源类型 | 验证命令 | 可信来源 |
|---|---|---|
Styling hook( | | |
Utility class( | | |
| Blueprint / CSS类 | | |
| Icon | | |
如果搜索无结果:请勿使用该资源。从搜索结果中寻找替代方案,或使用已验证的hooks构建自定义内容。
Naming Conventions
命名规范
Use a consistent prefix for custom classes to avoid collision with SLDS:
| Pattern | Use Case | Example |
|---|---|---|
| General custom styling | |
| LWC component-specific | |
| Package/app namespace | |
Avoid: generic names (, ), SLDS-like names (), BEM on SLDS classes ().
containerwrappercustom-slds-buttonslds-card__custom-headerCustom hook namespacing:
css
:root {
--my-app-primary: var(--slds-g-color-accent-1);
--my-app-card-padding: var(--slds-g-spacing-4);
}为自定义类使用一致的前缀,避免与SLDS冲突:
| 模式 | 使用场景 | 示例 |
|---|---|---|
| 通用自定义样式 | |
| LWC组件专属 | |
| 包/应用命名空间 | |
避免: 通用名称(、)、类似SLDS的名称()、在SLDS类上使用BEM命名()。
containerwrappercustom-slds-buttonslds-card__custom-header自定义hook命名空间:
css
:root {
--my-app-primary: var(--slds-g-color-accent-1);
--my-app-card-padding: var(--slds-g-spacing-4);
}Knowledge Map
知识图谱
This skill bundles comprehensive SLDS knowledge. Read files as needed -- don't read everything upfront.
本技能包含全面的SLDS知识。按需阅读文件——无需提前通读所有内容。
Decision Guides (start here for each task)
决策指南(每项任务从这里开始)
| File | Read when |
|---|---|
| references/component-selection.md | Choosing a component or blueprint |
| references/styling-decision-guide.md | Applying colors, spacing, typography, shadows |
| references/icons-decision-guide.md | Selecting or implementing an icon |
| references/utilities-quick-ref.md | Using utility classes for layout/spacing |
| 文件 | 阅读场景 |
|---|---|
| references/component-selection.md | 选择组件或蓝图时 |
| references/styling-decision-guide.md | 应用颜色、间距、排版、阴影时 |
| references/icons-decision-guide.md | 选择或实现图标时 |
| references/utilities-quick-ref.md | 使用实用工具类处理布局/间距时 |
Search Scripts (find specific artifacts)
搜索脚本(查找特定资源)
| Script | What it searches | Example |
|---|---|---|
| 85 blueprint YAMLs | |
| 523 styling hooks | |
| 1,732 icons with synonyms | |
| 1,147 utility classes | |
| 脚本 | 搜索内容 | 示例 |
|---|---|---|
| 85个蓝图YAML文件 | |
| 523个styling hooks | |
| 1,732个带同义词的图标 | |
| 1,147个实用工具类 | |
Deep-Dive Guidance (read for detailed rules)
深度指南(阅读以了解详细规则)
| Folder | Content | Index |
|---|---|---|
| Foundational concepts (color, spacing, typography, etc.) | guidance/README.md |
| Hook categories with detailed usage | guidance/README.md |
| 27 utility class categories | guidance/README.md |
| Full SLDS development guide | -- |
| 文件夹 | 内容 | 索引 |
|---|---|---|
| 基础概念(颜色、间距、排版等) | guidance/README.md |
| Hook类别及详细用法 | guidance/README.md |
| 27个实用工具类类别 | guidance/README.md |
| 完整SLDS开发指南 | -- |
Raw Metadata (structured data for lookup)
原始元数据(用于查询的结构化数据)
Do not read metadata JSON files directly — they are too large for agent context (hooks-index.json is 6,000+ lines; icon-metadata.json is 38,000+ lines). Use the search scripts above to query them.
| File | Content | Lines |
|---|---|---|
| 85 blueprint specs (classes, variants, a11y, HTML) | ~50-200 each |
| 523 hooks with values and CSS properties | ~6,300 |
| 1,732 icons with synonyms for search | ~38,500 |
| 1,147 utility classes with CSS rules | ~6,900 |
请勿直接阅读元数据JSON文件——它们过大,超出上下文范围(hooks-index.json有6000多行;icon-metadata.json有38000多行)。请使用上述搜索脚本进行查询。
| 文件 | 内容 | 行数 |
|---|---|---|
| 85个蓝图规范(类、变体、可访问性、HTML) | 每个约50-200行 |
| 523个带值和CSS属性的hooks | ~6,300行 |
| 1,732个带搜索同义词的图标 | ~38,500行 |
| 1,147个带CSS规则的实用工具类 | ~6,900行 |
Authoring Workflow
开发工作流
Phase 1: Understand the Need
阶段1:理解需求
Identify:
- What UI pattern is needed? (form, table, modal, card, etc.)
- What framework? (LWC, React, Vue, Angular, vanilla)
- What data will it display?
- What states does it need? (loading, empty, error, success)
明确:
- 需要什么UI模式?(表单、表格、模态框、卡片等)
- 使用什么框架?(LWC、React、Vue、Angular、原生JS)
- 将展示什么数据?
- 需要哪些状态?(加载、空状态、错误、成功)
Phase 2: Select the Artifact
阶段2:选择资源
- If LWC: Check the Lightning Component Library for an LBC
- Search blueprints:
node scripts/search-blueprints.cjs --search "<pattern>" - Read the blueprint YAML: for exact classes, modifiers, states, and accessibility requirements
metadata/blueprints/components/<name>.yaml - No match? Build custom with hooks (see Phase 3)
Details: references/component-selection.md
- 如果是LWC:查看Lightning组件库是否有对应的LBC
- 搜索蓝图:
node scripts/search-blueprints.cjs --search "<pattern>" - 阅读蓝图YAML:获取精确的类、修饰符、状态和可访问性要求
metadata/blueprints/components/<name>.yaml - 无匹配结果? 使用hooks构建自定义内容(见阶段3)
详情:references/component-selection.md
Phase 3: Apply Styling
阶段3:应用样式
- Read: references/styling-decision-guide.md
- Colors: Classify role (surface, accent, feedback, border) then pick hook
- Spacing: Use utility classes (,
slds-p-*) or hooks (slds-m-*)--slds-g-spacing-* - Layout: Use grid utilities (,
slds-grid,slds-col)slds-size_* - Custom CSS: Use , custom class prefixes only
var(--slds-g-*, fallback)
- 阅读:references/styling-decision-guide.md
- 颜色:分类角色(表面、强调、反馈、边框)然后选择hook
- 间距:使用实用工具类(、
slds-p-*)或hooks(slds-m-*)--slds-g-spacing-* - 布局:使用网格工具类(、
slds-grid、slds-col)slds-size_* - 自定义CSS:仅使用和自定义类前缀
var(--slds-g-*, fallback)
Phase 4: Add Icons
阶段4:添加图标
- Read: references/icons-decision-guide.md
- Search:
node scripts/search-icons.cjs --query "<description>" - In LWC: Use with
<lightning-icon>alternative-text - In non-LWC: Use SVG with classes and
slds-iconslds-assistive-text
- 阅读:references/icons-decision-guide.md
- 搜索:
node scripts/search-icons.cjs --query "<description>" - 在LWC中:使用并添加
<lightning-icon>alternative-text - 在非LWC中:使用SVG并添加类和
slds-iconslds-assistive-text
Phase 5: Validate (Mandatory — Do Not Skip)
阶段5:验证(必填——请勿跳过)
Step 1: Run the SLDS linter. This is required. Zero violations is the target.
bash
npx @salesforce-ux/slds-linter@latest lint <component-path>The linter catches hardcoded values, class overrides, and deprecated tokens. Fix all violations before proceeding. Do not rationalize violations as acceptable.
Step 2: Verify no invented hooks. Confirm every hook in the output exists in . Cross-reference against the T051 check in checklists.md.
--slds-g-*metadata/hooks-index.jsonStep 3: Run through checklists.md for the checks the linter cannot automate:
- All have fallback values (T002)
var(--slds-g-*) - Surface/accent/feedback color hooks are properly paired (T010–T013)
- Spacing uses hooks or utility classes — no magic values (T020–T021)
px - Font sizes use , not
--slds-g-font-scale-*(T031)--slds-g-font-size-N - All icons have accessibility text (A004)
- Custom classes use or
my-*prefix (Q010)c-*
Step 4 (optional): Run the full quality audit using the skill for a scored report before code review or deployment. Use it directly for LWC / HTML-CSS-JS components; for JSX/TSX outputs, treat the result as partial coverage only. Target a B grade (≥80) or higher before marking work complete.
validating-slds步骤1:运行SLDS检查器。这是必填项。目标是零违规。
bash
npx @salesforce-ux/slds-linter@latest lint <component-path>检查器会捕获硬编码值、类覆盖和已弃用令牌。修复所有违规后再继续。请勿将违规合理化。
步骤2:验证无无效hooks。确认输出中每个hook都存在于中。对照checklists.md中的T051检查项。
--slds-g-*metadata/hooks-index.json步骤3:对照checklists.md完成检查,涵盖检查器无法自动化的内容:
- 所有都有回退值(T002)
var(--slds-g-*) - 表面/强调/反馈颜色hook已正确配对(T010–T013)
- 间距使用hooks或实用工具类——无魔法值(T020–T021)
px - 字体大小使用,而非
--slds-g-font-scale-*(T031)--slds-g-font-size-N - 所有图标都有可访问性文本(A004)
- 自定义类使用或
my-*前缀(Q010)c-*
步骤4(可选):运行完整质量审计,使用技能在代码审查或部署前生成评分报告。直接用于LWC/HTML-CSS-JS组件;对于JSX/TSX输出,仅作为部分覆盖结果。目标达到B级(≥80分)或更高后再标记工作完成。
validating-sldsQuick Reference
快速参考
Common Hook Patterns
常见Hook模式
css
/* Surface + text pairing (always use numbered variants) */
background: var(--slds-g-color-surface-1, #ffffff);
color: var(--slds-g-color-on-surface-2, #181818);
/* Standard padding */
padding: var(--slds-g-spacing-4, 1rem);
/* Card-like container */
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));
/* Accent for primary actions */
background: var(--slds-g-color-accent-1, #0176d3);
color: var(--slds-g-color-on-accent-1, #ffffff);
/* Typography -- use font-scale-*, NOT font-size-* (only font-size-base exists) */
font-size: var(--slds-g-font-scale-2, 0.875rem);css
/* 表面+文本配对(始终使用编号变体) */
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);Common Utility Patterns
常见实用工具类模式
html
<!-- Responsive grid -->
<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>
<!-- Spacing -->
<div class="slds-p-around_medium slds-m-bottom_small">...</div>
<!-- Truncation -->
<p class="slds-truncate" title="Full text here">Full text here</p>html
<!-- 响应式网格 -->
<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="完整文本">完整文本</p>Examples
示例
See examples.md for worked examples demonstrating the full workflow from intent to SLDS artifact selection.
请查看examples.md获取完整工作流示例,涵盖从需求到SLDS资源选择的全过程。
Validation
验证
See checklists.md for validation checklists aligned with the validating-slds skill.
请查看checklists.md获取与validating-slds技能对齐的验证检查清单。
Resources
资源
| Resource | URL |
|---|---|
| SLDS Website | 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 Reference | https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks |