Lightning Design System for React

🚧 Modernization in Progress — This library is being updated to React 19, TypeScript, and modern tooling. Most components are ready, but some features are still being completed. See ROADMAP.md for details.

Now with SLDS 2 and Dark Mode support!

• SLDS 2 Compatible — Works with the latest Salesforce Lightning Design System
• Dark Mode — Built-in dark mode support with prefers-color-scheme detection
• React 19 — Modern React with functional components and hooks
• TypeScript — Full type definitions for improved developer experience
• Accessible — WCAG 2.1 AA compliant with keyboard navigation and screen reader support

npm install @salesforce/design-system-react

Note: SLDS 2 styles are currently bundled with this package. When the official SLDS 2 npm package is released, you'll install it separately.

• Node.js: >= 20.19.0 (or >= 22.12.0)
• React: 19.x

Welcome to this community-supported project! This library is the React implementation of the Salesforce Lightning Design System.

• Usage
• Contributing
• Codebase overview

import { Button, IconSettings } from '@salesforce/design-system-react';

function App() {
  return (
    <IconSettings iconPath="/assets/icons">
      <Button label="Hello Button" />
    </IconSettings>
  );
}

For tree-shaking and smaller bundles:

import Button from '@salesforce/design-system-react/components/button';
import IconSettings from '@salesforce/design-system-react/components/icon-settings';

Add the SLDS 2 stylesheet to your page from the official @salesforce-ux/design-system-2 package. The bundled Lightning Blue theme is the SLDS 2 default (Cosmos is the alternate):

<link
  rel="stylesheet"
  href="/node_modules/@salesforce-ux/design-system-2/dist/css/bundled/slds2.lightning-blue.css"
/>

Note: This replaces the previously bundled slds-plus.css stopgap. Styling now comes from the published SLDS 2 npm package. Storybook is wired up the same way — see .storybook/preview-head.html.

<link 
  rel="stylesheet" 
  href="/node_modules/@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.min.css" 
/>

Dark mode is supported out of the box. Components automatically respond to SLDS dark mode styling when you apply the appropriate theme class:

<!-- Light mode (default) -->
<div class="slds-scope">...</div>

<!-- Dark mode -->
<div class="slds-scope slds-theme_dark">...</div>

Components also respect the user's system preference via prefers-color-scheme when configured with the SLDS theme tokens.

Icons are loaded from external SVG sprite files. Set the path with <IconSettings>:

import IconSettings from '@salesforce/design-system-react/components/icon-settings';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <IconSettings iconPath="/assets/icons">
    <App />
  </IconSettings>
);

Serve the icons from your public folder:

// Express.js example
app.use('/assets/icons', express.static('node_modules/@salesforce-ux/design-system/assets/icons/'));

• Node.js >= 20.19.0
• npm >= 10.x

git clone [email protected]:salesforce/design-system-react.git
cd design-system-react
npm install

• Build: Vite
• Testing: Vitest + React Testing Library
• Documentation: Storybook 10
• Language: TypeScript (progressive migration)

This library follows WCAG 2.1 guidelines and is tested for accessibility.

• Automated testing with axe-core
• Keyboard navigation support
• Screen reader compatibility (JAWS, NVDA, VoiceOver)
• ARIA attributes and roles

Please report any security issues to [email protected].

Please read CONTRIBUTING.md before submitting pull requests.

• Questions: Post on StackOverflow with the design-system-react tag
• Bugs: Create a GitHub Issue

• Source code: BSD 3-Clause
• Icons and images: Creative Commons Attribution-NoDerivatives 4.0
• Salesforce Sans font: Font License