fix: accept later 2.x releases of the @salesforce-ux/design-system peer dependency

CHANGELOG.md

@@ -11,6 +11,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `Button`: `xx-small` icon size ([#3228](https://github.com/salesforce/design-system-react/pull/3228))
 - `ButtonStateful`: `success` and `text` variants ([#3234](https://github.com/salesforce/design-system-react/pull/3234))
 
+### Fixed
+
+- The `@salesforce-ux/design-system` peer dependency accepts `^2.25.0-alpha.2` instead of exactly `2.25.0-alpha.2`, so installing into a project that already has a newer version no longer fails with `ERESOLVE`
+
 ## [11.0.0-alpha.4] - 2026-10-06
 
 ### Changed

README.md

@@ -39,7 +39,7 @@ npm 7 and later also installs the peer dependencies: `react`, `react-dom`, and `
 ### Troubleshooting `ERESOLVE` errors
 
 - **`Found: react@18…`**: v11 requires React 19.2 or later. Upgrade React, or stay on 0.10.x.
-- **`Found: @salesforce-ux/design-system@…`**: v11 pins this peer dependency to `2.25.0-alpha.2`, so a project that already has a newer version fails to install. Until the pin is loosened, install with `--legacy-peer-deps`. That flag also skips automatic peer installs, so add React yourself:
+- **`Found: @salesforce-ux/design-system@…`**: 11.0.0-alpha.4 and earlier pin this peer dependency to exactly `2.25.0-alpha.2`, so a project that already has another version fails to install. Later releases accept any 2.x version from `2.25.0-alpha.2` on. On an affected version, install with `--legacy-peer-deps`. That flag also skips automatic peer installs, so add React yourself:
 
   ```bash
   npm install @salesforce/design-system-react@alpha react@^19.2.0 react-dom@^19.2.0 --legacy-peer-deps

ROADMAP.md

@@ -26,9 +26,9 @@
 - [ ] Fix the `components/<name>` entry points for `ColorPicker`, `Filter`, and `Tree`.
       `scripts/generate-entry-shims.mjs` only emits a shim beside a built `index` file,
       and these three have none in `dist/`, so the subpath import fails to resolve.
-- [ ] Loosen the `@salesforce-ux/design-system` peer dependency. It is pinned to
-      `2.25.0-alpha.2`, which npm 7+ auto-installs and which conflicts with any newer
-      version already in the consumer's tree. It is only needed for the icon sprites.
+- [x] Loosen the `@salesforce-ux/design-system` peer dependency. It was pinned to
+      `2.25.0-alpha.2`, which conflicted with any newer version already in the
+      consumer's tree. It is now `^2.25.0-alpha.2`.
 - [ ] Write a 0.10.x → v11 migration guide (removed components, `DataTable` rename,
       React 19, module format).
 - [ ] Publish hosted docs for v11. `react.lightningdesignsystem.com` redirects to

components/__tests__/package-dependencies.test.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import pkg from '../../package.json';
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+describe('package.json peerDependencies', () => {
+	// An exact pin makes npm fail with ERESOLVE for any consumer that already
+	// has a newer @salesforce-ux/design-system, though only its icon sprites are used.
+	it('accepts later 2.x releases of @salesforce-ux/design-system', () => {
+		const range = pkg.peerDependencies['@salesforce-ux/design-system'];
+		expect(range).not.toMatch(EXACT_VERSION);
+		expect(range).toMatch(/^\^2\./);
+	});
+});

package.json

@@ -120,7 +120,7 @@
     "warning": "^4.0.3"
   },
   "peerDependencies": {
-    "@salesforce-ux/design-system": "2.25.0-alpha.2",
+    "@salesforce-ux/design-system": "^2.25.0-alpha.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },