canopy-v21-migration

Canopy v20 → v21 Migration

When asked to apply this migration, work through each section below in order. After completing all sections, follow the Verification steps at the end.

---

1. Alert / Inline message / Banner / Details / Form Validation: replace variant input with status

What changed: The variant input has been removed from the Alert, Inline message, Banner, Details, and Form Validation components. It has been replaced by the new lgStatus directive, which accepts the same string values. This change aligns these components with a consistent status-signalling API across the library.

Search for (in *.html files):

variant="

Replace with:

status="

Before:

<lg-alert variant="info">
  Content
</lg-alert>

<lg-banner variant="warning">
  Content
</lg-banner>

<lg-details variant="success">
  Content
</lg-details>

After:

<lg-alert status="info">
  Content
</lg-alert>

<lg-banner status="warning">
  Content
</lg-banner>

<lg-details status="success">
  Content
</lg-details>

Also search for property bindings (in *.html files):

[variant]="

Replace with:

[status]="

Also search for any TypeScript component properties named variant that are passed to these components, and check that the binding is updated consistently.

Automated? No — you will need to apply this change manually to each template file that uses these components.

---

2. lgVariant directive: replace with lgColour and lgColourTheme

What changed: The lgVariant directive has been removed entirely and replaced by two new directives: lgColour (sets a colour mode) and lgColourTheme (sets a colour theme). Any element that previously used lgVariant must now use lgColour and lgColourTheme together, following the mapping table below. Where possible, consider replacing lgVariant usages with one of the components that now use lgStatus instead (Alert, Inline message, Banner, Details, Form Validation).

Search for (in *.html files):

lgVariant

Use the following mapping table to determine the correct replacement values:

lgVariant value	lgColour value	lgColourTheme value
error	red	subtle
info	blue	subtle
warning	yellow	subtle
success	green	subtle
generic	blue	neutral-inverse

Before:

<div lgVariant="error">
  Content
</div>

After:

<div lgColour="red" lgColourTheme="subtle">
  Content
</div>

Before:

<div lgVariant="generic">
  Content
</div>

After:

<div lgColour="blue" lgColourTheme="neutral-inverse">
  Content
</div>

Also search *.ts files for any imports or references to LgVariantDirective or lgVariant and remove or replace them with LgColourDirective from the lgColour module.

Automated? No — you will need to apply this change manually, consulting the mapping table above for each occurrence.

---

3. Link CSS variables: rename updated variables and remove deleted ones

What changed: Several CSS custom properties related to link colours have been renamed to follow the new colour-token naming convention. A larger set of status-specific and link-related variables has been removed entirely as they are no longer used by the library. Any direct references to these variables in your project's CSS or SCSS files must be updated or removed.

Renamed variables

Search for each old variable name and replace it with the new one:

Old variable	New variable
--link-color	--link-primary-rest-colour
--link-hover-color	--link-primary-hover-colour
--link-visited-color	--link-primary-visited-colour
--link-active-color	--link-primary-active-colour
--link-focus-color	--link-primary-focus-colour

Search for (in *.css and *.scss files), one at a time:

--link-color
--link-hover-color
--link-visited-color
--link-active-color
--link-focus-color

Removed variables

The following variables have been removed entirely. Search for any references to them in your CSS and SCSS files and remove the declarations or replace them with equivalent tokens from the design system:

--link-active-bg-color
--link-focus-bg-color

--generic-bg-color
--generic-color
--generic-link-color
--generic-link-hover-color
--generic-link-visited-color
--generic-link-active-color
--generic-link-active-bg-color
--generic-link-focus-color
--generic-link-focus-bg-color

--info-bg-color
--info-color
--info-link-color
--info-link-hover-color
--info-link-visited-color
--info-link-active-color
--info-link-active-bg-color
--info-link-focus-color
--info-link-focus-bg-color

--success-bg-color
--success-color
--success-link-color
--success-link-hover-color
--success-link-visited-color
--success-link-active-color
--success-link-active-bg-color
--success-link-focus-color
--success-link-focus-bg-color

--warning-bg-color
--warning-color
--warning-link-color
--warning-link-hover-color
--warning-link-visited-color
--warning-link-active-color
--warning-link-active-bg-color
--warning-link-focus-color
--warning-link-focus-bg-color

--error-bg-color
--error-color
--error-link-color
--error-link-hover-color
--error-link-visited-color
--error-link-active-color
--error-link-active-bg-color
--error-link-focus-color
--error-link-focus-bg-color

Refer to the link component colour modes documentation for the correct replacement tokens.

Automated? No — you will need to search your CSS and SCSS files for each variable listed above and either rename or remove it.

---

4. SCSS imports: remove old paths and add new token paths

What changed: Two SCSS paths have been removed and must be replaced with three new paths. If your project uses SCSS modules, remove any @use or @import references to @legal-and-general/canopy/styles/variants and @legal-and-general/canopy/styles/tokens/colour, and add the three new paths listed below.

Search for (in *.scss files and any global stylesheet configuration, e.g. angular.json):

@legal-and-general/canopy/styles/variants

and:

@legal-and-general/canopy/styles/tokens/colour

Remove both of the above and add all three of the following:

@legal-and-general/canopy/styles/tokens/status.css
@legal-and-general/canopy/styles/tokens/component-themes.css
@legal-and-general/canopy/styles/colour-modes

Also check angular.json for any styles array entries referencing either removed path, and update them to include all three new paths instead.

Before:

@use '@legal-and-general/canopy/styles/variants';
@use '@legal-and-general/canopy/styles/tokens/colour';

After:

@use '@legal-and-general/canopy/styles/tokens/status.css';
@use '@legal-and-general/canopy/styles/tokens/component-themes.css';
@use '@legal-and-general/canopy/styles/colour-modes';

Automated? No — you will need to apply this change manually to each SCSS file (and to angular.json if either path is referenced there).

---

Verification

1. Read the consumer project's package.json scripts field to identify the build and test commands. Common script names include build, compile, type-check, test, and test:ci — use whichever are present.
2. Ask the user to run their build command and confirm there are no TypeScript or compilation errors related to any of the APIs changed above.
3. Ask the user to run their test command and confirm the test suite passes.
4. If errors remain after applying all changes, re-read the relevant section above and check whether the pattern matched all occurrences (e.g. in template .html files as well as .ts files, or across multiple components and angular.json).