[showerbee]

Follow-up to #3236

Additional description

Symptom: npm install @salesforce/design-system-react@alpha fails with ERESOLVE in any project that already has @salesforce-ux/design-system. The current latest is 2.264.1.

Root cause: the @salesforce-ux/design-system peer dependency is pinned to exactly 2.25.0-alpha.2, and has been since #3148. npm 7+ enforces peer ranges, so every version other than that one prerelease conflicts. The package is used only for its icon sprites (assets/icons/*-sprite).

Fix: the peer range is now ^2.25.0-alpha.2. The tested version stays the floor, and any later 2.x release is accepted.

Why this range is safe: I diffed the sprite <symbol id>s between 2.25.0-alpha.2 and 2.264.2. All five sprites have the same layout, and no symbols were removed:

Sprite	2.25.0-alpha.2	2.264.2
action	187	187
custom	113	113
doctype	41	47
standard	546	646
utility	631	787

So every icon a component can reference still exists. The artwork of existing symbols can differ between versions, but the names don't.

Verified end to end: I packed this branch, installed it into clean consumer projects, and ran the same projects against the published alpha.4:

Consumer project	Published alpha.4	This branch
Fresh project	OK (installs SLDS 2.25.0-alpha.2)	OK (installs SLDS 2.264.1)
Has SLDS 2.264.1	ERESOLVE	OK
Has SLDS 2.25.0-alpha.2	OK	OK
Has an older SLDS, 2.24.5	ERESOLVE	OK (upgraded to 2.264.1)
Has React 18	ERESOLVE	ERESOLVE (expected)

Note: a fresh install now gets the latest SLDS sprites (2.264.1) instead of 2.25.0-alpha.2.

Other changes:

• Regression test: components/__tests__/package-dependencies.test.js fails if this peer is pinned to one exact version again.
• package-lock.json: syncs the peer range and the root version, which still said alpha.3 after the alpha.4 release commit.
• README: the --legacy-peer-deps workaround now applies only to 11.0.0-alpha.4 and earlier, which stay on npm with the pin.
• CHANGELOG: an Unreleased "Fixed" entry.
• ROADMAP: the P1 item is ticked.

Not changed: the devDependency stays at 2.25.0-alpha.2, so Storybook and CI keep testing the lowest supported version and this PR introduces no Chromatic diffs. Bumping it can be a separate PR if we'd rather develop against the latest sprites.

---

CONTRIBUTOR checklist (do not remove)

Please complete for every pull request.

Green gate — all of these must pass locally (CI runs the same):

• npm run lint passes with 0 errors (npm run lint:fix to auto-fix). Warnings are the tracked gradual-migration backlog; do not add new errors.
• npm run typecheck is clean (tsc --noEmit).
• npm test -- --run passes — this runs both Vitest projects (jsdom unit + real-browser browser) and the story HTML snapshots. If you changed rendered markup on purpose, update snapshots with npm test -- --run -u and review the diff.
• npm run build succeeds (type-check + Vite library build + .d.ts + entry shims).

Behavior & docs:

• First-time contributors: sign the CLA (a bot will comment with instructions).
• Added/updated Vitest + React Testing Library tests for the change (template: components/button/__tests__). New props and bug fixes should get a regression test. Tests that genuinely need a real browser (focus traversal, layout/measurement, canvas) go in a *.browser.test.jsx file (the browser project); everything else is jsdom.
• Reviewed the component's Storybook stories: npm run storybook → http://localhost:6007/. Confirm the story actually renders and behaves (deprecated Storyshots/Karma are gone; there is no separate browser-tests server). N/A: no component changes.
• Story/example code uses the component's real prop API (e.g. render-props like onRenderContent / onRenderVisualPicker, icon props, events), not assumptions — a common source of "component looks broken" reports has been stories authored against the wrong API. Cross-check against components/<name>/__examples__. N/A.
• Storybook Accessibility (a11y) panel shows no new violations for the affected stories. N/A.
• If you added or changed a type, remember runtime PropTypes were removed in the TS migration — types are the contract. Ship accurate .d.ts (they're generated by the build); JS consumers rely on them via editor type-acquisition. N/A.

REVIEWER checklist (do not remove)

• CI is green (GitHub Actions CI workflow: lint, typecheck, test, build). Chromatic visual review, if configured, has been checked.
• Change has adequate test coverage; bug fixes include a regression test.
• Reviewed the affected Storybook stories and their a11y panels.
• Rendered markup still conforms to SLDS — check the story HTML snapshot diff (components/__tests__/__snapshots__/story-snapshots.test.jsx.snap).
• Public API / package surface: if exports changed, the deep-import contract still holds (@salesforce/design-system-react/components/<name> and nested paths resolve for ESM, CJS, and types). Removing/renaming a public component or export is a breaking change → feat!:/BREAKING CHANGE: and a major version bump.