Applying SLDS

Version: This skill targets SLDS v2. Legacy --lwc-* tokens and slds-*--modifier syntax are deprecated.

Audit scope: The companion design-systems-slds-validate skill analyzer only scans .css, .html, and .js files. 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.

What is SLDS?

Scope

• 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

• 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)

Component Selection Hierarchy

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 values

Core Rules

Do

• Follow the selection hierarchy: LBC > Blueprint > Hooks > Custom CSS
• Use var(--slds-g-*, fallback) for all themeable values
• Create custom classes (my-*, c-*) instead of overriding .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 alternative-text on every <lightning-icon>

Don't

• Hard-code colors, spacing, or typography values
• Override .slds-* classes directly
• Use deprecated --lwc-* tokens as primary values
• Use --slds-s-* (shared) hooks -- they are private/internal
• 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)

Hook Naming Traps

Trap 1: Font size hooks are NOT numbered

Trap 2: Color hooks always require a number

Trap 3: Not all values have hook equivalents

.c-field-label {
  /* No SLDS hook exists for this width; intentional custom value */
  min-width: 7rem;
}

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.

Naming Conventions

:root {
  --my-app-primary: var(--slds-g-color-accent-1);
  --my-app-card-padding: var(--slds-g-spacing-4);
}

Knowledge Map

Decision Guides (start here for each task)

Search Scripts (find specific artifacts)

Deep-Dive Guidance (read for detailed rules)

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.

Authoring Workflow

Phase 1: Understand the Need

• 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)

Phase 2: Select the Artifact

1. If LWC: Check the Lightning Component Library for an LBC
2. Search blueprints: node scripts/search-blueprints.cjs --search "<pattern>"
3. Read the blueprint YAML: assets/blueprints/components/<name>.yaml for exact classes, modifiers, states, and accessibility requirements
4. No match? Build custom with hooks (see Phase 3)

Phase 3: Apply Styling

1. Read: references/styling-decision-guide.md [blocked]
2. Colors: Classify role (surface, accent, feedback, border) then pick hook
3. Spacing: Use utility classes (slds-p-*, slds-m-*) or hooks (--slds-g-spacing-*)
4. Layout: Use grid utilities (slds-grid, slds-col, slds-size_*)
5. Custom CSS: Use var(--slds-g-*, fallback), custom class prefixes only

Phase 4: Add Icons

1. Read: references/icons-decision-guide.md [blocked]
2. Search: node scripts/search-icons.cjs --query "<description>"
3. In LWC: Use <lightning-icon> with alternative-text
4. In non-LWC: Use SVG with slds-icon classes and slds-assistive-text

Phase 5: Validate (Mandatory — Do Not Skip)

npx @salesforce-ux/slds-linter@latest lint <component-path>

• All var(--slds-g-*) have fallback values (T002)
• Surface/accent/feedback color hooks are properly paired (T010–T013)
• Spacing uses hooks or utility classes — no magic px values (T020–T021)
• Font sizes use --slds-g-font-scale-*, not --slds-g-font-size-N (T031)
• All icons have accessibility text (A004)
• Custom classes use my-* or c-* prefix (Q010)

Quick Reference

Common Hook Patterns

/* 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);

Common Utility Patterns

<!-- 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>

Examples

Validation

Resources