DS-372 :: Icon naming sync

CHANGELOG.md

@@ -6,6 +6,14 @@ We are following [Semantic Versioning](https://semver.org/spec/v2.0.0.html), as
 
 ## Monorepo Package Releases (`toolkit-v*`, `react-v*`)
 
+### 2026-04-08
+
+#### @ourfuturehealth/toolkit 4.8.1 (`toolkit-v4.8.1`)
+
+##### Added
+
+- Added `AddCircleOutlineOutlined` and `RemoveCircleOutlineOutlined` to the toolkit icon set, generated sprite, and docs gallery
+
 ### 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.8.1](#upgrading-to-v481)                            | April 2026    | No breaking changes | 🟢 None - optional icon additions only |
 | [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,28 @@ This guide provides detailed migration instructions for upgrading between versio
 
 ---
 
+## Upgrading to v4.8.1
+
+**Released:** April 2026
+**Affected packages:**
+
+- `@ourfuturehealth/toolkit` v4.8.1+
+
+### Breaking Changes
+
+None.
+
+### Release Overview
+
+This patch release adds two new toolkit icon names:
+
+- `AddCircleOutlineOutlined`
+- `RemoveCircleOutlineOutlined`
+
+No migration is required for existing consumers.
+
+---
+
 ## Upgrading to v4.8.0 / React v0.6.0
 
 **Released:** March 2026

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.

docs/prompts/component-pr-readiness-template-prompt.md

@@ -1,10 +1,10 @@
-# Component PR Readiness Template Prompt
+# Component Merge Readiness Template Prompt
 
-This template is for the final repo-wide cleanup once a component branch is functionally done and you want to make it review-ready.
+This template is for the final repo-wide cleanup once a component branch is functionally done and you want to make it merge-ready.
 
-Use this prompt after manual QA passes, or when you want the final PR-preparation sweep across docs, release notes, branch state, and commits.
+Use this prompt after manual QA passes, or when you want the final merge-preparation sweep across docs, release notes, branch state, commits, release prep, and PR metadata.
 
-This prompt assumes the implementation phase already included the main template's documentation and Storybook UX pass. PR-readiness work should verify consistency and clean up leftovers, not rely on this stage as the first place to discover misleading Storybook controls or unclear prop descriptions.
+This prompt assumes the implementation phase already included the main template's documentation and Storybook UX pass. Merge-readiness work should verify consistency and clean up leftovers, not rely on this stage as the first place to discover misleading Storybook controls or unclear prop descriptions.
 
 ---
 
@@ -30,7 +30,9 @@ Context:
 - If relevant, Figma: `[FIGMA URL]`
 - If relevant, related PRs or dependency order: `[details]`
 
-I want you to make this branch PR-ready.
+I want you to make this branch merge-ready.
+
+Treat `merge-ready` as `reviewable, independently releasable, and safe to merge into the intended base branch` unless I explicitly say this branch is intentionally non-releasable.
 
 Workflow I want you to follow:
 1. Inspect the current diff, branch status, and recent component work across toolkit, React, docs/examples, Storybook, and tests.
@@ -49,69 +51,85 @@ Workflow I want you to follow:
    - package READMEs
    - migration/upgrading docs
    - changelog or release notes
-5. Check public API and migration clarity:
+5. Decide release impact before sign-off:
+   - determine which published packages are affected: `toolkit`, `react-components`, `both`, or `none`
+   - recommend the correct bump type for each affected package: `patch`, `minor`, or `major`
+   - explain the reasoning briefly in user-facing terms
+   - if this branch is expected to be independently releasable, apply the version bump instead of only suggesting it
+   - if no package version, changelog entry, or migration guidance is updated for an affected releasable package, treat that as a merge-readiness failure and fix it before sign-off
+6. Check public API and migration clarity:
    - confirm deprecated compatibility paths exist only where intended
    - confirm toolkit vs React consumer expectations are documented clearly
    - confirm Storybook controls policy and prop docs are still coherent after any late changes
    - confirm no interactive single-component stories are still relying on raw JSON controls for stable nested props when clearer story-specific controls would be more usable
    - confirm no story is exposing controls for values the component visibly ignores or overrides
    - if the component was touched by a spacing/typography token migration, do a final spot-check for same-number static-token substitutions where Figma expected responsive tokens
    - do a final spot-check for accidental semantic-element inheritance (`p`, `ul`, `li`, `h*`, `a`) that may have reintroduced wrong spacing or typography
-   - confirm release/version metadata is internally consistent wherever this branch claims a release number or tag:
-     - `packages/*/package.json` version fields
-     - `CHANGELOG.md`
-     - `UPGRADING.md`
-     - release/versioning strategy docs
-     - PR title/body if it mentions planned release versions or tags
-   - if docs claim a package release version or tag that is not reflected in the relevant `package.json`, treat that as a PR-readiness failure and fix it before sign-off
-   - if the component was touched by a spacing/typography token migration, do a final spot-check for same-number static-token substitutions where Figma expected responsive tokens
-   - do a final spot-check for accidental semantic-element inheritance (`p`, `ul`, `li`, `h*`, `a`) that may have reintroduced wrong spacing or typography
-   - confirm release/version metadata is internally consistent wherever this branch claims a release number or tag:
-     - `packages/*/package.json` version fields
-     - `CHANGELOG.md`
-     - `UPGRADING.md`
-     - release/versioning strategy docs
-     - PR title/body if it mentions planned release versions or tags
-   - if docs claim a package release version or tag that is not reflected in the relevant `package.json`, treat that as a PR-readiness failure and fix it before sign-off
-   - confirm no interactive single-component stories are still relying on raw JSON controls for stable nested props when clearer story-specific controls would be more usable
-   - confirm no story is exposing controls for values the component visibly ignores or overrides
-   - if the component was touched by a spacing/typography token migration, do a final spot-check for same-number static-token substitutions where Figma expected responsive tokens
-   - do a final spot-check for accidental semantic-element inheritance (`p`, `ul`, `li`, `h*`, `a`) that may have reintroduced wrong spacing or typography
-   - confirm release/version metadata is internally consistent wherever this branch claims a release number or tag:
+   - confirm release/version metadata is internally consistent for every affected releasable package:
      - `packages/*/package.json` version fields
      - `CHANGELOG.md`
      - `UPGRADING.md`
      - release/versioning strategy docs
      - PR title/body if it mentions planned release versions or tags
-   - if docs claim a package release version or tag that is not reflected in the relevant `package.json`, treat that as a PR-readiness failure and fix it before sign-off
+   - if docs claim a package release version or tag that is not reflected in the relevant `package.json`, treat that as a merge-readiness failure and fix it before sign-off
    - identify any temporary internal adapters or dependency workarounds that were introduced because a reusable component was missing or not ready
    - if any remain, either remove them or document them explicitly as follow-up debt
    - add or refresh migration guidance if the branch changes APIs, names, routes, or recommended usage
-6. If any stale references, repo-drift issues, or missing release-doc updates are found, fix them with minimal changes and run the required checks.
-7. Make sure the branch is attached if the worktree is on a detached `HEAD`.
-8. Update the branch against the intended base branch using the repo's preferred workflow:
+7. If any stale references, repo-drift issues, or missing release-doc updates are found, fix them with minimal changes and run the required checks.
+8. Make sure the branch is attached if the worktree is on a detached `HEAD`.
+9. Update the branch against the intended base branch using the repo's preferred workflow:
    - merge or rebase, whichever is appropriate
    - if another PR must land first, explain that clearly and stop before forcing a bad merge
    - if updating from base introduces dependency, lint, test, or build issues, fix them as part of branch prep
-9. Re-run final validation after the cleanup and base-branch update:
+10. Re-run final validation after the cleanup and base-branch update:
    - `npm test` after JavaScript or TypeScript changes
    - `pnpm lint`
    - `pnpm build` when relevant
+   - `pnpm docs:release-contract` for releasable branches
+   - `pnpm smoke:release-artifacts` when preparing a package release branch that bumps a published package version
    - any package-specific checks that matter, especially Storybook if React/docs were touched
-10. If any lint/build/test issue appears during the review-ready stage, explain clearly:
+11. If any lint/build/test issue appears during the merge-ready stage, explain clearly:
    - what failed
    - whether it came from this branch, from updating from base, or from local dependency drift
    - what you changed to resolve it
-11. Create appropriate conventional commit(s):
+12. Create appropriate conventional commit(s):
    - use concise subjects
    - include short bodies when helpful
    - if there are clearly separate concerns, split them into logical commits
-12. Once the branch is fully ready, draft:
-   - a PR title
-   - a concise PR description in the style used in this repo
-13. Do not push. Give me the exact `git push` command(s) to run manually.
+13. Once the branch is fully ready, draft the PR metadata in the house style used in this repo:
+   - use a ticket-led title when the branch maps cleanly to ticketed work:
+     - single ticket: `[TICKET] :: [concise scope summary]`
+     - multi-ticket: `[TICKET A] / [TICKET B] :: [shared scope summary]`
+   - use a non-ticket title only for repo/infra/release work that genuinely does not map to a ticket
+   - keep titles short, specific, and noun-led where possible; avoid filler such as "misc", "stuff", or generic "update" unless it adds clarity
+   - use the repo-style sections intentionally rather than mechanically
+   - start from the common section set below, but only keep sections that add reviewer value for this specific PR:
+     - `## Description`
+     - `Ticket:`, `Tickets:`, or `Closes:`
+     - `## Release scope` or `## Scope`
+     - `## Breaking Changes`
+     - `## Key Changes`
+     - `## Validation`
+     - `## Reviewer Focus`
+   - section selection rules:
+     - always include `## Description`
+     - include `Ticket:`, `Tickets:`, or `Closes:` when the work maps to ticketed work
+     - use `## Release scope` when package version bumps, release metadata, or release coordination are part of the branch
+     - use `## Scope` when the branch needs contextual boundaries but release scope is not the main framing
+     - include `## Breaking Changes` when the PR is breaking, or when explicitly saying `None.` helps reviewers and release prep
+     - include `## Key Changes` when there are multiple meaningful change buckets; for very small PRs, fold the substance into `## Description` instead
+     - include `## Validation` with exact commands and meaningful manual QA surfaces
+     - include `## Reviewer Focus` when you can point reviewers at the highest-risk or highest-value review areas; omit it when it would only repeat the obvious diff
+   - body-writing rules:
+     - opening paragraph pattern: `This PR delivers **[ticket/work summary]** across [affected surfaces].`
+     - add a second context paragraph only when it genuinely helps, for example rebases, stacked dependencies, release baseline shifts, or why the branch goes beyond a narrow ticket interpretation
+     - keep the body review-oriented: explain what changed, why it changed, release impact, and where reviewers should focus
+     - avoid padding the PR with empty, repetitive, or low-information sections just to match a template
+14. Do not push. Give me the exact `git push` command(s) to run manually.
 
 Important constraints:
+- Default to independently releasable branches for review units unless I explicitly tell you otherwise.
+- If the branch changes a published package, do not sign off merge readiness until you have assessed release impact and either applied or explicitly justified the absence of package-version, changelog, and migration updates.
 - Run `npm test` after modifying JavaScript or TypeScript files.
 - Run `pnpm lint` before considering the branch ready to push.
 - Prefer minimal, surgical changes.
@@ -140,5 +158,5 @@ Output style I want from you:
 
 ## Notes
 
-- This template is intentionally focused on review-readiness rather than interactive QA.
+- This template is intentionally focused on merge-readiness rather than interactive QA.
 - Use `component-validation-qa-template-prompt.md` when you want the agent to stop after each validation step and wait for pass/fail feedback.

docs/prompts/component-update-template-prompt.md

@@ -5,7 +5,7 @@ This template provides a complete workflow for updating/creating design system c
 Follow this with the dedicated finish-up prompts:
 
 - `component-validation-qa-template-prompt.md` for interactive manual QA
-- `component-pr-readiness-template-prompt.md` for final cleanup, release-doc refresh, commits, and PR prep
+- `component-pr-readiness-template-prompt.md` for the final merge-readiness pass: cleanup, release-doc refresh, commits, and PR prep
 
 ---
 
@@ -25,7 +25,7 @@ Follow this with the dedicated finish-up prompts:
 4. The agent will follow the structured workflow automatically
 
 **💡 Best Practice:** Keep this file as your master template. Don't create component-specific files.
-After implementation is mostly done, move to the dedicated validation and PR-readiness prompts instead of trying to do everything in one long session.
+After implementation is mostly done, move to the dedicated validation and merge-readiness prompts instead of trying to do everything in one long session.
 This workflow also includes a temporary external-reference audit against the BSM React repo to speed up component work while OFH React coverage is still catching up. Once OFH React reaches comparable coverage, stop relying on that external repo.
 
 ---

docs/prompts/component-validation-qa-template-prompt.md

@@ -98,12 +98,12 @@ Output style I want from you:
 - Drive the QA one step at a time.
 - Make each QA step specific enough that a reviewer can validate it without guessing what "good" looks like.
 - When something fails, explain it plainly and fix it before moving on.
-- Keep the summary concise and useful for handing off into PR-readiness work.
+- Keep the summary concise and useful for handing off into merge-readiness work.
 ```
 
 ---
 
 ## Notes
 
 - This template is intentionally focused on human-in-the-loop validation.
-- Use `component-pr-readiness-template-prompt.md` after this when you want the final cleanup, release-doc refresh, commits, and branch handoff.
+- Use `component-pr-readiness-template-prompt.md` after this when you want the final merge-readiness pass: cleanup, release-doc refresh, commits, PR metadata, and branch handoff.

docs/release-versioning-strategy.md

@@ -124,8 +124,9 @@ This table is a visual aid for pre-monorepo versus post-monorepo releases.
 | 15    | `react-v0.4.0`   | N/A             | `0.4.0`       | Monorepo       | Released               |
 | 16    | `toolkit-v4.7.0` | `4.7.0`         | N/A           | Monorepo       | Released               |
 | 17    | `react-v0.5.0`   | N/A             | `0.5.0`       | Monorepo       | Released               |
-| 18    | `toolkit-v4.8.0` | `4.8.0`         | N/A           | Monorepo       | Planned in this branch |
-| 19    | `react-v0.6.0`   | N/A             | `0.6.0`       | Monorepo       | Planned in this branch |
+| 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.8.1` | `4.8.1`         | N/A           | Monorepo       | Planned in this branch |
 
 ## References
 

packages/site/views/_data/materialIcons.js

@@ -31,7 +31,9 @@ const categoryOrders = {
     "CancelOutlined",
     // Add/Remove
     "AddCircle",
+    "AddCircleOutlineOutlined",
     "RemoveCircle",
+    "RemoveCircleOutlineOutlined",
   ],
   Action: [
     "Search",