[NO-TICKET] Improve heading documentation (#2825)

* Crosslink doc pages in `ds-content` page

* Add some explanatory text about heading levels plus an alert about margins

* Rewrite it after getting some feedback

* Add a note about headings to the v7 spacing updates guide

* Include a code example

* Avoid scrolling of the code example on large screens

* Fix alert body content bleeding out of bounds

* Get rid of p tag around pre, which is invalid

* Redo: Drop this line so we don't have to scroll on large screens

* Move the alert down to the code section

* Stop using deprecated classes in the examples

* Don't have an example where we show multiple h1s on the same page

* Don't have an example of a form element without form fields

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

@@ -6,7 +6,7 @@ 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.
+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 (see [Headings](/foundation/typography/headings)) as well as `ol` and `ul` list tags (see [Lists](/foundation/typography/lists)).
 
 ## Example
 

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

@@ -38,7 +38,7 @@ Sans-serifs have been proven to be easier to read on-screen and are incredibly a
 
 </ThemeContent>
 
-The design system doesn't style base HTML typography elements (like `h1`, `h2`, `p`, etc) in order to avoid conflicting with any existing site styles.
+The design system doesn't style base HTML typography elements (like `h1`, `h2`, `p`, etc) unless they're inside an element with the [ds-content class](/foundation/typography/content). Instead, it provides heading classes (available on this page) corresponding to visual sizes. These classes can be applied to any heading elements, irrespective of their semantic heading level (`h1` to `h6`). This approach allows teams to first choose the semantic heading level that make the most sense for the document and its accessibility and then choose a visual heading size class that fits the page's visual hierarchy.
 
 ## Examples
 
@@ -163,6 +163,25 @@ This is an optional header design.
 
 ## Code
 
+<Alert variation="warn" heading="First and last children">
+
+  The design system heading styles have alternate margins for headings that are the first or last child of their parent element. Headings that are the first child have no top margin, and headings that are last children have no bottom margin. Some examples of what we mean:
+
+  ```html
+    <main>
+      <h1>I'm the first child of my parent.</h1>
+      <h2>I'm not the first child of my parent</h2>
+      <div>
+        <h2>I'm actually the first child of my parent even
+          though I'm not the first heading on the page</h2>
+        <h2>I'm the last child of my parent</h2>
+      </div>
+      <h2>I'm also the last child of my parent</h2>
+    </main>
+  ```
+
+</Alert>
+
 ### 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, consider using the [`ds-content`](/foundation/typography/content/) class.

packages/docs/content/migration-guides/v7-spacing-updates.mdx

@@ -43,6 +43,8 @@ If the gap below these components disappears in your application when upgrading,
 
 </Alert>
 
+Note that headings were not included in this spacing update.
+
 ## Example of margin collapsing and stacking
 
 While margin collapse is an understandable concept, it is prone to producing unexpected results, especially when translating from designs to code. Consider the following annotated screenshot which shows the default spacing between a sample of components in the previous version:

packages/docs/content/utilities/flexbox.mdx

@@ -150,11 +150,11 @@ Use the `align-items` utility class on a flexbox container to change the alignme
         class="ds-u-align-items--start ds-u-display--flex ds-u-padding--1 ds-u-border--1"
         style="height: 100px"
       >
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--small">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--sm">
           start
         </div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lead">start</div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--h3">start</div>
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lg">start</div>
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--xl">start</div>
       </article>
     </div>
     <div class="ds-u-margin-bottom--2">
@@ -163,9 +163,9 @@ Use the `align-items` utility class on a flexbox container to change the alignme
         class="ds-u-align-items--end ds-u-display--flex ds-u-padding--1 ds-u-border--1"
         style="height: 100px"
       >
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--small">end</div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lead">end</div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--h3">end</div>
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--sm">end</div>
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lg">end</div>
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--xl">end</div>
       </article>
     </div>
     <div class="ds-u-margin-bottom--2">
@@ -174,13 +174,13 @@ Use the `align-items` utility class on a flexbox container to change the alignme
         class="ds-u-align-items--center ds-u-display--flex ds-u-padding--1 ds-u-border--1"
         style="height: 100px"
       >
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--small">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--sm">
           center
         </div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lead">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lg">
           center
         </div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--h3">center</div>
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--xl">center</div>
       </article>
     </div>
     <div class="ds-u-margin-bottom--2">
@@ -189,13 +189,13 @@ Use the `align-items` utility class on a flexbox container to change the alignme
         class="ds-u-align-items--baseline ds-u-display--flex ds-u-padding--1 ds-u-border--1"
         style="height: 100px"
       >
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--small">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--sm">
           baseline
         </div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lead">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lg">
           baseline
         </div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--h3">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--xl">
           baseline
         </div>
       </article>
@@ -206,13 +206,13 @@ Use the `align-items` utility class on a flexbox container to change the alignme
         class="ds-u-align-items--stretch ds-u-display--flex ds-u-padding--1 ds-u-border--1"
         style="height: 100px"
       >
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--small">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--sm">
           stretch
         </div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lead">
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--lg">
           stretch
         </div>
-        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--h3">stretch</div>
+        <div class="utility-example ds-u-padding--1 ds-u-margin--1 ds-u-font-size--xl">stretch</div>
       </article>
     </div>
   </section>

packages/docs/src/components/content/ResponsiveExample.tsx

@@ -110,7 +110,7 @@ const ResponsiveExample = ({ storyId, title, theme }: ResponsiveExample) => {
                 onClick={() => setIframeBreakpoint(breakpointName)}
               >
                 <strong>{breakpointName}</strong>
-                <div className="ds-u-font-size--small">Width: {breakpoints[breakpointName]}</div>
+                <div className="ds-u-font-size--sm">Width: {breakpoints[breakpointName]}</div>
               </button>
             </li>
           ))}