Website: create new content section (#2572)

Author: shleewhite

website/app/components/doc/page/header/index.hbs

@@ -12,6 +12,7 @@
     <ul role="list" aria-labelledby="primary-navigation">
       <Doc::Page::Header::NavItem @label="About" @route="about" @currentTopRoute={{@currentTopRoute}} />
       <Doc::Page::Header::NavItem @label="Foundations" @route="foundations" @currentTopRoute={{@currentTopRoute}} />
+      <Doc::Page::Header::NavItem @label="Content" @route="content" @currentTopRoute={{@currentTopRoute}} />
       <Doc::Page::Header::NavItem @label="Components" @route="components" @currentTopRoute={{@currentTopRoute}} />
       <Doc::Page::Header::NavItem @label="Patterns" @route="patterns" @currentTopRoute={{@currentTopRoute}} />
       <li class="doc-page-header__nav-item-generic doc-page-header__nav-item--split">
@@ -21,24 +22,28 @@
           discover the search results.</div>
         <button
           type="button"
-          class="doc-page-header__search-button"
+          class="doc-page-header__desktop-icon-item"
           data-doc-algolia-search-autocomplete-secondary-trigger
           aria-describedby="search-button"
+          aria-label="Search"
         >
-          <Hds::Icon @name="search" />
-          Search
+          <Hds::Icon @name="search" @size="24" />
         </button>
       </li>
-      <Doc::Page::Header::NavItem
-        @label="Support"
-        @route="show"
-        @model="about/support"
-        @currentTopRoute={{@currentTopRoute}}
-      />
       <li class="doc-page-header__nav-item-generic">
-        <a href="https://github.com/hashicorp/design-system" target="_blank" rel="noopener noreferrer">
+        <LinkTo class="doc-page-header__desktop-icon-item" @route="show" @model="about/support" aria-label="Support">
+          <Hds::Icon @name="help" @size="24" />
+        </LinkTo>
+      </li>
+      <li class="doc-page-header__nav-item-generic">
+        <a
+          href="https://github.com/hashicorp/design-system"
+          target="_blank"
+          rel="noopener noreferrer"
+          class="doc-page-header__desktop-icon-item"
+          aria-label="GitHub"
+        >
           <Hds::Icon @name="github" @size="24" />
-          <span class="doc-sr-only">GitHub</span>
         </a>
       </li>
     </ul>
@@ -49,17 +54,21 @@
       class="doc-page-header__mobile-only-menu-button"
       data-doc-algolia-search-autocomplete-secondary-trigger
       aria-describedby="search-button"
+      aria-label="Search"
     >
-      <Hds::Icon @name="search" />
-      Search
+      <Hds::Icon @name="search" @size="24" />
     </button>
-    <button type="button" class="doc-page-header__mobile-only-menu-button" {{on "click" @onToggleBurgerMenu}}>
+    <button
+      type="button"
+      aria-label="Menu"
+      aria-expanded={{if @isSidebarVisibleOnSmallViewport "true" "false"}}
+      class="doc-page-header__mobile-only-menu-button"
+      {{on "click" @onToggleBurgerMenu}}
+    >
       {{#if @isSidebarVisibleOnSmallViewport}}
-        <Hds::Icon @name="x" />
-        Close
+        <Hds::Icon @name="x" @size="24" />
       {{else}}
-        <Hds::Icon @name="menu" />
-        Menu
+        <Hds::Icon @name="menu" @size="24" />
       {{/if}}
     </button>
   </div>

website/app/components/doc/page/sidebar.hbs

@@ -16,6 +16,9 @@
         <li class="doc-table-of-contents__item doc-table-of-contents__item--depth-2">
           <LinkTo class="doc-table-of-contents__link" @route="foundations">Foundations</LinkTo>
         </li>
+        <li class="doc-table-of-contents__item doc-table-of-contents__item--depth-2">
+          <LinkTo class="doc-table-of-contents__link" @route="content">Content</LinkTo>
+        </li>
         <li class="doc-table-of-contents__item doc-table-of-contents__item--depth-2">
           <LinkTo class="doc-table-of-contents__link" @route="components">Components</LinkTo>
         </li>

website/app/components/doc/page/sidebar.js

@@ -17,6 +17,7 @@ const getTocSectionsBundle = (section) => {
   const ABOUT = ['about', 'whats-new', 'getting-started'];
   const FOUNDATIONS = ['foundations', 'icons'];
   const COMPONENTS = ['components', 'layouts', 'overrides', 'utilities'];
+  const CONTENT = ['content'];
   const PATTERNS = ['patterns'];
   // this will be removed later
   const TESTING = ['testing'];
@@ -29,6 +30,8 @@ const getTocSectionsBundle = (section) => {
     return COMPONENTS;
   } else if (PATTERNS.includes(section)) {
     return PATTERNS;
+  } else if (CONTENT.includes(section)) {
+    return CONTENT;
   } else if (TESTING.includes(section)) {
     return TESTING;
   } else {

website/app/controllers/content.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Controller from '@ember/controller';
+
+export default class ContentController extends Controller {
+  get cards() {
+    // we want to use a flat tree here...
+    const tocTree = this.model.toc.flat;
+    const sections = ['content'];
+    const cards = {};
+    sections.forEach((section) => {
+      cards[section] = tocTree
+        .filter(
+          (page) =>
+            page.pageParents[0] === section &&
+            !page.pageAttributes?.navigation?.hidden
+        )
+        .map((page) => {
+          return {
+            image: page.pageAttributes.previewImage,
+            title:
+              page.pageAttributes?.navigation?.label ||
+              page.pageAttributes.title,
+            caption: page.pageAttributes.caption,
+            status: page.pageAttributes.status,
+            route: 'show',
+            model: page.pageURL,
+          };
+        });
+    });
+    return cards;
+  }
+}

website/app/controllers/index.js

@@ -7,18 +7,18 @@ import Controller from '@ember/controller';
 
 export default class IndexController extends Controller {
   cards = [
-    {
-      title: 'About',
-      description:
-        'Our aims, principles, and strategy and how to get started with Helios.',
-      route: 'about',
-    },
     {
       title: 'Foundations',
       description:
         'Design decisions and guidance for colors, icons, typography, and more.',
       route: 'foundations',
     },
+    {
+      title: 'Content',
+      description:
+        'Structured guidelines on tone and voice, user communication and more.',
+      route: 'content',
+    },
     {
       title: 'Components',
       description:

website/app/router.js

@@ -16,6 +16,7 @@ Router.map(function () {
   this.route('foundations');
   this.route('components');
   this.route('patterns');
+  this.route('content');
 
   this.route('error');
 

website/app/styles/pages/application/header.scss

@@ -113,7 +113,7 @@
 
   a {
     @include doc-font-style-navigation();
-    @include doc-header-custom-focus ();
+    @include doc-header-custom-focus();
     display: flex;
     align-items: center;
     height: 100%;
@@ -139,75 +139,36 @@
   }
 }
 
-.doc-page-header__nav-item-generic {
-  a {
-    display: block;
-    color: var(--doc-color-gray-400);
-
-    &:visited {
-      color: var(--doc-color-gray-400);
-    }
-
-    &:hover {
-      color: var(--doc-color-white);
-    }
-
-    &:focus-visible {
-      border-radius: 3px;
-      outline: 2px solid var(--doc-focus-ring-color);
-    }
-  }
-}
-
 .doc-page-header__nav-item--split {
   margin: 0 0 0 auto;
 }
 
-// "fake" search button (this triggers another button, the "Algolia search" one, which is hidden)
-
-.doc-page-header__search-button {
+.doc-page-header__desktop-icon-item {
   @include doc-font-style-navigation();
-  @include doc-header-custom-focus ();
-  display: flex;
-  gap: 4px;
-  align-items: center;
-  height: 36px;
-  margin: 0;
-  padding: 4px 12px;
+  @include doc-header-custom-focus();
+  display: block;
+  margin: 0 12px;
+  padding: 0;
   color: var(--doc-color-gray-400);
-  background-color: var(--doc-color-gray-100);
-  border: 1px solid var(--doc-color-gray-300);
-  border-radius: 3px;
+  background-color: transparent;
+  border: 1px solid transparent;
   cursor: pointer;
 
-  &:hover {
-    color: var(--doc-color-white);
-  }
-
-  &:focus {
-    border-color: var(--doc-focus-ring-color);
-    outline: 1px solid var(--doc-focus-ring);
-    outline-offset: 0;
-  }
-
   svg {
-    display: block;
-    width: 16px;
-    height: 16px;
-    color: inherit;
+    width: 24px;
+    height: 24px;
+  }
 
-    &:hover { // we need this to avoid overwriting by the `aa-SubmitIcon` class, which is the same classname used in the modal form
-      color: inherit;
-    }
+  &:hover {
+    color: var(--doc-color-white);
   }
 }
 
-
 // "MOBILE" ONLY MENU
 
 .doc-page-header__mobile-only-menu {
   display: flex;
-  gap: 8px;
+  gap: 24px;
   align-items: center;
   align-self: stretch;
   margin: 0 0 0 auto;
@@ -222,16 +183,17 @@
 .doc-page-header__mobile-only-menu-button {
   @include doc-font-style-navigation();
   @include doc-header-custom-focus ();
-  display: flex;
-  gap: 8px;
-  align-items: center;
-  align-self: stretch;
-  padding: 4px 6px;
+  padding: 0;
   color: var(--doc-color-gray-400);
   background-color: transparent;
   border: 1px solid transparent;
   cursor: pointer;
 
+  svg {
+    width: 24px;
+    height: 24px;
+  }
+
   &:hover {
     color: var(--doc-color-white);
   }

website/app/templates/content.hbs

@@ -0,0 +1,13 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+{{page-title "Content"}}
+
+<Doc::Page::Stage>
+  <Doc::Page::Cover @title="Content" />
+  <Doc::Page::Content @breakthrough={{true}}>
+    <Doc::Cards::Deck @cols="4" @cards={{this.cards.content}} />
+  </Doc::Page::Content>
+</Doc::Page::Stage>

website/docs/content/writing-guidelines/index.md

@@ -0,0 +1,30 @@
+---
+title: Writing guidelines
+caption: Consistent language guidelines for components and patterns.
+description: Consistent language guidelines for components and patterns.
+previewImage: assets/illustrations/content/writing-guidelines.jpg
+---
+
+## Date and time
+
+Display dates and times clearly and consistently across products.
+
+### Usage
+
+These formatting options are available in the [Time](/components/time) component. Choose the format most appropriate for your user needs.
+
+- **Relative date**: Displays time in relative terms, e.g., "3 hours ago" or "in 2 days". This format is recommended for recent events, particularly within the past or upcoming week, as it simplifies recognition of time-sensitive actions.
+- **Friendly date**: Provides a user-friendly date and time, e.g., "Sep 5, 2018, 3:30 PM EST". Limit time format to the minute.
+- **Friendly local date**: Converts the date to the user’s local timezone for added clarity, e.g., "Sep 2, 2024, 3:30 PM EST". Ideal for exact dates and times. Limit time format to the minute.
+- **Date range**: Displays a range by specifying a start and end date, e.g., "Sep 2–Sep 9, 2024".
+- **Precise time**: Displays date and time in a UTC format for a log stream or where human readability isn't necessary, e.g., “2024-09-05T23:15:17345Z”.
+
+### Relative dates
+
+Relative dates work well for periods from one minute up to one week. For added accuracy, a [Tooltip](/components/tooltip) can display the exact timestamp, including seconds and the local timezone, e.g., "Sep 5, 2018, 4:07:32 PM PST". This helps users who need precise information without manually converting from UTC.
+
+![A relative date displayed as "5 days ago" with the full date shown in a tooltip in the friendly local format "Sep 5, 2018, 4:07:32 PM EST".](/assets/content/writing-guidelines/writing-guidelines-relative-dates-with-tooltip.png)
+
+- Omit "about" in phrases like "about 3 hours ago" since the approximation is implied.
+To improve readability, show only the most significant unit, e.g., "3 days ago" instead of "3 days, 4 hours ago."
+- Friendly dates limit the visible display to the minute, e.g., "Sep 5, 2018, 4:07 PM".