mirror of https://github.com/forcedotcom/afv-library.git synced 2026-08-03 21:56:02 +08:00

GitHub Action 3a358c3b1c feat: Release: Standardize skill folder structure scripts/, references/, assets/ @W-23262449@

2026-07-03 05:25:02 +00:00

11 KiB

Raw Blame History

title

description

summary

artifact_type

domain

content_format

complexity

audience

tasks

children

refs

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:

Global Semantic (--slds-g-*): System-wide hooks for universal use across all components
Shared (--slds-s-*): Private/internal hooks — DO NOT USE (reserved for Salesforce)
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 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:

/* 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 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:

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

.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

.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

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

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:

/* ✅ 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