DSE-335 :: Link family FE update (#200)

* feat: update link family components

* fix: preserve right link icon layout

* fix: refine link family naming and guidance

* docs(prompts): tighten token conformance checks

* chore: refresh canonical link-family references

* chore(release): prepare link family release

* docs(prompts): preserve full Jira keys in PR metadata

* fix: address link family review feedback

* docs: align link family docs across storybook and site

* chore(release): bump link family react version to 0.9.0

* docs(storybook): refine link family stories

Author: diogo-filipe-costa

CHANGELOG.md

@@ -6,20 +6,43 @@ We are following [Semantic Versioning](https://semver.org/spec/v2.0.0.html), as
 
 ## Monorepo Package Releases (`toolkit-v*`, `react-v*`)
 
-### Unreleased
+### 2026-04-09
+
+#### @ourfuturehealth/toolkit 4.10.0 (`toolkit-v4.10.0`)
+
+##### Changed
 
-#### @ourfuturehealth/react-components 0.8.0 (`react-v0.8.0`)
+- Renamed the public link-family docs, examples, and canonical toolkit component paths to match Figma and Jira terminology:
+  - `action-link` is now taught as `link-action`
+  - `back-link` is now taught as `link-icon`
+  - `skip-link` is now taught as `link-skip`
+- Preserved low-risk toolkit compatibility aliases for the previous macro paths and examples while moving docs navigation, examples, and site templates to the canonical names
+- Expanded the canonical `link-icon` guidance to cover usage, placement, accessibility notes, and the broader icon-led link pattern instead of only back-navigation
+- Aligned link-family spacing, typography, focus, and visible-state token usage with the current Figma spec
+
+#### @ourfuturehealth/react-components 0.9.0 (`react-v0.9.0`)
 
 ##### ⚠️ BREAKING CHANGES
 
 - React `Icon` and `Card` icon configuration no longer accept `spritePath`. React icons now always render from bundled toolkit SVG data.
 
+##### Changed
+
+- Reorganized React Storybook so the link family is taught under `Components / Link / ...`
+- Expanded `LinkIcon` stories to support the full icon set and an optional icon-colour override while keeping the default icon behaviour aligned with the label colour
+- Updated React docs, stories, and tests to use the canonical `LinkAction`, `LinkIcon`, and `LinkSkip` names
+
+##### Added
+
+- First public React release of the link family:
+  - `LinkAction`
+  - `LinkIcon`
+  - `LinkSkip`
+
 ##### 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`)
 
 ##### ⚠️ BREAKING CHANGES

UPGRADING.md

@@ -8,7 +8,7 @@ This guide provides detailed migration instructions for upgrading between versio
 
 | 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.10.0 / React v0.9.0](#upgrading-to-v4100--react-v090) | April 2026    | React `spritePath` removal | 🟢 Low - Remove the deprecated prop and adopt canonical names for new usage |
 | [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    |
@@ -20,55 +20,74 @@ This guide provides detailed migration instructions for upgrading between versio
 
 ---
 
-## Upgrading to React v0.8.0
+## Upgrading to v4.10.0 / React v0.9.0
 
 **Planned:** April 2026
 **Affected packages:**
 
-- `@ourfuturehealth/react-components` v0.8.0+
+- `@ourfuturehealth/toolkit` v4.10.0+
+- `@ourfuturehealth/react-components` v0.9.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.
 
+Toolkit macro paths and site routes now teach the canonical names below, while compatibility aliases remain available in this release:
+
+| Preferred toolkit name | Compatibility alias |
+| ---------------------- | ------------------- |
+| `link-action` | `action-link` |
+| `link-icon` | `back-link` |
+| `link-skip` | `skip-link` |
+
+### Release Overview
+
+This release introduces the public React link family and aligns the toolkit link-family naming and IA to the current design-system terminology used in Figma and Jira.
+
+- React consumers can adopt the new public `LinkAction`, `LinkIcon`, and `LinkSkip` components directly.
+- Toolkit consumers can continue using the old macro paths temporarily, but new usage should move to the canonical names above.
+- The canonical docs, examples, and Storybook surfaces now teach `Link action`, `Link icon`, and `Link skip`.
+
 ### 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`.
+1. Remove any `spritePath` prop from `Icon` usage and any `spritePath` field from `Card` icon configuration objects.
+2. Adopt the new public React `LinkAction`, `LinkIcon`, and `LinkSkip` components where you want React parity for the link family.
+3. Prefer the canonical toolkit macro paths and macro names when touching existing templates.
+4. Re-run manual QA for keyboard and focus behavior, especially for `LinkSkip`, `LinkIcon`, and any icon-bearing surfaces such as `Icon`, `Select`, and `Card`.
 
 #### React example
 
-**Before:**
+**New in `react-v0.9.0`:**
 
 ```tsx
-<Icon name="Search" spritePath="/assets/icons/icon-sprite.svg" />
-
-<Card
-  icon={{
-    name: 'Search',
-    spritePath: '/assets/icons/icon-sprite.svg',
-  }}
-/>
+import {
+  LinkAction,
+  LinkIcon,
+  LinkSkip,
+} from '@ourfuturehealth/react-components';
 ```
 
-**After:**
+### Toolkit reminder
 
-```tsx
-<Icon name="Search" />
+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`.
 
-<Card
-  icon={{
-    name: 'Search',
-  }}
-/>
-```
+#### Toolkit example
 
-If an application previously passed `spritePath` in React, that prop should now be removed.
+**Before (`toolkit-v4.9.0`):**
 
-### Toolkit reminder
+```njk
+{% from "components/action-link/macro.njk" import actionLink %}
+{% from "components/back-link/macro.njk" import backLink %}
+{% from "components/skip-link/macro.njk" import skipLink %}
+```
 
-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`.
+**After (`toolkit-v4.10.0`):**
+
+```njk
+{% from "components/link-action/macro.njk" import linkAction %}
+{% from "components/link-icon/macro.njk" import linkIcon %}
+{% from "components/link-skip/macro.njk" import linkSkip %}
+```
 
 ## Upgrading to v4.9.0 / React v0.7.0
 

docs/installation/installing-with-npm.md

@@ -104,7 +104,7 @@ You can also import toolkit layers individually:
 
 ```scss
 @import '@ourfuturehealth/toolkit/core/all';
-@import '@ourfuturehealth/toolkit/components/action-link/action-link';
+@import '@ourfuturehealth/toolkit/components/link-action/link-action';
 ```
 
 ## Importing JavaScript
@@ -138,7 +138,7 @@ import Details from '@ourfuturehealth/toolkit/components/details/details';
 import ErrorSummary from '@ourfuturehealth/toolkit/components/error-summary/error-summary';
 import Header from '@ourfuturehealth/toolkit/components/header/header';
 import Radios from '@ourfuturehealth/toolkit/components/radios/radios';
-import SkipLink from '@ourfuturehealth/toolkit/components/skip-link/skip-link';
+import LinkSkip from '@ourfuturehealth/toolkit/components/link-skip/link-skip';
 import '@ourfuturehealth/toolkit/polyfills';
 
 document.addEventListener('DOMContentLoaded', () => {
@@ -148,7 +148,7 @@ document.addEventListener('DOMContentLoaded', () => {
   ErrorSummary();
   Header();
   Radios();
-  SkipLink();
+  LinkSkip();
 });
 ```
 

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

@@ -23,7 +23,7 @@ This prompt assumes the implementation phase already included the main template'
 I'm working on the `[ComponentName]` update in this worktree.
 
 Context:
-- Ticket: `[JIRA URL or ID]`
+- Ticket: `[JIRA URL or ID]` (preserve the full Jira key exactly, for example `DSE-335`, not a shortened `DS-335`)
 - Intended base branch: `[origin/main or another branch/PR]`
 - Local site/docs server: `[http://localhost:8080]`
 - Local Storybook server: `[http://localhost:6006]`
@@ -57,12 +57,16 @@ Workflow I want you to follow:
    - 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:
+6. Check public API, token conformance, 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
+   - do a final token conformance pass for every public surface changed in this review unit, even if the ticket was not framed as a token migration
+   - verify typography, spacing, icon sizing, and state-color tokens against the Figma token map used during implementation
+   - do not treat inherited global styles as acceptable by default; confirm whether any inherited `a`, `p`, `ul`, `li`, `h*`, or body styles are intentional
+   - if the rendered result only matches Figma because of accidental inheritance, treat that as a merge-readiness failure and fix it
    - 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 for every affected releasable package:
@@ -125,6 +129,8 @@ Workflow I want you to follow:
      - 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
+     - when linking Jira tickets, preserve the exact key and use the full browse URL, for example `https://ourfuturehealth.atlassian.net/browse/DSE-335`
+     - never silently shorten or rewrite Jira keys when drafting PR metadata
 14. Do not push. Give me the exact `git push` command(s) to run manually.
 
 Important constraints:
@@ -136,6 +142,7 @@ Important constraints:
 - 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 rely on lint, tests, or build checks to prove token correctness; they only confirm mechanical health, not design-token conformance.
 - 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.

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

@@ -196,6 +196,33 @@ Compare Figma ↔ Toolkit ↔ React:
 - React API simplification opportunities where toolkit-style class or macro APIs could become clearer semantic props
 - Documentation gaps
 
+### 5a. Token Alignment Report (MANDATORY OUTPUT BEFORE IMPLEMENTATION)
+
+Before you change code, produce a short token-alignment report for every public subcomponent or public variant surface being updated.
+
+For each surface, list at minimum:
+
+- typography token(s) used in Figma
+- spacing token(s) used in Figma, including icon gaps and invisible hit-area spacing
+- icon size token(s) used in Figma
+- color tokens used for default, hover, focus, active, disabled, and visited states where applicable
+- whether each token is expected to be static or responsive
+- the current code primitive used today
+- whether that current code primitive is correct, incorrect, or inherited implicitly
+
+Format the report as:
+
+- `aligned`
+- `must fix before QA`
+- `acceptable inherited behavior`
+
+Rules:
+
+- Do not treat implicit inheritance from global `a`, `p`, `ul`, `li`, `h*`, or page/body styles as aligned unless you explicitly verified that Figma intends the component to inherit that token rather than declare it itself.
+- If Figma defines an explicit component typography or spacing token and the implementation only reaches that value by accident through global inheritance, treat that as `must fix before QA`.
+- If a component has multiple public surfaces in one review unit, do not stop after auditing only the primary one.
+- Do not move to implementation summary or manual QA handoff until every `must fix before QA` item is either fixed or explicitly escalated to the user as intentional follow-up scope.
+
 ### 6. Design Token & Pattern Alignment (MANDATORY)
 
 **This step is REQUIRED, not optional. Do not skip even if the JIRA ticket is narrow in scope.**
@@ -223,6 +250,7 @@ Review the entire component implementation against design system standards:
   - Hover states change correct properties (color, background, border)
   - Active states are visually distinct from focus states
 - [ ] **Document design spec vs. code discrepancies** before any implementation
+- [ ] **Produce the Token Alignment Report** described above and keep it updated as you implement
 
 **Design Tokens Audit:**
 
@@ -242,6 +270,9 @@ Review the entire component implementation against design system standards:
 - [ ] Audit semantic-element inheritance:
   - check whether global `ul > li`, `p`, `h*`, or link styles are adding margins/typography the component did not ask for
   - add explicit overrides when Figma requires component-specific spacing or typography
+- [ ] Audit inherited state colors:
+  - check whether focus/active/visited colors are coming from generic global link styling rather than the component spec
+  - if the first visible state in Figma uses a different token from the default inherited link token, implement that component-level override explicitly
 - [ ] Audit shared-primitives inheritance:
   - check whether reused primitives such as labels, hints, error messages, form groups, or wrappers are contributing margins, gaps, or typography that compound with the component's own layout rules
   - verify the computed browser output, not just the source SCSS intent

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

@@ -46,21 +46,28 @@ Workflow I want you to follow:
    - the exact reason those values are expected, not just a vague design note
    - the exact element/class I should inspect in DevTools when visual validation is not enough
    - any shared primitive or layout-object classes whose computed margins/gaps should also be inspected because they might still be affecting the rendered result
-4. Then walk me through that QA script one step at a time.
-5. After each step, stop and wait for my response in the format:
+4. Before giving me QA steps, give me a concise agent-side token conformance summary for the review unit:
+   - each public component surface reviewed
+   - typography token status
+   - spacing/icon-gap token status
+   - state-color token status
+   - any inherited-style overrides added or still missing
+   - whether there are any remaining MUST FIX token mismatches
+5. Then walk me through that QA script one step at a time.
+6. After each step, stop and wait for my response in the format:
    - `pass`
    - `fail - ...`
    - `other - ...`
-6. Treat `other` as feedback for refinement, missing demo clarity, missing docs clarity, Storybook demo issues, or follow-up questions.
-7. If I report `other` or `fail`, make the necessary code/story/docs refinements, run the required targeted checks, then resume the same QA step.
-8. Keep going until all QA steps pass.
-9. Once all QA is validated on my side, summarize:
+7. Treat `other` as feedback for refinement, missing demo clarity, missing docs clarity, Storybook demo issues, or follow-up questions.
+8. If I report `other` or `fail`, make the necessary code/story/docs refinements, run the required targeted checks, then resume the same QA step.
+9. Keep going until all QA steps pass.
+10. Once all QA is validated on my side, summarize:
    - what was validated
    - any fixes made during QA
    - whether any temporary internal adapter or dependency workaround was introduced during implementation
    - any residual risks or follow-ups
    - whether the branch is ready for the PR-readiness prompt
-10. Do not create final commits or PR text unless I explicitly ask for that in this session.
+11. Do not create final commits or PR text unless I explicitly ask for that in this session.
 
 Important constraints:
 - Run `npm test` after modifying JavaScript or TypeScript files.
@@ -71,6 +78,7 @@ Important constraints:
 - Treat raw JSON controls for stable nested props as implementation misses when the story could reasonably offer clearer text/select/boolean controls instead.
 - Treat controls for values the component visibly ignores or overrides as implementation misses to be fixed before QA is considered complete.
 - Treat responsive token mismatches or accidental inherited element styles (`p`, `ul`, `li`, `h*`, `a`) as implementation misses to be fixed before QA is considered complete.
+- Treat missing explicit component-level typography, spacing, or state-color tokens as implementation misses when the current appearance only works because of inherited global styles.
 - Treat spacing or typography contributed by reused shared primitives or layout objects (`label`, `hint`, `error-message`, `fieldset`, `form-group`, list wrappers, etc.) as implementation misses when they make the rendered output diverge from Figma.
 - Treat React components that depend on toolkit progressive-enhancement classes such as `.js-enabled` for core interactive behavior as implementation misses to be fixed before QA is considered complete.
 - Treat Storybook docs-page examples that share effective IDs or form names across stories and interfere with each other as implementation misses to be fixed before QA is considered complete.