forcedotcom/sf-skills / skills/design-systems-slds-apply
design-systems-slds-apply
UnverifiedApply 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".
references/styling-hooks/index.md
View on GitHub---
id: slds.guidance.hooks
title: SLDS Styling Hooks - Agent Guidance
description: Comprehensive guidance for using SLDS styling hooks in component development
summary: "Entry point for all styling hooks guidance. Covers the three-tier hook hierarchy (global, shared, component), core categories (color, spacing, typography, shadows, borders), usage patterns, decision trees, and accessibility requirements. Use styling hooks instead of hard-coded values for theme-aware, maintainable components."
artifact_type: index
domain: styling-hooks
content_format: structured
complexity: intermediate
audience: [implementer]
tasks: [choose, implement, troubleshoot]
children:
- slds.guidance.hooks.color
- slds.guidance.hooks.typography
- slds.guidance.hooks.spacing
- slds.guidance.hooks.borders
- slds.guidance.hooks.shadows
refs:
- slds.guidance.hooks.shadows
- slds.guidance.hooks.borders
tags: [styling-hooks, index, color, spacing, typography, shadows, borders, theming]
keywords: [styling hooks, CSS custom properties, theming, accessibility, design tokens, SLDS]
---
# SLDS Styling Hooks: Guidance for Coding Agents
## Overview
The Salesforce Lightning Design System (SLDS) styling hooks are CSS custom properties that provide a theme-aware, maintainable styling system. When generating or optimizing SLDS components, **always use styling hooks instead of hard-coded values** to ensure components adapt automatically to:
- Brand themes and customizations
- Light/dark mode switches
- Density settings (compact, comfy, spacious)
- Accessibility requirements
- Future design system updates
**Critical Rule:** Reference styling hooks using `var()` — never reassign their values. Salesforce controls these values and can change them at any time.
---
## Styling Hook Hierarchy
SLDS styling hooks follow a three-tier naming convention:
1. **Global Semantic** (`--slds-g-*`): System-wide hooks for universal use across all components
2. **Shared** (`--slds-s-*`): Private/internal hooks — **DO NOT USE** (reserved for Salesforce)
3. **Component-Specific** (`--slds-c-*`): Hooks scoped to individual component types for fine-tuning
**Always use global hooks (`--slds-g-*`) unless component-specific hooks exist for your use case.**
---
## Core Categories
### 1. Color Hooks (`--slds-g-color-*`)
SLDS provides a comprehensive color system organized into three tiers:
#### **Tier 1: Semantic UI Colors (PREFERRED)**
Purpose-driven colors that automatically adapt to themes and modes:
- **Surface** (`surface-*`): Page backgrounds, panels, modal overlays
- **Container** (`container-*`): Buttons, cards, tabs, input fields
- **Accent** (`accent-*`): Brand emphasis and selection states
- **Border** (`border-*`): Component borders, dividers, separators
- **Feedback** (`feedback-*`): Alerts, notifications, validation states
- **On-Colors** (`on-*`): Text and icons on colored backgrounds
#### **Tier 2: System Colors**
Accessible, system-wide colors for edge cases where semantic colors don't apply.
#### **Tier 3: Palette Colors (Use Sparingly)**
Raw color values for data visualization and custom scenarios.
> **💡 Detailed color guidance:** See [Color Styling Hooks Index](ref:slds.guidance.hooks.color) for the complete color system documentation.
---
### 2. Spacing Hooks (`--slds-g-spacing-*`)
SLDS uses a numbered scale (NOT named like "small/medium/large"):
| Hook Name | Value | Pixels | Legacy Equivalent |
| --------------------- | ------- | ------ | ----------------- |
| `--slds-g-spacing-1` | 0.25rem | 4px | xx-small |
| `--slds-g-spacing-2` | 0.5rem | 8px | x-small |
| `--slds-g-spacing-3` | 0.75rem | 12px | small |
| `--slds-g-spacing-4` | 1rem | 16px | medium |
| `--slds-g-spacing-5` | 1.5rem | 24px | large |
| `--slds-g-spacing-6` | 2rem | 32px | x-large |
| `--slds-g-spacing-7` | 2.5rem | 40px | xx-large |
| `--slds-g-spacing-8` | 3rem | 48px | xxx-large |
| `--slds-g-spacing-9` | 3.5rem | 56px | - |
| `--slds-g-spacing-10` | 4rem | 64px | - |
| `--slds-g-spacing-11` | 4.5rem | 72px | - |
| `--slds-g-spacing-12` | 5rem | 80px | - |
**Usage:**
```css
/* Use numbered hooks - NOT named ones */
margin: var(--slds-g-spacing-4); /* ✅ Correct */
padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4); /* ✅ Correct */
/* DON'T use named hooks - they don't exist */
margin: var(--slds-g-spacing-medium); /* ❌ Wrong - hook doesn't exist */
```
> **💡 Detailed spacing guidance:** See [Spacing and Sizing Hooks](ref:slds.guidance.hooks.spacing) for complete documentation.
---
### 3. Typography Hooks (`--slds-g-font-*`)
#### Font Families
- `--slds-g-font-family` - Default font family
- `--slds-g-font-family-base` - Base font family
- `--slds-g-font-family-monospace` - For code snippets
#### Font Weights (Numbered 1-7)
| Hook Name | Typical Value | Common Name |
| ------------------------ | ------------- | ----------- |
| `--slds-g-font-weight-1` | 300 | Light |
| `--slds-g-font-weight-2` | 300 | Light |
| `--slds-g-font-weight-3` | 400 | Regular |
| `--slds-g-font-weight-4` | 400 | Regular |
| `--slds-g-font-weight-5` | 500 | Medium |
| `--slds-g-font-weight-6` | 600 | Semi-Bold |
| `--slds-g-font-weight-7` | 700 | Bold |
**Usage:**
```css
/* Use numbered hooks */
font-weight: var(--slds-g-font-weight-7); /* Bold */
/* DON'T use named hooks - they don't exist */
font-weight: var(--slds-g-font-weight-bold); /* ❌ Wrong */
```
> **💡 Detailed typography guidance:** See [Typography Styling Hooks](ref:slds.guidance.hooks.typography) for complete documentation.
---
### 4. Other Styling Hooks
- **Sizing** (`--slds-g-sizing-*`): Component dimensions, icon sizes, border widths
- **Shadow** (`--slds-g-shadow-*`): Elevation and depth effects
- **Radius** (`--slds-g-radius-*`): Border radius values for rounded corners
---
## Usage Patterns
### Pattern 1: Interactive Component States (Accent Colors)
```css
.button {
background: var(--slds-g-color-accent-container-1);
color: var(--slds-g-color-on-accent-1);
border: 1px solid var(--slds-g-color-border-accent-1);
padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
border-radius: var(--slds-g-radius-border-1);
}
.button:hover {
background: var(--slds-g-color-accent-container-2);
color: var(--slds-g-color-on-accent-2);
border-color: var(--slds-g-color-border-accent-2);
}
.button:active {
background: var(--slds-g-color-accent-container-3);
color: var(--slds-g-color-on-accent-3);
border-color: var(--slds-g-color-border-accent-3);
}
```
### Pattern 2: Semantic Surfaces
```css
.card {
background: var(--slds-g-color-surface-container-1);
color: var(--slds-g-color-on-surface-1);
padding: var(--slds-g-spacing-4);
border: 1px solid var(--slds-g-color-border-1);
border-radius: var(--slds-g-radius-border-1);
}
```
### Pattern 3: Feedback States
```css
.alert-error {
background: var(--slds-g-color-error-container-1);
color: var(--slds-g-color-on-error-1);
border-left: 4px solid var(--slds-g-color-error-1);
padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
}
.alert-success {
background: var(--slds-g-color-success-container-1);
color: var(--slds-g-color-on-success-1);
border-left: 4px solid var(--slds-g-color-success-1);
}
```
---
## Decision Tree for Coding Agents
### Step 1: Check for Component-Specific Hooks
Search for `--slds-c-[component-name]-*` hooks first (highest specificity).
### Step 2: Use Semantic UI Colors (Preferred)
For colors, prefer semantic hooks:
- **Surface/Container**: `surface-1/2/3`, `surface-container-1/2/3`, `on-surface-1/2/3`
- **Accent**: `accent-1/2/3`, `accent-container-1/2/3`, `border-accent-1/2/3`, `on-accent-1/2/3`
- **Feedback**: `error-1`, `success-1`, `warning-1`, `info-1` with their container and on-color variants
### Step 3: Use Numbered Spacing & Typography
Always use numbered hooks where available:
```css
padding: var(--slds-g-spacing-4);
font-weight: var(--slds-g-font-weight-5);
font-size: var(--slds-g-font-size-base); /* Or use rem values */
```
---
## Critical Rules
### DO:
- Reference hooks with `var()`: `color: var(--slds-g-color-accent-1);`
- Use numbered spacing: `spacing-4` not `spacing-medium`
- Use numbered font weights: `font-weight-5` not `font-weight-medium`
- Prefer semantic UI colors over system colors and palette colors
- Pair container colors with on-colors for text/icons
- Follow the 50-point rule for text contrast, 40-point rule for UI elements
### DON'T:
- Reassign hook values: `--slds-g-color-accent-1: #ff0000;` ❌
- Use private hooks (`--_slds-*` or `--slds-s-*`)
- Use `@layer` syntax (reserved for Salesforce)
- Use named spacing hooks (`spacing-small`, `spacing-medium`) - they don't exist
- Use named font hooks (`font-weight-medium`, `font-weight-bold`) - they don't exist
- Hard-code values when hooks exist
---
## Accessibility Compliance
### Color Contrast Rules
| Separation | Contrast Ratio | Use Case |
| ---------- | -------------- | -------------------------- |
| 50 points | 4.5:1 | Text (WCAG AA) |
| 40 points | 3:1 | UI elements, borders |
### Automatic Compliance with Semantic Colors
When using semantic accent colors, SLDS ensures contrast automatically:
```css
/* ✅ ALWAYS COMPLIANT when using matching pairs */
.accent-button {
background: var(--slds-g-color-accent-container-1);
color: var(--slds-g-color-on-accent-1); /* Pre-validated pairing */
}
```
---
## Troubleshooting
### Problem: Hook name not working
**Solution:** Verify naming convention:
- Use numbered spacing: `spacing-4` NOT `spacing-medium`
- Use numbered fonts: `font-weight-5` NOT `font-weight-medium`
### Problem: Colors have poor contrast
**Solution:**
- Use semantic hooks with paired on-colors
- For palette: 50-point separation for text, 40-point for UI elements
### Problem: Spacing inconsistent
**Solution:**
- Use numbered spacing hooks: `spacing-2`, `spacing-4`
- Check spacing scale: 8px=spacing-2, 16px=spacing-4, 24px=spacing-5
---
## Summary
When generating or optimizing SLDS components:
1. **Use semantic hooks first** — Prefer semantic UI colors over system/palette
2. **Use numbered hooks** — spacing-4, font-weight-5 (NOT named like "medium")
3. **Font sizes** — Use `font-size-base` or rem values
4. **Follow the three-tier color system** — Semantic UI → System Colors → Expressive Palette
5. **Pair containers with on-colors** — Use `on-surface-*`, `on-accent-*`, `on-error-*` for text/icons
6. **Test accessibility** — Verify contrast ratios and keyboard navigation
**The goal:** Build theme-aware, accessible components that adapt automatically to brand customizations, light/dark modes, and density settings.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |