Primary navigation: Improve documentation

- Add section on how it works
- How to incorporate below header
- How to incorporate below phase banner
- Add section on research and usage

docs/examples/primary-navigation-below-header.njk

@@ -0,0 +1,37 @@
+---
+eleventyExcludeFromCollections: true
+layout: example-full-width.njk
+title: Primary navigation example below header
+---
+<style>
+  .app-header--full-width-border {
+    border-bottom: 10px solid #2188aa;
+  }
+</style>
+
+{% from "govuk/components/header/macro.njk" import govukHeader %}
+{{ govukHeader({
+  classes: "app-header--full-width-border"
+}) }}
+
+{% from "x-govuk/components/primary-navigation/macro.njk" import xGovukPrimaryNavigation %}
+{{ xGovukPrimaryNavigation({
+  visuallyHiddenTitle: "Navigation",
+  items: [{
+    text: "Home",
+    href: "#",
+    current: true
+  }, {
+    text: "Support",
+    href: "#"
+  }, {
+    text: "Features",
+    href: "#"
+  }, {
+    text: "Pricing",
+    href: "#"
+  }, {
+    text: "Contact us",
+    href: "#"
+  }]
+}) }}

docs/examples/primary-navigation-below-phase-banner.njk

@@ -0,0 +1,50 @@
+---
+eleventyExcludeFromCollections: true
+layout: example-full-width.njk
+title: Primary navigation example below phase banner
+---
+<style>
+  .app-header--full-width-border {
+    border-bottom: 10px solid #2188aa;
+  }
+
+  .app-phase-banner--no-border {
+    border-bottom: none;
+  }
+</style>
+
+{% from "govuk/components/header/macro.njk" import govukHeader %}
+{{ govukHeader({
+  classes: "app-header--full-width-border"
+}) }}
+
+{% from "govuk/components/phase-banner/macro.njk" import govukPhaseBanner %}
+{{ govukPhaseBanner({
+  classes: "app-phase-banner--no-border govuk-width-container",
+  tag: {
+    text: "Alpha"
+  },
+  html: 'This is a new service – your <a class="govuk-link" href="#">feedback</a> will help us to improve it.'
+}) }}
+
+{% from "x-govuk/components/primary-navigation/macro.njk" import xGovukPrimaryNavigation %}
+{{ xGovukPrimaryNavigation({
+  visuallyHiddenTitle: "Navigation",
+  items: [{
+    text: "Home",
+    href: "#",
+    current: true
+  }, {
+    text: "Support",
+    href: "#"
+  }, {
+    text: "Features",
+    href: "#"
+  }, {
+    text: "Pricing",
+    href: "#"
+  }, {
+    text: "Contact us",
+    href: "#"
+  }]
+}) }}

docs/examples/primary-navigation.njk

@@ -1,7 +1,7 @@
 ---
 eleventyExcludeFromCollections: true
 layout: example-full-width.njk
-title: Primary navigation
+title: Primary navigation example
 ---
 {% from "x-govuk/components/primary-navigation/macro.njk" import xGovukPrimaryNavigation %}
 {{ xGovukPrimaryNavigation({

docs/primary-navigation.md

@@ -11,6 +11,34 @@ description: Link to the primary sections of your service.
   example: "primary-navigation"
 }) }}
 
+## When to use this component
+
+Use the primary navigation component to let users navigate to the main sections of your service.
+
+You must use this component with [the header component](https://design-system.service.gov.uk/components/header/).
+
+## How it works
+
+The primary navigation component takes up the full width of the page. To ensure there is no gap between the header and this component, create a modifying class to make the bottom border on the header also take up the full width of the page:
+
+{{ appExample({
+  example: "primary-navigation-below-header"
+}) }}
+
+Only include links to top level sections within your service.
+
+One of the items should be highlighted if it matches the current page or parent section. This item remains a link, but includes an `aria-current="page"` attribute with a line displayed beneath it to indicate that it is the current section.
+
+If your service uses [the phase banner component](https://design-system.service.gov.uk/components/phase-banner/), this should appear directly above the primary navigation component.
+
+To ensure there is no border between the phase banner and navigation, create a modifying class to remove the bottom border from the phase banner:
+
+{{ appExample({
+  example: "primary-navigation-below-phase-banner"
+}) }}
+
+You can use HTML or, if you are using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.
+
 ## Component options
 
 Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
@@ -34,3 +62,9 @@ If you’re using Nunjucks macros in production with `html` options, or ones end
 | **href**    | array   | **Required**. The value of the navigation link’s `href` attribute. |
 | **current** | boolean | Indicate that the item is the current page.                        |
 | **classes** | string  | Classes to add to the navigation item.                             |
+
+## Research on this component
+
+This component is based on [the Primary navigation component originally developed as part of the Ministry of Justice Design System](https://design-patterns.service.justice.gov.uk/components/primary-navigation/).
+
+It also follows the design of the [GOV.UK One Login service header](https://github.com/govuk-one-login/service-header).