Salesforce Shannon Schupbach — React Design System Libraries

USWDS 3.13 and Ontario Government Design System React component libraries for Salesforce Experience Cloud.

Built by Salesforce Shannon Schupbach, these libraries bring U.S. and Canadian government design systems to Salesforce Experience Cloud's native React developer experience. Components deploy directly on Salesforce React Experience Cloud — no LWC bridge required.

4,700+ tests — unit tests and Playwright e2e tests across all packages

---

What this is

Layer	What it does
React component library (packages/react-uswds/src/)	54 pure-React USWDS 3.13 components. No Salesforce dependencies. Publishable to npm as @sfgps-ds/react-uswds.
Ontario React component library (packages/react-ontario/src/)	33 Ontario Government Design System components wrapping @ongov/ontario-design-system-component-library-react Stencil web components. No Salesforce dependencies. Publishable to npm as @sfgps-ds/react-ontario.
Salesforce React Experience Cloud	Components deploy directly using Salesforce's native React developer experience — no LWC bridge or IIFE bundle required. See Salesforce Multi-Framework developer guide.

---

Quick start

@sfgps-ds/react-uswds — USWDS (Standalone React: Vite, CRA, Next.js)

npm install @sfgps-ds/react-uswds dompurify

import { SfGpsDsUsGovProvider, Banner, Alert } from "@sfgps-ds/react-uswds";
import "@sfgps-ds/react-uswds/dist/styles.css";

function App() {
  return (
    <SfGpsDsUsGovProvider assetsBasePath="/assets">
      <Banner type="gov" />
      <Alert variant="info" heading="Notice">
        This site uses USWDS components.
      </Alert>
    </SfGpsDsUsGovProvider>
  );
}

@sfgps-ds/react-ontario — Ontario Design System (Standalone React: Vite, CRA, Next.js)

npm install @sfgps-ds/react-ontario @ongov/ontario-design-system-component-library-react dompurify

import { OntarioProvider, OntarioButton, OntarioHeader } from "@sfgps-ds/react-ontario";
import "@sfgps-ds/react-ontario/dist/styles.css";

function App() {
  return (
    <OntarioProvider assetsBasePath="/assets">
      <OntarioHeader
        applicationHeaderInfo={{ name: "My Application", href: "/" }}
      />
      <OntarioButton label="Get started" type="primary" />
    </OntarioProvider>
  );
}

OntarioProvider is required — it calls Stencil's setAssetPath to wire the web component asset path. Without it, icons and other static assets will not resolve.

Salesforce React Experience Cloud

Import components directly from either library — no bridge or bundle step required:

import { SfGpsDsUsGovProvider, Banner, Alert } from "@sfgps-ds/react-uswds";
import "@sfgps-ds/react-uswds/dist/styles.css";

export default function MyPage() {
  return (
    <SfGpsDsUsGovProvider assetsBasePath="/assets">
      <Banner type="gov" />
      <Alert variant="info" heading="Notice">This site uses USWDS components.</Alert>
    </SfGpsDsUsGovProvider>
  );
}

See the Salesforce Multi-Framework developer guide for deploying React components to Experience Cloud.

New to React on Salesforce? multiframework-recipes is the official Trailhead sample app — it covers GraphQL data fetching, navigation, error handling, and other platform patterns. Use it alongside this library: recipes show you the platform mechanics, this library gives you the USWDS design system on top.

---

Components

Tier 1 — UI components (54 total)

Component	Description
Banner	Official US government/military site banner (gov/mil, English/Spanish)
Alert	Inline alert (info/warning/error/success/emergency); dismissible via allowClose
SiteAlert	Site-wide dismissible alert banner
Header	Page header with agency logo and mobile nav
Footer	Page footer (slim/medium/big variants)
Hero	Hero section with callout
Nav	Primary navigation with submenu support
Breadcrumb	Breadcrumb trail
Sidenav	Side navigation (nested)
InPageNav	In-page anchor navigation
Pagination	Page navigation; createPageUrl for real hrefs (SSR/progressive enhancement)
StepIndicator	Multi-step progress indicator
Accordion	Expandable accordion (multiselect, bordered)
Modal	Dialog/modal with focus trap and aria-modal
SidePanel	Sliding panel dialog with focus trap
Table	Responsive/sortable/scrollable table
Card	Content card (flag, header-first, exdent variants)
CardGroup	Card group layout
Collection	Media collection (news/article list with tags, dates, authors)
Button	USWDS button (all variants + link mode)
ButtonGroup	Button group (segmented; accepts items array or React children)
Tag	Status/category tag
Icon	USWDS SVG icon (from sprite)
Tooltip	Hover/focus tooltip with merged aria-describedby
Skipnav	Skip-to-main-content link
LanguageSelector	Language switcher; onChange callback for SPA navigation
Section	Content section (dark/light background)
ErrorSummary	Form error summary with focus management
ProcessList	Step-by-step process list
SummaryBox	Key information summary box
IconList	List with icons
MediaBlock	Media + text block
ProseBlock	Rich text prose container
Identifier	Agency identifier footer
Search	Search bar

Tier 2 — Form components (controlled)

All form components are controlled inputs with value/onChange and expose a validation handle via forwardRef:

const ref = useRef<InputHandle>(null);
ref.current?.reportValidity();
ref.current?.setCustomValidity("Custom error message");

Component	Description
Input	Text input (all HTML types)
Select	Select dropdown
Checkbox	Single checkbox (tile variant)
CheckboxGroup	<fieldset> + <legend> wrapper for grouped checkboxes (WCAG 1.3.1)
Radio	Single radio button (tile variant)
RadioGroup	<fieldset> + <legend> wrapper for grouped radio buttons (WCAG 1.3.1)
Textarea	Multiline text area
FileInput	File upload with client-side MIME validation
RangeInput	Range/slider input
CharacterCount	Input/textarea with live character counter
PasswordToggle	Password input with show/hide toggle
InputMask	Masked input (SSN, phone, ZIP, any _-pattern mask)
InputPrefixSuffix	Input with prefix/suffix addons (size variants)
ComboBox	Typeahead combobox — pure React, full keyboard nav
DatePicker	Calendar date picker with full keyboard nav
DateRangePicker	Start + end date range picker
TimePicker	Time selector (15/30/60 min steps)
MemorableDate	Three-field date entry (month/day/year)

---

assetsBasePath

Point SfGpsDsUsGovProvider to the directory containing USWDS static assets (fonts, sprite SVG, icons). In local Vite development, copy the USWDS assets into public/ and pass assetsBasePath="/uswds-assets". On Salesforce React Experience Cloud, serve the assets as a Static Resource and pass the resource URL.

CSS

// Load after uswds.min.css — component-level overrides only
import "@sfgps-ds/react-uswds/dist/styles.css";

---

Document map

Use this to find the right guide for your role or question.

Getting started

Document	Who it's for	What it covers
QUICKSTART.md	All developers	Step-by-step: first component, first Salesforce data call, common gotchas
GLOSSARY.md	New developers	Plain-English definitions of UIBundle, LWC, LWS, shadow DOM, wire adapter, gateway, and 25+ other terms

Role-based guides

Document	Who it's for	What it covers
REACT_DEVELOPER_GUIDE.md	React developers new to Salesforce	Component usage, local dev, testing, Salesforce React Experience Cloud deployment

Architecture and internals

Document	Who it's for	What it covers
ARCHITECTURE.md	All developers	Component tier model, CSS architecture, design decisions with Mermaid diagrams

Component and API reference

Document	Who it's for	What it covers
AGENT_GUIDE.md	All developers	Full component prop reference, full-page patterns, security and accessibility rules

Quality, security, and operations

Document	Who it's for	What it covers
CONTRIBUTING.md	Contributors	How to report bugs and submit pull requests
SECURITY.md	All developers	HTML sanitization policy, XSS prevention (DOMPurify), vulnerability reporting
TROUBLESHOOTING.md	All developers	Symptom → cause → fix for: CSS not loading, icons missing, deploy errors

---

Build and deploy

# Build the React component library
npm run build

# Build the UIBundle showcase and deploy to a Salesforce org
cd showcase/main/default/uiBundles/sfGpsDsUsGovShowcase
npm run copy-assets && npm run build
cd ../../../../..
sf project deploy start --source-dir showcase/main/default/uiBundles --target-org BUILD

The library distributes as standard ESM/CJS via dist/. On Salesforce, it deploys as a UIBundle on Salesforce React Experience Cloud — no custom bridge or IIFE bundle required.

---

Security

HTML body props (Alert, Card, SiteAlert, ProseBlock, MediaBlock) are sanitized via DOMPurify before rendering. DOMPurify initializes lazily at first call — not at module load — to avoid LWS proxy membrane failures.

All dynamic <a href> props across 15 components (ButtonGroup, Header, Hero, Skipnav, Nav, Button, Card, Breadcrumb, Collection, Sidenav, InPageNav, Identifier, MultiChannelContact, PhoneNumber, SocialShare) pass through sanitizeHref(), blocking javascript: and data: URI injection. See SECURITY.md.

ESLint enforcement

Three lint rules enforce the React/Salesforce boundary at build time:

Rule	Scope	What it blocks
SB-1	All React source	@salesforce/apex/*, @salesforce/label/*, @salesforce/schema/*, and 6 other LWC virtual modules — not resolvable outside the LWC compile context
PB-1	packages/react-bridge/**	Imports from @sfgps-ds/react-uswds, @sfgps-ds/react-ontario, or @gov-ido/gov-components — the platform adapter layer must stay design-system-agnostic
SER-2	packages/react-bridge/**	JSON.parse(JSON.stringify( — use stripProxy() instead, which correctly handles Date, Map, Set, and BigInt

All three are ESLint errors that fail the build. @salesforce/agentforce-conversation-client is a real npm package and is not restricted.

Third-party dependencies

This section is intended for legal review. It lists every third-party package that ships to end-users — either bundled into the distributed artifact or required as a peer — along with the license terms under which each is used.

Scope: runtime dependencies, peerDependencies, and the USWDS design asset package (@uswds/uswds). Dev-only packages (test runners, linters, type definitions, build tools) are excluded — they never reach a production runtime.

This project is licensed Apache 2.0. All runtime dependencies below are compatible with Apache 2.0 distribution. The one item requiring attention is DOMPurify: its dual license (MPL-2.0 OR Apache-2.0) permits use under either license; this project treats it as Apache-2.0.

Runtime dependencies (bundled or peer-required)

Package	Version	License	Role	Ships how
react	>=18 (@sfgps-ds/react-uswds) / ^19 (@sfgps-ds/react-ontario)	MIT	UI rendering engine	Peer dependency — caller provides
react-dom	>=18 (@sfgps-ds/react-uswds) / ^19 (@sfgps-ds/react-ontario)	MIT	DOM mounting	Peer dependency — caller provides
dompurify	3.2.6	MPL-2.0 OR Apache-2.0	HTML sanitization for rich-text props (Alert.body, Card.body, etc.)	Peer dependency — caller provides; externalized from tsup bundle
@uswds/uswds	3.13.0	CC0 / Apache-2.0 / SIL OFL 1.1 / MIT (see note)	USWDS CSS, fonts (Source Sans Pro, Merriweather, Public Sans), icons, and SVG sprite	Served as static assets; not bundled into JS
@ongov/ontario-design-system-component-library-react	^8.1.0	MIT	Ontario Government Design System Stencil web components	Peer dependency for @sfgps-ds/react-ontario — caller provides
@salesforce/agentforce-conversation-client	10.2.0	Salesforce Terms of Use	Agentforce chat widget SDK (AgentforceWidget component)	Peer dependency for @sfgps-ds/react-uswds/agentforce sub-path only; excluded from the main bundle

License notes for legal review

@uswds/uswds (multi-license): The USWDS package contains assets under four different licenses depending on the file:

• CC0 1.0 (public domain): All GSA-authored code and design modifications. This is the majority of the package.
• Apache-2.0: Underlying third-party icon designs (Google Material Icons) before GSA modification.
• SIL Open Font License 1.1: Typefaces — Source Sans Pro, Merriweather, Public Sans, Font Awesome.
• MIT: Certain utility JavaScript files.

None of these impose copyleft or distribution restrictions incompatible with Apache-2.0 distribution of this project.

dompurify (MPL-2.0 OR Apache-2.0): The dual license allows the consumer to choose which applies. This project elects Apache-2.0. DOMPurify is a peer dependency and is not bundled — the end-user's application resolves it, so the election carries to the application's license compatibility analysis.

@salesforce/agentforce-conversation-client (Salesforce Terms of Use): This is a Salesforce-proprietary SDK. It is a peer dependency for the agentforce sub-path export only and is not included in the default @sfgps-ds/react-uswds bundle. Applications that do not import @sfgps-ds/react-uswds/agentforce are not subject to these terms.

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 — see LICENSE.

Terms of Use

Thank you for using Global Public Sector (GPS) Accelerators. Accelerators are provided by Salesforce.com, Inc., located at 1 Market Street, San Francisco, CA 94105, United States.

By using this site and these accelerators, you are agreeing to these terms. Please read them carefully.

Accelerators are not supported by Salesforce, they are supplied as-is, and are meant to be a starting point for your organization. Salesforce is not liable for the use of accelerators.

For more about the Accelerator program, visit: https://gpsaccelerators.developer.salesforce.com/