Skip to content
SalesforceSkills

Design System

Makes your components look like they belong in Salesforce. Handles colors, spacing, and fonts automatically.

Always use `--slds-g-*` CSS custom propertiesNever hardcodeAlways provide fallback valuesPrefer `lightning-*` base componentsStructure CSS

Skill Details

Install this skill

Versionv1.0.0AuthorBrendan SheridanLicenseMITSections9

Works with

Claude CodeCursorWindsurf

Generate Lightning Web Components that are fully compliant with SLDS 2 (Salesforce Cosmos theme). All styling must use global styling hooks (--slds-g-) — never hardcoded values.

Core Rules

1
*Always use --slds-g- CSS custom properties** for colors, spacing, sizing, typography, shadows, and radii
2
Never hardcode hex colors, pixel sizes, or font stacks
3
Always provide fallback values in var() for resilience
4
*Prefer lightning- base components** over custom HTML where available
5
Structure CSS with semantic intent, not visual description

SLDS 2 Architecture

SLDS 2 decouples structure (layout, spacing) from visual design (colors, radii, shadows). This enables theme switching (light/dark/custom) without component changes.

┌─────────────────────────────────────────┐
│  Theme Layer (Cosmos, custom, dark)     │  --slds-g-color-*, --slds-g-shadow-*
├─────────────────────────────────────────┤
│  Structure Layer (layout, spacing)      │  --slds-g-spacing-*, --slds-g-sizing-*
├─────────────────────────────────────────┤
│  Component Layer (lightning-*, LWC)     │  Consumes hooks, never overrides them
└─────────────────────────────────────────┘

Global Styling Hooks Reference

Surface Colors

Use for backgrounds, text on backgrounds, and borders of content areas.

Accent Colors

Use for interactive elements, links, and branded highlights.

Feedback Colors

Use for status indicators, alerts, and validation states.

All hooks above are prefixed with --slds-g-color-. Example: var(--slds-g-color-error-1).

Typography

Spacing

Use for margin and padding. Do not use for width/height (use sizing instead).

Sizing

Use for element dimensions (width, height, icons).

Shadows and Borders

Theme-Safe Styling

Components use light mode by default. By using --slds-g- hooks instead of hardcoded values, components automatically adapt if an org later enables dark mode (Cosmos dark theme) — no code changes needed. Dark mode is an opt-in enhancement, not a default requirement.

Before adding dark mode support, ask the user: "Do you want this component to support dark mode, or is light mode sufficient?"

Rules (Apply Always — Light and Dark)

  • No hex/rgb/hsl literals in CSS — always var(--slds-g-color-)
  • No inline color styles in HTML templates
  • Provide fallbacks: var(--slds-g-color-surface-1, #ffffff) (fallback to light mode values)
  • Icons: Use lightning-icon with SLDS utility sprites, never custom SVGs with hardcoded fill

Additional Rules (Only When Dark Mode Requested)

  • Images: Use mix-blend-mode or CSS filters when images must adapt to dark backgrounds
  • Test in both themes: Verify all text is readable and contrast ratios meet WCAG AA in both light and dark

CSS Pattern

CSS
.card {
    background-color: var(--slds-g-color-surface-1, #ffffff);
    color: var(--slds-g-color-on-surface-1, #181818);
    border: var(--slds-g-sizing-border-1) solid var(--slds-g-color-border-1, #e5e5e5);
    border-radius: var(--slds-g-radius-border-2, 0.25rem);
    box-shadow: var(--slds-g-shadow-1);
    padding: var(--slds-g-spacing-4, 1rem);
}

.card-header {
    color: var(--slds-g-color-on-surface-1, #181818);
    font-size: var(--slds-g-font-size-5, 1rem);
    font-weight: var(--slds-g-font-weight-7, 700);
    margin-bottom: var(--slds-g-spacing-3, 0.75rem);
}

SLDS 1 to SLDS 2 Migration

Component Structure Patterns

Prefer Base Components

HTML
class="code-comment"><!-- Preferred: base component with built-in SLDS 2 -->
<class="code-tag">lightning-card title="Account Details">
    <class="code-tag">lightning-badge label="Active"></class="code-tag">lightning-badge>
    <class="code-tag">lightning-icon icon-name="utility:check" size="small"></class="code-tag">lightning-icon>
</class="code-tag">lightning-card>

class="code-comment"><!-- Custom HTML only when base components lack functionality -->
<class="code-tag">div class="custom-metric-card">
    <class="code-tag">span class="metric-label">{label}</class="code-tag">span>
    <class="code-tag">span class="metric-value">{value}</class="code-tag">span>
</class="code-tag">div>

Template Structure

HTML
<class="code-tag">template>
    <class="code-tag">lightning-card title={cardTitle} icon-name={iconName}>
        class="code-comment"><!-- Status region: use feedback hooks -->
        <class="code-tag">div class="status-banner" if:true={hasStatus}>
            <class="code-tag">lightning-icon icon-name={statusIcon} size="x-small"></class="code-tag">lightning-icon>
            <class="code-tag">span class="status-text">{statusMessage}</class="code-tag">span>
        </class="code-tag">div>

        class="code-comment"><!-- Content region: use surface hooks -->
        <class="code-tag">div class="content-body">
            <class="code-tag">slot></class="code-tag">slot>
        </class="code-tag">div>

        class="code-comment"><!-- Action region: use accent hooks -->
        <class="code-tag">div slot="actions">
            <class="code-tag">lightning-button label="Edit" onclick={handleEdit}></class="code-tag">lightning-button>
        </class="code-tag">div>
    </class="code-tag">lightning-card>
</class="code-tag">template>

Scoring Rubric (100 Points)Reference

Scoring Guide

  • 90-100: Production-ready, fully SLDS 2 compliant
  • 70-89: Minor issues (missing fallbacks, 1-2 hardcoded values)
  • 50-69: Needs rework (mixed SLDS 1/2, several hardcoded values)
  • Below 50: Major redesign needed

Cross-Skill IntegrationReference

HookPurposeExample Use
--slds-g-color-surface-1Primary backgroundPage/card background
--slds-g-color-surface-2Secondary backgroundNested card, sidebar
--slds-g-color-surface-3Tertiary backgroundHover row highlight
--slds-g-color-surface-container-1Container backgroundOuter wrapper
--slds-g-color-surface-container-2Nested containerInner panel
--slds-g-color-surface-container-3Deep nested containerCollapsible section
--slds-g-color-on-surface-1Primary textBody text
--slds-g-color-on-surface-2Secondary textLabels, captions
--slds-g-color-on-surface-3Tertiary textPlaceholder, disabled
--slds-g-color-border-1Default borderCard border, dividers
--slds-g-color-border-2Subtle borderInner separators
HookPurpose
--slds-g-color-accent-1Primary interactive (links, active)
--slds-g-color-accent-2Secondary interactive
--slds-g-color-accent-3Tertiary interactive
--slds-g-color-accent-container-1Active/selected background
--slds-g-color-on-accent-1Text on accent background
--slds-g-color-border-accent-1Active/focus border
StateColorContainerTextBorder
Errorerror-1, error-2error-container-1on-error-1border-error-1
Warningwarning-1, warning-2warning-container-1on-warning-1border-warning-1
Successsuccess-1, success-2success-container-1on-success-1border-success-1
Infoinfo-1, info-2info-container-1on-info-1—
Disableddisabled-1, disabled-2disabled-container-1on-disabled-1border-disabled-1
HookPurpose
--slds-g-font-size-1 through -15Font size scale (1 = smallest)
--slds-g-font-size-baseRoot font size
--slds-g-font-weight-1 through -7Weight scale (4 = normal, 7 = bold)
--slds-g-line-height-1 through -5Line height scale (unitless)
HookScale
--slds-g-spacing-1 through -12Modular scale of 4, relative to root font size
HookScale
--slds-g-sizing-1 through -12Relative to root font size
HookPurpose
--slds-g-shadow-1 through -4Elevation layers (1 = subtle, 4 = prominent)
--slds-g-radius-border-1 through -4Corner radius scale
--slds-g-radius-circleCircle (50%)
--slds-g-radius-border-pillPill shape
--slds-g-sizing-border-1 through -4Border width scale
SLDS 1 (Deprecated)SLDS 2 Replacement
var(--lwc-colorBackground)var(--slds-g-color-surface-1)
var(--lwc-colorTextDefault)var(--slds-g-color-on-surface-1)
var(--lwc-colorBorder)var(--slds-g-color-border-1)
var(--lwc-colorTextLink)var(--slds-g-color-accent-1)
var(--lwc-colorTextError)var(--slds-g-color-error-1)
var(--lwc-colorTextSuccess)var(--slds-g-color-success-1)
var(--lwc-colorTextWarning)var(--slds-g-color-warning-1)
var(--lwc-spacingMedium)var(--slds-g-spacing-4)
var(--lwc-borderRadiusMedium)var(--slds-g-radius-border-2)
var(--lwc-fontSize4)var(--slds-g-font-size-5)
var(--lwc-fontWeightBold)var(--slds-g-font-weight-7)
t-salesforce-sans (font token)var(--slds-g-font-family)
CategoryPointsPass Criteria
SLDS 2 Hook Usage25All colors, spacing, sizing, typography use --slds-g- hooks
Theme-Safe Styling20Zero hardcoded colors; fallbacks on every var(); no inline styles
Migration Compliance15No SLDS 1 --lwc- tokens; no deprecated class names
Component Structure15Uses lightning- base components where available; semantic HTML
Surface/Accent/Feedback15Correct semantic use of color categories (not accent for errors, etc.)
Typography & Spacing10Consistent use of scale hooks; no magic numbers
SkillRelationship
sf-lwcHandles JS logic, wire service, Apex, Jest — this skill handles design tokens
sf-lwc-uxConsumes the design foundation for UX patterns and accessibility
sf-lwc-stylingMaps these hooks to utility-first CSS classes

DependenciesReference

  • Target org with SLDS 2 support (API 62.0+, Spring '25+)
  • Salesforce Cosmos theme enabled (or custom SLDS 2 theme)
  • sf CLI authenticated for deployment validation

More in Look & Feel

Styling & CSS

Look & Feel

Ready-made styles for cards, badges, tables, forms, and more. Like a recipe book for making things look good.

Branding & Themes

Look & Feel

Customize colors and branding to match your company. Supports light mode, dark mode, and multi-brand setups.

Navigate Look & Feel

Next
Styling & CSS