DS-372 :: Icon naming sync (#196)

* feat: add circle outline icons

* chore(toolkit): prepare 4.8.1 release

Bump the toolkit package for the circle outline icon addition. Refresh the changelog, upgrading guide, and release versioning docs for the standalone patch release.

* docs(prompts): tighten PR readiness release rules

Clarify that review units are independently releasable by default. Require release-impact assessment, versioning, changelog work, and release-contract checks before sign-off.

* docs(prompts): refine merge readiness PR drafting

Rename the workflow concept to merge readiness in the prompt copy and make the PR title/body guidance intentional instead of mechanically section-driven.

* feat(icons): align public names with figma

Hard-rename the toolkit and React icon surface to the current Figma names, including the sprite assets, docs gallery, and component/example usages.

* chore(release): prepare 4.9.0 and 0.7.0

Document the breaking icon rename release across toolkit and react-components, update package versions, and refresh migration guidance.

* chore(icons): sort gallery and story options

Sort docs gallery names alphabetically within each icon category and keep Storybook icon dropdowns alphabetical for easier review.

* chore(icons): preserve stepper number order

Keep the Stepper gallery rows in 0 through 9 order while leaving the other icon categories alphabetical.

* fix(icons): align HospitalOutline name with figma

Author: diogo-filipe-costa

CHANGELOG.md

@@ -6,6 +6,42 @@ We are following [Semantic Versioning](https://semver.org/spec/v2.0.0.html), as
 
 ## Monorepo Package Releases (`toolkit-v*`, `react-v*`)
 
+### 2026-04-09
+
+#### @ourfuturehealth/toolkit 4.9.0 (`toolkit-v4.9.0`)
+
+##### ⚠️ BREAKING CHANGES
+
+- **Icon naming aligned with Figma**: hard-renamed the public toolkit icon names to the current design-system set with no backward-compatible aliases
+  - `Done` → `Check`
+  - `ExpandLess` → `ChevronUp`
+  - `ExpandMore` → `ChevronDown`
+  - `CalendarTodayOutlined` → `CalendarOutline`
+  - `FmdGoodOutlined` → `LocationOutline`
+  - `HospitalOutlined` → `HospitalOutline`
+  - see [UPGRADING.md](UPGRADING.md#upgrading-to-v490--react-v070) for the full rename table
+
+##### Changed
+
+- Renamed the toolkit icon SVG files, manifest entries, sprite symbols, docs gallery entries, and current component/example usages to the Figma-aligned public names
+- Folded the earlier circle-outline addition into the renamed public surface as `AddCircleOutline` and `MinusCircleOutline`
+- Updated the icon docs page and contributor guidance to reflect the renamed toolkit and React icon APIs
+
+#### @ourfuturehealth/react-components 0.7.0 (`react-v0.7.0`)
+
+##### ⚠️ BREAKING CHANGES
+
+- **React Icon names aligned with toolkit/Figma**: any React consumer using the old `Icon` names must migrate to the renamed public set
+  - `Done` → `Check`
+  - `AccessTime` → `ClockOutline`
+  - `LinkedIn` → `Linkedin`
+  - `HospitalOutlined` → `HospitalOutline`
+  - see [UPGRADING.md](UPGRADING.md#upgrading-to-v490--react-v070) for the full rename table
+
+##### Changed
+
+- Updated the public React `Icon` stories/tests and current component consumers to use the renamed icon surface
+
 ### 2026-03-30
 
 #### @ourfuturehealth/toolkit 4.8.0 (`toolkit-v4.8.0`)

UPGRADING.md

@@ -8,6 +8,7 @@ This guide provides detailed migration instructions for upgrading between versio
 
 | 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 |
@@ -18,6 +19,104 @@ This guide provides detailed migration instructions for upgrading between versio
 
 ---
 
+## Upgrading to v4.9.0 / React v0.7.0
+
+**Released:** April 2026
+**Affected packages:**
+
+- `@ourfuturehealth/toolkit` v4.9.0+
+- `@ourfuturehealth/react-components` v0.7.0+
+
+### Breaking Changes
+
+Toolkit and React icon names now match the current Figma icon set directly. This is a hard rename with no backward-compatible aliases.
+
+| Category | Previous name | New name |
+| -------- | ------------- | -------- |
+| DataValidation | `CancelOutlined` | `CancelOutline` |
+| DataValidation | `Done` | `Check` |
+| DataValidation | `AddCircleOutlineOutlined` | `AddCircleOutline` |
+| DataValidation | `RemoveCircle` | `MinusCircle` |
+| DataValidation | `RemoveCircleOutlineOutlined` | `MinusCircleOutline` |
+| Action | `AccountCircleOutlined` | `AccountCircleOutline` |
+| Action | `FileDownloadOutlined` | `FileDownloadOutline` |
+| Action | `FavoriteBorderOutlined` | `FavoriteOutline` |
+| Action | `CalendarTodayOutlined` | `CalendarOutline` |
+| Action | `CalendarToday` | `Calendar` |
+| Arrows | `ExpandLess` | `ChevronUp` |
+| Arrows | `ExpandMore` | `ChevronDown` |
+| Arrows | `East` | `ArrowRight` |
+| Arrows | `West` | `ArrowLeft` |
+| Graphical | `InfoOutlined` | `InfoOutline` |
+| Graphical | `WorkOutlined` | `WorkOutline` |
+| Graphical | `HealthCrossOutlined` | `HealthCrossOutline` |
+| Graphical | `ListAltOutlined` | `ListAltOutline` |
+| Graphical | `HealthAndSafetyOutlined` | `HealthAndSafetyOutline` |
+| Graphical | `ListAltCheckedOutlined` | `ListAltCheckedOutline` |
+| Graphical | `TestTubeOutlined` | `TestTubeOutline` |
+| Graphical | `AccessTime` | `ClockOutline` |
+| Graphical | `WatchLater` | `Clock` |
+| Graphical | `FmdGoodOutlined` | `LocationOutline` |
+| Graphical | `HospitalOutlined` | `HospitalOutline` |
+| Stepper | `LooksZero` | `ListZero` |
+| Stepper | `LooksOne` | `ListOne` |
+| Stepper | `LooksTwo` | `ListTwo` |
+| Stepper | `LooksThree` | `ListThree` |
+| Stepper | `LooksFour` | `ListFour` |
+| Stepper | `LooksFive` | `ListFive` |
+| Stepper | `LooksSix` | `ListSix` |
+| Stepper | `LooksSeven` | `ListSeven` |
+| Stepper | `LooksEight` | `ListEight` |
+| Stepper | `LooksNine` | `ListNine` |
+| Socials | `LinkedIn` | `Linkedin` |
+| Socials | `LinkedInHover` | `LinkedinHover` |
+
+### Release Overview
+
+This breaking release removes the older icon names and replaces them with the Figma-aligned public set across toolkit and React.
+
+Current toolkit component templates, docs examples, React stories, and tests have already been moved to the renamed icon surface in this branch.
+
+### Migration Steps
+
+1. Search for old icon names in toolkit macros, Nunjucks data, React `Icon` props, and any manifest-driven tests.
+2. Replace each old name with the corresponding Figma-aligned name from the table above.
+3. Re-run any tests or visual checks that assert icon symbol ids or class names such as `ofh-icon--Done`.
+
+#### Toolkit example
+
+**Before (`toolkit-v4.8.0`):**
+
+```njk
+{{ icon({ "name": "Done", "size": 24 }) }}
+{{ icon({ "name": "ExpandMore", "size": 24 }) }}
+```
+
+**After (`toolkit-v4.9.0`):**
+
+```njk
+{{ icon({ "name": "Check", "size": 24 }) }}
+{{ icon({ "name": "ChevronDown", "size": 24 }) }}
+```
+
+#### React example
+
+**Before (`react-v0.6.0`):**
+
+```tsx
+<Icon name="AccessTime" size={24} />
+<Icon name="LinkedIn" size={24} />
+```
+
+**After (`react-v0.7.0`):**
+
+```tsx
+<Icon name="ClockOutline" size={24} />
+<Icon name="Linkedin" size={24} />
+```
+
+---
+
 ## Upgrading to v4.8.0 / React v0.6.0
 
 **Released:** March 2026

docs/contributing/material-icons.md

@@ -121,17 +121,20 @@ Example usage:
 
 Core icon styles are in [`packages/toolkit/core/styles/_icons-material.scss`](../../packages/toolkit/core/styles/_icons-material.scss) and imported in [`packages/toolkit/core/all.scss`](../../packages/toolkit/core/all.scss).
 
-### React components (future)
+### React components
 
-Current status: the React package does not yet have a shared icon component.
+The React package now exposes a shared `Icon` component:
 
-When React icon support is added, this doc should be updated with the final approach. Recommended baseline:
+- [`packages/react-components/src/components/Icon/Icon.tsx`](../../packages/react-components/src/components/Icon/Icon.tsx)
+- [`packages/react-components/src/components/Icon/Icon.stories.tsx`](../../packages/react-components/src/components/Icon/Icon.stories.tsx)
 
-- Keep icon names aligned with toolkit `manifest.json`
-- Reuse the same icon semantics (`name`, `size`, decorative vs titled)
-- Decide implementation explicitly:
-  - Sprite-based `<use>` approach (consistency with toolkit/docs), or
-  - Build-time inlined SVG components
+React icon names should stay aligned with toolkit `manifest.json` and the generated sprite symbols.
+
+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>`
+- 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/)
 
@@ -172,7 +175,7 @@ Most icons should use `currentColor` to inherit CSS colors, but some icons need
 
 **Icons that need brand colors preserved:**
 
-- Social media icons (LinkedIn, X, Facebook, Youtube, Instagram, Tiktok) and their hover states
+- Social media icons (Linkedin, X, Facebook, Youtube, Instagram, Tiktok) and their hover states
 - `ArrowCircleRightColour` (uses `#011D4B` and `#FFC62C`)
 
 **Solution**: For brand-colored icons, keep the original Figma fill colors. For all other icons, replace fill colors with `currentColor`.

docs/prompts/README.md

@@ -9,14 +9,14 @@ Use these prompts as a staged workflow when updating a component.
 2. `component-validation-qa-template-prompt.md`
    Use once implementation is mostly done and you want an interactive manual QA pass with exact URLs and step-by-step validation.
 3. `component-pr-readiness-template-prompt.md`
-   Use after QA passes, or when you want the final repo-wide cleanup, release-doc refresh, commit prep, and branch handoff.
+   Use after QA passes, or when you want the final merge-readiness pass: repo-wide cleanup, release-doc refresh, commit prep, PR metadata, and branch handoff.
 
 ## Why These Are Separate
 
 The implementation prompt and the two finish-up prompts ask the agent to work in different modes:
 
 - implementation work should stay focused on design analysis and code changes
 - interactive QA should pause after each step and wait for pass/fail feedback
-- PR-readiness work should keep moving and clean up repo-wide surfaces without stopping after every check
+- merge-readiness work should keep moving and clean up repo-wide surfaces without stopping after every check
 
 Keeping them separate makes the workflow easier to follow and reduces prompt ambiguity.