From 07305e2d2b4815c98b21be8c23f0bf8f2677b029 Mon Sep 17 00:00:00 2001
From: Jami Gibbs <jami.gibbs@adhocteam.us>
Date: Tue, 7 Nov 2023 11:04:26 -0600
Subject: [PATCH] add utilities stylesheet and claryifing notes

---
 packages/formation/sass/core.scss             |  41 +--
 .../sass/formation-overrides/_variables.scss  |  15 +-
 .../formation-overrides/core/_utilities.scss  | 258 ++++++++++++++++++
 .../elements/_buttons.scss                    |   3 +
 .../elements/_typography.scss                 |   3 +
 5 files changed, 288 insertions(+), 32 deletions(-)
 create mode 100644 packages/formation/sass/formation-overrides/core/_utilities.scss

diff --git a/packages/formation/sass/core.scss b/packages/formation/sass/core.scss
index 576768ebb4..c17b9715ee 100644
--- a/packages/formation/sass/core.scss
+++ b/packages/formation/sass/core.scss
@@ -2,9 +2,9 @@
 // Note: if you add variable files in here, make sure you updated shared-variables.scss
 
 //============ VENDOR PARTIALS ==============//
-@import '~uswds/src/stylesheets/lib/bourbon';
-@import '~uswds/src/stylesheets/lib/neat';
-@import '~uswds/src/stylesheets/lib/normalize'; // Currently 3.0.3
+@import '~uswds/src/stylesheets/lib/bourbon'; // [x]
+@import '~uswds/src/stylesheets/lib/neat'; // [x]
+@import '~uswds/src/stylesheets/lib/normalize'; // Currently 3.0.3 // [x]
 
 @import '~foundation-sites/scss/foundation/components/grid';  // [x]
 @import '~foundation-sites/scss/foundation/components/block-grid';  // [x]
@@ -17,7 +17,7 @@
 // ============ SETTINGS ============//
 // Order matters here! Please don't change it.
 // @import '~uswds/src/stylesheets/core/variables'; // [x]
-@import 'formation-overrides/variables';
+@import 'formation-overrides/variables'; // [x]
 
 // A VA partial. Here so that we can override the
 // USWDS breakpoint and grid variables from above before
@@ -25,31 +25,32 @@
 @import 'base/b-variables'; // [x]
 @import 'base/b-breakpoints'; // [x]
 
-@import '~uswds/src/stylesheets/core/fonts';
-@import '~uswds/src/stylesheets/core/grid';
-@import '~uswds/src/stylesheets/core/utilities';
+@import '~uswds/src/stylesheets/core/fonts'; // [x]
+@import '~uswds/src/stylesheets/core/grid'; // [x]
+// @import '~uswds/src/stylesheets/core/utilities'; // [x]
+@import 'formation-overrides/core/utilities'; // [x]
 
 // VA mixins. Here so that we can override USWDS mixins.
 // Specifically, the "focus" mixin.
-@import 'base/b-mixins';
+@import 'base/b-mixins'; // [x]
 
-@import '~uswds/src/stylesheets/core/base';
+@import '~uswds/src/stylesheets/core/base'; // [x]
 
 // ---- U.S. WEB DESIGN STANDARDS ELEMENTS/COMPONENTS --- //
 // @import '~uswds/src/stylesheets/elements/buttons'; // [x]
 @import 'formation-overrides/elements/buttons'; // [x]
-@import '~uswds/src/stylesheets/elements/inputs'; // [ ]
-@import '~uswds/src/stylesheets/elements/labels'; // [ ]
-@import '~uswds/src/stylesheets/elements/list'; // [ ]
-@import '~uswds/src/stylesheets/elements/table'; // [ ]
+@import '~uswds/src/stylesheets/elements/inputs';
+@import '~uswds/src/stylesheets/elements/labels';
+@import '~uswds/src/stylesheets/elements/list';
+@import '~uswds/src/stylesheets/elements/table';
 // @import '~uswds/src/stylesheets/elements/typography'; // [x]
-@import 'formation-overrides/elements/typography'; // [ ]
-@import '~uswds/src/stylesheets/components/accordions'; // [ ]
-@import '~uswds/src/stylesheets/components/alerts'; // [ ]
-@import '~uswds/src/stylesheets/components/forms'; // [ ]
-@import '~uswds/src/stylesheets/components/sidenav'; // [ ]
-@import '~uswds/src/stylesheets/components/media-block'; // [ ]
-@import '~uswds/src/stylesheets/components/banner'; // [ ]
+@import 'formation-overrides/elements/typography'; // [x]
+@import '~uswds/src/stylesheets/components/accordions';
+@import '~uswds/src/stylesheets/components/alerts';
+@import '~uswds/src/stylesheets/components/forms';
+@import '~uswds/src/stylesheets/components/sidenav';
+@import '~uswds/src/stylesheets/components/media-block';
+@import '~uswds/src/stylesheets/components/banner';
 
 // ----- VA BASE (VARIABLES/HELPERS) ---- //
 @import 'base/b-element-overrides';
diff --git a/packages/formation/sass/formation-overrides/_variables.scss b/packages/formation/sass/formation-overrides/_variables.scss
index bed97770a7..5263ca863c 100644
--- a/packages/formation/sass/formation-overrides/_variables.scss
+++ b/packages/formation/sass/formation-overrides/_variables.scss
@@ -1,17 +1,8 @@
 @import '../override-function';
 
-// These variables drive almost every aspect of the U.S. Web Design
-// system. Every variable is declared as !default so that it can be
-// overridden by a previous import.
-//
-// XXX Do not modify this file!
-//
-// If you want to override a variable, set that variable in one of your
-// own partials, then @import '{path/to/uswds/}core/variables'.
-
-// Typography
-// Removing the !default from $em-base so we are not inheriting that
-// value from Bourbon.
+// This is a copy of the entire ~uswds/src/stylesheets/core/variables.scss file
+// so that we can convert the rem values for USWDS v3.
+
 $em-base:             10px;
 $base-font-size:      scale-rem(1.7rem) !default;
 $small-font-size:     scale-rem(1.4rem) !default;
diff --git a/packages/formation/sass/formation-overrides/core/_utilities.scss b/packages/formation/sass/formation-overrides/core/_utilities.scss
new file mode 100644
index 0000000000..3e133a2c70
--- /dev/null
+++ b/packages/formation/sass/formation-overrides/core/_utilities.scss
@@ -0,0 +1,258 @@
+// This is a copy of the entire ~uswds/src/stylesheets/core/utilities file
+// so that we can convert the rem values for USWDS v3.
+
+@import '../../override-function';
+
+
+// Heading mixins
+@mixin title {
+  font-size: $title-font-size;
+  font-weight: $font-bold;
+}
+
+@mixin h1 {
+  font-size: $h1-font-size;
+  font-weight: $font-bold;
+}
+
+@mixin h2 {
+  font-size: $h2-font-size;
+  font-weight: $font-bold;
+}
+
+@mixin h3 {
+  font-size: $h3-font-size;
+  font-weight: $font-bold;
+}
+
+@mixin h4 {
+  font-size: $h4-font-size;
+  font-weight: $font-bold;
+}
+
+@mixin h5 {
+  font-size: $h5-font-size;
+  font-weight: $font-bold;
+}
+
+@mixin h6 {
+  font-size: $h6-font-size;
+  font-weight: $font-normal;
+  line-height: $base-line-height;
+  text-transform: uppercase;
+}
+
+// Focus state mixin
+@mixin focus {
+  outline: $focus-outline;
+  outline-offset: $focus-spacing;
+}
+
+// Mobile-first media query helper
+@mixin media($bp) {
+  @media screen and (min-width: #{$bp}) {
+    @content;
+  }
+}
+
+// Screen reader only helper
+@mixin sr-only() {
+  position: absolute;
+  left: -999em;
+}
+
+// This "negates" the sr-only() helper; useful if
+// we want the default state of something to be
+// for screen readers only, but we want to force
+// it to show for sighted users under more specific
+// conditions.
+@mixin not-sr-only() {
+  position: static;
+}
+
+.usa-sr-only {
+  @include sr-only();
+}
+
+// Aria hidden helper
+@mixin accessibly-hidden() {
+  &[aria-hidden=true] {
+    display: none;
+  }
+}
+
+// Unstyled list helper
+@mixin unstyled-list() {
+  @include margin(0 null);
+  list-style-type: none;
+  padding-left: 0;
+
+  > li {
+    margin-bottom: 0;
+  }
+}
+
+// Font smoothing mixin
+// Only use for light text on dark background
+// TODO: Remove after adding PostCSS
+@mixin font-smoothing {
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+}
+
+// Content size helpers
+@mixin allow-layout-classes {
+  @include margin(null auto);
+
+  &.width-one-half {
+    @include media($medium-screen) {
+      width: 50%;
+    }
+  }
+
+  &.width-one-third {
+    @include media($medium-screen) {
+      width: 33%;
+    }
+  }
+
+  &.width-two-thirds {
+    @include media($medium-screen) {
+      width: 67%;
+    }
+  }
+
+  &.width-one-fourth {
+    @include media($medium-screen) {
+      width: 25%;
+    }
+  }
+
+  &.width-three-fourths {
+    @include media($medium-screen) {
+      width: 75%;
+    }
+  }
+
+  &.align-left {
+    @include media($medium-screen) {
+      float: left;
+      margin-right: 2em;
+      margin-top: 0.5em;
+    }
+  }
+
+  &.align-right {
+    @include media($medium-screen) {
+      float: right;
+      margin-left: 2em;
+      margin-top: 0.5em;
+    }
+  }
+}
+
+@mixin display-icon($icon, $direction, $size, $margin, $hover) {
+  &::#{$direction} {
+    background-image: url('#{$image-path}/#{$icon}.png');
+    background-image: url('#{$image-path}/#{$icon}.svg');
+    background-size: 100%;
+    content: '';
+    display: inline-block;
+    height: $size;
+    width: $size;
+
+    /* stylelint-disable block-closing-brace-newline-after, at-rule-empty-line-before */
+    @if $direction == 'after' {
+      margin-left: $margin;
+    } @else {
+      margin-right: $margin;
+    }
+    /* stylelint-enable */
+  }
+
+  @if $hover == 'hover' {
+    &:hover::#{$direction} {
+      background-image: url('#{$image-path}/#{$icon}-hover.png');
+      background-image: url('#{$image-path}/#{$icon}-hover.svg');
+    }
+  }
+}
+
+@mixin usa-sidenav-list {
+  @include unstyled-list();
+
+  > li {
+    background-color: transparent;
+    border-top: 1px solid $color-gray;
+    font-size: $h4-font-size;
+
+    &:first-child {
+      border-top: none;
+    }
+  }
+
+  a {
+    border: none;
+    color: $color-base;
+    display: block;
+    font-family: $font-sans;
+    line-height: 1.3;
+    padding: scale-rule(0.85rem 1rem 0.85rem $site-margins-mobile);
+    text-decoration: none;
+
+    &:hover {
+      background-color: $color-gray-lightest;
+      color: $color-primary;
+      text-decoration: none;
+    }
+
+    &:focus {
+      outline-offset: 0;
+      position: relative;
+      z-index: 1;
+    }
+
+    &.usa-current { /* stylelint-disable-line selector-no-qualifying-type */
+      border-left: $sidenav-current-border-width solid $color-primary;
+      color: $color-primary;
+      font-weight: $font-bold;
+      padding-left: $site-margins-mobile - $sidenav-current-border-width;
+    }
+  }
+}
+
+@mixin usa-sidenav-sublist {
+  @include unstyled-list();
+  margin: 0;
+  width: 100%;
+
+  li {
+    border: none;
+    font-size: $h5-font-size;
+  }
+
+  a {
+    padding-left: scale-rem(2.8rem);
+    line-height: $heading-line-height;
+
+    &:hover,
+    &.usa-current { /* stylelint-disable-line selector-no-qualifying-type */
+      border: none;
+      padding-left: scale-rem(2.8rem);
+    }
+  }
+
+  .usa-sidenav-sub_list {
+    a {
+      padding-left: scale-rem(3.8rem);
+
+      &:focus {
+        outline-offset: 0;
+      }
+
+      &:hover {
+        padding-left: scale-rem(3.8rem);
+      }
+    }
+  }
+}
diff --git a/packages/formation/sass/formation-overrides/elements/_buttons.scss b/packages/formation/sass/formation-overrides/elements/_buttons.scss
index 7a8755b6e7..b96ed69202 100644
--- a/packages/formation/sass/formation-overrides/elements/_buttons.scss
+++ b/packages/formation/sass/formation-overrides/elements/_buttons.scss
@@ -1,3 +1,6 @@
+// This is a copy of the entire ~uswds/src/stylesheets/elements/buttons.scss file
+// so that we can convert the rem values for USWDS v3.
+
 @import '../../override-function';
 
 // Buttons variables
diff --git a/packages/formation/sass/formation-overrides/elements/_typography.scss b/packages/formation/sass/formation-overrides/elements/_typography.scss
index c2e33fe1ba..82cdea21a7 100644
--- a/packages/formation/sass/formation-overrides/elements/_typography.scss
+++ b/packages/formation/sass/formation-overrides/elements/_typography.scss
@@ -1,3 +1,6 @@
+// This is a copy of the entire ~ uswds/src/stylesheets/elements/typography.scss file
+// so that we can convert the rem values for USWDS v3.
+
 html {
   font-family: $font-sans;
   font-size: $em-base;