# Salesforce Lightning Design System 2 (SLDS2)

## Overview

This design system documents **Salesforce's Lightning Design System 2 (SLDS2)** — also called the "Enhanced Lightning UI." It is the visual and interaction framework powering Salesforce's cloud products, including Sales Cloud, Service Cloud, and the broader Lightning Platform.

SLDS2 represents a major visual refresh from classic SLDS, introducing a more expressive type system, a richer color palette, new component states, and updated visual language under the banner of "Enhanced Lightning UI."

**Sources provided:**
- Figma file: `🆕 Components for Web _ Lightning Design System 2 (Community).fig` (mounted as virtual filesystem)
  - 95 pages, ~1,300 top-level frames, ~89,000 nodes
  - Includes: Color Palette, Style Guide, all major components (Button, Card, Input, Badge, Modal, Data Table, Global Header, Navigation, Avatar, Toast, etc.)

---

## CONTENT FUNDAMENTALS

### Tone & Voice
- **Professional but approachable** — Salesforce speaks to business users (admins, developers, sales reps) with clarity and confidence.
- **Direct and action-oriented** — Copy uses imperative verbs: "Add," "Save," "Edit," "View All."
- **Second-person ("you")** — Interface copy addresses users directly: "Your accounts," "Set up your experience."
- **Sentence case** for UI labels, button text, and form labels (not Title Case, not ALL CAPS).
- **No emoji** in product UI — iconography uses the SLDS icon library only.
- **No slang or jargon** — plain English for all interface labels.
- **Contextual help text** is short, parenthetical, e.g., "Required" or "(Optional)."

### Examples from the Figma
- "A guide of our visual language that imparts a new Lightning UI look and feel to the user interface (UI)."
- "Providing an overview of the styling hooks properties used in the SLDS redesign…"
- "Reference the Style Guide →"
- "SLDS 2 UI Style Guide" (eyebrow, uppercase treatment for section labels only)

---

## VISUAL FOUNDATIONS

### Color System
SLDS2 uses a **10-step numeric scale** per hue (5–95), with semantic aliases layered on top.

**Primary Brand Colors:**
- Blue 60: `#1b96ff` — Interactive / brand primary
- Blue 50: `#0176d3` — Hover / pressed
- Blue 30: `#014486` — Dark / text on light
- Navy: `#032d60` — Deep background / brand dark

**Semantic Colors:**
- Success Green 50: `#2e844a`
- Error Red 50: `#ea001e`
- Warning Orange 60: `#dd7a01`
- Info Cloud Blue 50: `#107cad`
- Indigo 50: `#5867e8` — Accent / AI/Agentforce

**Neutrals:**
- Gray 95: `#f3f3f3` — Page background
- Gray 90: `#e5e5e5` — Borders light
- Gray 80: `#c9c9c9` — Borders standard
- Gray 50: `#757575` — Placeholder text
- Gray 40: `#5C5C5C` — Secondary text
- Gray 30: `#444444` — Body text
- Near-black: `#2e2e2e` — Primary text
- White: `#ffffff`

**Highlight / Accent:**
- Hot Orange: `#ff784f` / `#ff5d2d` — Marketing accent
- Pink 50: `#e3066a`
- Violet 50: `#ba01ff`
- Teal 50: `#0b827c`

### Typography
- **Display / Hero**: `Avant Garde For Salesforce` (Demi) — sizes 48–160px. _Google Fonts substitute: Josefin Sans Bold or ITC Avant Garde._
- **UI Primary**: `SF Pro` Regular/Semibold/Bold — 12–16px. _Substitute: system-ui, -apple-system._
- **Body / Labels**: `Inter` Regular/Bold/Medium — 12–24px.
- **Supporting**: `SF Pro Display` Light/Regular — 20–40px for subheadings.
- Base UI font size: **13px** (most common), labels **12–14px**, headers **14–16px semibold**.

### Spacing
4px base grid. Common increments: 4, 8, 12, 16, 24, 32, 40, 64px.

### Backgrounds
- App background: `#f3f3f3` (Gray 95)
- Card/panel background: `#ffffff`
- Global header: `#ffffff`
- No gradients in product UI — clean flat whites and grays
- Marketing / style guide uses soft pastel light-leak backgrounds (blush, lavender)

### Shadows / Elevation
- **Level 1** (cards, dropdowns): `0 2px 2px rgba(0,0,0,0.10), 0 2px 8px rgba(0,0,0,0.08)`
- **Level 2** (modals): `0 8px 16px rgba(0,0,0,0.15)`
- **Level 3** (overlays): `0 16px 48px rgba(0,0,0,0.25)`

