Skip to content

Commit eea87fb

Browse files
romaricpascalromaricpascal
committed
Warn if people are trying to use applied colours variable to configure GOV.UK Frontend
Log a deprecation warning if, when importing `_colours-functional.scss` one of the legacy variables for applied colour is already defined. It needs a little extra care for when the file is imported multiple times. Not through users doing multiple `@import` explicitely, but because our components, objects and core files, may `@import` files from settings, helpers and tools. This leads to `_colours-functional.scss` getting evaluated multiple times, and its subsequent imports seeing the legacy applied colour variables already defined.
1 parent 7626fcb commit eea87fb

File tree

2 files changed

+100
-21
lines changed

2 files changed

+100
-21
lines changed

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

Lines changed: 38 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -55,30 +55,51 @@ $_govuk-functional-colours: _govuk-define-functional-colours(
5555
// Legacy variables
5656
//
5757
// To help migrate to `govuk-functional-colour`, we're keeping the variables
58-
// which were previously storing the applied colours. This should reduce
58+
// which were previously storing the functional colours. This should reduce
5959
// breakage as teams upgrade
6060
// =============================================================================
6161

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);
6283
/// Brand colour
6384
///
6485
/// @type Colour
6586
/// @access public
6687
/// @deprecated
6788
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
6889
/// function instead: `govuk-functional-colour(brand)`.
69-
7090
$govuk-brand-colour: govuk-functional-colour(brand);
7191

92+
@include deprecate-applied-colour-variable(text);
7293
/// Text colour
7394
///
7495
/// @type Colour
7596
/// @access public
7697
/// @deprecated
7798
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
7899
/// function instead: `govuk-functional-colour(text)`.
79-
80100
$govuk-text-colour: govuk-functional-colour(text);
81101

102+
@include deprecate-applied-colour-variable(template-background);
82103
/// Template background colour
83104
///
84105
/// Used by components that want to give the illusion of extending
@@ -89,19 +110,19 @@ $govuk-text-colour: govuk-functional-colour(text);
89110
/// @deprecated
90111
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
91112
/// function instead: `govuk-functional-colour(template-background)`.
92-
93113
$govuk-template-background-colour: govuk-functional-colour(template-background);
94114

115+
@include deprecate-applied-colour-variable(body-background);
95116
/// Body background colour
96117
///
97118
/// @type Colour
98119
/// @access public
99120
/// @deprecated
100121
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
101122
/// function instead: `govuk-functional-colour(body-background)`.
102-
103123
$govuk-body-background-colour: govuk-functional-colour(body-background);
104124

125+
@include deprecate-applied-colour-variable(print-text);
105126
/// Text colour for print media
106127
///
107128
/// Use 'true black' to avoid printers using colour ink to print body text
@@ -111,9 +132,9 @@ $govuk-body-background-colour: govuk-functional-colour(body-background);
111132
/// @deprecated
112133
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
113134
/// function instead: `govuk-functional-colour(print-text)`.
114-
115135
$govuk-print-text-colour: govuk-functional-colour(print-text);
116136

137+
@include deprecate-applied-colour-variable(secondary-text);
117138
/// Secondary text colour
118139
///
119140
/// Used in for example 'muted' text and help text.
@@ -123,9 +144,9 @@ $govuk-print-text-colour: govuk-functional-colour(print-text);
123144
/// @deprecated
124145
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
125146
/// function instead: `govuk-functional-colour(secondary-text)`.
126-
127147
$govuk-secondary-text-colour: govuk-functional-colour(secondary-text);
128148

149+
@include deprecate-applied-colour-variable(focus);
129150
/// Focus colour
130151
///
131152
/// Used for outline (and background, where appropriate) when interactive
@@ -136,9 +157,9 @@ $govuk-secondary-text-colour: govuk-functional-colour(secondary-text);
136157
/// @deprecated
137158
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
138159
/// function instead: `govuk-functional-colour(focus)`.
139-
140160
$govuk-focus-colour: govuk-functional-colour(focus);
141161

162+
@include deprecate-applied-colour-variable(focus-text);
142163
/// Focused text colour
143164
///
144165
/// Ensure that the contrast between the text and background colour passes
@@ -149,9 +170,9 @@ $govuk-focus-colour: govuk-functional-colour(focus);
149170
/// @deprecated
150171
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
151172
/// function instead: `govuk-functional-colour(focus-text)`.
152-
153173
$govuk-focus-text-colour: govuk-functional-colour(focus-text);
154174

175+
@include deprecate-applied-colour-variable(error);
155176
/// Error colour
156177
///
157178
/// Used to highlight error messages and form controls in an error state
@@ -161,9 +182,9 @@ $govuk-focus-text-colour: govuk-functional-colour(focus-text);
161182
/// @deprecated
162183
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
163184
/// function instead: `govuk-functional-colour(error)`.
164-
165185
$govuk-error-colour: govuk-functional-colour(error);
166186

187+
@include deprecate-applied-colour-variable(success);
167188
/// Success colour
168189
///
169190
/// Used to highlight success messages and banners
@@ -173,9 +194,9 @@ $govuk-error-colour: govuk-functional-colour(error);
173194
/// @deprecated
174195
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
175196
/// function instead: `govuk-functional-colour(error)`.
176-
177197
$govuk-success-colour: govuk-functional-colour(success);
178198

199+
@include deprecate-applied-colour-variable(border);
179200
/// Border colour
180201
///
181202
/// Used in for example borders, separators, rules and keylines.
@@ -185,9 +206,9 @@ $govuk-success-colour: govuk-functional-colour(success);
185206
/// @deprecated
186207
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
187208
/// function instead: `govuk-functional-colour(border)`.
188-
189209
$govuk-border-colour: govuk-functional-colour(border);
190210

211+
@include deprecate-applied-colour-variable(input-border);
191212
/// Input border colour
192213
///
193214
/// Used for form inputs and controls
@@ -197,9 +218,9 @@ $govuk-border-colour: govuk-functional-colour(border);
197218
/// @deprecated
198219
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
199220
/// function instead: `govuk-functional-colour(input-border)`.
200-
201221
$govuk-input-border-colour: govuk-functional-colour(input-border);
202222

223+
@include deprecate-applied-colour-variable(hover);
203224
/// Input hover colour
204225
///
205226
/// Used for hover states on form controls
@@ -209,47 +230,46 @@ $govuk-input-border-colour: govuk-functional-colour(input-border);
209230
/// @deprecated
210231
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
211232
/// function instead: `govuk-functional-colour(hover)`.
212-
213233
$govuk-hover-colour: govuk-functional-colour(hover);
214234

235+
@include deprecate-applied-colour-variable(link);
215236
/// Link colour
216237
///
217238
/// @type Colour
218239
/// @access public
219240
/// @deprecated
220241
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
221242
/// function instead: `govuk-functional-colour(link)`.
222-
223243
$govuk-link-colour: govuk-functional-colour(link);
224244

245+
@include deprecate-applied-colour-variable(link-visited);
225246
/// Visited link colour
226247
///
227248
/// @type Colour
228249
/// @access public
229250
/// @deprecated
230251
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
231252
/// function instead: `govuk-functional-colour(link-visited)`.
232-
233253
$govuk-link-visited-colour: govuk-functional-colour(link-visited);
234254

255+
@include deprecate-applied-colour-variable(link-hover);
235256
/// Link hover colour
236257
///
237258
/// @type Colour
238259
/// @access public
239260
/// @deprecated
240261
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
241262
/// function instead: `govuk-functional-colour(link-hover)`.
242-
243263
$govuk-link-hover-colour: govuk-functional-colour(link-hover);
244264

265+
@include deprecate-applied-colour-variable(link-active);
245266
/// Active link colour
246267
///
247268
/// @type Colour
248269
/// @access public
249270
/// @deprecated
250271
/// Variables for applied colours are deprecated. Please use the `govuk-functional-colour`
251272
/// function instead: `govuk-functional-colour(link-active)`.
252-
253273
$govuk-link-active-colour: govuk-functional-colour(link-active);
254274

255275
// =============================================================================

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

Lines changed: 62 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,19 @@ describe('Functional colours', () => {
141141
})
142142

143143
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+
144157
describe.each([
145158
'brand',
146159
'text',
@@ -157,8 +170,8 @@ describe('Functional colours', () => {
157170
'link',
158171
'link-visited',
159172
'link-hover',
160-
'link-active',
161-
])("$govuk-%s-colour", (functionalColourName) => {
173+
'link-active'
174+
])('$govuk-%s-colour', (functionalColourName) => {
162175
it('sets a Sass variable with the functional colour value', async () => {
163176
const sass = `
164177
@import "settings/colours-functional";
@@ -168,10 +181,56 @@ describe('Functional colours', () => {
168181
}
169182
`
170183

171-
const { css } = await compileSassString(sass)
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+
)
172192

173193
expect(css).toContain(`result: true;`)
174194
})
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+
})
175234
})
176235
})
177236
})

0 commit comments

Comments
 (0)