[NO-TICKET] Sass to CSS migration guide (#2355)

* Noticed a code-only mismatch in how we described these examples

Doesn't affect users, but it confused me for a moment which section was which

* Working on a new migration page for Sass to CSS

* Working on the first section more

* Moar writing. Might want to give ds-content its own page

* Finished this migration page

* Give `ds-content` its own page

* Add link to the new migration guide in the blog post

* Close the gap between page header and page content when there are no links

* Make fixes according to feedback

packages/docs/content/blog/release-6.0.mdx

@@ -19,17 +19,17 @@ Previously we had two options for teams consuming our design system styles: CSS
   <img src={scssToCssImg} alt="Sass to CSS" className="ds-u-display--inline-block" height="100" />
 </div>
 
-With this move, [as we mentioned in our previous blog post](https://design.cms.gov/blog/?theme=core#sasscss-changes), we've decided to stop distributing a Sass version of our stylesheets in our npm package, but we are still providing Sass files with the Sass versions of all our theme variables while teams transition over to using CSS Custom Properties. You can [read about how to use the CSS files and our theme variables](https://design.cms.gov/getting-started/for-developers/) in our getting-started guide for developers.
+With this move, [as we mentioned in our previous blog post](/blog/#sasscss-changes), we've decided to stop distributing a Sass version of our stylesheets in our npm package, but we are still providing Sass files with the Sass versions of all our theme variables while teams transition over to using CSS Custom Properties. You can [read about how to use the CSS files and our theme variables](/getting-started/for-developers/) in our getting-started guide for developers. If you're currently using Sass, we've put together a more detailed [Sass to CSS migration guide for you](/migration-guides/sass-to-css/).
 
 ### New masked fields and automatic SSN obfuscation
 
-When we created the [single-input date field](https://design.cms.gov/components/date-field/single-input-date-field/) a while back, we introduced a new masking pattern called the [label-mask](https://design.cms.gov/components/text-field/label-masked-field/). Now that we've been using it internally for a few months, we've decided to open it up for use as a drop-in replacement for our old [input-mask](https://design.cms.gov/components/text-field/input-masked-field/) pattern. The label-mask now supports every feature that the old input-mask supported, with the additional improvement that the Social Security Number (SSN) field now automatically obfuscates the SSN when the input doesn't have focus by only showing the last four digits.
+When we created the [single-input date field](/components/date-field/single-input-date-field/) a while back, we introduced a new masking pattern called the [label-mask](/components/text-field/label-masked-field/). Now that we've been using it internally for a few months, we've decided to open it up for use as a drop-in replacement for our old [input-mask](/components/text-field/input-masked-field/) pattern. The label-mask now supports every feature that the old input-mask supported, with the additional improvement that the Social Security Number (SSN) field now automatically obfuscates the SSN when the input doesn't have focus by only showing the last four digits.
 
 <div className="ds-u-measure--wide ds-u-text-align--center">
   <img src={ssnInput} alt="Animated screen capture of inputting a Social Security Number using the new label-mask pattern" className="ds-u-display--inline-block" />
 </div>
 
-Hiding the SSN is previously something application teams had to implement themselves to use the SSN field and maintain their users' privacy. You can [read more about the label-mask pattern](https://design.cms.gov/components/text-field/label-masked-field/)—what it is and why we built it—on the new documentation page.
+Hiding the SSN is previously something application teams had to implement themselves to use the SSN field and maintain their users' privacy. You can [read more about the label-mask pattern](/components/text-field/label-masked-field/)—what it is and why we built it—on the new documentation page.
 
 ### Sunsetting InVision DSM
 
@@ -54,15 +54,15 @@ In our [3.6.0 release](https://github.com/CMSgov/design-system/releases/tag/%40c
   <img src={swatches} alt="Color ramps from the 'System Color Tokens' page, showing a range of light to dark shades of a color" className="ds-u-display--inline-block" width="400" />
 </div>
 
-In this release we've added a page to the design system to show all color tokens in an easy-to-read and scannable way. We're exposing this base set of tokens to better highlight the design decisions made within a particular theme. Think of them as [a complete box of crayons](https://design.cms.gov/foundation/system-color-tokens/?theme=core). Our themes make use of certain colors from the crayon box but not all of them.
+In this release we've added a page to the design system to show all color tokens in an easy-to-read and scannable way. We're exposing this base set of tokens to better highlight the design decisions made within a particular theme. Think of them as [a complete box of crayons](/foundation/system-color-tokens/). Our themes make use of certain colors from the crayon box but not all of them.
 
 ### Streamlining the ZIP Code design pattern
 
 We dove deep into a dozen CMS, HealthCare, and Medicare products, and what we discovered was truly eye-opening. We found a wide range of design patterns used for ZIP code input fields, but we also found some commonalities that can lead to a more efficient and user-friendly experience.
 
 Some products used a 5-digit ZIP code pattern, others used a 9-digit ZIP code pattern for stricter data validation. We also discovered services using an autocomplete feature for users to confirm their geo-location.
 
-ZIP codes are an important part of how we search for services and determine eligibility at CMS. Overall, we're thrilled to bring these design insights to the table and excited to see the impact they'll have on our user's experiences. [ZIP code pattern guidance](https://design.cms.gov/patterns/zip-codes/?theme=core).
+ZIP codes are an important part of how we search for services and determine eligibility at CMS. Overall, we're thrilled to bring these design insights to the table and excited to see the impact they'll have on our user's experiences. [See ZIP code pattern guidance](/patterns/zip-codes/).
 
 ### Sketch layer order
 

packages/docs/content/foundation/typography/content.mdx

@@ -0,0 +1,16 @@
+---
+title: Content
+order: 0
+intro: The "ds-content" class provides an easy way to style written content on your page
+core:
+  githubLink: design-system/src/styles/_base.scss
+---
+
+For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels, we have a special `ds-content` CSS class. Applying this class to an element that surrounds your content will automatically apply design system heading styles to the appropriate `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` tags as well as `ol` and `ul` list tags.
+
+## Example
+
+<StorybookExample
+  componentName="content-class"
+  storyId="foundations-typography-headings--content-class"
+/>

packages/docs/content/foundation/typography/headings.mdx

@@ -164,12 +164,7 @@ This is an optional header design.
 
 ### The `ds-content` class
 
-For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels , we have a special `ds-content` CSS class. Applying this class to an element that surrounds your content will automatically apply design system heading styles to the appropriate `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` tags.
-
-<StorybookExample
-  componentName="content-class"
-  storyId="foundations-typography-headings--content-class"
-/>
+For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels, consider using the [`ds-content`](/foundation/typography/content/) class.
 
 ### Responsive typography
 

packages/docs/content/migration-guides/agnostic-typography-classes.mdx

@@ -1,6 +1,6 @@
 ---
 title: Using agnostic typography classes
-order: 40
+order: 90
 ---
 
 In [version 2.5.0](https://github.com/CMSgov/design-system/releases/tag/core-2.5.0), we updated the font size and typography utility classes to make them more flexible. We removed the semantic heading-level references (h1, h2, etc...) from the class names and replaced them with a basic sizing scale (xl, lg, …). Semantic heading levels in an HTML document don't always match the visual hierarchy in designs, so we're no longer pretending they do.

packages/docs/content/migration-guides/migrating-to-new-buttons.mdx

@@ -1,6 +1,6 @@
 ---
 title: Migrating to v4 buttons
-order: 20
+order: 70
 intro: We've created a more consistent, scalable, and themable button framework for the CMS design system.
 ---
 

packages/docs/content/migration-guides/migrating-to-v2.mdx

@@ -1,6 +1,6 @@
 ---
 title: Migrating to v2
-order: 30
+order: 80
 ---
 
 The CMS Design System v2 release introduces several breaking changes, and this migration guide outlines high-level steps to upgrade. See the [release notes](https://github.com/CMSgov/design-system/releases/tag/core-2.0.0) for a detailed list of changes.

packages/docs/content/migration-guides/sass-to-css.mdx

@@ -0,0 +1,113 @@
+---
+title: Sass to CSS
+order: 60
+intro: New features in CSS have allowed us to stop relying on Sass to share design tokens with product teams. We're now only distributing our styles as CSS.
+---
+
+## What we changed and why
+
+Prior to [version 6.0.0](https://github.com/CMSgov/design-system/releases/tag/%40cmsgov%2Fdesign-system%406.0.0), we provided two ways of consuming our design system styles: as [Sass](https://sass-lang.com/) and as CSS. We used to recommend that product teams use our [Sass](https://sass-lang.com/) files because only then would they gain access to our [design tokens](/foundation/theme-colors/) and [theme variables](/components/alert/#styles). However, these three things lead us to reconsider Sass's future in the design system:
+
+1. Sass has a new compiler, but the upgrade path is messy and difficult to synchronize across teams
+2. Having product teams build our Sass source files is exposing them to unnecessary complexity
+3. Features we once relied on Sass for, like [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*), are now available in CSS
+
+We researched and prototyped and eventually [published an RFC](https://github.com/CMSgov/design-system/discussions/2223) proposing that use Sass internally but only distribute the compiled CSS output. We shared our findings with product teams and heard no objections, so we went forward with the change.
+
+## Updating style imports
+
+If you're consuming the design system styles as Sass, you likely have something like this in your project:
+
+```css
+/* Old way of importing design-system styles */
+$font-path: '~@cmsgov/design-system/dist/fonts';
+$image-path: '~@cmsgov/design-system/dist/images';
+@import '@cmsgov/design-system/dist/scss/index';
+
+/* Your styles here */
+```
+
+Due to [limitations with some build systems](/getting-started/for-developers/#with-an-asset-bundler) and the Sass compiler, these `$font-path` and `$image-path` variables were necessary to make sure the bundler knew where to get fonts and images. In the move to CSS, we've made these paths static. It assumes these files exist at a location relative to your CSS bundle.
+
+For best results, we recommend importing our CSS files in the most direct way possible given your particular build system. That could be importing them from within a JavaScript module, creating a `<link>` tag in your HTML, or importing them with a `.css` extension in Sass. Take a look at the [_Including the CSS_](https://design.cms.gov/getting-started/for-developers/#including-the-css) section of our developer docs and [our example projects](https://github.com/CMSgov/design-system/tree/main/examples/) for more info.
+
+Note that if you need your project Sass to evaluate the CSS files as Sass so you can do Sassy things, you'll have to [leave out the `.css` extension](https://sass-lang.com/documentation/at-rules/import#plain-css-imports). However, we have provided alternatives to several things that you might have needed Sass for previously, so be sure to read the sections below.
+
+## What to do about the focus-style mixin
+
+Your project might have previously used our `focus-styles` [mixin](https://sass-lang.com/documentation/at-rules/mixin) to apply design-system focus styles to custom components. In that case, you will want to [use the new focus utility classes](/utilities/focus/) instead. We're no longer distributing any Sass mixins with the design system.
+
+## What to do with instances of `@extends`
+
+It's still possible to use the `@extends` rule to apply design system styles to your own CSS rules if you import our CSS files into one of your Sass files and [leave out the `.css` extension](https://sass-lang.com/documentation/at-rules/import#plain-css-imports); however, you may not need to.
+
+We've introduced a new [`ds-content`](/foundation/typography/content/) CSS class that is useful for styling content that lives in plain HTML elements that aren't decorated with design system classes. For instance, you may have previously done something like this
+
+```css
+h1 {
+  @extend .ds-text-heading--3xl;
+}
+
+h2 {
+  @extend .ds-text-heading--2xl;
+}
+
+/* et cetera */
+```
+
+so you could get design system styling for content like this
+
+```html
+<article>
+  <h1>I'm a page heading</h1>
+  <p>This is a really thoughtful sentence.</p>
+  <h2>I'm a section heading</h2>
+</article>
+```
+
+Now you can style that content without any Sass by applying the `ds-content` class to a parent element of that content (direct or indirect parent does not matter):
+
+```html
+<article class="ds-content">
+  <h1>I'm a page heading</h1>
+  <p>This is a really thoughtful sentence.</p>
+  <h2>I'm a section heading</h2>
+</article>
+```
+
+Note that the mapping of heading styles to semantic heading levels represents what we consider sane defaults and that there may be cases where you want to override a particular heading's styles. In those cases we'd recommend applying one of the [headings classes](/foundation/typography/headings/) to the element.
+
+## Referencing our variables in CSS
+
+Most likely the biggest change you will want to make is referencing our design tokens and theme variables as [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*). We have a section on [using our CSS custom properties](/getting-started/for-developers/#css-custom-properties) in the developer docs, but just note that you don't have to make this transition right away. If you're using the Sass variables, they're still there; they've just moved (see next section). If you were always using CSS, you now have access to our variables in your stylesheets!
+
+## Sass variables are still available
+
+To help teams transition to using CSS custom properties in their own time, we're still providing Sass equivalents of all our variables. The example below shows which files you will need to import from your project Sass.
+
+<ThemeContent neverThemes={['healthcare', 'medicare']}>
+
+```css
+@import '@cmsgov/design-system/dist/scss/core-tokens';
+@import '@cmsgov/design-system/dist/scss/core-component-tokens';
+```
+
+</ThemeContent>
+
+<ThemeContent onlyThemes={['healthcare']}>
+
+```css
+@import '@cmsgov/ds-healthcare-gov/dist/scss/healthcare-tokens';
+@import '@cmsgov/ds-healthcare-gov/dist/scss/healthcare-component-tokens';
+```
+
+</ThemeContent>
+
+<ThemeContent onlyThemes={['medicare']}>
+
+```css
+@import '@cmsgov/ds-medicare-gov/dist/scss/medicare-tokens';
+@import '@cmsgov/ds-medicare-gov/dist/scss/medicare-component-tokens';
+```
+
+</ThemeContent>

packages/docs/content/utilities/focus.mdx

@@ -17,10 +17,10 @@ Use the `.ds-u-focus` utility to conditionally apply focus styles to your compon
 Click or tab into the following example to see this utility in action.
 
 <EmbeddedExample>
-  <FormLabel fieldId="focus-visible" className="ds-u-margin-top--0">
+  <FormLabel fieldId="focus" className="ds-u-margin-top--0">
     Select a color
   </FormLabel>
-  <input type="color" id="focus-visible" name="color-focus-visible" class="ds-u-focus ds-u-radius ds-u-margin-top--1" />
+  <input type="color" id="focus" name="color-focus" class="ds-u-focus ds-u-radius ds-u-margin-top--1" />
 </EmbeddedExample>
 
 **Focus-visible**
@@ -30,10 +30,10 @@ Use the `.ds-u-focus-visible` utility to conditionally apply focus styles to you
 Tab into the following example to see this utility in action.
 
 <EmbeddedExample>
-  <FormLabel fieldId="focus" className="ds-u-margin-top--0">
+  <FormLabel fieldId="focus-visible" className="ds-u-margin-top--0">
     Select another color
   </FormLabel>
-  <input type="color" id="focus" name="color-focus" class="ds-u-focus-visible ds-u-radius ds-u-margin-top--1" />
+  <input type="color" id="focus-visible" name="color-focus-visible" class="ds-u-focus-visible ds-u-radius ds-u-margin-top--1" />
 </EmbeddedExample>
 
 **Focus-within**

packages/docs/src/components/layout/PageHeader.tsx

@@ -3,6 +3,7 @@ import { FrontmatterInterface } from '../../helpers/graphQLTypes';
 import { withPrefix } from 'gatsby';
 import { makeGithubUrl, makeSketchUrl, makeStorybookUrl } from '../../helpers/urlUtils';
 import GithubIcon from '../icons/GithubIcon';
+import classNames from 'classnames';
 
 type PageHeaderProps = {
   frontmatter?: FrontmatterInterface;
@@ -19,39 +20,53 @@ const PageHeader = ({ frontmatter = { title: '' }, theme }: PageHeaderProps) =>
   const ghPath = themeLinks?.githubLink || core?.githubLink || null;
   const sketchId = themeLinks?.sketchLink || null;
   const storyId = themeLinks?.storybookLink || core?.storybookLink || null;
+  const showLinkBar = Boolean(ghPath || sketchId || storyId);
+
+  const headerClassNames = classNames(
+    'ds-u-padding-x--3',
+    'ds-u-sm-padding-x--6',
+    'ds-u-sm-padding-top--2',
+    showLinkBar ? 'ds-u-md-margin-bottom--7' : 'ds-u-md-margin-bottom--3'
+  );
 
   return (
-    <header className="ds-u-padding--3 ds-u-sm-padding-x--6 ds-u-sm-padding-bottom--7 ds-u-sm-padding-top--2">
+    <header className={headerClassNames}>
       <h1 className="ds-text-heading--4xl">{title}</h1>
-      {intro && <p className="ds-u-font-size--lg ds-u-measure--base ds-u-margin-top--1">{intro}</p>}
-      <div>
-        {ghPath && (
-          <a href={makeGithubUrl(`tree/main/packages/${ghPath}`)} className="c-page-header__link">
-            <GithubIcon />
-            Github
-          </a>
-        )}
-        {storyId && (
-          <a href={makeStorybookUrl(storyId, theme)} className="c-page-header__link">
-            <img
-              alt="Storybook logo"
-              src={withPrefix('/images/storybook-icon.png')}
-              className="ds-u-display--inline c-page-header__icon"
-            />
-            Storybook
-          </a>
-        )}
-        {sketchId && (
-          <a href={makeSketchUrl(sketchId, theme)} className="c-page-header__link">
-            <img
-              alt="Sketch logo"
-              src={withPrefix('/images/sketch-icon.png')}
-              className="ds-u-display--inline c-page-header__icon"
-            />
-            Sketch
-          </a>
-        )}
-      </div>
+      {intro && (
+        <p className="ds-u-font-size--lg ds-u-measure--base ds-u-margin-top--1 ds-u-margin-bottom--0">
+          {intro}
+        </p>
+      )}
+      {showLinkBar && (
+        <div className="ds-u-margin-top--1 ds-u-margin-bottom--0">
+          {ghPath && (
+            <a href={makeGithubUrl(`tree/main/packages/${ghPath}`)} className="c-page-header__link">
+              <GithubIcon />
+              Github
+            </a>
+          )}
+          {storyId && (
+            <a href={makeStorybookUrl(storyId, theme)} className="c-page-header__link">
+              <img
+                alt="Storybook logo"
+                src={withPrefix('/images/storybook-icon.png')}
+                className="ds-u-display--inline c-page-header__icon"
+              />
+              Storybook
+            </a>
+          )}
+          {sketchId && (
+            <a href={makeSketchUrl(sketchId, theme)} className="c-page-header__link">
+              <img
+                alt="Sketch logo"
+                src={withPrefix('/images/sketch-icon.png')}
+                className="ds-u-display--inline c-page-header__icon"
+              />
+              Sketch
+            </a>
+          )}
+        </div>
+      )}
     </header>
   );
 };