Applying Slds

Applying SLDS

The Salesforce Lightning Design System (SLDS) is a CSS framework with thousands of artifacts. This skill teaches agents how to find and correctly use them.

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

>

Audit scope: The companion validating-slds skill analyzer only scans .css, .html, and .js files. Use it directly for LWC and similar HTML/CSS/JS components; treat it as a partial signal for JSX/TSX or other framework-specific template formats and supplement with manual review.

What is SLDS?

---

Scope

This skill covers:

• Which blueprint to use for a given UI pattern
• How to style with hooks (color, spacing, typography, shadows, borders)
• Which utility classes to use for layout, spacing, visibility
• Which icon to use and from which category
• SLDS naming conventions, class structure, hook syntax

This skill includes basic accessibility reminders (icon alt text, focus outlines, color-not-sole-indicator) in the validation checklists. Full WCAG compliance requires a dedicated accessibility review.

This skill does NOT cover (use companion skills):

• Design decisions -- visual hierarchy, composition, interaction patterns
• LWC mechanics -- component structure, @wire, @api, lifecycle, events (not yet available)
• Full accessibility -- WCAG conformance, ARIA patterns, keyboard navigation, focus management, contrast ratios (not yet available)

---

Component Selection Hierarchy

Always follow this order:

1. Lightning Base Components (LWC only)    ← Check first
2. SLDS Blueprints (any framework)         ← Use exact SLDS classes
3. Custom with Styling Hooks               ← Use var(--slds-g-*)
4. Custom CSS (last resort)                ← Still use hooks for values

If building in LWC, check for an LBC first: Lightning Component Library

If no LBC exists (or not using LWC), select an SLDS Blueprint. See references/component-selection.md.

---

Core Rules

Do

• Follow the selection hierarchy: LBC > Blueprint > Hooks > Custom CSS
• Use var(--slds-g-*, fallback) for all themeable values
• Create custom classes (my-*, c-*) instead of overriding .slds-*
• Verify every hook, class, and utility exists before using it — run the search scripts; never assume an artifact exists based on naming patterns (see Verify Before You Use)
• Pair surface colors with on-surface colors for text
• Provide alternative-text on every <lightning-icon>

Don't

• Hard-code colors, spacing, or typography values
• Override .slds-* classes directly
• Use deprecated --lwc-* tokens as primary values
• Use --slds-s-* (shared) hooks -- they are private/internal
• Reassign hook values -- only reference them with var()
• Use color alone to convey meaning
• Invent hook names by interpolating patterns from other families (see Na

Validation Checklists

Run through these checks before finalizing any SLDS-authored component. Check IDs align with the validating-slds skill's quality-checks.md.

Theming & Styling (T-series)

Code produced by this skill should score high on T-series checks.

---

Code Quality (Q-series)

---

Component Usage (C-series)

---

Accessibility Reminders (A-series)

Deep accessibility is owned by the accessibility skill. These are minimal reminders to nudge agents.

For full WCAG compliance, apply the accessibility skill after authoring.

---

Quick Validation Script

Run the SLDS linter to catch the most common issues automatically:

npx @salesforce-ux/slds-linter@latest lint .

The linter catches:

• slds/class-override -- overriding SLDS classes
• slds/lwc-token-to-slds-hook -- deprecated tokens
• slds/no-hardcoded-values -- hardcoded colors/spacing

Everything above the linter line must be checked manually or by the auditing skill.

Examples

Worked examples showing the SLDS authoring workflow: from intent to artifact selection.

Each example follows the 5-phase workflow from SKILL.md and shows which files were consulted and why.

Example 1: Build a Confirmation Dialog

Phase 1: Understand the Need

• Pattern: Confirmation dialog before a destructive action
• Framework: LWC
• States: Open, confirming (loading), closed

Phase 2: Select the Artifact

Check LBC: LightningModal exists in the Lightning Component Library. Use it.

Also search blueprints (for class reference):

node scripts/search-blueprints.cjs --search "modal"
# Found: Modals (category: Overlay, root: slds-modal)

Read blueprint YAML for class details: metadata/blueprints/components/modals.yaml

Key takeaway: LightningModal handles the slds-modal, slds-backdrop, and ARIA attributes automatically. No need to apply blueprint classes manually in LWC.

Phase 3: Apply Styling

Read: references/styling-decision-guide.md

The destructive action button needs error color to signal danger:

node scripts/search-hooks.cjs --prefix "--slds-g-color-error-"
# Found: --slds-g-color-error-1 (#ea001e), --slds-g-color-on-error-1 (#ffffff)

Result: Use variant="destructive" on lightning-button inside the modal footer. The LBC handles the correct SLDS color hooks internally.

For the modal body spacing, use utility classes:

<div class="slds-p-around_medium slds-text-align_center">
  <p>Are you sure you want to delete this record?</p>
</div>

Phase 4: Add Icons

Search: node scripts/search-icons.cjs --query "warning"

Found: utility:warning (score: 100, match: exact)

<lightning-icon
    icon-name="utility:warning"
    alternative-text="Warning"
    variant="error"
    size="small"
    class="slds-m-right_x-small">
</lightning-icon>

Phase 5: Validate (checklists.md)

• No hardcoded colors (using LBC variants + hooks)
• Icon has alternative-text
• Spacing uses utility classes (slds-p-around_medium, slds-m-right_x-small)
• No .slds-* overrides

---

Example 2: Styled Card with Status Badge (Non-LWC)

Phase 1: Understand the Need

• Pattern: A card showing a record with a colored status badge
• Framework: React (not LWC -- no LBCs available)
• States: Active, inactive, pending

Phase 2: Select the Artifact

LBC check: Not applicable (React).

Search blueprints:

node scripts/search-blueprints.cjs --search "card"
# Found: Cards (category: Layout, root: slds-card)

node scripts/search-blueprints.cjs --search "badge"
# Found: Badges (category: Feedback, root: slds-badge)

Read YAMLs:

• metadata/blueprints/components/cards.yaml -- classes: slds-card, slds-card__header, slds-card__body, slds-card__footer
• metadata/blueprints/components/badges.yaml -- classes: slds-badge, modifiers: slds-badge_lightest, slds-badge_inverse

Phase 3: Apply Styling

Read: references/styling-decision-guide.md

Card background and text use surface hooks. The status is conveyed by badge text plus a custom status accent on the card, rather than invented badge modifiers.

<article class="slds-card my-status-card">
  <div class="slds-card__header slds-grid">
    <header class="slds-media slds-media_center slds-has-flexi-truncate">
      <div class="slds-media__body">
        <h2 class="slds-card__header-title slds-truncate">Account Name</h2>
      </div>
      <div class="slds-no-flex">
        <span class="slds-badge slds-badge_lightest">Active</span>
      </div>
    </header>
  </div>
  <div class="slds-card__body slds-card__body_inner">
    <p>Record details here</p>
  </div>
</article>

Custom styling for a subtle card border:

.my-status-card {
  border-left: 3px solid var(--slds-g-color-accent-1, #0176d3);
}

Note: custom class uses my-* prefix, hook with fallback, no .slds-* overrides.

Phase 4: Add Icons

Search for a standard object icon:

node scripts/search-icons.cjs --query "account" --category "standard"
# Found: standard:account (score: 100, match: exact)

In React (non-LWC), use the SVG blueprint pattern:

<span class="slds-icon_container slds-icon-standard-account" title="Account">
  <svg class="slds-icon slds-icon_small" aria-hidden="true">
    <use xlinkHref="/assets/icons/standard-sprite/svg/symbols.svg#account"></use>
  </svg>
  <span class="slds-assistive-text">Account</span>
</span>

Phase 5: Validate

• Card uses exact blueprint classes (slds-card, slds-card__header, etc.)
• Badge uses a real blueprint modifier (slds-badge_lightest), not an invented status variant
• Custom border uses my-* prefix and hook with fallback
• Icon uses slds-assistive-text for accessibility
• No hardcoded colors

---

Example 3: Responsive Data Layout with Hooks

Phase 1: Understand the Need

• Pattern: A responsive grid of metric cards
• Framework: LWC
• States: Loading (spinner), populated, empty (illustration)

Phase 2: Select the Artifact

LBC: lightning-card for each metric card. lightning-spinner for loading.

Search for empty state:

node scripts/search-blueprints.cjs --search "illustration"
# Found: Illustration (category: Media, root: slds-illustration)

Phase 3: Apply Styling

Verify grid and spacing utilities before using them:

node scripts/search-utilities.cjs --search "slds-grid"
# Found: slds-grid (category: grid, css: display: flex)

node scripts/search-utilities.cjs --search "slds-text-heading_large"
# Found: slds-text-heading_large (category: typography)

node scripts/search-utilities.cjs --search "slds-text-body_small"
# Found: slds-text-body_small (category: typography)

Grid layout uses utility classes (see references/utilities-quick-ref.md):

<div class="slds-grid slds-wrap slds-gutters">
  <template for:each={metrics} for:item="metric">
    <div key={metric.id} class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2 slds-large-size_1-of-3">
      <lightning-card title={metric.label}>
        <div class="slds-p-horizontal_small">
          <p class="slds-text-heading_large">{metric.value}</p>
          <p class="slds-text-body_small slds-text-color_weak">{metric.subtitle}</p>
        </div>
      </lightning-card>
    </div>
  </template>
</div>

Custom metric styling with hooks:

.my-metric-value {
  font-size: var(--slds-g-font-scale-6, 2rem);
  font-weight: var(--slds-g-font-weight-7, 700);
  color: var(--slds-g-color-on-surface-3, #181818);
}

.my-metric-trend-up {
  color: var(--slds-g-color-success-1, #2e844a);
}

.my-metric-trend-down {
  color: var(--slds-g-color-error-1, #ea001e);
}

Note: trend colors use semantic feedback hooks (success/error), not hardcoded green/red.

Empty state uses the SLDS illustration blueprint:

<template if:false={hasData}>
  <div class="slds-illustration slds-illustration_small">
    <img src="/img/chatter/Desert.svg" class="slds-illustration__svg" alt="" />
    <div class="slds-text-longform">
      <h3 class="slds-text-heading_medium">No metrics available</h3>
      <p class="slds-text-body_regular">Check back when data is loaded.</p>
    </div>
  </div>
</template>

Phase 4: Add Icons

Trend indicators need icons:

node scripts/search-icons.cjs --query "arrow up"
# Found: utility:arrowup (score: 100)

node scripts/search-icons.cjs --query "arrow down"
# Found: utility:arrowdown (score: 100)

<lightning-icon
    icon-name={metric.trendIcon}
    alternative-text={metric.trendLabel}
    size="xx-small"
    class="slds-m-left_xx-small">
</lightning-icon>

Phase 5: Validate

• Grid uses slds-grid + slds-col + responsive slds-*-size_* classes
• Spacing uses utilities (slds-p-horizontal_small, slds-m-left_xx-small)
• Typography uses utilities (slds-text-heading_large, slds-text-body_small)
• Custom CSS uses my-* prefix and hooks with fallbacks
• Trend colors use semantic hooks (success/error), not hardcoded values
• Empty state uses SLDS illustration blueprint
• Icons have alternative-text

SLDS Blueprints Index

Overview

Blueprints provide HTML structure, CSS classes, ARIA requirements, and code examples for each SLDS component. Each blueprint includes:

• HTML structure: Element hierarchy and required markup
• CSS classes: Root, element, modifier, size, and state classes
• Styling hooks: CSS custom properties for theming
• Accessibility: ARIA attributes, keyboard patterns, screen reader guidance
• Code examples: Usage examples for variants
• Lightning component mapping: Corresponding LWC when available

Use blueprints when building custom HTML/CSS, targeting non-Salesforce platforms, or when no Lightning Base Component exists.

Use Lightning Base Components when working within Salesforce (LWC, Aura, Visualforce) — they handle accessibility, events, and framework integration automatically.

---

Blueprints by Category

Actions

---

Input

Form controls for user input and data entry.

---

Layout

Components for organizing and structuring content.

---

Navigation

Components for navigation and wayfinding.

---

Display

---

Data

Components for displaying structured data.

---

Feedback

Components for communicating status and feedback.

---

Overlay

Components that appear above the main interface.

---

Complex Components

Advanced components with rich functionality.

---

Framework Notes

• LWC / Aura: Prefer the mapped Lightning component when listed — it handles accessibility and events.
• React / Vue / Angular / plain HTML: Use the blueprint HTML structure and CSS classes directly.
• Customization: Apply styling hooks (CSS custom properties) to theme components without overriding base styles.

SLDS Icons Guidance

Overview

SLDS icons are a curated set of reusable SVG symbols grouped into sprite categories. They're used to add quick, consistent visual meaning to UI elements (buttons, navigation, record headers, status indicators, file types, and more).

This guidance covers:

• Category guidance for picking the right sprite
• Implementation patterns (Lightning + SLDS markup)
• Accessibility requirements for icons in UI

---

Icon Naming Model (Critical)

An icon is referenced as:

• `sprite:symbol` (example: utility:search, action:save, standard:account)

Where:

• sprite = category (action, utility, standard, custom, doctype)
• symbol = the icon name within that sprite

---

Category Decision Guide (What to Use When)

Action Icons (action:*)

• Use for: verbs / user actions (save, delete, edit, add, close)
• Common placements: buttons, menus, toolbars, row actions
• Rule of thumb: if the UI text could start with "Do …", use action:

Utility Icons (utility:*)

• Use for: general interface affordances and controls (search, settings, filter, chevrons)
• Common placements: nav, search fields, utility panels, small inline UI hints
• Rule of thumb: if it's a UI control concept (not a business object), use utility:

Standard Icons (standard:*)

• Use for: Salesforce objects/entities (Account, Contact, Case, Opportunity)
• Common placements: record headers, object pickers, list tiles
• Rule of thumb: if the icon represents "what this thing is" (a noun/object), use standard:

Custom Icons (custom:*)

• Use for: generic shapes/symbols, often for custom objects when no standard icon fits
• Common placements: custom object tiles, app launcher tiles, branded placeholders
• Rule of thumb: use custom: when standard: is not appropriate and you still want a "record/object style" icon

Doctype Icons (doctype:*)

• Use for: file types (pdf, image, spreadsheet, etc.)
• Common placements: attachments, file lists, previews
• Rule of thumb: if you're representing a file format, use doctype:

---

How to Search Icons

Effective query patterns:

• Intent-first: "save", "delete", "filter", "settings", "add user"
• Object-first: "account", "contact", "case"
• UI affordance: "chevron right", "close x", "search magnifier"

Optional filters:

• Restrict to a sprite category (action / utility / standard / custom / doctype)
• Limit results to keep responses tight

Searchable Metadata Fields

Each icon entry in the JSON metadata supports these lookup strategies:

• Exact match: category + icon name (mapped to sprite:symbol at runtime, e.g. utility:chevronright)
• Discovery: synonyms (best for intent searches — e.g. "next" finds chevronright)
• Styling: className (computed as slds-icon-{category}-{name} for SLDS <svg> containers)
• Context: description (matches long-form queries about icon purpose)
• RTL: directionality.hasRtl (rare, but important for directional glyphs)

---

Implementation Patterns

Lightning Web Components (preferred inside Salesforce)

Icon only:

<lightning-icon
  icon-name="utility:search"
  alternative-text="Search"
  title="Search"
  size="x-small">
</lightning-icon>

Icon button:

<lightning-button-icon
  icon-name="action:save"
  alternative-text="Save"
  title="Save"
  onclick={handleSave}>
</lightning-button-icon>

SLDS (raw HTML/SVG usage)

If you're implementing outside Lightning components, use the className from the JSON (example: slds-icon-utility-search) with the appropriate SLDS blueprint patterns for icon containers.

---

Sizes

When rendering icons in Lightning Web Components, prefer the built-in size tokens on lightning-icon / lightning-button-icon instead of custom CSS.

---

Accessibility Requirements (Do Not Skip)

When the icon communicates meaning

• Provide text for assistive tech:
• LWC: alternative-text (required), title (recommended)
• HTML/SVG: ensure an accessible name via text, aria-label, or title as appropriate

When the icon is purely decorative

• Hide it from assistive tech (don't create "noise"):
• LWC: use an empty alternative-text="" only if the containing control already has an accessible label
• HTML/SVG: aria-hidden="true" on the decorative icon element

Don't rely on icons alone

If the icon represents status (success/error/warning), ensure there's text and/or non-color cues in addition to the icon.

---

Icon Metadata Structure

All 1,732 icons are stored in a single icon-metadata.json file, keyed by icon name. Each entry includes:

• displayName — the icon identifier (e.g. chevronright, add_contact)
• category — sprite category: action, utility, standard, custom, doctype
• synonyms — search terms for discovery (e.g. ["next", "forward", "arrow", "chevron"])
• description — what the icon represents
• directionality — type (common or directional) and hasRtl flag

Borders and Radius Guidance for SLDS Implementation

Purpose: This document provides the foundational principles and constraints for all border and radius decisions in Salesforce Lightning Design System. Borders and radiuses are basic visual design elements that help create clarity, hierarchy, and a consistent look. When implementing components and layouts, follow these guidelines to ensure visual harmony and cohesion across all experiences.

---

Core Principles

When working with borders and radiuses in UI interfaces, adhere to these foundational principles:

1. Create clarity through structure. Borders delineate components and sections for better readability and navigation. Use them to separate content areas, indicate clickable elements, or highlight active states.

2. Support hierarchy and meaning. Borders differentiate elements to show importance or interactivity. Ensure border treatments draw attention to important features without overwhelming the experience.

3. Maintain consistency and harmony. Apply consistent thickness, color, and radius across similar elements. Avoid mixing sharp and rounded corners within the same component to keep designs looking polished and cohesive.

4. Foster accessibility. Use subtle but effective visual cues to support usability for all users. Ensure borders remain visible and easy to perceive across all screen sizes and resolutions.

---

SLDS 2 Design Philosophy

CRITICAL: SLDS 2 does not use borders around cards and components, unlike SLDS 1.

This represents a significant design shift from previous versions. When uplifting code from SLDS 1 to SLDS 2, remove decorative borders from cards, panels, and container components. SLDS 2 relies more on spacing, shadows, and surface colors to create visual separation rather than explicit borders.

When borders ARE appropriate in SLDS 2:

• Separating content using neutral borders to divide sections or groups of related content
• Highlighting interactive elements by applying neutral borders for structure, or accent colors for specific branded variants and focus states
• Communicating component states with context-appropriate colors like red for error states or lighter shades for disabled components
• Creating subtle divider lines between content areas

---

Borders Fundamentals

What are Borders?

Borders outline elements and provide structure, serving as visual separators, indicators of interactivity, or highlights for active or selected states. Border width, sometimes called stroke width, refers to the thickness of the lines that define the edges of components, containers, and other visual elements.

Borders help with these design aspects:

• Differentiate between various UI elements, such as cards, panels, or input fields
• Highlight important information and de-emphasize less important information
• Make content more accessible by ensuring that borders are always visible and easy to read on all screen sizes and resolutions

Best Practices for Borders

• Less is Best — Apply borders sparingly to avoid visual clutter. SLDS 2 favors minimal border usage.
• Consistency — Use consistent thickness and color across similar elements.
• Subtlety — Use light or subtle borders to create separation without overwhelming the interface.

---

Radius Fundamentals

What is Radius?

Radius defines how rounded the corners are on elements. Borders have a radius, and container elements such as cards and buttons have a radius too. Rounded corners soften the visual appearance and create a more approachable design style.

Radius contributes to the design in these ways:

• Establish a consistent style for rounded corners across components such as cards, modals, and buttons
• Create a modern, approachable aesthetic that aligns with the brand identity
• Improve usability by subtly guiding users' focus to key interface elements

For radius sizing guidance and component examples, refer to the Borders and Radius Styling Hooks documentation.

Best Practices for Radius

• Consistency — Apply the same radius to similar elements for a cohesive design style throughout the interface.
• Harmony — Avoid mixing sharp and rounded corners. Mixing these styles within the same component can create a visually jarring experience and reduce design harmony.
• Branding — Use the radius to reflect the brand's personality. Whether the brand should be approachable, professional, or bold, use the SLDS 2 design guidelines to choose the right radius for the elements.
• Usability — Confirm through testing that rounded corners don't detract from clarity or usability, especially for focus and hover states in interactive elements.

Nested Container Pattern

Nested containers should use the next smaller radius value to maintain visual harmony. For example, if an outer card uses --slds-g-radius-border-4, a nested card inside should use --slds-g-radius-border-3. This creates a consistent visual rhythm where inner elements have subtly tighter corners than their parent containers.

---

Border Color Fundamentals

SLDS 2 uses specific colors for borders to align with the system's visual design, ensuring clarity and usability across all products.

Common Border Colors and Meanings

• Neutral grays — The standard choice for creating structural separation and outlining functional components
• Accent colors (Blue) — Reserved for specialized branded treatments and thematic emphasis
• Dark blue — Indicates an element has focus
• Red — Indicates an error state
• Yellow — Indicates a warning state
• Transparent or white — Maintains visual balance in lighter or less prominent elements

Where to Use Border Colors

• Separate and outline content — Use neutral gray borders to divide sections or outline standard functional components (buttons, inputs)
• Highlight branded elements — Apply accent colors for specialized branded treatments or thematic emphasis
• Communicate focus — Use dark blue focus indicators to support accessibility

For complete border color hook details, refer to the Color Overview and Semantic Color Styling Hooks documentation, which covers the full semantic color system including border-specific tokens.

---

Theming Considerations

SLDS 2 allows for customizable theming. When making changes to borders or radiuses:

• Ensure any customizations align with brand guidelines
• Maintain contrast ratios for accessibility
• Verify border treatments appear correctly across light/dark themes
• Use styling hooks to enable theme adaptability rather than hard-coded values

---

Density Awareness Note

Important: Unlike spacing and typography, borders and radius values are NOT density-aware in SLDS 2. Border width and radius values remain constant regardless of whether the user has selected comfy or compact display density mode.

When implementing density-aware layouts, note that:

• Border thickness stays the same across density modes
• Radius values stay the same across density modes
• Spacing around bordered elements may change (via density-aware spacing hooks), but the borders themselves do not adapt

---

Available Styling Hooks

Border Width Hooks

• --slds-g-sizing-border-*

Border Radius Hooks

• --slds-g-radius-border-*
• --slds-g-radius-border-circle
• --slds-g-radius-border-pill

Border Color Hooks

Border color hooks are part of the semantic color system. Key hooks include:

• --slds-g-color-border-* — Neutral borders for functional structure
• --slds-g-color-border-accent-* — Branded emphasis and thematic exceptions
• --slds-g-color-border-error-* — Error state borders
• --slds-g-color-border-success-* — Success state borders
• --slds-g-color-border-warning-* — Warning state borders
• --slds-g-color-border-disabled-* — Disabled state borders
• --slds-g-color-border-inverse-* — Borders on dark backgrounds

For detailed usage patterns, refer to the Borders and Radius Styling Hooks documentation.

---

Implementation Workflow

Follow this sequence when implementing any border or radius solution:

Step 1: Determine if a Border is Needed

Apply the SLDS 2 design philosophy — borders should be used sparingly. Ask:

• Is this border necessary for structure or clarity?
• Could spacing or shadows achieve the same visual separation?
• Am I uplifting from SLDS 1 where borders were used decoratively?

Step 2: Select the Appropriate Treatment

If a border is needed, determine:

• Width — Select the visual weight needed for the component type
• Radius — Match to content density (smaller for dense, larger for spacious)
• Color — Select based on semantic meaning (neutral, accent, feedback, inverse)

Step 3: Apply Styling Hooks

Never use hard-coded values. Use the appropriate styling hooks:

• Width: --slds-g-sizing-border-*
• Radius: --slds-g-radius-border-*
• Color: --slds-g-color-border-*

Step 4: Validate Implementation

Before finalizing, verify the implementation using the Pre-Implementation Checklist below.

---

Pre-Implementation Checklist

Before generating or modifying any border or radius related code, verify:

Target outcome: Clean, minimal interfaces that use borders purposefully for structure and meaning, not decoration. Visual separation achieved through spacing and depth where possible.

Color Guidance for SLDS Implementation

Purpose: This document provides the foundational principles and constraints for all color-related decisions in Salesforce Lightning Design System. Always reference the companion metadata files for specific token names, contrast pairings, and approved combinations.

---

Core Principles

When working with colors in UI interfaces, adhere to these three foundational principles:

1. Signal hierarchy and meaning. Color must highlight actions, alerts, and key information without overpowering the experience. Do not use color decoratively.

2. Accessibility is mandatory. All implementations must meet WCAG 2.1 AA minimum standards for text and interactive elements. Use only the approved pairings documented in the metadata layer.

3. Maintain system consistency. Always use semantic styling hooks. These tokens automatically adapt to brand themes, density modes, and light/dark modes. Never use hard-coded color values.

---

Color Role Taxonomy

Every element must be classified into one of these five color roles before selecting a token:

• Surfaces: The base canvas for content. Each new layer (panel, modal, popover) is a distinct surface with its own depth level. Use surface tokens for backgrounds.

• Containers: Elements that hold interactive or readable content (cards, buttons, tabsets). Always pair container background colors with their corresponding "on-container" tokens for text and icons.

• Accents: Colors that draw attention to primary interactions or selected states. Use sparingly and only for meaningful emphasis. Overuse destroys visual hierarchy.

• Feedback colors: Status indicators (error, warning, success, info, disabled). Reserve exclusively for CRUD operations and system feedback. Never use for general styling.

• Borders/dividers: Structural elements that create separation. Must maintain sufficient contrast with adjacent surfaces and containers.

---

Color Density Rule (85-5-10)

CONSTRAINT: All UI implementations should maintain the following color distribution. This distribution is strongly recommended for maintaining SLDS visual consistency.

UI Foundation: 85% (Required)

Foundational colors create the neutral canvas for all content. Use whites, light grays, dark grays, and dark blue for contrast with text and interactive elements.

Allowed Palettes: Whites, light grays, dark grays, dark blue Usage: Page backgrounds, surface layers, neutral containers, structural elements

Accents: 5% (Required)

Accent colors are reserved for strategic emphasis on interactive elements. Use the foundational accent (electric blue) and feedback palettes (pink, yellow, teal, blue) to guide users toward task completion.

Allowed Palettes: Foundational accent (electric blue), feedback (pink, yellow, teal, blue), functional accent colors Usage: Primary actions, selected states, status indicators, critical CTAs

Expressive Colors: 10% (Maximum)

Expressive palettes provide extended color options for data visualization and customized app experiences. Use with restraint.

Allowed Palettes: Green, Cloud Blue, Indigo, Purple, Violet, Red, Hot Orange, Orange Usage: Data charts, custom branding, visualization highlights, app-specific accents

Strict Usage Rules:

• Cool tones first. Prioritize Cloud Blue, Purple, Indigo, Violet for general page designs. These integrate better with the foundational palette.
• Indigo warning. Indigo resembles electric blue. Using it carelessly will break button hierarchy and confuse users about interactive affordances.
• Warm = attention only. Orange, Red, and Green signal importance or issues. Reserve them exclusively for drawing user attention to critical information.
• Prevent feedback confusion. Expressive colors can be misinterpreted as system feedback (pink=error, yellow=warning, teal=success, blue=info). Apply expressive colors minimally to avoid this conflict.

---

The Numerical Color System

System Architecture: SLDS uses a 0-100 point scale where accessibility compliance is mathematically guaranteed:

• 100 points = white
• 0 points = black
• Color lane = full 0-100 spectrum of a single hue
• Color step = 5-10 point increments within a lane (e.g., Cloud Blue-15, Cloud Blue-25, Cloud Blue-35)

How It Works

Colors share horizontal point values across different hues. This means the same mathematical rules apply:

• Vertically within each monochromatic palette (single lane)
• Horizontally across all color lanes (different hues)

This consistency enables pattern replication across the entire system.

Automatic Accessibility: Magic Numbers

CRITICAL: Use these point separations to achieve WCAG compliance without manual checking:

Works across hues: A 50-point separation maintains 4.5:1 contrast even when using different color lanes.

Example Application:

• Page background: Gray-95
• Button background: Any-50 (45 point difference = compliant)
• Button hover: Any-40 (55 point difference = compliant)
• Button text: Any-0 or Any-100 depending on background

The 10-point step from 50→40 creates consistent hover states across all color lanes.

Attribution: The "magic numbers" concept originates from the U.S. Web Design System (USWDS) and has been adopted into SLDS to ensure systematic color progression and accessibility.

---

Implementation Workflow

Follow this mandatory sequence when implementing any color solution:

Step 1: Classify the Element

Identify the element's semantic role:

• Is it a surface (background layer)?
• Is it a container (holds content)?
• Is it an accent (emphasis/interaction)?
• Is it feedback (status/state)?
• Is it a border/divider (structure)?

Step 2: Reference the Metadata

Never invent color values. The companion metadata files contain:

• Approved styling hook names
• Pre-validated contrast pairings
• State transition sequences (default → hover → active → disabled)
• Theme adaptations (light/dark/branded)

Step 3: Handle Exceptions

If no semantic hook matches the requirement: 1. Document why standard patterns don't apply 2. Verify contrast manually using the numerical system 3. Ensure brand consistency is maintained 4. Flag for design system team review

Step 4: Validate Implementation

Before finalizing, verify the implementation using the Pre-Implementation Checklist below to ensure all color requirements are met.

---

Metadata Integration

Source of Truth: The metadata files are authoritative for all implementation details.

What the metadata provides:

• Exact token names and values
• Pre-validated contrast pairings (text-on-background, icon-on-surface)
• State progression maps (default → hover → active → focus → disabled)
• Cross-reference between semantic roles and color values
• Theme-specific overrides

When to consult metadata:

• Before selecting any color token
• When implementing state changes
• When validating a custom pattern
• When introducing new component styles

Validation question: Does this color choice reinforce semantic meaning, meet accessibility standards, and maintain brand consistency?

---

Hook Selection Hierarchy

When selecting color hooks, follow this decision order:

1. Semantic Hooks (First Choice — 85% of Cases)

Pattern: --slds-g-color-{purpose}-{n} (e.g., error-1, accent-container-1, surface-1)

Use semantic hooks for standard UI patterns. These hooks:

• Are purpose-built for specific UI use cases (errors, accents, surfaces, feedback)
• Automatically adapt to light/dark mode with curated values
• Have pre-validated accessibility pairings
• Reference system and palette hooks underneath

Use when: You can describe your element using semantic terms (surface, accent, error, warning, success, disabled).

2. System Hooks (Edge Cases — 5-10% of Cases)

Pattern: --slds-g-color-{category}-base-{grade} (e.g., error-base-50, brand-base-40)

Use system hooks when semantic hooks don't cover your specific need. These hooks:

• Provide grade-level control within a color category
• Still adapt to light/dark mode with curated values per mode
• Reference palette hooks underneath

Use when: Data visualization, legacy migration, or custom requirements where semantic hooks are insufficient.

3. Palette Hooks (Raw Access — Rare Cases)

Pattern: --slds-g-color-palette-{color}-{grade} (e.g., palette-pink-50, palette-cloud-blue-30)

Use palette hooks only when system hooks don't meet your requirements. These hooks:

• Provide direct access to the color palette by color name and grade
• Have light/dark mode variants
• Are the foundation that semantic and system hooks reference

Use when: Custom color requirements that don't fit any semantic or system category.

Internal Hooks (Not for External Use)

The following hook prefixes are internal to Salesforce and should not be used by external developers:

How They Connect (Aliasing Chain)

Semantic hooks reference system hooks, which reference palette hooks. When the theme changes (light → dark), the underlying references change, so semantic hooks automatically adapt.

Example: --slds-g-color-error-1

• Light mode: → error-base-50 → palette-pink-50 → #hex
• Dark mode: → error-base-40 → palette-pink-40 → #different-hex

This aliasing chain means you get theme adaptation "for free" when using semantic hooks.

---

Pre-Implementation Checklist

Before generating or modifying any color-related code, verify:

Target outcome: Calm, purposeful interfaces that are unmistakably Salesforce. Color should enhance usability without becoming decorative.

Display Density Guidance for SLDS Implementation

Purpose: This document provides the foundational principles and guidance for implementing display density in Salesforce Lightning Design System. When working with SLDS components and interfaces, follow these guidelines to ensure consistent user experiences across both comfy and compact density settings.

---

About Display Density

Display density controls the spacing and layout of interface elements within a given screen area. Salesforce Lightning Design System 2 (SLDS 2) offers two density settings: comfy and compact.

Comfy (the default setting) places labels on top of fields and adds more space between page elements, creating a spacious view with increased vertical and horizontal spacing. Compact increases visual density with labels on the same line as fields and less space between lines, allowing more information to be visible simultaneously.

Key Requirement: Because users select which display density setting to use, design Salesforce interfaces to work well in both settings. Display density is a user preference that must be supported universally across all implementations.

---

Core Principles

When working with display density in UI interfaces, adhere to these foundational principles:

1. Respect user preferences. Display density is a user-controlled setting, not a design decision. Interfaces must function equally well in both comfy and compact modes, as users select their preferred density based on their needs and workflows.

2. Design for both settings from the start. Implement components with density-aware styling hooks to ensure seamless adaptation. Retrofitting density support is more complex than building it in from the beginning.

3. Maintain accessibility across densities. Both comfy and compact modes must meet WCAG standards. Touch targets, text readability, and visual hierarchy must remain accessible regardless of the density setting.

4. Use density-aware styling hooks strategically. Not every element needs to adapt to density changes. Identify which components truly benefit from density responsiveness—typically data-dense elements like tables, lists, forms, and navigation.

---

Comfy Setting

Comfy is the default density setting in Salesforce. The comfy setting offers a spacious view with increased vertical and horizontal spacing, and vertically stacked form elements.

Benefits of Comfy Setting

The comfy setting provides these benefits:

• Better accommodation for localized content with longer text strings, reducing truncation and improving internationalization support
• Enhanced visual separation for improved accessibility, particularly benefiting users with cognitive disabilities or those who benefit from clear visual grouping
• Reduced cognitive load and better scannability, particularly beneficial for new users learning the system or users navigating complex workflows

Comfy Setting Guidelines

When implementing components for comfy mode, address these factors:

• Critical information prominence: Ensure that critical information remains prominent despite additional whitespace. The increased spacing should enhance, not diminish, the visibility of important content.
• Localized content testing: Test with localized content to verify that spacing accommodates longer text strings common in languages like German or Finnish.
• Vertical scrolling requirements: Elements use more vertical space in comfy mode, which may increase scrolling requirements for long forms or data-heavy screens.

---

Compact Setting

Compact mode creates a denser view with reduced spacing between elements, more information visibility in the viewport, and horizontally stacked form elements.

Benefits of Compact Setting

The compact setting provides these benefits:

• Improved efficiency when working with large data sets, allowing users to see and compare more records without scrolling
• Reduced scrolling for data-heavy screens, improving workflow efficiency for power users
• More information visible simultaneously, supporting tasks that require viewing multiple data points at once

Compact Setting Guidelines

When implementing components for compact mode, address these critical factors:

• Touch target accessibility: Verify that touch targets remain large enough for comfortable interaction, meeting minimum size requirements of 44×44 pt/dp/px for mobile and 24×24 CSS pixels for desktop (with 44×44 recommended for Salesforce mixed environments).
• Text readability: Ensure that text remains readable with reduced spacing, maintaining appropriate line height and letter spacing for legibility.
• Horizontal layout behavior: Test how horizontal layouts behave in narrower viewports, ensuring form elements that stack horizontally don't create usability issues on smaller screens.

---

User Control of Density

To personalize the look of Lightning Experience, users can change their display density setting through their profile menu. After a user changes their display density setting, the page automatically refreshes to apply the new density. Salesforce administrators can also set org-wide defaults.

Implementation Requirement: When designing and developing interfaces, ensure that the interface adapts appropriately to both density settings. Components must respond gracefully to density changes without breaking layouts or compromising functionality.

---

Density-Aware Styling Hooks

Use density-aware styling hooks when specific areas, components, spacing, and typographical elements require the ability to adapt or respond to a user's density setting. Density-aware styling hooks are denoted by "var" in the naming convention (e.g., --slds-g-spacing-var-1) and act as responsive variables that change their values when the density setting changes.

Elements That Benefit from Density-Aware Hooks

Implement density-aware styling hooks for these element types:

• Data-dense components like tables, lists, and grids where information density directly impacts usability
• Form layouts and field arrangements where spacing affects scannability and completion efficiency
• Card and container padding where internal spacing adapts to user preference
• Navigation and toolbar spacing where compact spacing supports power users while comfy spacing aids discoverability

Matching Hooks to Properties

When implementing density-aware styling hooks, match the styling hooks with the appropriate CSS properties:

• For all-sides spacing (top-bottom-left-right): Use --slds-g-spacing-var-[size]
• For horizontal spacing (left-right): Use --slds-g-spacing-var-inline-[size]
• For vertical spacing (top-bottom): Use --slds-g-spacing-var-block-[size]
• For font sizes: Use --slds-g-font-scale-var-[size]
• For font line height: Use --slds-g-font-lineheight-var-base

Implementation Example

When the system detects a density change, properties using density-aware hooks automatically adapt:

/* This hook provides different values based on density setting */
.my-component {
  padding: var(--slds-g-spacing-var-4);
  /* Comfy: 1rem | Compact: 0.5rem */
}

---

Available Density-Aware Styling Hooks

The following sections list all density-aware styling hooks available in SLDS. For detailed usage patterns, dos and don'ts, and accessibility requirements for spacing-related hooks, refer to the Spacing and Sizing Styling Hooks documentation.

Density-Aware Spacing (All Sides)

These density-aware styling hooks control spacing applied equally to all sides of an element (top, bottom, left, right) when the system switches between comfy and compact display density settings.

Hook Pattern: --slds-g-spacing-var-{size} where {size} is the spacing size

Reference: See Spacing and Sizing Styling Hooks for complete usage guidance, accessibility requirements, and implementation patterns.

Density-Aware Vertical Spacing (Block Axis)

These density-aware styling hooks control spacing along the vertical (block) axis when the system switches between comfy and compact display density settings. This spacing corresponds to top and bottom margins or paddings.

Hook Pattern: --slds-g-spacing-var-block-{size} where {size} is the spacing size

Reference: See Spacing and Sizing Styling Hooks for complete usage guidance, accessibility requirements, and implementation patterns.

Density-Aware Horizontal Spacing (Inline Axis)

These density-aware styling hooks control spacing along the horizontal (inline) axis when the system switches between comfy and compact display density settings. This spacing corresponds to left and right margins or paddings.

Hook Pattern: --slds-g-spacing-var-inline-{size} where {size} is the spacing size

Reference: See Spacing and Sizing Styling Hooks for complete usage guidance, accessibility requirements, and implementation patterns.

Density-Aware Line Height

This density-aware styling hook controls the line height when the system switches between comfy and compact display density settings.

Hook Pattern: --slds-g-font-lineheight-var-base

Density-Aware Font Scale

These density-aware styling hooks control the font scale when the system switches between comfy and compact display density settings.

Hook Pattern: --slds-g-font-scale-var-{size} where {size} is the density-aware scale step

---

Responsive Density

Density settings control global spacing, but different screen sizes require additional responsive adjustments. Combine density-aware hooks with responsive design patterns to create interfaces that adapt to both user preferences and device constraints.

Implementing Responsive Density

When building responsive components, follow this approach:

1. Use SLDS standard CSS media queries (30em, 48em, 64em, 80em) to define responsive breakpoints 2. Apply appropriate SLDS density-aware styling hooks within each media query breakpoint 3. Test thoroughly across device sizes in both density settings to ensure layouts work in all combinations

Responsive Density Example

Use this pattern for implementing responsive table cell padding that adapts to both viewport size and density setting:

/* Default (Mobile-first) padding */
.my-custom-table td,
.my-custom-table th {
  padding: var(--slds-g-spacing-var-1); /* Smallest padding for narrow screens */
}

/* Medium screens and up (768px+) */
@media (min-width: 48em) {
  .my-custom-table td,
  .my-custom-table th {
    /* Increase padding for tablets / small laptops */
    padding: var(--slds-g-spacing-var-3);
  }
}

/* Large screens and up (1024px+) */
@media (min-width: 64em) {
  .my-custom-table td,
  .my-custom-table th {
    /* Use larger padding for standard desktops */
    padding: var(--slds-g-spacing-var-4);
  }
}

---

Custom Component Guidelines

When building custom components that need to respond to density, follow these guidelines to ensure consistent behavior with SLDS standards.

Design Guidelines

When implementing custom density-aware components:

• Analyze similar SLDS components: Review how existing SLDS components adapt to density and follow similar patterns for consistency
• Identify which elements need to adapt: Not everything needs to respond to density changes. Focus density adaptation on spacing, typography, and form layouts
• Use appropriate styling hooks: Select hooks that match the property's purpose (spacing-var for padding/margin, font-scale-var for text sizing)
• Test in both density settings: Verify that your component works well in both comfy and compact modes before finalizing implementation

Testing Custom Density Implementation

When validating custom density implementations, ensure that interfaces work well across display density settings:

• Test the same screens in both comfy and compact settings to verify visual consistency and functional parity
• Check rendering in different screen regions and viewports to ensure responsive density works across device sizes
• Verify that touch targets remain accessible in compact setting, meeting minimum size requirements (44×44 pt/dp/px recommended for Salesforce)
• Confirm that text remains readable and hierarchy is maintained with reduced spacing in compact mode
• Verify that localized content displays properly in both density settings, particularly for languages with longer text strings

---

SLDS Components with Built-in Density Support

SLDS includes several components with built-in density adaptation that automatically respond to density changes through density-aware styling hooks.

Components with Automatic Density Adaptation

The following components include density-aware styling hooks that enable automatic adjustments for different display densities:

• Cards
• File selector
• Tabs

Component Blueprints with Configurable Density Support

When using component blueprints, use the standard SLDS markup patterns and CSS classes. The following component blueprints include density-aware styling hooks:

• Cards
• Feed
• File selector
• Page header
• Path
• Split view
• Tabs

Reference: To access component blueprints, see the Salesforce Lightning Design System 1 website.

---

Implementation Workflow

Follow this sequence when implementing density-aware components:

Step 1: Determine Density Requirement

Identify whether your component needs density adaptation:

• Does the component contain data-dense elements? (tables, lists, grids)
• Does spacing significantly impact usability? (forms, cards, navigation)
• Will users benefit from density control? (power users vs. new users)

If the answer is yes to any of these, implement density-aware hooks.

Step 2: Select Appropriate Hooks

Choose the correct density-aware hooks for your use case:

• For padding/margin on all sides: Use --slds-g-spacing-var-*
• For vertical spacing only: Use --slds-g-spacing-var-block-*
• For horizontal spacing only: Use --slds-g-spacing-var-inline-*
• For text sizing: Use --slds-g-font-scale-var-*
• For line height: Use --slds-g-font-lineheight-var-base

Step 3: Implement with Appropriate Scale

Apply hooks with appropriate scale values:

• Smaller values (1-4): For compact elements, tight spacing
• Medium values (5-8): For standard component spacing
• Larger values (9-12): For section spacing and major divisions

Step 4: Validate Implementation

Before finalizing, verify the implementation using the Pre-Implementation Checklist below to ensure all requirements are met across both density settings.

---

Pre-Implementation Checklist

Before generating or modifying any display density related code, verify:

Target outcome: Interfaces that respect user density preferences while maintaining accessibility, visual consistency, and functional parity across both comfy and compact settings.

---

Related Documentation

For detailed implementation guidance and related concepts, refer to:

• Spacing and Sizing Styling Hooks - For complete density-aware spacing hook details, usage patterns, dos and don'ts, and accessibility requirements
• Spacing and Sizing Overview - For foundational spacing and sizing principles and the grid system architecture
• Accessibility Overview - For ensuring touch targets, contrast, and keyboard navigation work across density settings
• Typography Guidance (when available) - For font-scale density hooks and line height implementation patterns
• Color Overview - For understanding how spacing and density interact with visual hierarchy and surface layering

Icons Guidance for SLDS Implementation

Purpose: This document provides the foundational principles and guidance for implementing icons in Salesforce Lightning Design System. When working with SLDS components and interfaces, follow these guidelines to ensure consistent, readable, and accessible iconography across all experiences.

---

About Icons

Icons are symbols used to represent features, functionality, or content. They provide visual cues that help users navigate and interact with the interface more efficiently. Salesforce icon design blends professional and playful qualities, prioritizing simplicity, approachability, and legibility.

Key Requirement: To ensure an inclusive experience, implement icon accessibility by distinguishing between informational and decorative icons.

---

Core Principles

When working with icons in UI interfaces, adhere to these four foundational principles:

1. Choose the correct icon type for the context. Match the icon category (utility, object, action, doctype, or product) to its specific functional role in the UI. 2. Ensure accessibility compliance. Distinguish between informational icons (requiring labels) and decorative icons (hidden from screen readers). 3. Maintain visual consistency. Follow SLDS standards for stroke weight, corner radius, and color usage to ensure a cohesive system. 4. Follow the grid system and keyline shapes. Align icons to the 8pt grid and use approved keyline shapes to maintain visual balance and weight.

---

Icon Types

SLDS includes five distinct icon types, each optimized for specific use cases and platforms.

1. Utility Icons

Utility icons are simple, single-color glyphs that identify labels and actions. They are the most commonly used icons across all device types.

Use for:

• UI-specific actions (Close, Search, Edit, Settings)
• Global headers and navigation elements
• Button groups, alerts, and toasts
• Feed interactions (Share, Like, Comment)

Anatomy and Specs:

• Grid Sizes: 16x16px (small), 24x24px (standard).
• Stroke Weight: 1px (for 16px), 2px (for 24px).
• Standard Scales: 16x16, 24x24, 32x32, 48x48, and 60x60px.
• Color: No fixed background shape; can be any color (typically matches adjacent text).

SLDS 2 Note: Utility icons remain unchanged from SLDS 1.

2. Object Icons (Standard and Custom)

Object icons represent Salesforce entities. Standard icons are for core objects (e.g., Accounts), while custom icons represent customer-created objects.

Use for:

• Representing records in list views, search results, and page headers.
• Identifying entity types in related lists and cards.

Anatomy and Specs:

• Background Shape: White glyph on a solid colored circular background.
• Grid Size: 60x60px.
• Stroke Weight: 6px.
• Corner Radius: 6px (for glyph details).

SLDS 2 Note: The background shape for standard object icons has updated from a square to a circle.

Accessibility Warning: Not all custom object icons meet WCAG color contrast guidelines. Always pair them with text as decorative elements.

3. Action Icons

Action icons represent the primary ways users accomplish tasks on touch devices. They appear exclusively in the mobile action bar.

Use for:

• Touch-device specific actions (New Lead, Log a Call, Share Post).
• Mobile action bar interactions.

Anatomy and Specs:

• Background Shape: White glyph on a colored circle.
• Grid Size: 48x48px.
• Stroke Weight: 4px.
• Artboard: 52x52px with a 32x32px icon live area.

4. Doctype Icons

Doctype icons represent document file formats and are used when a file preview is unavailable.

Use for:

• Identifying file types (PDF, Word, Excel, Sheets, etc.).
• Feeds, publishers, cards, and related lists where files are attached.

Anatomy and Specs:

• Background Shape: Vertical rectangle (56x64px) with a folded corner (earflap).
• Glyph: White glyph or text abbreviation of the file extension.
• Corner Radius: 6px.

5. Product Icons

Product icons represent official Salesforce applications and feature product-specific branding.

Use for:

• App Launcher (Desktop) at 48x48px.
• Mobile device home screens and app headers.

Anatomy and Specs:

• Glyph: Two-color branded glyph on a white background.
• Stroke: 4px rounded stroke weight.

---

Accessibility

Screen readers handle icons based on their functional role.

Informational Icons

Icons that convey important information not present in surrounding text (e.g., a standalone button icon).

• Requirement: Must include an aria-label or assistive text.
• Description Rule: Describe the purpose (e.g., "Upload File"), not the appearance (e.g., "paperclip").

Decorative Icons

Icons that reinforce adjacent text or provide purely visual interest.

• Requirement: Must use an empty alt="" tag or be hidden from screen readers.
• Behavior: Screen readers will skip these to avoid redundant announcements.

---

Grid System and Keyline Shapes

SLDS icons are built on an 8pt grid system to ensure visual consistency across the entire library. Icons utilize four standard keyline shapes based on BPMN diagram conventions:

• Circle
• Square
• Vertical Rectangle
• Horizontal Rectangle

These shapes ensure that icons across different categories maintain consistent visual weight when appearing together.

---

Mobile Tap Targeting

When designing for mobile, ensure icons are easy to select by providing adequate spacing.

• Minimum Target Size: Maintain a minimum tap target of 44x44px.
• Spacing: Add generous padding around icons in touch environments to prevent accidental taps.

---

Usage and Best Practices

Recommended Usage

Implementation Constraints

• Utility Color Matching: Always match utility icon color to adjacent text (e.g., use on-surface-3 if the title is that color).
• White Glyphs: Use only white glyphs for Object and Action icons.
• Standard Scaling: Only scale icons to standard sizes (16, 24, 32, 48, 60px). Avoid scaling outside these increments.

Visual Standards (Dos and Don’ts)

Utility Icons

• Do: Scale to standard pixel sizes (16x16, 24x24, etc.).
• Do: Use front-facing solid shapes for clarity.
• Don't: Use outlines or angled/dimensional views.
• Don't: Make icons overly complicated for small scales.

Object Icons

• Do: Use white glyphs on approved colored backgrounds.
• Do: Use approved BPMN keyline shapes.
• Don't: Use unapproved background shapes or non-white glyphs.

Doctype Icons

• Do: Represent the earflap without a visible gap.
• Don't: Add a gap or separation to the icon's earflap.

---

Recommended Specs Summary

---

Implementation Workflow

Follow this sequence when implementing icons:

1. Identify Icon Need: Determine the semantic role (action, record type, file, etc.). 2. Select Icon Type: Choose the category that matches the role (e.g., Utility for actions). 3. Apply Sizing and Color: Use standard scales and match colors to context (for Utility). 4. Implement Accessibility: Add aria-label for informational icons; use empty alt for decorative. 5. Validate: Check against the pre-implementation checklist for compliance.

---

Pre-Implementation Checklist

Illustrations Guidance for SLDS Implementation

Purpose: This document provides the foundational principles and guidance for implementing illustrations in Salesforce Lightning Design System. When working with SLDS components and interfaces, follow these guidelines to ensure illustrations are used purposefully to enhance clarity, personality, and user engagement.

---

About Illustrations

Illustrations are engaging visuals that guide, inform, and delight users. In the Salesforce Lightning Design System (SLDS), they help communicate complex ideas, reinforce brand identity, and guide users through key moments in their journey. Illustrations are approachable and inclusive, reflecting the diversity of our users while aligning with the Salesforce brand.

Key Requirement: To ensure accessibility best practices, illustrations must always enhance the textual content, not replace it. Use them sparingly and align with the purpose and tone of the screen or message.

---

Core Principles

When working with illustrations in UI interfaces, adhere to these four foundational principles:

1. Prioritize clarity and purpose. Illustrations should soften negative impressions and provide context. Use them to help users understand the state of the system or to guide them through a workflow. 2. Accessibility is mandatory. Illustrations must enhance textual content, never replace it. Always provide meaningful text alongside illustrations to ensure the experience is accessible to all users. 3. Maintain visual restraint. Use illustrations sparingly to avoid distracting users. Follow the "one illustration per page" rule to maintain focus on the primary task. 4. Include actionable guidance. Pair illustrations with clear, actionable UI text. If a page is empty, provide a link or button to help the user take the next step.

---

Illustration Types

Illustrations in SLDS generally communicate one of three conditions: empty, informational, or error. The specific illustration and accompanying text vary depending on the context.

Empty States

Empty state illustrations provide context when a page or component has no data to display.

Use for:

• Empty object list views (opportunities, leads, cases, contacts)
• Empty feeds (activity feeds, Chatter feeds)
• Empty dashboards or reports
• Blank canvas states requiring user action

Informational

Informational illustrations support users as they explore new features, learn workflows, or encounter maintenance states.

Use for:

• System maintenance or scheduled downtime
• Authentication or connection prompts
• Onboarding and setup workflows
• Feature discovery or walkthrough introductions

Error States

Error state illustrations offer reassurance and guidance when something goes wrong.

Use for:

• Page not found (404 errors)
• Access denied or permission errors
• Data unavailable or loading failures
• Lightning Experience compatibility issues
• Broken links or deleted content
• System failures or service disruptions

---

Mobile Guidelines

When using illustrations on mobile devices, adjustments are necessary to ensure a consistent experience within smaller viewports.

• Maximum Width: 300px
• Maximum Height: 180px
• UI Text: Labels and body text must be shorter and use smaller font scales.

---

Layouts

Illustrations can surface within Salesforce products in three primary layout contexts:

Full Page

Used for major system states like 404 errors or initial onboarding where the illustration is the primary focus of the entire viewport.

Main Body

Used within the main content area of a page, often for empty states in list views or dashboards.

Panel or Sidebar

Used in narrower containers like utility panels, sidebars, or docked composers.

---

Recommended Specs

The following specifications define the typography and sizing constraints for illustrations across desktop and mobile platforms.

Desktop Specs

Mobile Specs

---

UI Text Guidelines

UI text for illustrations must be clear, concise, and helpful. While these examples serve as guidelines, text should always be adapted to the specific context.

---

Usage and Best Practices

Recommended Usage (Where & Why)

Illustrations are used to enhance scannability and provide visual context in specific scenarios. They are typically implemented in:

• Empty states: To provide context and reduce the "dead end" feeling of a blank page, guiding users on how to populate data (e.g., list views, dashboards).
• Informational moments: To support users during system maintenance, exploration of new features, or onboarding/setup workflows.
• Error states: To soften the impact of system failures or restricted access and provide a clear path forward (e.g., 404 pages, lack of permissions).
• Feeds: To encourage collaboration within activity or Chatter feeds.

Implementation Constraints

To maintain SLDS visual consistency and performance, adhere to these constraints:

• One per page: Use only one illustration per page. Multiple illustrations create visual clutter and distract from the primary task.
• Avoid small containers: Do not use illustrations inside related lists, cards, or narrow components. Use plain inline text or icons for these areas.
• No direct action feedback: Do not use illustrations as feedback for direct user actions. Toasts, popovers, or banners are better suited for these interactions.

Visual Standards

Character Positioning

Characters add personality but must not dominate the visual hierarchy of an illustration.

Do

• Keep characters in the background to maintain focus on the message and system state.
• Integrate characters as supporting elements that enhance the context without becoming the primary focal point.

Don't

• Avoid placing characters at the forefront of an illustration, as it can distract from the functional purpose of the screen.
• Never use characters as the sole indicator of the illustration's meaning.

---

Implementation Workflow

Follow this sequence when implementing illustrations in your components:

Step 1: Identify Illustration Need

Determine the state you are communicating:

• Is the container empty? (list views, feeds, dashboards)
• Is the state informational? (maintenance, onboarding, configuration)
• Is there an error? (page not found, no access, system failure)

Step 2: Select Illustration Type

Choose an illustration that matches the tone and purpose identified in Step 1. Ensure the visual style is consistent with SLDS standards.

Step 3: Apply Recommended Specs

Use the appropriate styling hooks for typography and respect the maximum dimensions for the target platform (Desktop vs. Mobile).

Step 4: Add Accompanying UI Text

Write clear, concise, and actionable text. Ensure the body text includes a resolution path (e.g., a link to create a record or contact support).

Step 5: Validate Accessibility

Ensure the illustration enhances the text and that all essential information is available via text. Verify that the layout works across different screen sizes and density settings.

---

Pre-Implementation Checklist

Before finalizing any illustration implementation, verify:

Target outcome: Purposeful, engaging illustrations that guide users through the Salesforce experience while maintaining brand consistency and accessibility standards.

Shadows and Elevation Guidance for SLDS Implementation

Purpose: This document provides guidance for implementing shadows in Salesforce Lightning Design System. Shadows add depth and dynamic layers to the UI, making it look more interesting and less static. When implementing components and layouts, follow these guidelines to ensure visual hierarchy and elevation are communicated effectively.

---

About Shadows

What is Box Shadow?

The box-shadow CSS property adds a shadow effect to an element. This property sets values for horizontal and vertical offsets, blur radius, spread radius, and shadow color. The combination of these properties creates a shadow around the frame of an element.

Box shadows indicate elevation and are applied to elements to show which elements are on top of one another. Elevation is applied to elements to show that surfaces can move on top of one another.

The SLDS 2 design uses soft shadows to create a sense of depth and dimension in the user interface. They also help separate components from each other and create a more realistic look.

The styling hook for shadows uses the label shadow.

Elevation System

When applying a shadow, match the priority or stacking order of the elements. Elements with a higher stacking order or which appear on top of others on the page should have higher shadow values. Leverage the z-index property to manage stacking order, and ensure that the elements with the highest shadow value appear above others on the page.

Elevation Levels:

Component Shadow Usage

Base Level (No Shadow)

Components that are base level sit on the surface and don't cover up other components. Base level components do not have shadows in the SLDS 2 design.

The background color of a base level component depends on the color of the surface it sits on:

• On a gray surface: A base level component has a white background
• On a white surface: A base level component has a white background with a border

---

Shadow Types

Depth Shadows

Depth shadows communicate elevation and visual hierarchy. They indicate which elements appear above others in the stacking order.

Hook Pattern: --slds-g-shadow-{n} where {n} is the depth level

• shadow-1 through shadow-4 provide increasing depth levels
• shadow-5 and shadow-6 are aliases that inherit from shadow-4

Directional Shadows

Directional shadow variants allow shadows to be cast in specific directions. These are useful for components that are positioned against edges of the screen.

Hook Pattern: --slds-g-shadow-{direction}-{n} where {direction} is the shadow direction and {n} is the depth level

Directions:

• block-start — Upward shadow
• block-end — Downward shadow (default direction, inherits from base shadow)
• inline-start — Left shadow
• inline-end — Right shadow

Focus Shadows

Focus shadows provide visual feedback for keyboard navigation and accessibility. Focus states within the SLDS 2 design consist of a white border outline surrounded by a dark blue border outline. This style ensures that the focus state meets accessibility requirements for any background.

Hook Pattern: --slds-g-shadow-{type}-focus-1 where {type} is the focus style

Types:

• outline-focus — Simple outline focus
• outset-focus — Double ring outset focus
• inset-focus — Single ring inset focus
• inset-inverse-focus — Double ring inset focus (inverse)

Inset Shadows (Component-Level)

Button components use a hover bevel and inner shadow on click that is separate from the elevation system. Bevels and insets are only used on buttons and inputs where specified and shouldn't be used in custom situations.

Button shadows:

• --slds-s-button-shadow-active — Used on all buttons when pressed, regardless of color or border
• --slds-s-button-shadow-focus — Focus state for buttons
• --slds-s-button-brand-shadow-hover — Hover effect for brand buttons
• --slds-s-button-bordered-shadow-hover — Hover effect for bordered/neutral buttons

Input shadows:

• --slds-s-input-shadow-focus — Used on active/focused input fields

Mark shadows (checkboxes, radios, toggles):

• --slds-s-mark-shadow-checked — Used on selected or active checkboxes, radio buttons, and checkbox toggles
• --slds-s-mark-shadow-focus — Focus state for mark elements

---

Available Styling Hooks

For detailed usage patterns, refer to the Shadows Styling Hooks documentation.

Global Shadow Hooks (--slds-g-)

Depth Shadows:

• --slds-g-shadow-{1-6}

Directional Shadows:

• --slds-g-shadow-block-start-{1-4}
• --slds-g-shadow-block-end-{1-4}
• --slds-g-shadow-inline-start-{1-4}
• --slds-g-shadow-inline-end-{1-4}

Focus Shadows:

• --slds-g-shadow-outline-focus-1
• --slds-g-shadow-outset-focus-1
• --slds-g-shadow-inset-focus-1
• --slds-g-shadow-inset-inverse-focus-1

Shared Shadow Hooks (--slds-s-)

Button Shadows:

• --slds-s-button-shadow-focus
• --slds-s-button-shadow-focus-inverse
• --slds-s-button-shadow-active
• --slds-s-button-brand-shadow-hover
• --slds-s-button-bordered-shadow-hover

Input Shadows:

• --slds-s-input-shadow-focus
• --slds-s-input-shadow-invalid

Mark Shadows:

• --slds-s-mark-shadow-focus
• --slds-s-mark-shadow-checked

Component Shadow Hooks (--slds-c-)

Button Variant Shadows:

• --slds-c-button-success-shadow-hover
• --slds-c-button-destructive-shadow-hover
• --slds-c-button-inverse-shadow-hover

Spacing and Sizing Guidance for SLDS Implementation

Purpose: This document provides the foundational principles and constraints for all spacing and sizing decisions in Salesforce Lightning Design System. When implementing components and layouts, follow these guidelines to ensure visual harmony, hierarchy, and consistency across all experiences.

---

Core Principles

When working with spacing and sizing in UI interfaces, adhere to these foundational principles:

1. Establish harmony through consistency. Spacing and sizing create predictable patterns that help users navigate interfaces efficiently. Use the spacing and sizing styling hooks consistently to create visual rhythm and balance.

2. Create hierarchy through deliberate spacing. Strategic use of space directs user attention, differentiates grouped elements from unrelated ones, and establishes clear relationships between components.

3. Ensure scalability and responsiveness. Components must adapt seamlessly across devices and screen sizes. Use relative units and the SLDS styling hooks to support responsive design patterns.

---

Spacing Fundamentals

What is Spacing?

Spacing controls the empty areas around or within components, such as margins, padding, and gaps between elements. In the context of styling hooks, spacing refers to padding or margins applied around an element.

Spacing defines these visual aspects:

• Proper alignment of components
• Clear differentiation of grouped and unrelated elements
• White space that directs user attention to key content or actions

Benefits of Effective Spacing

Effective spacing provides these benefits:

• Improves readability by preventing visual clutter and creating breathing room
• Reduces cognitive load by establishing clear visual relationships
• Enhances usability by making interactive elements easier to target and distinguish

The 4-Point Grid System

SLDS spacing follows a modular scale based on multiples of 4, aligning with the 4-point grid system. This mathematical foundation ensures consistent spacing relationships throughout the interface.

System Architecture:

• Base unit: 0.25rem (4px equivalent)
• Scale progression: Each step increases in predictable increments
• Values are relative to root font size for scalability

Density-Aware Spacing

SLDS provides density-aware spacing hooks that automatically adapt when the system switches between comfy and compact display density settings. These hooks ensure components respond appropriately to user density preferences.

Hook Patterns:

• All-Sides: --slds-g-spacing-var-{size} - Applies equally to top, bottom, left, right
• Vertical (Block): --slds-g-spacing-var-block-{size} - Top and bottom margins or padding
• Horizontal (Inline): --slds-g-spacing-var-inline-{size} - Left and right margins or padding

Where {size} represents the scale value appropriate for your spacing need.

For complete density-aware hook details including comfy and compact values, refer to the Spacing and Sizing Styling Hooks documentation.

---

Sizing Fundamentals

What is Sizing?

Sizing refers to the dimensions of a component, such as height, width, or size variants. In the context of styling hooks, sizing refers to the fixed height or width of an element. When sizes are consistent, it's easier for users to predict where things will be on the page. This predictability makes the interface easier to use.

Sizing defines these aspects:

• Physical dimensions of elements like buttons, icons, and cards
• Scalable size options (small, medium, large) to accommodate different contexts
• Responsive behavior to ensure designs function well on all screen sizes

Benefits of Consistent Sizing

Consistent sizing provides these benefits:

• Creates predictability by establishing recognizable component sizes
• Enhances usability by making interactive targets appropriately sized
• Supports responsiveness by providing size options that scale appropriately

The 8-Point Grid System

While spacing uses a 4-point grid, sizing aligns with an 8-point grid system using multiples of 8. This ensures dimension values work harmoniously with the spacing system while providing appropriate scaling for component dimensions.

System Architecture:

• Smaller increments for precise control (1-9)
• Larger increments for major dimensions (10-16)
• Values are relative to root font size for scalability

---

Understanding Padding vs. Margin

When implementing layouts, understand the distinction between padding and margin as they serve different purposes:

Padding:

• Controls internal spacing within a component
• Creates breathing room between a container's edge and its content
• Affects the component's total dimensions (when using border-box)
• Use spacing hooks for padding values

Margin:

• Defines external spacing around a component
• Creates separation between adjacent elements
• Does not affect the component's own dimensions
• Use spacing hooks for margin values

Design systems follow a consistent margin strategy so that components interact predictably and maintain harmonious spacing throughout the interface. Apply spacing values systematically rather than arbitrarily to maintain this consistency.

---

Implementation Workflow

Follow this sequence when implementing any spacing or sizing solution:

Step 1: Identify the Spacing/Sizing Need

Determine what you're trying to accomplish:

• For spacing: Is this internal space (padding) or external space (margin)?
• For spacing: Does this need to adapt to density settings (use density-aware hooks)?
• For sizing: Are you setting dimensions (height/width) for an element?
• For sizing: Is this for a small element (icon, button) or larger container?

Step 2: Choose the Appropriate Scale

Evaluate the visual hierarchy and relationship:

• Smaller values (1-4): Compact layouts, tight spacing, small elements
• Medium values (5-8): Standard spacing, common component sizes
• Larger values (9-12/16): Section spacing, large containers, major divisions

Step 3: Apply the Styling Hook

Use the appropriate hook for your context:

• Standard spacing: --slds-g-spacing-* for fixed spacing values
• Density-aware spacing (all sides): --slds-g-spacing-var-* for adaptive spacing
• Density-aware vertical spacing: --slds-g-spacing-var-block-* for top/bottom adaptive spacing
• Density-aware horizontal spacing: --slds-g-spacing-var-inline-* for left/right adaptive spacing
• Element sizing: --slds-g-sizing-* for dimensions

Step 4: Handle Exceptions

If no standard hook matches the requirement: 1. Document why standard patterns don't apply 2. Evaluate if a combination of hooks could achieve the goal 3. Ensure the custom approach maintains visual consistency 4. Flag for design system team review

Step 5: Validate Implementation

Before finalizing, verify the implementation using the Pre-Implementation Checklist below to ensure all spacing and sizing requirements are met.

---

Pre-Implementation Checklist

Before generating or modifying any spacing or sizing related code, verify:

Target outcome: Harmonious, predictable interfaces that maintain visual consistency and adapt seamlessly across devices, screen sizes, and user density preferences.

---

Related Documentation

For detailed implementation guidance, refer to:

• Spacing and Sizing Styling Hooks - For complete hook listings, density-aware values, and usage patterns
• Color Overview - For understanding how spacing interacts with visual depth and surface layering
• Accessibility Overview - For ensuring spacing supports touch targets and keyboard navigation

Typography Guidance for SLDS Implementation

Purpose: This document provides the foundational principles and guidance for implementing typography in Salesforce Lightning Design System. When working with SLDS components and interfaces, follow these guidelines to ensure consistent, readable, and accessible typography across all experiences.

---

About Typography

Typography is a cornerstone of any design system, shaping how users consume and understand content. In the Salesforce Lightning Design System (SLDS), typography is standardized to create a consistent, readable, and accessible experience across all products. SLDS uses a predefined set of font sizes, weights, and styles that adapt to various screen sizes and contexts.

The design system leverages system fonts provided by a user device's operating system, ensuring optimal performance and native feel across different platforms. The system font varies by device: SF Pro on macOS/iOS, Segoe UI on Windows, and Roboto on Android.

Key Requirement: Because typography establishes the foundation for content hierarchy and readability, implement SLDS typography styling hooks consistently across all interfaces. Typography choices directly impact user comprehension, task completion speed, and overall accessibility.

---

Core Principles

When working with typography in UI interfaces, adhere to these foundational principles:

1. Prioritize legibility above all else. To make text readable across devices and contexts, use appropriate font sizes and weights from the SLDS scale. Overly light or small text for essential content compromises usability and accessibility.

2. Establish clear visual hierarchy. To guide users through content efficiently, consistently apply the predefined heading styles, font scales, and text colors. Maintaining the SLDS typography scale creates predictable visual patterns that help users navigate complex interfaces.

3. Use styling hooks for all typography. To ensure consistency and receive automatic SLDS updates, use typography styling hooks instead of hardcoding font styles. Styling hooks provide resilience across theme changes and density settings.

4. Meet accessibility requirements. To make content accessible to all users, ensure proper contrast between text and background colors, use minimum font sizes for readability, and maintain appropriate line heights.

---

System Fonts

SLDS leverages the native fonts provided by each operating system, creating a seamless, high-performance user experience that feels natural on every platform.

Why System Fonts?

System fonts provide these benefits:

• Optimal performance: No font downloads required, reducing page load time
• Native appearance: Interfaces feel natural on each platform
• Automatic updates: Users benefit from OS-level font improvements
• Consistent sizing: All font weights and sizes remain identical across system fonts

Fonts by Platform

The Figma library for SLDS 2 uses SF Pro as its primary typeface for design work. In production, the actual font rendered depends on the user's operating system:

Download System Fonts

For design work in Figma or other design tools, download the appropriate system font:

• [Download SF Pro](https://devimages-cdn.apple.com/design/resources/download/SF-Pro.dmg) - For macOS and iOS design work
• [Download Segoe UI](https://aka.ms/WebFluentFonts) - For Windows design work
• [Download Roboto](https://fonts.google.com/specimen/Roboto) - For Android design work

Important: All font weights and sizes remain the same across all system fonts. A component designed with SF Pro will render identically in Segoe UI or Roboto in terms of sizing and spacing.

---

Font Scale System

The SLDS font scale provides a systematic range of font sizes that create consistent typographic hierarchy across all interfaces. Font sizes are scaled based on the --slds-g-font-size-base property, which sets the default font size of the application.

How Font Scale Works

The font scale uses styling hooks to provide systematic text sizing across the interface.

Hook Pattern: --slds-g-font-scale-{size} where {size} is the scale step

Base Size: --slds-g-font-size-base sets the default font size of the application.

Scale Categories:

• Body text: Scales neg-2 through 2
• Headings/Titles: Scales 3 through 6
• Display text: Scales 6 through 8

Use smaller scales for compact interfaces and larger scales for prominent content.

Note: In SLDS 2, font sizes differ slightly from the original Salesforce Lightning Design System (SLDS 1). Review your components to verify the new type scale specification when migrating from SLDS 1 to SLDS 2.

---

Font Weight System

SLDS 2 uses font weights to maintain clarity and consistency across all platforms. Each weight serves a specific purpose in the typographic hierarchy.

Available Font Weights

SLDS 2 uses four primary font weights to maintain clarity and consistency.

Hook Pattern: --slds-g-font-weight-{weight} where {weight} is the font weight level

Primary Weights:

• Light (weight-3): Display text at font-scale-7 and above
• Regular (weight-4): Titles (font-scale-3 through font-scale-6) and all body text
• Semibold (weight-6): Buttons and smaller body titles (font-size-base through font-scale-2)
• Bold (weight-7): Emphasis within body text only, never for headings

Important: Do not use font weights lighter than Regular (weight-4) for body text or small sizes, as they compromise readability and accessibility.

---

Font Color for Typography

Typography colors in SLDS use semantic color tokens to ensure proper contrast and accessibility across all surfaces and themes. The color system is designed to work seamlessly with both light and dark backgrounds.

On-Surface Colors for Text

For text on light backgrounds (surfaces), use the on-surface token hierarchy:

• `--slds-g-color-on-surface-1` - De-emphasized text (captions, placeholders, secondary content)
• `--slds-g-color-on-surface-2` - Body text (standard content, labels, descriptions)
• `--slds-g-color-on-surface-3` - Headings and titles only (reserved for headings, not body text)

For text on dark backgrounds, use:

• `--slds-g-color-on-surface-inverse-1` - Primary foreground color for inverse surfaces
• `--slds-g-color-on-surface-inverse-2` - Secondary foreground color for inverse surfaces

Specialized Text Colors

For specific text contexts, use these tokens:

• Text links: Use --slds-g-color-accent-2 (electric blue 40) for accessible links on light backgrounds
• Error messages: Use --slds-g-color-error-1 or --slds-g-color-on-error-1 as appropriate
• Warning messages: Use --slds-g-color-warning-1 or --slds-g-color-on-warning-1 as appropriate
• Success messages: Use --slds-g-color-success-1 or --slds-g-color-on-success-1 as appropriate

For complete typography color guidance including pairing rules, contrast requirements, and accessibility requirements, see the Surface Color Styling Hooks documentation.

---

Type Styles

A type style is a combination of font scale, weight, and line height designed for a specific purpose. SLDS has three type styles: body, title, and display. Each type style serves a distinct role in the content hierarchy.

Body Type

Text that conveys details in the form of phrases, labels, sentences, or blocks of copy.

Recommended Scales: --slds-g-font-scale-neg-2 through --slds-g-font-scale-2 Recommended Weights: Regular (weight-4), Semibold (weight-6) for emphasis

When to use:

• Paragraph content and long-form text
• Form labels and input text
• List items and table cells
• Button text (with semibold weight)

Title Type

Headings of components or body content that establish hierarchy and structure.

Recommended Scales: --slds-g-font-scale-3 through --slds-g-font-scale-6 Recommended Weights: Regular (weight-4), Semibold (weight-6)

When to use:

• Page titles and section headings
• Card and panel headings
• Modal and dialog titles
• Navigation headers

Display Type

Short titles in banners or prominent sections to make a bold visual statement.

Recommended Scales: --slds-g-font-scale-6 through --slds-g-font-scale-8 Recommended Weights: Light (weight-3)

When to use:

• Hero sections and landing page headers
• Empty state messages
• Large promotional banners
• Onboarding screens

---

Usage Guidance

When implementing typography in SLDS, follow these best practices to maintain consistency and accessibility.

For detailed usage guidance, do's and don'ts, and accessibility considerations for each typography styling hook, refer to the Typography Styling Hooks documentation.

Key principles:

• Use predefined SLDS text styles from the typography scale
• Ensure sufficient contrast between text and backgrounds (minimum 4.5:1 for body text)
• Avoid ALL CAPS for any text or labels (reduces readability)
• Never hardcode font sizes in pixels or points

Combining Typography Properties

When implementing typography, follow this systematic approach:

1. Start with the content type: Determine whether you need body, title, or display type 2. Select the appropriate scale: Choose a font scale that matches the content hierarchy 3. Apply the correct weight: Use Regular for most content, Semibold for emphasis, Bold sparingly 4. Use semantic colors: Apply on-surface tokens based on content importance (1 for low emphasis, 3 for high emphasis) 5. Set line height: Ensure appropriate line spacing for readability

---

Implementation Workflow

Follow this sequence when implementing typography in your components:

Step 1: Identify Typography Need

Determine the purpose and hierarchy of your text content:

• Is this body content? (paragraphs, labels, descriptions)
• Is this a heading or title? (section headers, component titles)
• Is this display text? (hero sections, prominent banners)
• What level of emphasis is needed? (primary, secondary, tertiary)

Step 2: Select Font Scale and Weight

Choose the appropriate combination based on the content type:

• Body text: font-scale-1 or font-scale-2 with font-weight-4 (regular)
• Emphasized body: Same scale with font-weight-6 (semibold)
• Small headings: font-scale-3 or font-scale-4 with font-weight-6
• Large headings: font-scale-5 or font-scale-6 with font-weight-4 or font-weight-6
• Display text: font-scale-7 or font-scale-8 with font-weight-3 (light)

Step 3: Apply Color Tokens

Select the appropriate color token based on emphasis and context:

• High-emphasis text (headings, titles): --slds-g-color-on-surface-3
• Standard body text: --slds-g-color-on-surface-2
• De-emphasized text (captions, metadata): --slds-g-color-on-surface-1
• Links: --slds-g-color-accent-2
• Feedback messages: Appropriate feedback color tokens

Reference: See the Surface Color Styling Hooks documentation for complete color pairing guidance.

Step 4: Evaluate Density Awareness

Determine if the typography should adapt to user density preferences:

• Does this component appear in data-dense contexts? (tables, lists, forms)
• Would users benefit from density control? (power users vs. casual users)
• If yes: Use --slds-g-font-scale-var-* instead of fixed scale
• If no: Use fixed --slds-g-font-scale-* for consistent sizing

Reference: See the Display Density Overview for density-aware typography guidance.

Step 5: Handle Exceptions

If standard patterns don't fit your requirement: 1. Document why standard typography styles don't apply 2. Verify contrast requirements manually (minimum 4.5:1 for body text) 3. Ensure the custom approach maintains brand consistency 4. Test across all platforms and screen sizes 5. Flag for design system team review

Step 6: Validate Implementation

Before finalizing, verify the implementation using the Pre-Implementation Checklist below to ensure all typography requirements are met.

---

Pre-Implementation Checklist

Before generating or modifying any typography-related code, verify:

Target outcome: Clear, readable, accessible typography that maintains visual hierarchy and brand consistency across all platforms, screen sizes, and user density preferences.

Alignment - Content Centering

Utility for absolute centering of content within containers.

Core Classes

Common Patterns

Center Content in Container

<!-- Center a single element -->
<div class="slds-align_absolute-center" style="height: 200px;">
  <div class="slds-box">
    Centered Content
  </div>
</div>

Center Modal Dialog

<!-- Center a modal in viewport -->
<div class="slds-backdrop slds-backdrop_open">
  <div class="slds-align_absolute-center" style="height: 100vh;">
    <section class="slds-modal slds-fade-in-open">
      <div class="slds-modal__container">
        <!-- Modal content -->
      </div>
    </section>
  </div>
</div>

Center Loading Spinner

<!-- Center spinner in card -->
<article class="slds-card">
  <div class="slds-align_absolute-center" style="height: 300px;">
    <div class="slds-spinner slds-spinner_medium">
      <span class="slds-assistive-text">Loading</span>
      <div class="slds-spinner__dot-a"></div>
      <div class="slds-spinner__dot-b"></div>
    </div>
  </div>
</article>

Center Empty State Message

<!-- Center illustration and message -->
<div class="slds-align_absolute-center" style="min-height: 400px;">
  <div class="slds-illustration slds-illustration_small">
    <img src="/assets/images/illustrations/empty-state.svg" alt="" />
    <h3 class="slds-text-heading_medium">No items to display</h3>
    <p class="slds-text-body_regular">Get started by creating your first item</p>
  </div>
</div>

Center Icon in Fixed Container

<!-- Center icon in square container -->
<div class="slds-align_absolute-center" style="width: 100px; height: 100px; background: #f3f3f3;">
  <span class="slds-icon_container slds-icon-utility-check">
    <svg class="slds-icon slds-icon_small">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#check"></use>
    </svg>
  </span>
</div>

Best Practices

✅ Use slds-align_absolute-center when content needs to be centered both horizontally and vertically ✅ Set explicit height on the container for vertical centering to work properly ✅ Combine with other layout utilities like slds-box or slds-card for complete designs ✅ Use for centering single elements or grouped content within defined containers

❌ Avoid using on elements without defined height - vertical centering requires container height ❌ Do not use for text alignment - use slds-text-align_center for inline text centering ❌ Avoid nesting multiple slds-align_absolute-center classes unnecessarily

Technical Details

The slds-align_absolute-center class applies these CSS properties:

• display: flex - Creates a flex container
• justify-content: center - Centers content horizontally
• align-content: center - Centers flex lines
• align-items: center - Centers content vertically
• margin: auto - Ensures proper centering within parent

This utility leverages flexbox for reliable cross-browser centering without requiring absolute positioning or transform calculations.