### Border Radius
- Cards: **20px**
- Buttons: **5px** (pill-style buttons NOT used in product)
- Inputs: **4–8px**
- Badges/pills: **100px** (fully rounded)
- Avatars: **100%** (circle) for person, **8px** for object/icon

### Borders
- Standard: `1px solid #c9c9c9` (gray-80)
- Subtle: `1px solid #e5e5e5` (gray-90)
- Focus: `2px solid #1b96ff` (blue-60)
- Component dashed outline (design annotation only): `1px dashed #9747FF`

### Animation
- Subtle and functional — no decorative motion
- Transitions: `0.15–0.2s ease` for hover/focus states
- No bounces or spring animations in product UI
- Spinners for loading states (not skeleton screens in this version)

### Hover / Press States
- Buttons: hover → darker background shade (e.g., blue-50 → blue-40)
- Links/icons: opacity 0.85 or slightly darker fill
- Table rows: `#f3f3f3` background on hover
- Press: brief darken, no scale transform

### Cards
- White bg, `borderRadius: 20px`
- Header with icon + title + overflow menu (⋮)
- Body with content placeholder
- Footer with "View All" link
- Subtle border + shadow

### Iconography
See ICONOGRAPHY section below.

### Imagery
- Product screenshots use clean real UI
- Marketing uses abstract "light leak" gradient overlays on pastel backgrounds
- No hand-drawn illustrations in product UI
- No background patterns/textures in product

---

## ICONOGRAPHY

Salesforce uses the **SLDS Utility Icon Library** — an internal SVG icon set.

- Icons are referenced as `Utility Icons / [Letter] / [name]` in Figma (e.g., `Utility Icons / F / fallback`, `Utility Icons / D / down`)
- Common sizes: **14px**, **16px**, **24px**
- Default fill color: `rgb(92,92,92)` (gray-40 equivalent) on white; white on colored backgrounds
- Icon names follow kebab-case: `agent-astro`, `favorite`, `down`, `new`, `question`, `setup`, `notification`
- The SLDS icon set is available at: https://www.lightningdesignsystem.com/icons/
- CDN available via SLDS static resources or as `@salesforce-ux/design-system` npm package
- **In this design system**: SLDS icons are replicated using inline SVG paths and `@salesforce-ux/design-system` icon sprite conventions; key icons are in `assets/icons/`
- **No emoji** used in product UI
- Object icons (Account, Contact, etc.) use distinct colored squares with rounded corners + white icon inside
- Standard icons for common objects are part of the SLDS `standard` sprite

---

## CONTENT INDEX

```
README.md                    ← This file
SKILL.md                     ← Claude skill definition
colors_and_type.css          ← All color + type CSS variables
assets/
  icons/                     ← SVG icons (SLDS utility subset)
  fonts/                     ← Font references (Google Fonts substitutes)
preview/
  colors-brand.html          ← Brand color swatches
  colors-semantic.html       ← Semantic / status colors
  colors-neutral.html        ← Gray scale
  type-scale.html            ← Typography specimens
  type-display.html          ← Display / hero type
  spacing-tokens.html        ← Spacing scale
  elevation-shadows.html     ← Shadow / elevation system
  components-buttons.html    ← Button variants
  components-badges.html     ← Badge variants
  components-inputs.html     ← Input / form elements
  components-cards.html      ← Card component
  components-avatar.html     ← Avatar variants
  components-toast.html      ← Toast / notification
  components-navigation.html ← Global navigation bar
ui_kits/
  salesforce-app/
    README.md                ← UI kit guide
    index.html               ← Main interactive prototype (CRM admin)
    GlobalHeader.jsx         ← Top navigation header
    Sidebar.jsx              ← App launcher / navigation sidebar
    RecordPage.jsx           ← Record detail page
    ListView.jsx             ← List/table view
    Dashboard.jsx            ← Home dashboard
```

---

## FONT SUBSTITUTIONS

⚠️ **Avant Garde For Salesforce** (Demi) is a proprietary Salesforce font. Substituted with **Josefin Sans** (Bold) from Google Fonts — similar geometric sans geometry. For production use, obtain the actual font file from Salesforce.

⚠️ **SF Pro** is Apple's system font, available on macOS/iOS natively. Substituted with `system-ui, -apple-system, BlinkMacSystemFont` for cross-platform rendering.

**SF Pro Display** (Light, Regular) → substituted with `system-ui` weight 300/400.