fix: a11y: heading elements usage and ordering (#1220)

* changes settings page title to h1

* changes sites & applications page title to h1

* changes documentation page title to h1

* changes my space  title to h1

* adjusting header order on page to use h2s for what was using h3s before because it was cuasing my space and other layouts to have a skip in the heading order

* adjusts more widgets to use h2 instead of h3

* adds back styling for welcome, name

* styles widget headers to be bold and the correct font size

* corrects spacing in my space area to account for widget header style changes

* ensuring styles match for lower level headings with what is in Figma designs and accounts for visual look of being off center in weather widget due to degree symbol having elevated bseline and low visual weight

* edits styling around header usage in weather widget

* adjusts footer syntax to use h2s instead of h3s so to not break heading order

* turns h3 on news page that is not a header to a p

* turns h3 on internal news page that is not a header to a p

* fixes heading order on about page

* changes display name preview to not use h2 element

* edits sites & apps test to account for collections having a heading level of 2

* edits custom collection test to account for collections having a heading level of 2

* edits my space test to account for collections having a heading level of 2

* edits collection test to account for collections having a heading level of 2

* edits editable collection test to account for collections having a heading level of 2

* changes the way the page title is searched for in the error layout test to prevent the test from picking up the h2s in the footer

* edits news item test to account for change to news component structure where article titles are now h3s instead of h4s

* changes the way the page title is searched for in the page layout test to prevent the test from picking up the h2s in the footer

* adjusts feedback card test to account for feedback card having an h2

* changes the way the page title is searched for in the article layout test to prevent the test from picking up the h2s in the footer

* adjusts test in sites and applications to look for collections by h2 instead of h3

* adjusts h2 on ussf documentation page to align to styles in figma

* adjusts widget markup in stories file

* adding spacing to personal data

* adds space to top of page header

---------

Co-authored-by: John Gedeon <[email protected]>
Co-authored-by: Jacob Capps <[email protected]>

src/__tests__/pages/index.test.tsx

@@ -105,28 +105,28 @@ describe('Home page', () => {
 
       expect(
         await screen.findByRole('heading', {
-          level: 2,
+          level: 1,
           name: 'My Space',
         })
       ).toBeInTheDocument()
 
       expect(
         await screen.findByRole('heading', {
-          level: 3,
+          level: 2,
           name: 'Example Collection',
         })
       ).toBeInTheDocument()
 
       expect(
         await screen.findByRole('heading', {
-          level: 3,
+          level: 2,
           name: 'Maxed Out Collection',
         })
       ).toBeInTheDocument()
 
       expect(
         await screen.findByRole('heading', {
-          level: 3,
+          level: 2,
           name: 'Recent News',
         })
       ).toBeInTheDocument()

src/__tests__/pages/sites-and-applications.test.tsx

@@ -223,7 +223,7 @@ describe('Sites and Applications page', () => {
           sitesAndAppsMock
         )
 
-        const collections = await screen.findAllByRole('heading', { level: 3 })
+        const collections = await screen.findAllByRole('heading', { level: 2 })
         expect(collections).toHaveLength(mockCMSCollections.length)
         collections.forEach((c, i) => {
           // eslint-disable-next-line security/detect-object-injection
@@ -271,7 +271,7 @@ describe('Sites and Applications page', () => {
         })
         await user.click(sortType)
 
-        expect(screen.queryAllByRole('heading', { level: 3 })).toHaveLength(
+        expect(screen.queryAllByRole('heading', { level: 2 })).toHaveLength(
           mockCMSCollections.length
         )
         expect(screen.queryByRole('table')).not.toBeInTheDocument()

src/components/Collection/Collection.test.tsx

@@ -30,7 +30,7 @@ describe('Collection component', () => {
     })
 
     it('renders a title', () => {
-      const title = screen.getByRole('heading', { level: 3 })
+      const title = screen.getByRole('heading', { level: 2 })
       expect(title).toHaveTextContent('Example collection')
     })
 

src/components/Collection/Collection.tsx

@@ -24,7 +24,7 @@ const Collection = ({
       className={className}
       header={
         <>
-          {title && <h3>{title}</h3>}
+          {title && <h2>{title}</h2>}
           {header}
         </>
       }>

src/components/CustomCollection/CustomCollection.test.tsx

@@ -249,7 +249,7 @@ describe('CustomCollection component', () => {
     expect(screen.getByRole('list')).toBeInTheDocument()
     expect(
       screen.getByRole('heading', {
-        level: 3,
+        level: 2,
       })
     ).toHaveTextContent(exampleCollection.title)
 

src/components/CustomCollection/EditableCollectionTitle.test.tsx

@@ -22,7 +22,7 @@ describe('EditableCollectionTitle component', () => {
     )
 
     expect(
-      screen.getByRole('heading', { level: 3, name: 'Test Collection' })
+      screen.getByRole('heading', { level: 2, name: 'Test Collection' })
     ).toBeInTheDocument()
   })
 

src/components/CustomCollection/EditableCollectionTitle.tsx

@@ -77,7 +77,7 @@ export const EditableCollectionTitle = ({
           </ButtonGroup>
         </Form>
       ) : (
-        <h3 className={styles.collectionTitle}>{text}</h3>
+        <h2 className={styles.collectionTitle}>{text}</h2>
       )}
     </div>
   )

src/components/EditDisplayName/EditDisplayName.module.scss

@@ -1,8 +1,11 @@
 @use 'uswds-core' as *;
 @use 'styles/sfds/index.scss' as *;
 .updateNameAndRank {
-  h2 {
+  p {
     text-transform: uppercase;
+    font-family: $sfds-heading-font;
+    font-weight: bold;
+    font-size: 1.5rem;
   }
 
   label > strong {

src/components/EditDisplayName/EditDisplayName.tsx

@@ -36,7 +36,7 @@ const EditDisplayName = ({
       <Grid col="fill">
         <div className={styles.updateNameAndRank}>
           <label htmlFor="something">Current welcome display title:</label>
-          <h2>{greeting}</h2>
+          <p>{greeting}</p>
 
           <label htmlFor="displayName">
             Update display name <strong aria-hidden="true">*</strong>

src/components/FeedbackCard/FeedbackCard.test.tsx

@@ -16,7 +16,7 @@ describe('Feedback Card component', () => {
     render(<FeedbackCard />)
 
     expect(
-      screen.getByRole('heading', { level: 3, name: 'Got Feedback?' })
+      screen.getByRole('heading', { level: 2, name: 'Got Feedback?' })
     ).toBeInTheDocument()
     expect(
       screen.getByRole('link', { name: '[email protected]' })

src/components/FeedbackCard/FeedbackCard.tsx

@@ -10,7 +10,7 @@ const FeedbackCard = () => {
 
   return (
     <div>
-      <h3>Got Feedback?</h3>
+      <h2>Got Feedback?</h2>
       <p>
         We’d love to hear it! Contact us at{' '}
         <a

src/components/Footer/Footer.module.scss

@@ -14,9 +14,9 @@
     padding: 0 0;
   }
 
-  h3 {
+  h2 {
     color: white;
-    margin: 0;
+    margin: 0 0 14px 0;
     font-size: 18px;
   }
 

src/components/Footer/Footer.tsx

@@ -31,7 +31,7 @@ const Footer = () => {
           <Grid row gap col="auto">
             <PortalLogo />
             <Grid col role="navigation" aria-labelledby="portal">
-              <h3 id="portal">Space Force Portal</h3>
+              <h2 id="portal">Space Force Portal</h2>
               <Grid row gap className={styles.miniRow}>
                 <Grid col className={styles.miniCol}>
                   <ul className="usa-list usa-list--unstyled">
@@ -85,7 +85,7 @@ const Footer = () => {
           </Grid>
           <Grid col="auto" className={styles.border}></Grid>
           <Grid col="auto" role="navigation" aria-labelledby="ql">
-            <h3 id="ql">Quick Links</h3>
+            <h2 id="ql">Quick Links</h2>
             <Grid row gap className={styles.miniRow}>
               <Grid col className={styles.miniCol}>
                 <ul className="usa-list usa-list--unstyled">

src/components/GuardianIdeal/GuardianIdealCarousel.module.scss

@@ -8,7 +8,7 @@
   padding: 0 !important;
   background: transparent !important;
 
-  h3 {
+  h2 {
     position: absolute;
     left: -999em;
     right: auto;

src/components/MySpace/MySpace.module.scss

@@ -24,6 +24,5 @@
 
   .featuredShortcuts {
     width: 100%;
-    margin-bottom: 1rem;
   }
 }

src/components/MySpace/MySpace.test.tsx

@@ -72,21 +72,21 @@ describe('My Space Component', () => {
 
       expect(
         await screen.findByRole('heading', {
-          level: 3,
+          level: 2,
           name: 'Example Collection',
         })
       ).toBeInTheDocument()
 
       expect(
         await screen.findByRole('heading', {
-          level: 3,
+          level: 2,
           name: 'Maxed Out Collection',
         })
       ).toBeInTheDocument()
 
       expect(
         await screen.findByRole('heading', {
-          level: 3,
+          level: 2,
           name: 'Recent News',
         })
       ).toBeInTheDocument()

src/components/MySpace/MySpace.tsx

@@ -134,7 +134,7 @@ const MySpace = ({ bookmarks }: { bookmarks: CMSBookmark[] }) => {
   return (
     <div id="skip-announcements-carousel" className={styles.mySpace}>
       <div className={styles.widgetContainer}>
-        <h2 className={styles.pageTitle}>My Space</h2>
+        <h1 className={styles.pageTitle}>My Space</h1>
 
         <DndContext
           sensors={sensors}

src/components/NewsItem/NewsItem.module.scss

@@ -25,8 +25,9 @@ a.articleLink {
     display: inline;
   }
 
-  h4 {
+  h3 {
     margin: 0;
+    font-size: 1rem;
   }
 }
 

src/components/NewsItem/NewsItem.test.tsx

@@ -24,7 +24,7 @@ describe('NewsItem component', () => {
     })
 
     test('renders the article contents', () => {
-      expect(screen.getByRole('heading', { level: 4 })).toHaveTextContent(
+      expect(screen.getByRole('heading', { level: 3 })).toHaveTextContent(
         testArticle.title
       )
       expect(

src/components/NewsItem/NewsItem.tsx

@@ -28,7 +28,7 @@ const NewsItem = ({
         {/* eslint-disable-next-line react/jsx-no-comment-textnodes */}
         <small>{publishDate} //</small>
         &nbsp;
-        <h4>{title}</h4>
+        <h3>{title}</h3>
       </Link>
 
       <p className={styles.articleExcerpt}>

src/components/NewsWidget/NewsWidget.test.tsx

@@ -35,7 +35,7 @@ describe('NewsWidget component', () => {
   test('renders a widget that displays RSS items and a link to the News page', async () => {
     render(<NewsWidget widget={mockNewsWidget} />)
 
-    expect(screen.getByRole('heading', { level: 3 })).toHaveTextContent(
+    expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent(
       'Recent News'
     )
     expect(await screen.findAllByRole('article')).toHaveLength(10)

src/components/PageHeader/PageHeader.module.scss

@@ -2,7 +2,7 @@
 
 .PageHeader {
   color: var(--text);
-  @include u-padding-bottom(4);
+  padding-top: units(1);
 
   h1 {
     text-transform: uppercase;

src/components/PersonalData/PersonalData.module.scss

@@ -2,13 +2,15 @@
 @use 'styles/sfds/index.scss' as *;
 
 .personalData {
-  h2 {
+  p {
+    @include heading-bold;
     margin-bottom: 0;
     text-transform: uppercase;
+    font-size: 1rem;
   }
 
-  h2 + div > nav {
-    padding-top: 0 !important;
+  p + div > nav {
+    padding: 0 !important;
 
     :global(
         ol.usa-breadcrumb__list
@@ -19,6 +21,10 @@
     }
   }
 
+  :global(.usa-breadcrumb__list) {
+    padding-top: 0;
+  }
+
   dt {
     font-family: $sfds-heading-font;
     @include u-line-height('heading', 3);

src/components/PersonalData/PersonalData.test.tsx

@@ -27,7 +27,7 @@ describe('Personal Data component', () => {
     })
 
     test('renders the greeting with a name', () => {
-      const greeting = screen.getByRole('heading', { level: 2 })
+      const greeting = screen.getByTestId('personal-data')
       expect(greeting).toHaveTextContent('Welcome, BERNADETTE CAMPBELL')
     })
 

src/components/PersonalData/PersonalData.tsx

@@ -15,7 +15,7 @@ const PersonalData = ({ userDisplayName }: { userDisplayName: string }) => {
 
   return (
     <div className={styles.personalData}>
-      <h2 data-testid={'personal-data'}>{greeting}</h2>
+      <p data-testid={'personal-data'}>{greeting}</p>
 
       {currentPage != '/settings' && (
         <div>

src/components/SelectableCollection/SelectableCollection.test.tsx

@@ -47,7 +47,7 @@ describe('SelectableCollection component', () => {
     )
 
     expect(screen.getByRole('list')).toBeInTheDocument()
-    expect(screen.getByRole('heading', { level: 3 })).toHaveTextContent(
+    expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent(
       exampleCollection.title
     )
     expect(screen.getAllByRole('listitem')).toHaveLength(

src/components/WeatherWidget/WeatherWidget.module.scss

@@ -25,6 +25,10 @@ $iconsize: 110px;
   display: flex;
   justify-content: flex-start;
   align-items: center;
+  :global(.usa-button--unstyled) {
+    font-family: $sfds-heading-font;
+    font-weight: 500;
+  }
 }
 
 .alertPadding {
@@ -68,7 +72,7 @@ $iconsize: 110px;
       border-right: none;
     }
 
-    > h4 {
+    > h3 {
       font-size: 40px;
       line-height: normal;
       @include heading-bold;
@@ -103,11 +107,17 @@ $iconsize: 110px;
     width: 33%;
     padding: 0.5rem 0;
 
-    > h6 {
+    > h5 {
       padding-top: 0.5rem;
       padding-bottom: 0.25rem;
-      font-size: 22px;
+      font-size: 30px;
+      font-weight: bold;
       line-height: normal;
+      transform: translateX(5px);
+      @media (max-width: 400px) {
+        font-size: 20px;
+        transform: translateX(0px);
+      }
     }
 
     > * {
@@ -116,6 +126,10 @@ $iconsize: 110px;
   }
 }
 
+.section .h4 {
+  font-size: 18px;
+}
+
 .errorContainer {
   display: flex;
   flex-direction: column;