Skip to content

forcedotcom/sf-skills / skills/design-systems-slds-apply

design-systems-slds-apply

Unverified

Apply SLDS-compliant UI using the correct blueprints, styling hooks, utility classes, and icons. Use when building any UI that needs SLDS, choosing between Lightning Base Components and SLDS Blueprints, applying styling hooks for theming, using utility classes for layout and spacing, or selecting icons. Triggers include "build a modal", "create a form", "data table", "SLDS styling", "style with hooks", "add an icon".

FileKindSize
SKILL.mdskill md14.6 KB
assets/README.mdmarkdown2.3 KB
assets/blueprints/components/accordion.yamlconfig15.0 KB
assets/blueprints/components/activity-timeline.yamlconfig3.8 KB
assets/blueprints/components/alert.yamlconfig4.4 KB
assets/blueprints/components/app-launcher.yamlconfig3.8 KB
assets/blueprints/components/avatar-group.yamlconfig3.2 KB
assets/blueprints/components/avatar.yamlconfig3.5 KB
assets/blueprints/components/badges.yamlconfig3.3 KB
assets/blueprints/components/brand-band.yamlconfig12.9 KB
assets/blueprints/components/breadcrumbs.yamlconfig4.0 KB
assets/blueprints/components/builder-header.yamlconfig10.1 KB
assets/blueprints/components/button-groups.yamlconfig3.1 KB
assets/blueprints/components/button-icons.yamlconfig12.9 KB
assets/blueprints/components/buttons.yamlconfig9.4 KB
assets/blueprints/components/cards.yamlconfig4.6 KB
assets/blueprints/components/carousel.yamlconfig6.0 KB
assets/blueprints/components/chat.yamlconfig9.7 KB
assets/blueprints/components/checkbox-button-group.yamlconfig8.3 KB
assets/blueprints/components/checkbox-button.yamlconfig13.8 KB
assets/blueprints/components/checkbox-toggle.yamlconfig7.7 KB
assets/blueprints/components/checkbox.yamlconfig4.4 KB
assets/blueprints/components/color-picker.yamlconfig8.5 KB
assets/blueprints/components/combobox.yamlconfig5.5 KB
assets/blueprints/components/counter.yamlconfig6.6 KB
assets/blueprints/components/data-tables.yamlconfig6.0 KB
assets/blueprints/components/datepickers.yamlconfig6.1 KB
assets/blueprints/components/datetime-picker.yamlconfig7.4 KB
assets/blueprints/components/docked-composer.yamlconfig13.3 KB
assets/blueprints/components/docked-form-footer.yamlconfig6.1 KB
assets/blueprints/components/docked-utility-bar.yamlconfig10.9 KB
assets/blueprints/components/drop-zone.yamlconfig4.5 KB
assets/blueprints/components/dueling-picklist.yamlconfig8.8 KB
assets/blueprints/components/dynamic-icons.yamlconfig5.0 KB
assets/blueprints/components/dynamic-menu.yamlconfig7.7 KB
assets/blueprints/components/expandable-section.yamlconfig4.6 KB
assets/blueprints/components/expression.yamlconfig7.3 KB
assets/blueprints/components/feeds.yamlconfig5.7 KB
assets/blueprints/components/file-selector.yamlconfig6.8 KB
assets/blueprints/components/files.yamlconfig4.8 KB
assets/blueprints/components/form-element.yamlconfig6.1 KB
assets/blueprints/components/global-header.yamlconfig4.7 KB
assets/blueprints/components/global-navigation.yamlconfig4.3 KB
assets/blueprints/components/icons.yamlconfig5.1 KB
assets/blueprints/components/illustration.yamlconfig8.5 KB
assets/blueprints/components/input.yamlconfig5.4 KB
assets/blueprints/components/list-builder.yamlconfig6.2 KB
assets/blueprints/components/lookups.yamlconfig5.8 KB
assets/blueprints/components/map.yamlconfig5.0 KB
assets/blueprints/components/menus.yamlconfig5.5 KB
assets/blueprints/components/modals.yamlconfig6.1 KB
assets/blueprints/components/notifications.yamlconfig3.1 KB
assets/blueprints/components/page-headers.yamlconfig6.0 KB
assets/blueprints/components/panels.yamlconfig6.8 KB
assets/blueprints/components/path.yamlconfig6.4 KB
assets/blueprints/components/picklist.yamlconfig5.2 KB
assets/blueprints/components/pills.yamlconfig5.9 KB
assets/blueprints/components/popovers.yamlconfig4.6 KB
assets/blueprints/components/progress-bar.yamlconfig4.4 KB
assets/blueprints/components/progress-indicator.yamlconfig5.6 KB
assets/blueprints/components/progress-ring.yamlconfig4.0 KB
assets/blueprints/components/prompt.yamlconfig5.5 KB
assets/blueprints/components/publishers.yamlconfig7.0 KB
assets/blueprints/components/radio-button-group.yamlconfig7.3 KB
assets/blueprints/components/radio-group.yamlconfig5.0 KB
assets/blueprints/components/rich-text-editor.yamlconfig6.0 KB
assets/blueprints/components/scoped-notifications.yamlconfig7.6 KB
assets/blueprints/components/scoped-tabs.yamlconfig3.7 KB
assets/blueprints/components/select.yamlconfig4.3 KB
assets/blueprints/components/setup-assistant.yamlconfig8.8 KB
assets/blueprints/components/slider.yamlconfig4.2 KB
assets/blueprints/components/spinners.yamlconfig5.4 KB
assets/blueprints/components/split-view.yamlconfig4.4 KB
assets/blueprints/components/summary-detail.yamlconfig4.1 KB
assets/blueprints/components/tabs.yamlconfig6.1 KB
assets/blueprints/components/textarea.yamlconfig4.6 KB
assets/blueprints/components/tiles.yamlconfig4.0 KB
assets/blueprints/components/timepicker.yamlconfig5.1 KB
assets/blueprints/components/toast.yamlconfig6.5 KB
assets/blueprints/components/tooltips.yamlconfig4.1 KB
assets/blueprints/components/tree-grid.yamlconfig4.9 KB
assets/blueprints/components/trees.yamlconfig4.8 KB
assets/blueprints/components/trial-bar.yamlconfig4.2 KB
assets/blueprints/components/vertical-navigation.yamlconfig5.2 KB
assets/blueprints/components/vertical-tabs.yamlconfig6.9 KB
assets/blueprints/components/visual-picker.yamlconfig6.8 KB
assets/blueprints/components/welcome-mat.yamlconfig5.5 KB
assets/hooks-index.jsonconfig141.1 KB
assets/icon-metadata.jsonconfig919.3 KB
assets/utilities-index.jsonconfig508.6 KB
references/README.mdmarkdown5.8 KB
references/blueprints-index.mdmarkdown9.0 KB
references/checklists.mdmarkdown3.8 KB
references/component-selection.mdmarkdown3.7 KB
references/examples.mdmarkdown8.1 KB
references/icons-decision-guide.mdmarkdown3.8 KB
references/icons-guidance.mdmarkdown6.2 KB
references/overviews/borders.mdmarkdown11.0 KB
references/overviews/color.mdmarkdown12.0 KB
references/overviews/display-density.mdmarkdown18.7 KB
references/overviews/icons.mdmarkdown9.3 KB
references/overviews/illustrations.mdmarkdown10.3 KB
references/overviews/shadows.mdmarkdown7.0 KB
references/overviews/spacing.mdmarkdown9.8 KB
references/overviews/typography.mdmarkdown14.8 KB
references/overviews/utilities.mdmarkdown23.9 KB
references/slds-development-guide.mdmarkdown8.8 KB
references/styling-decision-guide.mdmarkdown9.3 KB
references/styling-hooks/borders.mdmarkdown9.0 KB
references/styling-hooks/color/expressive-palette-hooks.mdmarkdown6.7 KB
references/styling-hooks/color/index.mdmarkdown6.5 KB
references/styling-hooks/color/semantic/accent-hooks.mdmarkdown9.9 KB
references/styling-hooks/color/semantic/feedback-hooks.mdmarkdown33.4 KB
references/styling-hooks/color/semantic/surface-hooks.mdmarkdown17.1 KB
references/styling-hooks/color/system-hooks.mdmarkdown5.8 KB
references/styling-hooks/index.mdmarkdown10.8 KB
references/styling-hooks/shadows.mdmarkdown8.3 KB
references/styling-hooks/spacing.mdmarkdown12.3 KB
references/styling-hooks/typography.mdmarkdown17.8 KB
references/utilities-quick-ref.mdmarkdown3.7 KB
references/utilities/alignment.mdmarkdown3.7 KB
references/utilities/borders.mdmarkdown4.0 KB
references/utilities/box.mdmarkdown4.3 KB
references/utilities/color.mdmarkdown7.7 KB
references/utilities/dark-mode.mdmarkdown3.5 KB
references/utilities/description-list.mdmarkdown5.5 KB
references/utilities/floats.mdmarkdown3.8 KB
references/utilities/grid.mdmarkdown9.7 KB
references/utilities/horizontal-list.mdmarkdown3.7 KB
references/utilities/hyphenation.mdmarkdown2.3 KB
references/utilities/index.mdmarkdown6.6 KB
references/utilities/interactions.mdmarkdown3.1 KB
references/utilities/layout.mdmarkdown3.6 KB
references/utilities/line-clamp.mdmarkdown4.3 KB
references/utilities/margin.mdmarkdown5.2 KB
references/utilities/media-object.mdmarkdown5.3 KB
references/utilities/name-value-list.mdmarkdown4.8 KB
references/utilities/padding.mdmarkdown5.3 KB
references/utilities/position.mdmarkdown5.9 KB
references/utilities/print.mdmarkdown3.0 KB
references/utilities/scrollable.mdmarkdown4.1 KB
references/utilities/sizing.mdmarkdown5.7 KB
references/utilities/themes.mdmarkdown4.0 KB
references/utilities/truncate.mdmarkdown3.7 KB
references/utilities/typography.mdmarkdown4.6 KB
references/utilities/vertical-list.mdmarkdown5.1 KB
references/utilities/visibility.mdmarkdown6.1 KB
scripts/search-blueprints.cjsscript3.6 KB
scripts/search-hooks.cjsscript4.4 KB
scripts/search-icons.cjsscript6.1 KB
scripts/search-utilities.cjsscript5.3 KB

references/slds-development-guide.md

View on GitHub
---
id: slds.guidance.development
title: SLDS Development Guide
description: Root-level guidance for generating or optimizing SLDS-compliant code
summary: "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."

artifact_type: guide
domain: development
topic: development

content_format: structured
complexity: intermediate
audience: [implementer]

tasks: [learn, implement, choose]

refs:
  - 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

tags: [development, lwc, slds, theming, styling-hooks]
keywords: [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:**

```text
┌─────────────────────────────────────────────────────────────┐
│ 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.

```css
.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](#when-hooks-dont-exist).

---

## Framework-Specific Patterns

### LWC Layout

```html
<!-- 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)

```html
<!-- 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):**
```javascript
handleSubmit() {
  const allValid = [...this.template.querySelectorAll('lightning-input')]
    .reduce((valid, input) => input.reportValidity() && valid, true);
  if (allValid) { /* submit */ }
}
```

**Modal pattern (LWC):**
```javascript
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:

```text
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:**
```css
.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)

```css
: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

```html
<!-- 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)

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

```css
/* 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 |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall