ourfuturehealth · diogo-filipe-costa · Mar 25, 2026 · Mar 16, 2026 · Mar 16, 2026 · Mar 16, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,38 @@ We are following [Semantic Versioning](https://semver.org/spec/v2.0.0.html), as
 
 ## Monorepo Package Releases (`toolkit-v*`, `react-v*`)
 
+### 2026-03-16
+
+#### @ourfuturehealth/toolkit 4.5.0 (`toolkit-v4.5.0`)
+
+##### Added
+
+- Dedicated `card-callout` and `card-do-dont` toolkit components aligned to the current Card family structure
+- Dismissible-with-image Card examples in the docs site and examples index
+
+##### Changed
+
+- Realigned the base `card` component to the current Figma structure across basic, dismissible, success, clickable, clickable-action, and clickable-numeric variants
+- Preserved legacy toolkit APIs such as `warningCallout()`, `list()`, and old Card inputs as deprecated compatibility paths for existing consumers
+- Updated Card-family documentation and examples to prefer the new Card family macros and options
+- Refined Card-family docs clarity across site docs, macro options, and toolkit READMEs
+
+#### @ourfuturehealth/react-components 0.4.0 (`react-v0.4.0`)
+
+##### Added
+
+- New Card family components using the current API only:
+  - `Card`
+  - `CardCallout`
+  - `CardDoDont`
+- Storybook coverage for base Card variants, Card / Callout, and Card / Do & Don’t
+- Unit and accessibility coverage for the Card family
+
+##### Changed
+
+- Bundled the toolkit icon sprite for React and Storybook consumers so Card icons render without a separately hosted `/assets/icons/icon-sprite.svg`
+- Refined Card-family Storybook docs, controls behaviour, and examples for easier manual QA
+
 ### 2026-03-11
 
 #### @ourfuturehealth/toolkit 4.4.0 (`toolkit-v4.4.0`)

diff --git a/UPGRADING.md b/UPGRADING.md
@@ -8,12 +8,63 @@ This guide provides detailed migration instructions for upgrading between versio
 
 | Version                                                 | Date          | Breaking Changes      | Migration Complexity                  |
 | ------------------------------------------------------- | ------------- | --------------------- | ------------------------------------- |
-| [v4.3.0 / React v0.2.0](#upgrading-to-v430--react-v020) | March 2026    | Button variant naming | 🟡 Medium - Find/replace required     |
+| [v4.5.0 / React v0.4.0](#upgrading-to-v450--react-v040) | March 2026    | Card family realignment | 🟡 Medium - API migration recommended |
+| [v4.3.0 / React v0.2.0](#upgrading-to-v430--react-v020) | March 2026    | Button 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 v4.5.0 / React v0.4.0
+
+**Released:** March 2026
+**Affected packages:**
+
+- `@ourfuturehealth/toolkit` v4.5.0+
+- `@ourfuturehealth/react-components` v0.4.0+
+
+### Breaking Changes
+
+None.
+
+### Card Family Realignment
+
+The Card family has been aligned to the current design-system split:
+
+- `card` remains the base component
+- `warning-callout` has moved to `card-callout`
+- `do-dont-list` has moved to `card-do-dont`
+
+#### Toolkit consumers
+
+Existing toolkit consumers should continue to work without immediate code changes:
+
+- `warningCallout()` still renders, but it is deprecated
+- `list()` still renders, but it is deprecated
+- legacy `card` inputs such as `clickable`, `feature`, `type`, and `HTML` still render, but they are deprecated
+
+For new work, migrate to the new APIs:
+
+| Deprecated toolkit API | Preferred API |
+| ---------------------- | ------------- |
+| `warningCallout()` | `cardCallout({ variant: 'warning', ... })` |
+| `list({ type: 'tick'|'cross' })` | `cardDoDont({ type: 'do'|'dont', ... })` |
+| `card({ clickable: true })` | `card({ variant: 'clickable' })` |
+| `cardWithIcon()` | `card({ icon: { ... } })` |
+| `card({ HTML: ... })` | `card({ descriptionHtml: ... })` |
+
+#### React consumers
+
+There was no existing React Card consumer base to migrate, so the React Card family only exposes the new API:
+
+- `Card`
+- `CardCallout`
+- `CardDoDont`
+
+React does not include the deprecated toolkit compatibility props.
+
+---
+
 ## Upgrading to v4.3.0 / React v0.2.0
 
 **Released:** March 2026  
@@ -336,7 +387,7 @@ Install from specific release tag (recommended):
 ```json
 {
   "dependencies": {
-    "@ourfuturehealth/toolkit": "github:ourfuturehealth/design-system-toolkit#toolkit-v4.0.0:packages/toolkit"
+    "@ourfuturehealth/toolkit": "github:ourfuturehealth/design-system-toolkit#toolkit-v4.5.0:packages/toolkit"
   }
 }
 ```
@@ -538,7 +589,7 @@ Server-side rendering templates for generating HTML:
 - **Packages can be released independently**
 - Tag format:
   - Toolkit: `toolkit-v*` (e.g., `toolkit-v4.0.0`)
-  - React: `react-v*` (e.g., `react-v0.0.1`)
+  - React: `react-v*` (e.g., `react-v0.2.0`)
 
 ### Installing Individual Packages
 
@@ -549,7 +600,7 @@ Each package in the monorepo can be installed independently:
 ```json
 {
   "dependencies": {
-    "@ourfuturehealth/toolkit": "github:ourfuturehealth/design-system-toolkit#toolkit-v4.0.0:packages/toolkit"
+    "@ourfuturehealth/toolkit": "github:ourfuturehealth/design-system-toolkit#toolkit-v4.5.0:packages/toolkit"
   }
 }
 ```
@@ -559,7 +610,7 @@ Each package in the monorepo can be installed independently:
 ```json
 {
   "dependencies": {
-    "@ourfuturehealth/react-components": "github:ourfuturehealth/design-system-toolkit#react-v0.0.1:packages/react-components"
+    "@ourfuturehealth/react-components": "github:ourfuturehealth/design-system-toolkit#react-v0.4.0:packages/react-components"
   }
 }
 ```

diff --git a/docs/consuming-react-components.md b/docs/consuming-react-components.md
@@ -1,5 +1,3 @@
-# WORK IN PROGRESS (Needs to be updated)
-
 # Consuming Our Future Health React Components
 
 This guide explains how to consume the `@ourfuturehealth/react-components` package in your React applications.
@@ -19,26 +17,26 @@ Currently, the React components are not published to npm registry. Install direc
 ### Using pnpm (recommended)
 
 ```bash
-pnpm add @ourfuturehealth/react-components@github:ourfuturehealth/design-system-toolkit#react-v0.0.1:packages/react-components
+pnpm add @ourfuturehealth/react-components@github:ourfuturehealth/design-system-toolkit#react-v0.4.0:packages/react-components
 ```
 
 ### Using npm
 
 ```bash
-npm install @ourfuturehealth/react-components@github:ourfuturehealth/design-system-toolkit#react-v0.0.1:packages/react-components
+npm install @ourfuturehealth/react-components@github:ourfuturehealth/design-system-toolkit#react-v0.4.0:packages/react-components
 ```
 
 ### Version Pinning
 
-- **Production**: Use specific version tags (e.g., `#react-v0.0.1`)
+- **Production**: Use specific version tags (e.g., `#react-v0.4.0`)
 - **Development**: You can use `#main:packages/react-components` but ensure your lockfile pins a specific commit
 
 **package.json example:**
 
 ```json
 {
   "dependencies": {
-    "@ourfuturehealth/react-components": "github:ourfuturehealth/design-system-toolkit#react-v0.0.1:packages/react-components",
+    "@ourfuturehealth/react-components": "github:ourfuturehealth/design-system-toolkit#react-v0.4.0:packages/react-components",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   }
@@ -112,10 +110,12 @@ To add a new custom React theme stylesheet export, follow `docs/theming/adding-a
 
 The React components package currently provides the following components:
 
-- `Button` - Call-to-action buttons
-- `TextInput` - Text input fields
-
-**More components coming soon!** We're actively developing additional React wrappers for the design system toolkit components.
+- `Button` - Call-to-action buttons and links
+- `TextInput` - Text input fields with hint and error support
+- `ErrorSummary` - Page-level validation summaries with linked errors
+- `Card` - Content presentation cards for summaries, status, and next steps
+- `CardCallout` - Feedback-style callout cards for informational, warning, success, and error messages
+- `CardDoDont` - Positive and negative recommendation lists
 
 For complete component documentation and live examples, run Storybook:
 

diff --git a/docs/prompts/README.md b/docs/prompts/README.md
@@ -0,0 +1,22 @@
+# Prompt Workflows
+
+Use these prompts as a staged workflow when updating a component.
+
+## Recommended Order
+
+1. `component-update-template-prompt.md`
+   Use for the full implementation workflow: Figma analysis, toolkit work, React parity, tests, Storybook, and documentation.
+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.
+
+## 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
+
+Keeping them separate makes the workflow easier to follow and reduces prompt ambiguity.
diff --git a/docs/prompts/component-pr-readiness-template-prompt.md b/docs/prompts/component-pr-readiness-template-prompt.md
@@ -0,0 +1,113 @@
+# Component PR 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.
+
+Use this prompt after manual QA passes, or when you want the final PR-preparation sweep across docs, release notes, branch state, and commits.
+
+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.
+
+---
+
+## How to Use This Template
+
+1. Copy the prompt block below.
+2. Replace the placeholders with your component and branch details.
+3. Paste it into the agent working in that worktree.
+4. Let the agent prepare the branch for review, then inspect the summary and commit history.
+
+---
+
+## Prompt
+
+```md
+I'm working on the `[ComponentName]` update in this worktree.
+
+Context:
+- Ticket: `[JIRA URL or ID]`
+- Intended base branch: `[origin/main or another branch/PR]`
+- Local site/docs server: `[http://localhost:8080]`
+- Local Storybook server: `[http://localhost:6006]`
+- If relevant, Figma: `[FIGMA URL]`
+- If relevant, related PRs or dependency order: `[details]`
+
+I want you to make this branch PR-ready.
+
+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.
+2. Give me a concise "what changed" summary in practical terms.
+3. Do a mechanical diff-hygiene pass:
+   - `git status --short`
+   - `git diff --stat`
+   - `git diff --check`
+   - targeted searches for old component names, old routes, outdated install tags, stale Storybook/docs references, and deprecated API wording
+4. Do a repo-wide stale-reference sweep for user-facing and contributor-facing surfaces that commonly drift:
+   - docs side navigation
+   - site map pages
+   - `sitemap.xml`
+   - examples index
+   - related component and pattern pages
+   - package READMEs
+   - migration/upgrading docs
+   - changelog or release notes
+5. 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
+   - 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:
+   - 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:
+   - `npm test` after JavaScript or TypeScript changes
+   - `pnpm lint`
+   - `pnpm build` when relevant
+   - 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:
+   - 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):
+   - 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.
+
+Important constraints:
+- Run `npm test` after modifying JavaScript or TypeScript files.
+- Run `pnpm lint` before considering the branch ready to push.
+- Prefer minimal, surgical changes.
+- Keep toolkit and React parity in scope where that is part of the intended component API.
+- If docs/examples are missing what is needed for consumers or reviewers, improve them.
+- If release or migration docs are expected for this repo, include them so the PR is review-ready rather than code-only.
+- Do not leave temporary dependency stand-ins implicit. Remove them if the real dependency is now available, or document them clearly if they must remain temporarily.
+- If the branch depends on another PR landing first, do not force a merge from the wrong base just to satisfy the workflow.
+- Leave unrelated modified or untracked files alone unless I explicitly ask you to include them.
+- At the end, summarize:
+  - the main functional changes
+  - any repo-wide cleanup or stale-reference fixes
+  - any post-base-update fixes
+  - the exact checks run
+  - the exact commit(s) created
+  - the exact push command(s)
+
+Output style I want from you:
+- Be practical and direct.
+- Keep the cleanup work moving rather than stopping after every minor step.
+- Explain stale-reference or migration issues plainly.
+- Keep the final summary concise but complete enough for PR handoff.
+```
+
+---
+
+## Notes
+
+- This template is intentionally focused on review-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.