Skip to content

Commit 12c3e9c

Browse files
romaricpascalromaricpascal
authored
Merge pull request #6437 from alphagov/restore-applied-colour-variables
2 parents e520ab3 + d7cf8e0 commit 12c3e9c

File tree

3 files changed

+318
-0
lines changed

3 files changed

+318
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ If you were using the value of one of the variables in [`settings/_colours-appli
3939
| `$govuk-link-hover-colour` | `govuk-functional-colour(link-hover)` |
4040
| `$govuk-link-active-colour` | `govuk-functional-colour(link-active)` |
4141

42+
Although we've now deprecated the Sass variables, they're still available to make your migration easier.
43+
However, if your code was using the Sass variables to do computations using the [Sass colour API](https://sass-lang.com/documentation/modules/color/), a compilation error will occur. This is because the variables now store a Sass string with a `var()` call, rather than a Sass colour.
44+
4245
#### Use `$govuk-functional-colours` to redefine functional (formerly applied) colours
4346

4447
We've restructured our applied colours in Sass. They are now called functional colours, and we've changed the way you redefine them.

‎packages/govuk-frontend/src/govuk/settings/_colours-functional.scss‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,227 @@ $_govuk-functional-colours: _govuk-define-functional-colours(
5151
)
5252
);
5353

54+
// =============================================================================
55+
// Legacy variables
56+
//
57+
// To help migrate to `govuk-functional-colour`, we're keeping the variables
58+
// which were previously storing the functional colours. This should reduce
59+
// breakage as teams upgrade
60+
// =============================================================================
61+
62+
// Because the file may be imported multiple times,
63+
// subsequent imports will see the legacy variable
64+
// and warn when they shouldn't so we need to track those
65+
$_govuk-deprecated-applied-colour-variables: () !default;
66+
67+
@mixin deprecate-applied-colour-variable($functional-colour-name) {
68+
@if not index($_govuk-deprecated-applied-colour-variables, $functional-colour-name) {
69+
@if variable-exists("govuk-#{$functional-colour-name}-colour") {
70+
$deprecation-message: "Using the \`$govuk-#{$functional-colour-name}-colour\` variable to configure a new value is deprecated. Please use \`$govuk-functional-colours: (#{$functional-colour-name}: <NEW_COLOUR_VALUE>);\`.";
71+
72+
@include _warning("applied-colour-variables", $deprecation-message);
73+
}
74+
75+
$_govuk-deprecated-applied-colour-variables: append(
76+
$_govuk-deprecated-applied-colour-variables,
77+
$functional-colour-name
78+
) !global;
79+
}
80+
}
81+
82+
@include deprecate-applied-colour-variable(brand);
83+
/// Brand colour
84+
///
85+
/// @type Colour
86+
/// @access public
87+
/// @deprecated
88+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
89+
/// function instead: `govuk-functional-colour(brand)`.
90+
$govuk-brand-colour: govuk-functional-colour(brand);
91+
92+
@include deprecate-applied-colour-variable(text);
93+
/// Text colour
94+
///
95+
/// @type Colour
96+
/// @access public
97+
/// @deprecated
98+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
99+
/// function instead: `govuk-functional-colour(text)`.
100+
$govuk-text-colour: govuk-functional-colour(text);
101+
102+
@include deprecate-applied-colour-variable(template-background);
103+
/// Template background colour
104+
///
105+
/// Used by components that want to give the illusion of extending
106+
/// the template background (such as the footer and cookie banner).
107+
///
108+
/// @type Colour
109+
/// @access public
110+
/// @deprecated
111+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
112+
/// function instead: `govuk-functional-colour(template-background)`.
113+
$govuk-template-background-colour: govuk-functional-colour(template-background);
114+
115+
@include deprecate-applied-colour-variable(body-background);
116+
/// Body background colour
117+
///
118+
/// @type Colour
119+
/// @access public
120+
/// @deprecated
121+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
122+
/// function instead: `govuk-functional-colour(body-background)`.
123+
$govuk-body-background-colour: govuk-functional-colour(body-background);
124+
125+
@include deprecate-applied-colour-variable(print-text);
126+
/// Text colour for print media
127+
///
128+
/// Use 'true black' to avoid printers using colour ink to print body text
129+
///
130+
/// @type Colour
131+
/// @access public
132+
/// @deprecated
133+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
134+
/// function instead: `govuk-functional-colour(print-text)`.
135+
$govuk-print-text-colour: govuk-functional-colour(print-text);
136+
137+
@include deprecate-applied-colour-variable(secondary-text);
138+
/// Secondary text colour
139+
///
140+
/// Used in for example 'muted' text and help text.
141+
///
142+
/// @type Colour
143+
/// @access public
144+
/// @deprecated
145+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
146+
/// function instead: `govuk-functional-colour(secondary-text)`.
147+
$govuk-secondary-text-colour: govuk-functional-colour(secondary-text);
148+
149+
@include deprecate-applied-colour-variable(focus);
150+
/// Focus colour
151+
///
152+
/// Used for outline (and background, where appropriate) when interactive
153+
/// elements (links, form controls) have keyboard focus.
154+
///
155+
/// @type Colour
156+
/// @access public
157+
/// @deprecated
158+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
159+
/// function instead: `govuk-functional-colour(focus)`.
160+
$govuk-focus-colour: govuk-functional-colour(focus);
161+
162+
@include deprecate-applied-colour-variable(focus-text);
163+
/// Focused text colour
164+
///
165+
/// Ensure that the contrast between the text and background colour passes
166+
/// WCAG Level AA contrast requirements.
167+
///
168+
/// @type Colour
169+
/// @access public
170+
/// @deprecated
171+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
172+
/// function instead: `govuk-functional-colour(focus-text)`.
173+
$govuk-focus-text-colour: govuk-functional-colour(focus-text);
174+
175+
@include deprecate-applied-colour-variable(error);
176+
/// Error colour
177+
///
178+
/// Used to highlight error messages and form controls in an error state
179+
///
180+
/// @type Colour
181+
/// @access public
182+
/// @deprecated
183+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
184+
/// function instead: `govuk-functional-colour(error)`.
185+
$govuk-error-colour: govuk-functional-colour(error);
186+
187+
@include deprecate-applied-colour-variable(success);
188+
/// Success colour
189+
///
190+
/// Used to highlight success messages and banners
191+
///
192+
/// @type Colour
193+
/// @access public
194+
/// @deprecated
195+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
196+
/// function instead: `govuk-functional-colour(error)`.
197+
$govuk-success-colour: govuk-functional-colour(success);
198+
199+
@include deprecate-applied-colour-variable(border);
200+
/// Border colour
201+
///
202+
/// Used in for example borders, separators, rules and keylines.
203+
///
204+
/// @type Colour
205+
/// @access public
206+
/// @deprecated
207+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
208+
/// function instead: `govuk-functional-colour(border)`.
209+
$govuk-border-colour: govuk-functional-colour(border);
210+
211+
@include deprecate-applied-colour-variable(input-border);
212+
/// Input border colour
213+
///
214+
/// Used for form inputs and controls
215+
///
216+
/// @type Colour
217+
/// @access public
218+
/// @deprecated
219+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
220+
/// function instead: `govuk-functional-colour(input-border)`.
221+
$govuk-input-border-colour: govuk-functional-colour(input-border);
222+
223+
@include deprecate-applied-colour-variable(hover);
224+
/// Input hover colour
225+
///
226+
/// Used for hover states on form controls
227+
///
228+
/// @type Colour
229+
/// @access public
230+
/// @deprecated
231+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
232+
/// function instead: `govuk-functional-colour(hover)`.
233+
$govuk-hover-colour: govuk-functional-colour(hover);
234+
235+
@include deprecate-applied-colour-variable(link);
236+
/// Link colour
237+
///
238+
/// @type Colour
239+
/// @access public
240+
/// @deprecated
241+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
242+
/// function instead: `govuk-functional-colour(link)`.
243+
$govuk-link-colour: govuk-functional-colour(link);
244+
245+
@include deprecate-applied-colour-variable(link-visited);
246+
/// Visited link colour
247+
///
248+
/// @type Colour
249+
/// @access public
250+
/// @deprecated
251+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
252+
/// function instead: `govuk-functional-colour(link-visited)`.
253+
$govuk-link-visited-colour: govuk-functional-colour(link-visited);
254+
255+
@include deprecate-applied-colour-variable(link-hover);
256+
/// Link hover colour
257+
///
258+
/// @type Colour
259+
/// @access public
260+
/// @deprecated
261+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
262+
/// function instead: `govuk-functional-colour(link-hover)`.
263+
$govuk-link-hover-colour: govuk-functional-colour(link-hover);
264+
265+
@include deprecate-applied-colour-variable(link-active);
266+
/// Active link colour
267+
///
268+
/// @type Colour
269+
/// @access public
270+
/// @deprecated
271+
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
272+
/// function instead: `govuk-functional-colour(link-active)`.
273+
$govuk-link-active-colour: govuk-functional-colour(link-active);
274+
54275
// =============================================================================
55276
// Brand refresh
56277
// =============================================================================

‎packages/govuk-frontend/src/govuk/settings/colours.unit.test.js‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,100 @@ describe('Functional colours', () => {
139139
' success, border, input-border, hover, link, link-visited, link-hover, link-active)'
140140
)
141141
})
142+
143+
describe('legacy variables', () => {
144+
let mockWarnFunction
145+
let sassConfig
146+
147+
beforeEach(() => {
148+
mockWarnFunction = jest.fn().mockReturnValue(sassNull)
149+
150+
sassConfig = {
151+
logger: {
152+
warn: mockWarnFunction
153+
}
154+
}
155+
})
156+
157+
describe.each([
158+
'brand',
159+
'text',
160+
'template-background',
161+
'body-background',
162+
'print-text',
163+
'secondary-text',
164+
'focus',
165+
'focus-text',
166+
'error',
167+
'success',
168+
'border',
169+
'input-border',
170+
'link',
171+
'link-visited',
172+
'link-hover',
173+
'link-active'
174+
])('$govuk-%s-colour', (functionalColourName) => {
175+
it('sets a Sass variable with the functional colour value', async () => {
176+
const sass = `
177+
@import "settings/colours-functional";
178+
179+
:root {
180+
result: $govuk-${functionalColourName}-colour == govuk-functional-colour(${functionalColourName});
181+
}
182+
`
183+
184+
const { css } = await compileSassString(sass, sassConfig)
185+
186+
expect(mockWarnFunction).not.toHaveBeenCalledWith(
187+
`Using the \`$govuk-${functionalColourName}-colour\` variable to configure a new value is deprecated.` +
188+
` Please use \`$govuk-functional-colours: (${functionalColourName}: <NEW_COLOUR_VALUE>);\`.` +
189+
' To silence this warning, update $govuk-suppressed-warnings with key: "applied-colour-variables"',
190+
expect.anything()
191+
)
192+
193+
expect(css).toContain(`result: true;`)
194+
})
195+
196+
it('logs a deprecation warning if an applied colour variable was set by the user', async () => {
197+
const sass = `
198+
$govuk-${functionalColourName}-colour: rebeccapurple;
199+
@import "settings/colours-functional";
200+
`
201+
202+
await compileSassString(sass, sassConfig)
203+
204+
// Expect our mocked @warn function to have been called once with a single
205+
// argument, which should be the deprecation notice
206+
expect(mockWarnFunction).toHaveBeenCalledWith(
207+
`Using the \`$govuk-${functionalColourName}-colour\` variable to configure a new value is deprecated.` +
208+
` Please use \`$govuk-functional-colours: (${functionalColourName}: <NEW_COLOUR_VALUE>);\`.` +
209+
' To silence this warning, update $govuk-suppressed-warnings with key: "applied-colour-variables"',
210+
expect.anything()
211+
)
212+
})
213+
214+
// This will likely not happen from users explicitely `@import`ing the file twice (though it could)
215+
// but will happen when importing GOV.UK Frontend as a whole, through object, core or component files
216+
// importing files from settings, helpers or tools
217+
it('does not log a deprecation if the file is imported twice without user configuration', async () => {
218+
const sass = `
219+
@import "settings/colours-functional";
220+
@import "settings/colours-functional";
221+
`
222+
223+
await compileSassString(sass, sassConfig)
224+
225+
// Expect our mocked @warn function to have been called once with a single
226+
// argument, which should be the deprecation notice
227+
expect(mockWarnFunction).not.toHaveBeenCalledWith(
228+
`Using the \`$govuk-${functionalColourName}-colour\` variable to configure a new value is deprecated.` +
229+
` Please use \`$govuk-functional-colours: (${functionalColourName}: <NEW_COLOUR_VALUE>);\`.` +
230+
' To silence this warning, update $govuk-suppressed-warnings with key: "applied-colour-variables"',
231+
expect.anything()
232+
)
233+
})
234+
})
235+
})
142236
})
143237

144238
describe('Organisation colours', () => {

0 commit comments

Comments
 (0)