From 0e2aab1469acea088d620ae29e8028b56abb9b5f Mon Sep 17 00:00:00 2001 From: Dano Williams Date: Thu, 12 Dec 2019 13:55:20 -0800 Subject: [PATCH 1/5] Add deprecated file for deprecated functionality --- src/stylesheets/core/_deprecated.scss | 31 +++++++++++++++++++++++++ src/stylesheets/packages/_required.scss | 3 +++ 2 files changed, 34 insertions(+) create mode 100644 src/stylesheets/core/_deprecated.scss diff --git a/src/stylesheets/core/_deprecated.scss b/src/stylesheets/core/_deprecated.scss new file mode 100644 index 0000000000..17d294f1ed --- /dev/null +++ b/src/stylesheets/core/_deprecated.scss @@ -0,0 +1,31 @@ +/* deprecated.scss + --- + Occasionally the design system will deprecate + old variables or functionality. If we replace + the old functionality with something new, this is a + place to connect the old functionality to the + new functionality, in the service of better + continuity and backwards compatibility within a + major release cycle. + + Note the USWDS version where we deprecated the + old functionality in a comment. + + This file should started fresh at each + major version. +*/ + +// Deprecated in 2.2.0 +$theme-navigation-width: $theme-header-min-width; +$theme-megamenu-logo-text-width: $theme-header-logo-text-width; + +// Deprecated in 2.0.2 +$theme-title-font-size: $theme-display-font-size; + +@mixin title { + @include display; +} + +@mixin typeset-title { + @include typeset-display; +} diff --git a/src/stylesheets/packages/_required.scss b/src/stylesheets/packages/_required.scss index 1806e63083..afda5f3bd7 100644 --- a/src/stylesheets/packages/_required.scss +++ b/src/stylesheets/packages/_required.scss @@ -15,3 +15,6 @@ @import "../core/properties"; @import "../core/mixins/all"; @import "../core/placeholders/all"; + +// deprecated import needs to be last +@import "../core/deprecated"; From 7cd180f4757e1827ac3039c925fdab1707180488 Mon Sep 17 00:00:00 2001 From: Dano Williams Date: Thu, 12 Dec 2019 14:24:30 -0800 Subject: [PATCH 2/5] Add a dreprecation warning and a way to hide it --- src/stylesheets/core/_deprecated.scss | 21 +++++++++++++++++++ .../settings/_settings-general.scss | 3 +++ .../theme/_uswds-theme-general.scss | 3 +++ 3 files changed, 27 insertions(+) diff --git a/src/stylesheets/core/_deprecated.scss b/src/stylesheets/core/_deprecated.scss index 17d294f1ed..0452574032 100644 --- a/src/stylesheets/core/_deprecated.scss +++ b/src/stylesheets/core/_deprecated.scss @@ -11,10 +11,31 @@ Note the USWDS version where we deprecated the old functionality in a comment. + Add the deprecation to the warning. + This file should started fresh at each major version. */ +@if $theme-show-deprecation-warnings { + @warn "\a" + + "--------------------------------------------------------------------\a" + + "Deprecated in USWDS 2.x\a" + + "--------------------------------------------------------------------\a" + + "2.2.0\a" + + "$theme-navigation-width \2192 $theme-header-min-width\a" + + "$theme-megamenu-logo-text-width \2192 $theme-header-logo-text-width\a" + + "--------------------------------------------------------------------\a" + + "2.0.2\a" + + "$theme-title-font-size \2192 $theme-display-font-size\a" + + "@include title \2192 @include display\a" + + "@include typeset-title \2192 @include typeset-display\a" + + "--------------------------------------------------------------------\a" + + "Disable this message using \a" + + "$theme-show-deprecation-warnings: false\a" + + "--------------------------------------------------------------------\a"; +} + // Deprecated in 2.2.0 $theme-navigation-width: $theme-header-min-width; $theme-megamenu-logo-text-width: $theme-header-logo-text-width; diff --git a/src/stylesheets/settings/_settings-general.scss b/src/stylesheets/settings/_settings-general.scss index 0ea22c0bf6..a66e5ca507 100644 --- a/src/stylesheets/settings/_settings-general.scss +++ b/src/stylesheets/settings/_settings-general.scss @@ -33,10 +33,13 @@ Show compile warnings ---------------------------------------- Show Sass warnings when functions and mixins use non-standard tokens. +AND +Show deprecation notifications. ---------------------------------------- */ $theme-show-compile-warnings: true !default; +$theme-show-deprecation-warnings: true !default; /* ---------------------------------------- diff --git a/src/stylesheets/theme/_uswds-theme-general.scss b/src/stylesheets/theme/_uswds-theme-general.scss index 8684968b79..3a0172f5cb 100644 --- a/src/stylesheets/theme/_uswds-theme-general.scss +++ b/src/stylesheets/theme/_uswds-theme-general.scss @@ -33,10 +33,13 @@ Show compile warnings ---------------------------------------- Show Sass warnings when functions and mixins use non-standard tokens. +AND +Show deprecation notifications. ---------------------------------------- */ $theme-show-compile-warnings: true; +$theme-show-deprecation-warnings: true; /* ---------------------------------------- From 5ef89de2d7325ec68d49ddbbe65f715e61e580a7 Mon Sep 17 00:00:00 2001 From: Dano Williams Date: Thu, 12 Dec 2019 15:12:45 -0800 Subject: [PATCH 3/5] Generalize to notifications and split into separate files --- src/stylesheets/core/_deprecated.scss | 26 ++++++------------- src/stylesheets/core/_notifications.scss | 19 ++++++++++++++ src/stylesheets/packages/_required.scss | 1 + .../settings/_settings-general.scss | 4 +-- .../theme/_uswds-theme-general.scss | 4 +-- 5 files changed, 32 insertions(+), 22 deletions(-) create mode 100644 src/stylesheets/core/_notifications.scss diff --git a/src/stylesheets/core/_deprecated.scss b/src/stylesheets/core/_deprecated.scss index 0452574032..810b8d7d54 100644 --- a/src/stylesheets/core/_deprecated.scss +++ b/src/stylesheets/core/_deprecated.scss @@ -17,24 +17,14 @@ major version. */ -@if $theme-show-deprecation-warnings { - @warn "\a" - + "--------------------------------------------------------------------\a" - + "Deprecated in USWDS 2.x\a" - + "--------------------------------------------------------------------\a" - + "2.2.0\a" - + "$theme-navigation-width \2192 $theme-header-min-width\a" - + "$theme-megamenu-logo-text-width \2192 $theme-header-logo-text-width\a" - + "--------------------------------------------------------------------\a" - + "2.0.2\a" - + "$theme-title-font-size \2192 $theme-display-font-size\a" - + "@include title \2192 @include display\a" - + "@include typeset-title \2192 @include typeset-display\a" - + "--------------------------------------------------------------------\a" - + "Disable this message using \a" - + "$theme-show-deprecation-warnings: false\a" - + "--------------------------------------------------------------------\a"; -} +$uswds-deprecation-warnings: "\a"+ "--------------------------------------------------------------------\a"+ + "Deprecated in USWDS 2.x\a"+ "--------------------------------------------------------------------\a"+ + "2.2.0\a"+ "$theme-navigation-width \2192 $theme-header-min-width\a"+ + "$theme-megamenu-logo-text-width \2192 $theme-header-logo-text-width\a"+ "--------------------------------------------------------------------\a"+ + "2.0.2\a"+ "$theme-title-font-size \2192 $theme-display-font-size\a"+ + "@include title \2192 @include display\a"+ "@include typeset-title \2192 @include typeset-display\a"+ + "--------------------------------------------------------------------\a"+ "Disable this message using \a"+ + "$theme-show-deprecation-warnings: false\a"+ "--------------------------------------------------------------------\a"; // Deprecated in 2.2.0 $theme-navigation-width: $theme-header-min-width; diff --git a/src/stylesheets/core/_notifications.scss b/src/stylesheets/core/_notifications.scss new file mode 100644 index 0000000000..3c0b46f5c1 --- /dev/null +++ b/src/stylesheets/core/_notifications.scss @@ -0,0 +1,19 @@ +/* notifications.scss + --- + Adds a notification at the top of each USWDS + compile. Use this file for important notifications + and updates to the design system. + + This file should started fresh at each + major version. + +*/ + +$uswds-notifications: "\a"+ "--------------------------------------------------------------------\a"+ + "USWDS Notifications\a"+ "--------------------------------------------------------------------\a"+ + 'Please make sure you\'re importing the components settings in \a your Sass entry point (often styles.scss) using something like \a `@import "uswds-theme-components"` \a'; + +@if $theme-show-notifications { + @warn "#{$uswds-notifications}" + + "#{$uswds-deprecation-warnings}"; +} diff --git a/src/stylesheets/packages/_required.scss b/src/stylesheets/packages/_required.scss index afda5f3bd7..ad13ffea28 100644 --- a/src/stylesheets/packages/_required.scss +++ b/src/stylesheets/packages/_required.scss @@ -18,3 +18,4 @@ // deprecated import needs to be last @import "../core/deprecated"; +@import "../core/notifications"; diff --git a/src/stylesheets/settings/_settings-general.scss b/src/stylesheets/settings/_settings-general.scss index a66e5ca507..6203db47fb 100644 --- a/src/stylesheets/settings/_settings-general.scss +++ b/src/stylesheets/settings/_settings-general.scss @@ -34,12 +34,12 @@ Show compile warnings Show Sass warnings when functions and mixins use non-standard tokens. AND -Show deprecation notifications. +Show updates and notifications. ---------------------------------------- */ $theme-show-compile-warnings: true !default; -$theme-show-deprecation-warnings: true !default; +$theme-show-notifications: true !default; /* ---------------------------------------- diff --git a/src/stylesheets/theme/_uswds-theme-general.scss b/src/stylesheets/theme/_uswds-theme-general.scss index 3a0172f5cb..d99ffcc940 100644 --- a/src/stylesheets/theme/_uswds-theme-general.scss +++ b/src/stylesheets/theme/_uswds-theme-general.scss @@ -34,12 +34,12 @@ Show compile warnings Show Sass warnings when functions and mixins use non-standard tokens. AND -Show deprecation notifications. +Show updates and notifications. ---------------------------------------- */ $theme-show-compile-warnings: true; -$theme-show-deprecation-warnings: true; +$theme-show-notifications: true; /* ---------------------------------------- From 7b716c693ca2f4f0bb190103e5884b571a47fdb2 Mon Sep 17 00:00:00 2001 From: Dano Williams Date: Thu, 12 Dec 2019 15:43:35 -0800 Subject: [PATCH 4/5] Improve language --- src/stylesheets/core/_deprecated.scss | 11 +-------- src/stylesheets/core/_notifications.scss | 30 ++++++++++++++++++++---- 2 files changed, 27 insertions(+), 14 deletions(-) diff --git a/src/stylesheets/core/_deprecated.scss b/src/stylesheets/core/_deprecated.scss index 810b8d7d54..5e3ef5132a 100644 --- a/src/stylesheets/core/_deprecated.scss +++ b/src/stylesheets/core/_deprecated.scss @@ -11,21 +11,12 @@ Note the USWDS version where we deprecated the old functionality in a comment. - Add the deprecation to the warning. + Be sure to update notifications.scss. This file should started fresh at each major version. */ -$uswds-deprecation-warnings: "\a"+ "--------------------------------------------------------------------\a"+ - "Deprecated in USWDS 2.x\a"+ "--------------------------------------------------------------------\a"+ - "2.2.0\a"+ "$theme-navigation-width \2192 $theme-header-min-width\a"+ - "$theme-megamenu-logo-text-width \2192 $theme-header-logo-text-width\a"+ "--------------------------------------------------------------------\a"+ - "2.0.2\a"+ "$theme-title-font-size \2192 $theme-display-font-size\a"+ - "@include title \2192 @include display\a"+ "@include typeset-title \2192 @include typeset-display\a"+ - "--------------------------------------------------------------------\a"+ "Disable this message using \a"+ - "$theme-show-deprecation-warnings: false\a"+ "--------------------------------------------------------------------\a"; - // Deprecated in 2.2.0 $theme-navigation-width: $theme-header-min-width; $theme-megamenu-logo-text-width: $theme-header-logo-text-width; diff --git a/src/stylesheets/core/_notifications.scss b/src/stylesheets/core/_notifications.scss index 3c0b46f5c1..c292083d52 100644 --- a/src/stylesheets/core/_notifications.scss +++ b/src/stylesheets/core/_notifications.scss @@ -9,11 +9,33 @@ */ -$uswds-notifications: "\a"+ "--------------------------------------------------------------------\a"+ - "USWDS Notifications\a"+ "--------------------------------------------------------------------\a"+ - 'Please make sure you\'re importing the components settings in \a your Sass entry point (often styles.scss) using something like \a `@import "uswds-theme-components"` \a'; +$uswds-notifications: " +-------------------------------------------------------------------- +\2709 USWDS Notifications +-------------------------------------------------------------------- +2.4.0: If your component settings aren't working as expected, make +sure you're importing the components settings in your Sass entry +point (often styles.scss) with `@import \"uswds-theme-components\"`. +A bug in 2.0 omitted that import. +-------------------------------------------------------------------- +2.2.0: We changed the names of some settings. +$theme-navigation-width \2192 $theme-header-min-width +$theme-megamenu-logo-text-width \2192 $theme-header-logo-text-width +-------------------------------------------------------------------- +2.0.2: We changed the names of some settings and mixins. +$theme-title-font-size \2192 $theme-display-font-size +@include title \2192 @include display +@include typeset-title \2192 @include typeset-display"; + +$uswds-notification-disable-message: " +-------------------------------------------------------------------- +These are notifications from the USWDS team, not necessarily a +problem with your code. + +Disable notifications using $theme-show-notifications: false +--------------------------------------------------------------------"; @if $theme-show-notifications { @warn "#{$uswds-notifications}" - + "#{$uswds-deprecation-warnings}"; + + "#{$uswds-notification-disable-message}"; } From a561e181663fa34bc764f0024977702aebda1b3a Mon Sep 17 00:00:00 2001 From: Dano Williams Date: Fri, 13 Dec 2019 13:18:04 -0800 Subject: [PATCH 5/5] Improve copy and display of notification text --- src/stylesheets/core/_notifications.scss | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/stylesheets/core/_notifications.scss b/src/stylesheets/core/_notifications.scss index c292083d52..50fced8e84 100644 --- a/src/stylesheets/core/_notifications.scss +++ b/src/stylesheets/core/_notifications.scss @@ -9,7 +9,7 @@ */ -$uswds-notifications: " +$uswds-notifications: "\a -------------------------------------------------------------------- \2709 USWDS Notifications -------------------------------------------------------------------- @@ -19,21 +19,23 @@ point (often styles.scss) with `@import \"uswds-theme-components\"`. A bug in 2.0 omitted that import. -------------------------------------------------------------------- 2.2.0: We changed the names of some settings. -$theme-navigation-width \2192 $theme-header-min-width -$theme-megamenu-logo-text-width \2192 $theme-header-logo-text-width + +- $theme-navigation-width \2192 $theme-header-min-width +- $theme-megamenu-logo-text-width \2192 $theme-header-logo-text-width -------------------------------------------------------------------- 2.0.2: We changed the names of some settings and mixins. -$theme-title-font-size \2192 $theme-display-font-size -@include title \2192 @include display -@include typeset-title \2192 @include typeset-display"; + +- $theme-title-font-size \2192 $theme-display-font-size +- @include title \2192 @include display +- @include typeset-title \2192 @include typeset-display"; $uswds-notification-disable-message: " -------------------------------------------------------------------- These are notifications from the USWDS team, not necessarily a problem with your code. -Disable notifications using $theme-show-notifications: false ---------------------------------------------------------------------"; +Disable notifications using `$theme-show-notifications: false` +--------------------------------------------------------------------\a"; @if $theme-show-notifications { @warn "#{$uswds-notifications}"