Open
Conversation
✅ Deploy Preview for ofh-design-system-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
Updates the design-system Tag styling and documentation to align with the latest design tokens/variant naming, and introduces a first-party React <Tag /> wrapper that maps to the toolkit modifiers.
Changes:
- Refresh toolkit Tag styles (neutral-by-default) and introduce the
ofh-tag--brandmodifier while deprecatingofh-tag--greyin favour ofofh-tag--neutral. - Update site examples + design-system docs to reflect the new canonical variants and default behaviour.
- Add
Tagto@ourfuturehealth/react-componentswith tests and Storybook stories, and document the breaking change in release docs.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/toolkit/components/tag/_tag.scss | Updates Tag base + variant styling tokens; adds brand variant; makes neutral the default styling. |
| packages/toolkit/components/tag/README.md | Updates toolkit Tag usage examples, supported modifiers list, and migration notes. |
| packages/site/views/examples/components/tag/index.njk | Updates example page to show the canonical Tag variants and new default behaviour. |
| packages/site/views/examples/components/all.njk | Keeps the “all components” examples page consistent with updated Tag variants/default. |
| packages/site/views/design-system/components/tag/macro-options.json | Updates Tag macro option docs (required flags + variant guidance). |
| packages/site/views/design-system/components/tag/index.njk | Updates design-system guidance text, deprecation note, and last-updated date. |
| packages/site/views/design-system/components/tag/default/index.njk | Updates default Tag design examples for neutral default and explicit blue usage. |
| packages/site/views/design-system/components/tag/colours/index.njk | Updates the colour-variant table and examples to match the new canonical set. |
| packages/site/views/_includes/_beta-banner.njk | Pins the beta banner Tag to the explicit blue variant to preserve previous appearance. |
| packages/site/styles/app/_example-callout.scss | Adjusts example callout heading styling to preserve contrast/appearance after Tag changes. |
| packages/react-components/src/index.ts | Exposes the new React Tag from the public package entrypoint. |
| packages/react-components/src/components/Tag/index.ts | Barrel export for the React Tag component + types. |
| packages/react-components/src/components/Tag/Tag.tsx | Implements React <Tag /> with a variant API mapping to toolkit modifier classes. |
| packages/react-components/src/components/Tag/Tag.test.tsx | Adds unit + a11y tests for default behaviour, variant mapping, props passthrough, and ref handling. |
| packages/react-components/src/components/Tag/Tag.stories.tsx | Adds Storybook docs/stories for default, all variants, and usage examples. |
| packages/react-components/README.md | Documents React Tag usage and props. |
| docs/prompts/component-validation-qa-template-prompt.md | Adds a manual QA prompt template for component validation. |
| docs/prompts/component-update-template-prompt.md | Expands the component update workflow templates (parity, docs UX, dependencies). |
| docs/prompts/component-pr-readiness-template-prompt.md | Adds a PR-readiness prompt template for final cleanup/release prep. |
| UPGRADING.md | Adds migration guidance for the Tag default change + new naming/variants. |
| CHANGELOG.md | Adds release notes entry describing the Tag changes and new React component. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Comment on lines
+20
to
+37
| export interface TagProps | ||
| extends Omit< | ||
| React.HTMLAttributes<HTMLElement>, | ||
| 'children' | 'dangerouslySetInnerHTML' | 'ref' | ||
| > { | ||
| /** | ||
| * Visual style variant. | ||
| */ | ||
| variant?: TagVariant; | ||
| /** | ||
| * Tag content. | ||
| */ | ||
| children: React.ReactNode; | ||
| /** | ||
| * Ref forwarding for the underlying strong element. | ||
| */ | ||
| ref?: React.Ref<HTMLElement>; | ||
| } |
Comment on lines
73
to
+78
| | Name | Type | Required | Description | | ||
| | -----------------|----------|-----------|-------------| | ||
| | text | string | Yes | If `html` is set, this is not required. Text to use within the tag component. If `html` is provided, the `text` argument will be ignored. | | ||
| | html | string | Yes | If `text` is set, this is not required. HTML to use within the tag component. If `html` is provided, the `text` argument will be ignored. | | ||
| | classes | string | No | Optional additional classes to add to the tag. Separate each class with a space. | | ||
| | attributes | object | No | HTML attributes (for example data attributes) to add to the tag. | | ||
| | text | string | No | Text to use within the tag component. If `html` is provided, the `text` argument will be ignored. | | ||
| | html | string | No | HTML to use within the tag component. If `html` is provided, it takes precedence over `text`. | | ||
| | classes | string | No | Optional additional classes to add to the tag. Use `ofh-tag--neutral`, `ofh-tag--brand`, `ofh-tag--blue`, `ofh-tag--green`, `ofh-tag--yellow`, or `ofh-tag--red` for the supported colour variants. `ofh-tag--grey` is deprecated. | | ||
| | attributes | object | No | HTML attributes (for example data attributes) to add to the tag. | |
Comment on lines
3
to
+19
| { | ||
| "name": "text", | ||
| "type": "string", | ||
| "required": true, | ||
| "description": "If `html` is set, this is not required. Text to use within the tag component. If `html` is provided, the `text` argument will be ignored." | ||
| "required": false, | ||
| "description": "Text to use within the tag component. If `html` is provided, the `text` argument will be ignored." | ||
| }, | ||
| { | ||
| "name": "html", | ||
| "type": "string", | ||
| "required": true, | ||
| "description": "If `text` is set, this is not required. HTML to use within the tag component. If `html` is provided, the `text` argument will be ignored." | ||
| "required": false, | ||
| "description": "HTML to use within the tag component. If `html` is provided, it takes precedence over `text`." | ||
| }, | ||
| { | ||
| "name": "classes", | ||
| "type": "string", | ||
| "required": false, | ||
| "description": "Classes to add to the tag." | ||
| "description": "Classes to add to the tag. Use `ofh-tag--neutral`, `ofh-tag--brand`, `ofh-tag--blue`, `ofh-tag--green`, `ofh-tag--yellow`, or `ofh-tag--red` for the supported colour variants. `ofh-tag--grey` is deprecated and should be replaced with `ofh-tag--neutral`." |
Comment on lines
+11
to
+25
| | [v4.5.0 / React v0.4.0](#upgrading-to-v450--react-v040) | March 2026 | Tag default + naming | 🟡 Medium - Search/replace recommended | | ||
| | [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 v4.5.0 / React v0.4.0 | ||
|
|
||
| **Released:** March 2026 | ||
| **Affected packages:** | ||
|
|
||
| - `@ourfuturehealth/toolkit` v4.5.0+ | ||
| - `@ourfuturehealth/react-components` v0.4.0+ | ||
|
|
Comment on lines
+11
to
+38
| #### @ourfuturehealth/toolkit 4.5.0 (`toolkit-v4.5.0`) | ||
|
|
||
| ##### ⚠️ BREAKING CHANGES | ||
|
|
||
| - Tag defaults now align with Figma: | ||
| - `.ofh-tag` now renders the neutral style by default | ||
| - `.ofh-tag--grey` is deprecated in favour of `.ofh-tag--neutral` | ||
| - consumers that relied on the old blue default should move to `.ofh-tag.ofh-tag--blue` | ||
| - see [Upgrading Guide](UPGRADING.md#upgrading-to-v450--react-v040) for migration steps | ||
|
|
||
| ##### Added | ||
|
|
||
| - New `ofh-tag--brand` modifier aligned with the OFH Tag component in Figma | ||
| - Canonical `ofh-tag--neutral` naming for the neutral tag variant | ||
|
|
||
| ##### Changed | ||
|
|
||
| - Updated Tag typography, spacing, and colour tokens to match the current design spec | ||
| - Refreshed toolkit Tag documentation, examples, and design-system guidance to use the supported Tag variants | ||
| - Preserved docs-site beta banner and example callout styling after the neutral default change | ||
|
|
||
| #### @ourfuturehealth/react-components 0.4.0 (`react-v0.4.0`) | ||
|
|
||
| ##### Added | ||
|
|
||
| - New `Tag` component with a semantic React API based on `variant` and `children` | ||
| - Storybook coverage for default, variant showcase, and usage-example Tag stories | ||
| - Unit and accessibility coverage for variant mapping, children rendering, passthrough props, and ref support |
diogo-filipe-costa
force-pushed
the
codex/dse-332-tag-update
branch
from
28aaf7e to
380ae8c
Compare
diogo-filipe-costa
requested review from
cfgreene,
jpsanders101,
rmds16,
willmcb and
wotton-software
jpsanders101
approved these changes
Mar 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR delivers DSE-332 Tag alignment with Figma across the toolkit, React component library, site examples, Storybook, migration/release documentation, and the reusable component workflow prompts used on this branch.
Refreshed on 2026-03-17 by rebasing the current
mainafter #179 landed.The release scope in this PR is now:
@ourfuturehealth/toolkit->4.5.0(tag:toolkit-v4.5.0)@ourfuturehealth/react-components->0.4.0(tag:react-v0.4.0)site/docschanges are included in-repo (no independently versioned release tag)Ticket: DSE-332
Breaking Changes
.ofh-tagnow renders the neutral treatment by default.ofh-tag--greyis deprecated in favour of.ofh-tag--neutral.ofh-tag.ofh-tag--blueKey Changes
1) Toolkit Tag alignment with Figma
.ofh-tagtreatment to neutral instead of blueofh-tag--brandmodifierofh-tag--neutralnaming and keptofh-tag--greyas a deprecated compatibility aliasofh-tag--bluemodifier2) Site docs, examples, and regression-safe consumer updates
white,aqua-green,purple,pink,orange)neutral,brand,blue,green,yellow, andred3) React Tag component with a simpler public API
Tagcomponent to@ourfuturehealth/react-componentsvariantandchildren, while still mapping to the toolkit Tag classes internally4) Release and migration documentation
4.5.0/ react-components0.4.0release scopeUPGRADING.mdfor:grey->neutralreplacement5) Reusable component workflow prompt updates
Validation
npm testpnpm lintpnpm buildpnpm --filter=@ourfuturehealth/react-components run build:storybookneutral,brand,blue,green,yellow, andredvariant+childrenReviewer Focus
brandvariant.ofh-tag,.ofh-tag--blue,.ofh-tag--grey, and.ofh-tag--neutral