design-system-react: the Lightning Design System, and its version 11 rewrite

Two lines in one package registry

The versions table is the most important thing in the readme, because the two lines differ in almost every dimension.

The alpha tag points to 11.x, on the default branch, and it requires React 19.2 or later and the second generation of the stylesheet. The latest tag points to 0.10.x, on a separate branch, and it works with React 16.8 or later and the first generation of the stylesheet.

The consequence for a new project is that a plain install of the package gives you the stable 0.10 release, not the new one. The readme is explicit that the version 11 line is a rewrite for React 19, TypeScript and the new design system, and that it must be installed with the alpha tag. It also warns that alpha releases can include breaking changes between versions, so you should consider pinning the exact version you tested against.

That warning is what makes the choice a real one rather than a formality. A design system is infrastructure, and infrastructure you rebuild is a cost, so the sensible order is to look at the changelog, see how much of the surface moved, and decide whether the new line is worth waiting for.

The readme is direct that 11 is not a drop-in upgrade from 0.10, because some components were removed or renamed, and the remaining work is tracked in a roadmap file in the repository.

What version 11 actually changes

The highlights list is short, and each item is a change in kind rather than a new component.

Styling moves to the second generation of the design system, which is a separate package, and it brings the Lightning Blue and Cosmos themes. Dark mode comes from the same stylesheet, with light, dark and system colour schemes. The components are function components with hooks, which is the React 19 idiom. Type definitions ship with the package rather than being something you install separately. And accessibility is a build goal rather than a later fix, since it is built to the AA level of the current web accessibility standard, with keyboard navigation and screen reader support.

The accessibility line is the one a buyer should check first, because a design system that is going into a regulated or public-facing product usually has a documented conformance target, and here the target is stated plainly alongside the note that the components are presentational. Presentational is the word to note. These components render structure and behaviour, and they do not own your layout, which is what makes them usable outside a single product shell.

The internationalisation claim is in the subtitle, with the components described as accessible, localisation-friendly and presentational. For a design system that is sold globally, a localisation-friendly component set is a meaningful property, since it usually means that the text handling and the direction and spacing assumptions do not assume English.

Installation, and the peer dependency trap

The install is one command, and the tag is the whole decision.

npm install @salesforce/design-system-react@alpha

Two details of the dependency model are worth knowing. Newer versions of the package manager install peer dependencies for you, and those peers are React, React DOM and the first generation design system package, which is where the icons come from. The second generation stylesheet package is a regular dependency rather than a peer, so it comes along automatically.

Then there is the trap, and the readme gives it its own section with a troubleshooting heading, because it is the failure a lot of people will hit.

If you see an error saying it found React 18, the reason is that version 11 requires React 19.2 or later, and the fix is to upgrade React or to stay on the old line.

If you see an error about the design system package, the cause is more specific. The alpha releases up to and including 11.0.0-alpha.4 pin that peer dependency to exactly one alpha version, so a project that already has a different version of it will fail to install. Later releases accept any version from that one onwards, so upgrading the package fixes the problem outright. On an affected version the workaround is to install with the legacy peer dependency flag, and the readme warns that the flag also skips the automatic peer installation, so you have to add React yourself:

npm install @salesforce/design-system-react@alpha react@^19.2.0 react-dom@^19.2.0 --legacy-peer-deps

That is a good example of a readme anticipating the exact error text, which is more useful than a note that says peer dependency conflicts can happen.

The requirements, including a Node version nobody expects

The requirements section has three items and one of them is a surprise.

React and React DOM at 19.2 or later. Node.js at 24 or later, which is declared in the engines field, and npm warns you on older versions. And a bundler that understands the exports field, with Vite, webpack 5, Rollup and esbuild given as examples, because the package ships ES modules, CommonJS and type declaration files.

The Node requirement is worth pausing on. A design system at version 0.10 has been around for years and will run on much older toolchains, while the 11 line demands a runtime that was released recently. If your organisation pins Node for compliance reasons, that alone may decide the line for you.

The bundler requirement is the other practical constraint. The exports field is how a modern package declares its entry points, and a bundler that ignores it will either fail to resolve the per-component imports or pull the whole package into your bundle, which defeats the point of a tree-shakeable design system.

The package is published as an ES module, which is why the type module flag is in the manifest, and the build pipeline type checks before it bundles, so a type error fails the build rather than shipping.

Styles, themes and the dark mode switch

The styling section explains a division of labour that is worth understanding before you write a line of application code.

The components render design system markup, but they do not ship CSS. You add a stylesheet from the second generation package to your page, and Lightning Blue is the default theme.

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

Four stylesheets ship in the package's bundled folder: Lightning Blue, Cosmos, and scoped variants of both. The scoped ones are the interesting pair, because a scoped build lets you apply the design system's tokens to a region of the page rather than the whole document, which is what makes it possible to use a design system inside a larger application that has its own visual language.

Dark mode is then a single class on the body element, and the readme explains the three options: follow the operating system's setting, always light, or always dark.

<body class="slds-color-scheme--system">

Because the stylesheet switches its colour tokens based on that class, the components follow with no extra props and no JavaScript. That is the right way to do it, and it is the reason the components do not need to know anything about theming.

Icons, per-component imports, and a known gap

Two practical features round out the usage documentation.

Icons load from external SVG sprite files, and the folder is set with a settings component that wraps the tree, so that every icon in the application resolves against the same sprite.

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

The second is per-component entry points, so an application that only needs a button does not have to ship the whole library.

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

And there is a known issue in the current alpha, listed in the readme: three components, a colour picker, a filter and a tree, have no per-component entry point in that release and must be imported from the package root.

That kind of note is small but it is the kind of detail that documentation of a large component library tends to omit, and it is exactly what an adopter hits on the first afternoon. The repository also carries a script that generates those entry shims, which is presumably how the gap will be closed.

The rest of the repository follows a modern React library layout, with the components in their own directory, the icons, the styles, the utilities, the types, a directory for their own linting rules, the Storybook configuration, a set of Vite and Vitest configuration files including a browser test setup, and a roadmap, a changelog, a security policy and a code of conduct.

Editorial conclusion

design-system-react suits a team that has already decided to build inside the Lightning Design System, because then the choice is between a mature 0.10 line and a rewrite rather than between competing design systems. It is a poor fit if you want the latest version today, because 11 is in alpha and the readme says an alpha release can include breaking changes between versions. Before you start, decide which line you are on, pin the exact version you tested against, and read the changelog, because the readme is explicit that 11 is not a drop-in upgrade from 0.10.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. salesforce/design-system-react on GitHub