Skip to content

docs: address #3236 review feedback (Cosmos default, stylesheet setup, CHANGELOG/ROADMAP corrections) #3240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
showerbee wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: address #3236 review feedback (Cosmos default, stylesheet setup, CHANGELOG/ROADMAP corrections) #3240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c8fb896
docs(readme): show a bundler CSS import and default to the Cosmos theme
showerbee Oct 13, 2026
e9bbfa3
docs(changelog): correct alpha.2 and alpha.3 entries
showerbee Oct 13, 2026
ab98b9e
docs(roadmap): correct coverage gaps and adapter location
showerbee Oct 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -58,16 +59,17 @@ 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

- **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

Expand Down
41 changes: 26 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
<link
rel="stylesheet"
href="/node_modules/@salesforce-ux/design-system-2/dist/css/bundled/slds2.lightning-blue.css"
/>
<link rel="stylesheet" href="/slds2/bundled/slds2.cosmos.css" />
```

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

Expand Down
44 changes: 25 additions & 19 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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).
Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand Down
Loading