afv-library/skills/applying-slds/guidance/slds-development-guide.md

id	title	description	summary	artifact_type	domain	topic	content_format	complexity	audience	tasks	refs	tags	keywords
slds.guidance.development	SLDS Development Guide	Root-level guidance for generating or optimizing SLDS-compliant code	Comprehensive development guide covering the component selection hierarchy (LBC → Blueprints → Hooks → Custom), framework-specific patterns, styling hooks usage, linter resolution, naming conventions, and code generation best practices.	guide	development	development	structured	intermediate	implementer	learn implement choose	slds.guidance.hooks.typography slds.guidance.hooks.spacing slds.guidance.uplift slds.guidance.hooks slds.guidance.hooks.color slds.guidance.blueprints slds.guidance.utilities slds.guidance.icons slds.guidance.design	development lwc slds theming styling-hooks	component hierarchy Lightning Base Components SLDS Blueprints styling hooks utility classes code generation linter naming conventions

SLDS Development Guide

Root-level guidance for AI coding agents generating or optimizing SLDS-compliant code.

---

What is SLDS?

The Salesforce Lightning Design System provides:

Resource	Description
Lightning Base Components	Pre-built LWC components with accessibility and theming built-in
SLDS Blueprints	CSS/HTML patterns for any framework (React, Vue, Angular, vanilla JS)
Styling Hooks	CSS custom properties (--slds-g-*) for theming
Utility Classes	Rapid styling classes for spacing, layout, visibility
Icons	SVG icons across action, utility, standard, custom, and doctype categories

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

---

Component Selection Hierarchy

Always follow this order when building UI:

┌─────────────────────────────────────────────────────────────┐
│ 1. Lightning Base Components (LWC only)                     │
├─────────────────────────────────────────────────────────────┤
│ 2. SLDS Blueprints (any framework)                          │
├─────────────────────────────────────────────────────────────┤
│ 3. Custom with Styling Hooks                                │
├─────────────────────────────────────────────────────────────┤
│ 4. Custom CSS (last resort, still use hooks for values)     │
└─────────────────────────────────────────────────────────────┘

Level 1: Lightning Base Components (LWC Only)

Pre-built, accessible, themed components. Always check first for LWC projects.

Component	Use Case
lightning-button	All button actions
lightning-input	Text, email, number, date inputs
lightning-combobox	Dropdown selection
lightning-datatable	Tabular data with sorting/selection
lightning-card	Content containers
lightning-modal	Dialog overlays

Level 2: SLDS Blueprints

HTML/CSS patterns for non-LWC frameworks or when no Lightning Base Component exists.

Level 3: Styling Hooks

CSS custom properties for theming. Use when customizing appearance.

.my-card {
  background: var(--slds-g-color-surface-1);
  padding: var(--slds-g-spacing-4);
  border-radius: var(--slds-g-radius-border-2);
}

Level 4: Custom CSS

Only when no hook exists for the property. See When Hooks Don't Exist.

---

Framework-Specific Patterns

LWC Layout

<!-- Use lightning-layout for responsive grids -->
<lightning-layout multiple-rows>
  <lightning-layout-item size="12" medium-device-size="6">
    <lightning-card title="Card 1">Content</lightning-card>
  </lightning-layout-item>
</lightning-layout>

Non-LWC Layout (React, Vue, Angular)

<!-- Use SLDS grid classes -->
<div class="slds-grid slds-wrap slds-gutters">
  <div class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2">
    <!-- Content -->
  </div>
</div>

---

Common Patterns Quick Reference

Pattern	LWC Component	Blueprint
Forms	lightning-input, lightning-combobox	Input, Combobox
Data Tables	lightning-datatable	Data Tables
Modals	lightning-modal	Modals
Cards	lightning-card	Cards

Form validation pattern (LWC):

handleSubmit() {
  const allValid = [...this.template.querySelectorAll('lightning-input')]
    .reduce((valid, input) => input.reportValidity() && valid, true);
  if (allValid) { /* submit */ }
}

Modal pattern (LWC):

import LightningModal from 'lightning/modal';
export default class MyModal extends LightningModal {
  handleClose() { this.close('result'); }
}

---

Core Rules

Do ✅

• Follow hierarchy: LBC → Blueprints → Styling Hooks → Custom CSS
• Use var(--slds-g-*) with fallbacks for all themeable values
• Create custom classes (e.g., my-*) instead of overriding .slds-*
• Verify components/hooks exist before implementing

Don't ❌

• Hard-code colors, spacing, or typography
• Override .slds-* classes directly
• Use deprecated --lwc-* tokens as primary values
• Use color alone to convey meaning

---

When Hooks Don't Exist

Not all CSS properties have styling hooks. Use this decision tree:

Does a styling hook exist for this property?
├─ YES → Use the hook with fallback: var(--slds-g-*, fallback)
├─ NO → Is there a utility class?
│       ├─ YES → Use the utility class
│       └─ NO → Use minimal custom CSS with:
│               1. Custom class (my-*, c-*)
│               2. Document why no hook/utility exists
│               3. Use hooks for related values (e.g., colors in gradients)

Properties without hooks (examples):

• transform, transition (use --slds-g-timing-* for duration only)
• z-index (use SLDS utility classes when possible)
• cursor
• overflow
• Complex gradients (use hook colors within gradient syntax)

Example - gradient with hook colors:

.my-gradient-bg {
  /* No gradient hook exists, but use hook colors */
  background: linear-gradient(
    to bottom,
    var(--slds-g-color-surface-1),
    var(--slds-g-color-surface-2)
  );
}

---

Naming Conventions

Custom Class Names

Use a consistent prefix to avoid collision with SLDS:

Pattern	Use Case	Example
my-*	General custom styling	my-card-header
c-*	LWC component-specific	c-accountList-row
[namespace]-*	Package/app namespace	acme-dashboard-widget

Avoid:

• Generic names: container, wrapper, header
• SLDS-like names: custom-slds-button
• BEM on SLDS classes: slds-card__custom-header

Custom Hook Names (for app-level theming)

:root {
  /* Namespace your custom hooks */
  --my-app-primary: var(--slds-g-color-brand-1);
  --my-app-card-padding: var(--slds-g-spacing-4);
}

---

Code Generation Style

When generating SLDS code, follow these patterns:

Minimal HTML + Classes

<!-- Prefer utility classes over custom CSS for common patterns -->
<div class="slds-card slds-p-around_medium slds-m-bottom_small">
  <h2 class="slds-text-heading_medium">Title</h2>
</div>

Avoid Unnecessary JavaScript

Use CSS/HTML solutions when possible:

• slds-hide instead of {if} for simple visibility
• slds-is-selected class toggling instead of complex state

Component Structure (LWC)

<template>
  <lightning-card title="Title">
    <div class="slds-p-around_medium">
      <!-- Content uses utility classes for spacing -->
    </div>
  </lightning-card>
</template>

/* Component CSS only for truly custom styles */
.my-custom-element {
  /* Use hooks */
  background: var(--slds-g-color-surface-2);
}

---

Resources

Resource	URL
SLDS Linter	https://developer.salesforce.com/docs/platform/slds-linter/guide
Lightning Components	https://developer.salesforce.com/docs/component-library/overview/components
SLDS Website	https://www.lightningdesignsystem.com/
Styling Hooks Index	https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks