Fix React icon rendering in published consumers (#203)

* fix(react-components): inline bundled icons for consumers

Switch the default icon path away from bundled data URL <use> references so published consumers render icons reliably. Remove the public React spritePath API while keeping toolkit-backed icon rendering bundled by default.

* test(example-react-consumer-app): expand consumer smoke coverage

Update the packaged consumer app to exercise direct icons, Select, Card metadata icons, and checkbox ticks against the published tarball install contract.

* docs: prep react-components 0.8.0 icon release

Bump the React package version, add migration notes for the spritePath removal, and clarify the toolkit hosted-sprite contract versus the React bundled-icon contract.

* fix(react-components): satisfy icon lint cleanup

Replace the temporary destructuring-based spritePath strip with delete-on-copy so the legacy prop cleanup still works without triggering the repo's unused-vars rule.

* fix(icon): address follow-up PR feedback

Align the example consumer app colours to design-system token values, add unknown-icon coverage, and make bundled sprite parsing less format-sensitive.

Author: diogo-filipe-costa

CHANGELOG.md

@@ -6,6 +6,18 @@ We are following [Semantic Versioning](https://semver.org/spec/v2.0.0.html), as
 
 ## Monorepo Package Releases (`toolkit-v*`, `react-v*`)
 
+### Unreleased
+
+#### @ourfuturehealth/react-components 0.8.0 (`react-v0.8.0`)
+
+##### ⚠️ BREAKING CHANGES
+
+- React `Icon` and `Card` icon configuration no longer accept `spritePath`. React icons now always render from bundled toolkit SVG data.
+
+##### Fixed
+
+- React icons now render correctly in published-consumer installs by inlining the requested bundled SVG symbol instead of referencing a bundled `data:` sprite URL.
+
 ### 2026-04-09
 
 #### @ourfuturehealth/toolkit 4.9.0 (`toolkit-v4.9.0`)

UPGRADING.md

@@ -6,19 +6,70 @@ This guide provides detailed migration instructions for upgrading between versio
 
 ## Breaking Changes by Version
 
-| Version                                                 | Date          | Breaking Changes      | Migration Complexity                  |
-| ------------------------------------------------------- | ------------- | --------------------- | ------------------------------------- |
-| [v4.9.0 / React v0.7.0](#upgrading-to-v490--react-v070) | April 2026    | Icon naming sync    | 🟡 Medium - Search/replace icon names  |
-| [v4.8.0 / React v0.6.0](#upgrading-to-v480--react-v060) | March 2026    | No breaking changes | 🟢 Low - only relevant if you adopted the earlier TextInput prototype |
-| [v4.7.0 / React v0.5.0](#upgrading-to-v470--react-v050) | March 2026    | Card family realignment | 🟡 Medium - API migration recommended |
-| [v4.6.0 / React v0.4.0](#upgrading-to-v460--react-v040) | March 2026    | Tag default + naming  | 🟡 Medium - Search/replace recommended |
+| Version                                                 | Date          | Breaking Changes           | Migration Complexity                     |
+| ------------------------------------------------------- | ------------- | -------------------------- | ---------------------------------------- |
+| [React v0.8.0](#upgrading-to-react-v080)                | April 2026    | React `spritePath` removal | 🟢 Low - Remove the deprecated prop      |
+| [v4.9.0 / React v0.7.0](#upgrading-to-v490--react-v070) | April 2026    | Icon naming sync           | 🟡 Medium - Search/replace icon names    |
+| [v4.8.0 / React v0.6.0](#upgrading-to-v480--react-v060) | March 2026    | No breaking changes        | 🟢 Low - only relevant if you adopted the earlier TextInput prototype |
+| [v4.7.0 / React v0.5.0](#upgrading-to-v470--react-v050) | March 2026    | Card family realignment    | 🟡 Medium - API migration recommended    |
+| [v4.6.0 / React v0.4.0](#upgrading-to-v460--react-v040) | March 2026    | Tag default + naming       | 🟡 Medium - Search/replace recommended   |
 | [v4.5.0](#upgrading-to-v450)                            | March 2026    | Spacing and typography API changes | 🟡 Medium - Replace legacy APIs and recheck overrides |
-| [v4.3.0 / React v0.2.0](#upgrading-to-v430--react-v020) | March 2026    | Button variant naming | 🟡 Medium - Find/replace required     |
-| [v4.1.0](#upgrading-to-v410)                            | February 2026 | Spacing scale indices | 🟡 Medium - Index updates required    |
-| [v4.0.0](#upgrading-to-v400-monorepo-restructure)       | 2025          | Monorepo restructure  | 🔴 High - Installation & paths change |
+| [v4.3.0 / React v0.2.0](#upgrading-to-v430--react-v020) | March 2026    | Button variant naming      | 🟡 Medium - Find/replace required        |
+| [v4.1.0](#upgrading-to-v410)                            | February 2026 | Spacing scale indices      | 🟡 Medium - Index updates required       |
+| [v4.0.0](#upgrading-to-v400-monorepo-restructure)       | 2025          | Monorepo restructure       | 🔴 High - Installation & paths change    |
 
 ---
 
+## Upgrading to React v0.8.0
+
+**Planned:** April 2026
+**Affected packages:**
+
+- `@ourfuturehealth/react-components` v0.8.0+
+
+### Breaking Changes
+
+`@ourfuturehealth/react-components` removes the `spritePath` prop from the public `Icon` API and from `Card` icon configuration. React icons now always render from bundled toolkit SVG data.
+
+### Migration Steps
+
+1. Remove any `spritePath` prop from `Icon` usage.
+2. Remove any `spritePath` field from `Card` icon configuration objects.
+3. Re-run visual checks for icon-bearing surfaces such as `Icon`, `Select`, `Card`, and `Checkboxes`.
+
+#### React example
+
+**Before:**
+
+```tsx
+<Icon name="Search" spritePath="/assets/icons/icon-sprite.svg" />
+
+<Card
+  icon={{
+    name: 'Search',
+    spritePath: '/assets/icons/icon-sprite.svg',
+  }}
+/>
+```
+
+**After:**
+
+```tsx
+<Icon name="Search" />
+
+<Card
+  icon={{
+    name: 'Search',
+  }}
+/>
+```
+
+If an application previously passed `spritePath` in React, that prop should now be removed.
+
+### Toolkit reminder
+
+Toolkit/Nunjucks icon consumers are unchanged. They must still serve `icon-sprite.svg` at a public URL, default `/assets/icons/icon-sprite.svg`, or override that URL with `spritePath`.
+
 ## Upgrading to v4.9.0 / React v0.7.0
 
 **Released:** April 2026

docs/consuming-react-components.md

@@ -130,7 +130,7 @@ The React components package currently provides the following components:
 - `CharacterCount` - Text input and textarea variants with count feedback
 - `Checkboxes` - Grouped checkbox inputs with hints, exclusive options, and conditional reveals
 - `Radios` - Grouped radio inputs with hints and conditional reveals
-- `Icon` - Toolkit sprite icon component with fixed and responsive sizing
+- `Icon` - Toolkit icon component with fixed and responsive sizing using bundled SVG data
 - `ErrorSummary` - Page-level validation summaries with linked errors
 - `Tag` - Status tags aligned with toolkit Tag variants
 - `Card` - Content presentation cards for summaries, status, and next steps

docs/contributing/material-icons.md

@@ -111,6 +111,8 @@ The macro renders:
 - An `<svg>` element with `.ofh-icon` classes
 - A `<use href="/assets/icons/icon-sprite.svg#ofh-icon-<name>">`
 
+Toolkit consumers must make that sprite file available at a public URL the browser can request. Installing the package places the file in `node_modules/@ourfuturehealth/toolkit/assets/icons/icon-sprite.svg`, but the consuming app still needs to copy or serve it as `/assets/icons/icon-sprite.svg`, or override the URL with `spritePath`.
+
 Example usage:
 
 ```njk
@@ -133,7 +135,7 @@ React icon names should stay aligned with toolkit `manifest.json` and the genera
 Current React approach:
 
 - Reuses the toolkit sprite semantics (`name`, `size`, responsive sizing, decorative vs titled)
-- Defaults to the bundled toolkit sprite asset and references symbols with `<use>`
+- Bundles toolkit icon data into the React package and renders the requested symbol inline
 - Treats icon-name changes as consumer-facing API changes that must be documented in release notes and the upgrading guide
 
 Related package: [`packages/react-components/`](../../packages/react-components/)

docs/installation/installing-with-npm.md

@@ -27,7 +27,7 @@ Add the dependency to `package.json`:
 ```json
 {
   "dependencies": {
-    "@ourfuturehealth/toolkit": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/toolkit-v4.0.0/ourfuturehealth-toolkit-4.0.0.tgz"
+    "@ourfuturehealth/toolkit": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/toolkit-v{version}/ourfuturehealth-toolkit-{version}.tgz"
   }
 }
 ```
@@ -42,7 +42,7 @@ npm install
 yarn install
 ```
 
-Use a specific tag for production upgrades. Replace `4.0.0` with the toolkit version you intend to consume.
+Use a specific tag for production upgrades. Replace `{version}` with the toolkit version you intend to consume.
 
 ### Unreleased maintainer testing
 
@@ -67,7 +67,7 @@ You will usually need these pieces:
 
 - [Importing styles](#importing-styles)
 - [Importing JavaScript](#importing-javascript)
-- [Importing assets (optional)](#importing-assets-optional)
+- [Importing assets](#importing-assets)
 
 ## Importing styles
 
@@ -152,10 +152,22 @@ document.addEventListener('DOMContentLoaded', () => {
 });
 ```
 
-## Importing assets (optional)
+## Importing assets
 
 Toolkit assets are available under `node_modules/@ourfuturehealth/toolkit/assets/`.
 
+If you use the toolkit `icon` macro or any toolkit component that renders an icon, your app must also publish the sprite file at a browser-visible URL. The default toolkit path is `/assets/icons/icon-sprite.svg`, so the usual setup is to copy:
+
+- `node_modules/@ourfuturehealth/toolkit/assets/icons/icon-sprite.svg`
+
+to:
+
+- `/assets/icons/icon-sprite.svg`
+
+The browser cannot read files directly from `node_modules`, so installing the package is not enough on its own.
+
+If your app serves the sprite from a different public URL, pass that URL to the toolkit icon macro with `spritePath`.
+
 ```html
 <link rel="shortcut icon" href="path-to-assets/favicons/favicon.ico" type="image/x-icon" />
 <link rel="apple-touch-icon" href="path-to-assets/favicons/apple-touch-icon-180x180.png" />

docs/release-versioning-strategy.md

@@ -60,7 +60,7 @@ Consumers must install the package release tarball:
 ```json
 {
   "dependencies": {
-    "@ourfuturehealth/toolkit": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/toolkit-v4.9.0/ourfuturehealth-toolkit-4.9.0.tgz"
+    "@ourfuturehealth/toolkit": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/toolkit-v{version}/ourfuturehealth-toolkit-{version}.tgz"
   }
 }
 ```
@@ -70,7 +70,7 @@ React consumers follow the same contract:
 ```json
 {
   "dependencies": {
-    "@ourfuturehealth/react-components": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/react-v0.7.0/ourfuturehealth-react-components-0.7.0.tgz"
+    "@ourfuturehealth/react-components": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/react-v{version}/ourfuturehealth-react-components-{version}.tgz"
   }
 }
 ```
@@ -126,8 +126,9 @@ This table is a visual aid for pre-monorepo versus post-monorepo releases.
 | 17    | `react-v0.5.0`   | N/A             | `0.5.0`       | Monorepo       | Released               |
 | 18    | `toolkit-v4.8.0` | `4.8.0`         | N/A           | Monorepo       | Released               |
 | 19    | `react-v0.6.0`   | N/A             | `0.6.0`       | Monorepo       | Released               |
-| 20    | `toolkit-v4.9.0` | `4.9.0`         | N/A           | Monorepo       | Planned in this branch |
-| 21    | `react-v0.7.0`   | N/A             | `0.7.0`       | Monorepo       | Planned in this branch |
+| 20    | `toolkit-v4.9.0` | `4.9.0`         | N/A           | Monorepo       | Released               |
+| 21    | `react-v0.7.0`   | N/A             | `0.7.0`       | Monorepo       | Released               |
+| 22    | `react-v0.8.0`   | N/A             | `0.8.0`       | Monorepo       | Planned in this branch |
 
 ## References
 

packages/example-react-consumer-app/README.md

@@ -7,6 +7,9 @@ This app is intentionally configured as a standalone published-consumer example:
 - it installs the released `@ourfuturehealth/react-components` tarball
 - it imports the published theme stylesheet bundle
 - it does not use the monorepo workspace protocol
+- it exercises icon-bearing components such as `Icon`, `Select`, `Card`, and `Checkboxes`
+
+The dependency in `package.json` intentionally stays on the current published release tag. For unreleased branch validation, use the local tarball workflow below.
 
 ## Install and run
 
@@ -29,6 +32,7 @@ pnpm dev:react-consumer
 - a published tarball install works in a real consumer app
 - the exported React components render in a Vite application
 - the published stylesheet entrypoints load correctly
+- current input-family and icon-bearing components can be smoke-tested outside Storybook
 
 This makes it useful as guidance for future React consumers outside the toolkit repo.
 

packages/example-react-consumer-app/package-lock.json

@@ -12,7 +12,7 @@
     "lint": "eslint . --ignore-pattern '*.config.js'"
   },
   "dependencies": {
-    "@ourfuturehealth/react-components": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/react-v0.5.0/ourfuturehealth-react-components-0.5.0.tgz",
+    "@ourfuturehealth/react-components": "https://github.com/ourfuturehealth/design-system-toolkit/releases/download/react-v0.7.0/ourfuturehealth-react-components-0.7.0.tgz",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },