feat(ontario): add react-ontario package, showcase integration, and Experience Cloud site metadata

- Add Ontario Design System React package (@sfgps-ds/react-ontario) with 33 components,
  OntarioProvider/OntarioContext, safeHtml/sanitizeHref utilities, and full test suite
- Add ontario-lab Vite dev app for component-level development
- Integrate Ontario routes into sfGpsDsUsGovShowcase UIBundle (vite.config woff2-only
  font strategy, stripped CSS alias, copy-uswds-assets rewrite)
- Add 278+ Playwright E2E specs for Ontario components (local + live configurations)
- Set UIBundle target=Experience for Experience Cloud site linking
- Add Digital Experience site metadata for SfGpsDsUsGovShowcase and SfGpsDsUsGovReact
  (Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle) in showcase/
- Retrieve and store pronto_app and Government_of_the_Future reference site metadata
- Fix ComboBox and DatePicker bugs; expand Popover tests
- Update docs: ARCHITECTURE, QUICKSTART, ADDING_A_DESIGN_SYSTEM process guide
- Update Playwright configs with ontario-live-chromium project and live URL support

Author: sschupbach-salesforce

.github/workflows/pages.yml

@@ -31,20 +31,30 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Build packages (react-uswds + gov-components)
+      - name: Build packages (react-uswds + gov-components + react-ontario)
         run: npm run build
 
       - name: Build component-lab
         env:
-          # Sub-path that GitHub Pages serves this repo under.
-          # Change to / if using a custom domain or org/user Pages site.
           COMPONENT_LAB_BASE: /gps-design-systems-react/
         run: npm run build --workspace=apps/component-lab
 
+      - name: Build ontario-lab
+        env:
+          ONTARIO_LAB_BASE: /gps-design-systems-react/ontario-lab/
+        run: npm run build --workspace=apps/ontario-lab
+
+      - name: Merge sites into a single artifact
+        run: |
+          mkdir -p _site
+          cp -r apps/component-lab/dist/. _site/
+          mkdir -p _site/ontario-lab
+          cp -r apps/ontario-lab/dist/. _site/ontario-lab/
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
-          path: apps/component-lab/dist
+          path: _site
 
   deploy:
     name: Deploy to GitHub Pages

AGENTS.md

@@ -36,6 +36,12 @@ packages/
     src/
       components/        83 gov-specific React components
 
+  react-ontario/         ← Ontario Design System package (@sfgps-ds/react-ontario)
+    src/
+      context/           OntarioContext.tsx (OntarioProvider — calls setAssetPath)
+      utils/             shared utilities
+      components/        33 ODS wrappers (Stencil web components)
+
 docs/                    All documentation — platform guides and design-system guides
 e2e/                     Playwright tests against local Vite fixture (no org required)
 showcase/                UIBundle showcase app for Salesforce React Experience Cloud
@@ -67,6 +73,7 @@ npm run test --workspaces --if-present                       # all packages
 npm run test --workspace=packages/react-uswds                # USWDS unit tests
 npm run test --workspace=packages/react-bridge               # bridge unit tests
 npm run test --workspace=packages/gov-components             # gov-components unit tests
+npm run test --workspace=packages/react-ontario              # Ontario unit tests
 npm run test:coverage --workspace=packages/react-uswds       # with coverage thresholds
 ```
 
@@ -108,7 +115,7 @@ sf org open --target-org BUILD
 ### Import rules
 - Import `@salesforce/agentforce-conversation-client` only from `src/agentforce.ts`, never from `src/index.ts`
 - Never import `@salesforce/apex/*`, `@salesforce/label/*`, `@salesforce/schema/*`, `@salesforce/user/*`, `@salesforce/client/*`, `@salesforce/featureFlag/*`, `@salesforce/customPermission/*`, `@salesforce/resourceUrl/*`, or `@salesforce/messageChannel/*` in any React source file — these are LWC compile-time virtual modules and cannot be resolved by npm or any bundler. ESLint rule SB-1 enforces this as a build error.
-- Never import `@sfgps-ds/react-uswds` or `@gov-ido/gov-components` from any file in `packages/react-bridge/`. ESLint rule PB-1 enforces this.
+- Never import `@sfgps-ds/react-uswds`, `@gov-ido/gov-components`, or `@sfgps-ds/react-ontario` from any file in `packages/react-bridge/`. ESLint rule PB-1 enforces this.
 - Never use `JSON.parse(JSON.stringify(` in `packages/react-bridge/`. Use `stripProxy()` instead. ESLint rule SER-2 enforces this.
 
 ---
@@ -121,13 +128,14 @@ sf org open --target-org BUILD
 - Export Agentforce-specific components from `packages/react-uswds/src/agentforce.ts` (not the main barrel)
 - Add platform-agnostic infrastructure (gateways, stores, hooks) to `packages/react-bridge/src/`
 - Add gov-specific components under `packages/gov-components/src/components/<ComponentName>/`
+- Add Ontario Design System components under `packages/react-ontario/src/components/<ComponentName>/`
 - Write Vitest tests alongside source in `src/**/__tests__/`
 - Write E2E tests in `e2e/tests/`
 
 ### Do not
 - Import `@salesforce/agentforce-conversation-client` from the main barrel (`index.ts`) — it belongs in `agentforce.ts` only
 - Import `@salesforce/` LWC virtual modules (`@salesforce/apex/*`, `@salesforce/label/*`, etc.) in any React file — LWC compile-time modules; use the gateway abstraction instead (ESLint SB-1)
-- Import `@sfgps-ds/react-uswds` or `@gov-ido/gov-components` from `packages/react-bridge/` — bridge is design-system-agnostic (ESLint PB-1)
+- Import `@sfgps-ds/react-uswds`, `@gov-ido/gov-components`, or `@sfgps-ds/react-ontario` from `packages/react-bridge/` — bridge is design-system-agnostic (ESLint PB-1)
 - Use `JSON.parse(JSON.stringify(` for LWC→React data crossing — use `stripProxy()` instead (ESLint SER-2)
 - Call `DOMPurify(window)` at module evaluation time
 - Use `document.activeElement` for focus management in React components
@@ -137,6 +145,19 @@ sf org open --target-org BUILD
 
 ## Known pre-existing issues
 - `safeHtml.test.ts` — all tests pass. If test `[SEC-1D]` regresses, the fix is the `afterSanitizeAttributes` hook in `getPurifier()` inside `src/utils/safeHtml.ts`.
+- `OntarioSummaryList` — upstream `@ongov/ontario-design-system-component-library-react` does not yet export `OntarioSummaryList`; 2 import tests in `packages/react-ontario` skip until the upstream ships the symbol.
+
+---
+
+## Ontario Design System (ODS) package architecture
+
+The `packages/react-ontario/` package wraps Stencil web components from `@ongov/ontario-design-system-component-library-react`.
+
+Key constraints:
+- **Shadow DOM rendering** — ODS components render inside shadow DOM. Playwright axe tests must use `disableRules` for shadow DOM label/list issues (upstream ODS behavior, not a local bug).
+- **OntarioProvider** — must wrap the component tree before any ODS component renders. It calls `setAssetPath` from `@stencil/core/loader` so Stencil can resolve icon and font assets at runtime. Never render ODS components outside an `OntarioProvider`.
+- **JSON prop sanitization** — ODS components accept complex props as JSON strings (arrays, objects). Use `useMemo` keyed on individual primitive values, not on the full props object, to avoid unnecessary re-serializations and infinite render loops.
+- **Package boundary** — `@sfgps-ds/react-ontario` is a design-system package; it must not be imported from `packages/react-bridge/` (ESLint PB-1).
 
 ---
 

README.md

@@ -1,10 +1,10 @@
-# @sfgps-ds/react-uswds
+# Salesforce GPS Accelerators — React Design System Libraries
 
-**USWDS 3.13 React component library for Salesforce Experience Cloud.**
+**USWDS 3.13 and Ontario Government Design System React component libraries for Salesforce Experience Cloud.**
 
-Built by Salesforce GPS Accelerators, this library brings the full U.S. Web Design System to Salesforce Experience Cloud's native React developer experience. Components deploy directly on Salesforce React Experience Cloud — no LWC bridge required.
+Built by Salesforce GPS Accelerators, 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.
 
-**1,100+ tests** — unit tests across 70+ files
+**4,700+ tests** — unit tests and Playwright e2e tests across all packages
 
 ---
 
@@ -13,13 +13,14 @@ Built by Salesforce GPS Accelerators, this library brings the full U.S. Web Desi
 | 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](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-reactdev-overview.html). |
 
 ---
 
 ## Quick start
 
-### Standalone React (Vite, CRA, Next.js)
+### `@sfgps-ds/react-uswds` — USWDS (Standalone React: Vite, CRA, Next.js)
 
 ```bash
 npm install @sfgps-ds/react-uswds dompurify
@@ -41,9 +42,33 @@ function App() {
 }
 ```
 
+### `@sfgps-ds/react-ontario` — Ontario Design System (Standalone React: Vite, CRA, Next.js)
+
+```bash
+npm install @sfgps-ds/react-ontario @ongov/ontario-design-system-component-library-react dompurify
+```
+
+```tsx
+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 — no bridge or bundle step required:
+Import components directly from either library — no bridge or bundle step required:
 
 ```tsx
 import { SfGpsDsUsGovProvider, Banner, Alert } from "@sfgps-ds/react-uswds";
@@ -222,7 +247,7 @@ 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` or `@gov-ido/gov-components` — the platform adapter layer must stay design-system-agnostic |
+| **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.
@@ -239,10 +264,11 @@ This section is intended for legal review. It lists every third-party package th
 
 | Package | Version | License | Role | Ships how |
 |---|---|---|---|---|
-| `react` | 18.3.1 | [MIT](https://github.com/facebook/react/blob/main/LICENSE) | UI rendering engine | Peer dependency — caller provides |
-| `react-dom` | 18.3.1 | [MIT](https://github.com/facebook/react/blob/main/LICENSE) | DOM mounting | Peer dependency — caller provides |
+| `react` | >=18 (`@sfgps-ds/react-uswds`) / ^19 (`@sfgps-ds/react-ontario`) | [MIT](https://github.com/facebook/react/blob/main/LICENSE) | UI rendering engine | Peer dependency — caller provides |
+| `react-dom` | >=18 (`@sfgps-ds/react-uswds`) / ^19 (`@sfgps-ds/react-ontario`) | [MIT](https://github.com/facebook/react/blob/main/LICENSE) | DOM mounting | Peer dependency — caller provides |
 | `dompurify` | 3.2.6 | [MPL-2.0 OR Apache-2.0](https://github.com/cure53/DOMPurify/blob/main/LICENSE) | 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)](https://github.com/uswds/uswds/blob/main/LICENSE.md) | 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](https://github.com/ongov/ontario-design-system-component-library/blob/main/LICENSE) | 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](https://github.com/salesforce/agentforce-conversation-client) | 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

apps/ontario-lab/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Ontario Component Lab</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/ontario-lab/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@gov-ido/ontario-lab",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 4174 --host 127.0.0.1",
+    "build": "vite build",
+    "preview": "vite preview --port 4174 --host 127.0.0.1"
+  },
+  "dependencies": {
+    "@ongov/ontario-design-system-component-library-react": "*",
+    "@ongov/ontario-design-system-global-styles": "*",
+    "@sfgps-ds/react-ontario": "*",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router-dom": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.0",
+    "typescript": "~5.8.0",
+    "vite": "^8.0.0"
+  }
+}

apps/ontario-lab/src/DemoShell.tsx

@@ -0,0 +1,91 @@
+import { useState } from 'react';
+import { useLocation } from 'react-router-dom';
+import { NAV_ENTRIES } from './nav-registry';
+
+interface DemoShellProps {
+  children: React.ReactNode;
+}
+
+type Tab = 'preview' | 'source';
+
+export default function DemoShell({ children }: DemoShellProps) {
+  const [tab, setTab] = useState<Tab>('preview');
+  const [copied, setCopied] = useState(false);
+  const location = useLocation();
+
+  const entry = NAV_ENTRIES.find((e) => e.path === location.pathname);
+
+  function handleCopy() {
+    if (!entry) return;
+    navigator.clipboard.writeText(entry.source).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    });
+  }
+
+  return (
+    <div className="cl-demo">
+      <div className="cl-demo__header">
+        <h1 className="cl-demo__title">{entry?.label ?? ''}</h1>
+        <span className="cl-badge cl-badge--ontario">react-ontario</span>
+      </div>
+
+      <div className="cl-demo__tabs" role="tablist" aria-label="Demo tabs">
+        <button
+          role="tab"
+          id="tab-preview"
+          aria-controls="panel-preview"
+          aria-selected={tab === 'preview'}
+          className={`cl-demo__tab${tab === 'preview' ? ' cl-demo__tab--active' : ''}`}
+          onClick={() => setTab('preview')}
+        >
+          Preview
+        </button>
+        <button
+          role="tab"
+          id="tab-source"
+          aria-controls="panel-source"
+          aria-selected={tab === 'source'}
+          className={`cl-demo__tab${tab === 'source' ? ' cl-demo__tab--active' : ''}`}
+          onClick={() => setTab('source')}
+        >
+          Source
+        </button>
+      </div>
+
+      <div
+        role="tabpanel"
+        id="panel-preview"
+        aria-labelledby="tab-preview"
+        hidden={tab !== 'preview'}
+        className="cl-demo__panel cl-demo__panel--preview"
+      >
+        {children}
+      </div>
+
+      <div
+        role="tabpanel"
+        id="panel-source"
+        aria-labelledby="tab-source"
+        hidden={tab !== 'source'}
+        className="cl-demo__panel cl-demo__panel--source"
+      >
+        <div className="cl-source__toolbar">
+          <span className="cl-source__filename">
+            {entry?.path.split('/').pop()}Page.tsx
+          </span>
+          <button
+            className="cl-source__copy-btn"
+            onClick={handleCopy}
+            aria-label="Copy source code"
+          >
+            {copied ? '✓ Copied' : 'Copy'}
+          </button>
+        </div>
+        <pre className="cl-source__pre" tabIndex={0}>
+          <code>{entry?.source ?? ''}</code>
+        </pre>
+      </div>
+    </div>
+  );
+}