Merge pull request #3261 from uswds/dw-deprecated

Promote better deprecation communication and compatibility

src/stylesheets/core/_deprecated.scss

@@ -0,0 +1,33 @@
+/*  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.
+
+    Be sure to update notifications.scss.
+
+    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;
+}

src/stylesheets/core/_notifications.scss

@@ -0,0 +1,43 @@
+/*  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
+--------------------------------------------------------------------
+\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`
+--------------------------------------------------------------------\a";
+
+@if $theme-show-notifications {
+  @warn "#{$uswds-notifications}"
+    + "#{$uswds-notification-disable-message}";
+}

src/stylesheets/packages/_required.scss

@@ -15,3 +15,7 @@
 @import "../core/properties";
 @import "../core/mixins/all";
 @import "../core/placeholders/all";
+
+// deprecated import needs to be last
+@import "../core/deprecated";
+@import "../core/notifications";

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 updates and notifications.
 ----------------------------------------
 */
 
 $theme-show-compile-warnings: true !default;
+$theme-show-notifications: true !default;
 
 /*
 ----------------------------------------

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 updates and notifications.
 ----------------------------------------
 */
 
 $theme-show-compile-warnings: true;
+$theme-show-notifications: true;
 
 /*
 ----------------------------------------