From c8fb8963eb943932f64ba58004bcb4722dac5d2a Mon Sep 17 00:00:00 2001 From: showerbee <13712377+showerbee@users.noreply.github.com> Date: Mon, 12 Oct 2026 23:06:51 -0400 Subject: [PATCH 1/3] docs(readme): show a bundler CSS import and default to the Cosmos theme Installing @salesforce-ux/design-system-2 doesn't serve node_modules over HTTP, so the old example left components unstyled. Lead with a bundler import, keep a serve-and-link alternative, make Cosmos the default theme, and note the ../../public/ images the 2.264.x package doesn't ship. Follow-up to #3236. --- README.md | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 96f854585..7bbcbcc15 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ v11 is not a drop-in upgrade from 0.10.x: some components were removed or rename ## Highlights -- **SLDS 2** — Styled by the [SLDS 2](https://www.lightningdesignsystem.com/) npm package, with the Lightning Blue and Cosmos themes +- **SLDS 2** — Styled by the [SLDS 2](https://www.lightningdesignsystem.com/) npm package, with the Cosmos (default) and Lightning Blue themes - **Dark mode** — Light, dark, and system color schemes from the SLDS 2 stylesheet - **React 19** — Function components and hooks - **TypeScript** — Type definitions ship with the package @@ -90,26 +90,37 @@ import IconSettings from '@salesforce/design-system-react/components/icon-settin ## Styling The components render SLDS markup but don't ship CSS. Add an SLDS 2 stylesheet from -[`@salesforce-ux/design-system-2`](https://www.npmjs.com/package/@salesforce-ux/design-system-2) -to your page. Lightning Blue is the SLDS 2 default theme: +[`@salesforce-ux/design-system-2`](https://www.npmjs.com/package/@salesforce-ux/design-system-2), +which installs with this package. Cosmos is the default theme. If your bundler handles CSS +imports (Vite, webpack, and so on), import it once at your app's entry point: + +```tsx +import '@salesforce-ux/design-system-2/dist/css/bundled/slds2.cosmos.css'; +``` + +Without a bundler, serve the package's `dist/css` folder from your app and link the stylesheet: ```html - + ``` -The package's `dist/css/bundled/` folder has these stylesheets: +Here `/slds2` is wherever you serve `dist/css`, e.g. +`app.use('/slds2', express.static('node_modules/@salesforce-ux/design-system-2/dist/css'))`. + +> **Note:** The stylesheet references a few images (avatar placeholders, Einstein +> backgrounds) through `../../public/` URLs that `@salesforce-ux/design-system-2` +> 2.264.x doesn't include. Vite warns and builds anyway; with webpack, set +> `css-loader`'s `url` option to skip those paths. Components that don't use those +> images are unaffected. -| File | Theme | -| --------------------------------- | ------------------------ | -| `slds2.lightning-blue.css` | Lightning Blue (default) | -| `slds2.cosmos.css` | Cosmos | -| `slds2.scoped.lightning-blue.css` | Lightning Blue, scoped | -| `slds2.scoped.cosmos.css` | Cosmos, scoped | +The package's `dist/css/bundled/` folder has these stylesheets: -Storybook loads the stylesheet the same way; see `.storybook/preview-head.html`. +| File | Theme | +| --------------------------------- | ---------------------- | +| `slds2.cosmos.css` | Cosmos (default) | +| `slds2.lightning-blue.css` | Lightning Blue | +| `slds2.scoped.cosmos.css` | Cosmos, scoped | +| `slds2.scoped.lightning-blue.css` | Lightning Blue, scoped | ### Dark mode From e9bbfa3930e50835d3edc50d3b126abe1bf911d7 Mon Sep 17 00:00:00 2001 From: showerbee <13712377+showerbee@users.noreply.github.com> Date: Mon, 12 Oct 2026 23:06:56 -0400 Subject: [PATCH 2/3] docs(changelog): correct alpha.2 and alpha.3 entries - alpha.2 already published with --tag alpha; alpha.3 made it the default via publishConfig.tag - Not every component became a function component - List the SLDSMenuPicklist alias and the SLDS-prefixed aliases removed alongside each component Follow-up to #3236. --- CHANGELOG.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 43a25d0aa..50289fc81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,7 +25,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ### Changed -- Releases publish under the `alpha` npm tag, so a plain `npm install @salesforce/design-system-react` keeps resolving to 0.10.x ([#3220](https://github.com/salesforce/design-system-react/pull/3220)) +- `alpha` is now the package's default publish tag (`publishConfig.tag`), so a plain `npm install @salesforce/design-system-react` keeps resolving to 0.10.x. Earlier alphas set the tag only in the publish workflow. ([#3220](https://github.com/salesforce/design-system-react/pull/3220)) ### Removed @@ -36,6 +36,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - `GlobalHeader` (`GlobalHeaderButton`, `GlobalHeaderDropdown`, `GlobalHeaderFavorites`, `GlobalHeaderHelp`, `GlobalHeaderNotifications`, `GlobalHeaderProfile`, `GlobalHeaderSearch`, `GlobalHeaderSetup`, `GlobalHeaderTask`) - `GlobalNavigationBar` (`GlobalNavigationBarButton`, `GlobalNavigationBarDropdown`, `GlobalNavigationBarLabel`, `GlobalNavigationBarLink`, `GlobalNavigationBarRegion`) - `LocationMap` + - The `SLDS`-prefixed alias of each component above (`SLDSAppLauncher`, `SLDSBrandBand`, and so on) ### Fixed @@ -58,7 +59,7 @@ First v11 release on npm: a rewrite for React 19, TypeScript, and SLDS 2. - **BREAKING**: Requires React and React DOM ^19.2.0 (previously >= 16.8) - **BREAKING**: Requires Node.js >= 24 - **BREAKING**: The package ships ES modules and CommonJS from `dist/`, with a package `exports` map, instead of the `lib/` and `module/` folders. Imports outside the `exports` map no longer resolve. The `@salesforce/babel-preset-design-system-react` preset is no longer needed. -- Components are rewritten as TypeScript function components, and the `.d.ts` files are generated from the source +- Components are migrated to TypeScript, many of them rewritten as function components, and the `.d.ts` files are generated from the source - Popups are positioned with `@floating-ui/dom` instead of `popper.js` ### Removed @@ -66,8 +67,9 @@ First v11 release on npm: a rewrite for React 19, TypeScript, and SLDS 2. - **BREAKING**: These components and their subcomponents: - `Lookup` (`LookupDefaultFooter`, `LookupDefaultHeader`, `LookupDefaultSectionDivider`) - `Notification` - - `Picklist` + - `Picklist` (and its `SLDSMenuPicklist` alias) - `TimePicker` (and its `Timepicker` alias) + - The `SLDS`-prefixed alias of each component above (`SLDSLookup`, `SLDSNotification`, and so on) - The `create-react-class`, `lodash.isequal`, `popper.js`, `react-onclickoutside`, `react-required-if`, and `react-text-truncate` dependencies - IE11 support and polyfills From ab98b9e9d9ce74098a93aa16291261bb625b0c2e Mon Sep 17 00:00:00 2001 From: showerbee <13712377+showerbee@users.noreply.github.com> Date: Mon, 12 Oct 2026 23:06:59 -0400 Subject: [PATCH 3/3] docs(roadmap): correct coverage gaps and adapter location - forms has a nested story and test; drop it from the gap lists - List nested stories the snapshot glob skips - The popper-shape adapter is computeFloatingData in utilities/dialog - VisualPicker already supports non-coverable content - Chromatic builds Storybook; what's missing is a public docs site Follow-up to #3236. --- ROADMAP.md | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 45a7ce776..9d7fbf137 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -7,17 +7,17 @@ ## Status Snapshot (2026-10-11) -| Area | State | Notes | -| ----------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| Component sources | **TypeScript** | `components/utilities/dialog/index.jsx` is the last `.jsx` source; the rest of the `.jsx` files are sample data | -| Positioning | **`@floating-ui/dom`** | `popper.js` is gone from dependencies; `utilities/dialog-helpers.js` still adapts Floating UI output to the old popper shape | -| TypeScript | **`tsc --noEmit` clean**, `strict: true` | `.d.ts` files are generated into `dist/types` | -| Storybook | **10**, CSF stories | 3 component folders have no story: `forms`, `grid`, `menu-list` | -| Tests | **48 Vitest files** | jsdom `unit` project plus a Playwright `browser` project; story HTML snapshots cover every non-portal story | -| Lint | **0 errors / 223 warnings** | Errors block CI; warnings are the tracked migration backlog | -| Toolchain | Vite 8, Vitest 4, ESLint 10, Storybook 10 | Node.js 24 (`.nvmrc`) | -| SLDS 2 CSS | **npm dependency** | `@salesforce-ux/design-system-2` installs with the package; consumers add the stylesheet themselves (see the README) | -| Publishing | **GitHub Release → npm, `alpha` tag** | `.github/workflows/npm-publish.yml`; alpha.3 and alpha.4 published from it | +| Area | State | Notes | +| ----------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| Component sources | **TypeScript** | `components/utilities/dialog/index.jsx` is the last `.jsx` source; the rest of the `.jsx` files are sample data | +| Positioning | **`@floating-ui/dom`** | `popper.js` is gone; `computeFloatingData` in `utilities/dialog` still reshapes Floating UI output into the old popper shape | +| TypeScript | **`tsc --noEmit` clean**, `strict: true` | `.d.ts` files are generated into `dist/types` | +| Storybook | **10**, CSF stories | 2 component folders have no story: `grid`, `menu-list` | +| Tests | **48 Vitest files** | jsdom `unit` project plus a Playwright `browser` project; story HTML snapshots cover non-portal stories in a top-level `__docs__/` folder | +| Lint | **0 errors / 223 warnings** | Errors block CI; warnings are the tracked migration backlog | +| Toolchain | Vite 8, Vitest 4, ESLint 10, Storybook 10 | Node.js 24 (`.nvmrc`) | +| SLDS 2 CSS | **npm dependency** | `@salesforce-ux/design-system-2` installs with the package; consumers add the stylesheet themselves (see the README) | +| Publishing | **GitHub Release → npm, `alpha` tag** | `.github/workflows/npm-publish.yml`; alpha.3 and alpha.4 published from it | ## Prioritized Plan @@ -32,7 +32,8 @@ - [ ] 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 - GitHub, and no Storybook is deployed for `master`. + GitHub, and there is no public v11 documentation site (Chromatic builds Storybook + on push, but only for review). - [ ] Use one tag format for releases. `11.0.0-alpha.4` has no `v` prefix, unlike the earlier `v11.0.0-alpha.*` tags. - [ ] At GA: change `publishConfig.tag` from `alpha` to `latest` and update the @@ -42,15 +43,20 @@ **Component folders with no Storybook story:** -- [ ] `forms` - [ ] `grid` - [ ] `menu-list` **Component folders with no Vitest test** (template: `components/button/__tests__`): -- [ ] `badge`, `breadcrumb`, `checkbox`, `dynamic-icon`, `files`, `forms`, `grid`, - `icon-settings`, `menu-list`, `panel`, `portal-settings`, `progress-bar`, - `progress-ring`, `radio`, `scoped-notification`, `trial-bar` +- [ ] `badge`, `breadcrumb`, `checkbox`, `dynamic-icon`, `files`, `grid`, `icon-settings`, + `menu-list`, `panel`, `portal-settings`, `progress-bar`, `progress-ring`, `radio`, + `scoped-notification`, `trial-bar` + +**Stories missing from the HTML snapshot suite:** the snapshot test only globs +`__docs__/*.stories.*`, so these nested stories are rendered by Storybook but not snapshotted: + +- [ ] `components/forms/input/__docs__/inline/InlineInput.stories.jsx` +- [ ] `components/input/__docs__/search/SearchInput.stories.jsx` **Story/feature gaps vs. SLDS 2** — from the component-by-component comparison in [`docs/superpowers/specs/2026-08-07-slds2-vs-react-comparison.md`](docs/superpowers/specs/2026-08-07-slds2-vs-react-comparison.md). @@ -75,14 +81,14 @@ Ordered by leverage; skip anything filed "Legacy Components" upstream. enhancement issues, not story fill-ins: - [ ] `vertical-navigation` — badge / compact / icon / shaded / overflow / validation variants. -- [ ] `visual-picker` — small size tier, disabled state, non-coverable content. +- [ ] `visual-picker` — small size tier, disabled state. - [ ] `date-picker` — date-**range** selection (SLDS 2 is a dual single/range picker; React is single-only). - [ ] `input` — native `type` variants (checkbox / toggle / range / color / file). ### P3 — Cleanup - [ ] Convert `components/utilities/dialog/index.jsx` to `.tsx`, and drop the - popper-shaped adapter in `utilities/dialog-helpers.js`. + popper-shaped adapter (`computeFloatingData`, consumed by `utilities/dialog-helpers.js`). - [ ] Delete the vendored `assets/styles/slds-plus.css`; nothing outside planning docs references it. - [ ] Work down the lint warning backlog. @@ -137,7 +143,7 @@ is the path — evaluated and deferred, not precluded. **Good first issues (P2 template-driven work):** - Add a Vitest + RTL test for a component that lacks one (template: `components/button/__tests__`) -- Add a CSF story for `forms`, `grid`, or `menu-list` +- Add a CSF story for `grid` or `menu-list` ## Timeline