From 227bb8f10061d376301649dd3b7ddc3af9a7a0b7 Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Wed, 26 Feb 2020 11:46:25 +0100
Subject: [PATCH 1/8] Move some of navigation styles to placeholders

---
 scss/_patterns_navigation.scss | 186 ++++++++++++++++++---------------
 1 file changed, 102 insertions(+), 84 deletions(-)

diff --git a/scss/_patterns_navigation.scss b/scss/_patterns_navigation.scss
index f336b2d0a4..2fa7ca6b6e 100644
--- a/scss/_patterns_navigation.scss
+++ b/scss/_patterns_navigation.scss
@@ -3,86 +3,109 @@
 $navigation-hover-opacity: 0.58;
 
 @mixin vf-p-navigation {
-  // no colours
-  .p-navigation {
+  // placeholders
+  %navigation-row {
     display: flex;
     flex-direction: column;
-    flex-shrink: 0;
-    position: relative;
-    z-index: 10;
 
     @media (min-width: $breakpoint-navigation-threshold) {
       flex-direction: row;
     }
+  }
 
-    &__banner {
-      display: flex;
-      flex: 0 0 auto;
-      justify-content: space-between;
-    }
+  %navigation-link {
+    $properties: #{background-color, color, opacity};
+    @include vf-animation($properties);
+    display: block;
+    line-height: map-get($line-heights, default-text);
+    margin-bottom: 0;
+    overflow: hidden;
+    padding: $spv-inner--medium 0;
+    position: relative;
+    text-overflow: ellipsis;
+    white-space: nowrap;
 
-    &__image {
-      align-self: center;
-      max-height: 2rem;
-      min-height: 1.5rem;
+    @media (min-width: $breakpoint-navigation-threshold) {
+      padding: $spv-inner--medium $sph-inner;
     }
 
-    &__link {
+    &::before {
+      content: '';
+      height: 1px;
+      left: 0;
+      position: absolute;
+      right: 0;
+      top: 0;
+
       @media (min-width: $breakpoint-navigation-threshold) {
-        $nav-link-max-width: 20em !default;
-        max-width: $nav-link-max-width;
+        content: none;
       }
+    }
 
-      & > a {
-        $properties: #{background-color, color, opacity};
-        @include vf-animation($properties);
-        display: block;
-        line-height: map-get($line-heights, default-text);
-        margin-bottom: 0;
-        overflow: hidden;
-        padding: $spv-inner--medium 0;
-        position: relative;
-        text-overflow: ellipsis;
-        white-space: nowrap;
+    &,
+    &:visited,
+    &:focus,
+    &:hover {
+      text-decoration: none;
+    }
+  }
 
-        @media (min-width: $breakpoint-navigation-threshold) {
-          padding: $spv-inner--medium $sph-inner;
-        }
+  %navigation-items {
+    list-style: none;
+    margin: -1px 0 0 0;
+    padding: 0;
 
-        &::before {
-          content: '';
-          height: 1px;
-          left: 0;
-          position: absolute;
-          right: 0;
-          top: 0;
-
-          @media (min-width: $breakpoint-navigation-threshold) {
-            content: none;
-          }
-        }
+    @media (min-width: $breakpoint-navigation-threshold) {
+      display: flex;
+      flex-wrap: wrap;
+      margin-top: 0; // prevents bottom border of nav from moving 1px
+    }
+  }
 
-        &,
-        &:visited,
-        &:focus,
-        &:hover {
-          text-decoration: none;
-        }
-      }
+  %navigation-item {
+    @media (min-width: $breakpoint-navigation-threshold) {
+      $nav-link-max-width: 20em !default;
+      max-width: $nav-link-max-width;
     }
+  }
 
-    &__links {
-      list-style: none;
-      margin: -1px 0 0 0;
-      padding: 0;
+  // no colours
+  .p-navigation {
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    position: relative;
+    z-index: 10;
 
-      @media (min-width: $breakpoint-navigation-threshold) {
-        display: flex;
-        flex-wrap: wrap;
-        margin-top: 0; // prevents bottom border of nav from moving 1px
+    @media (min-width: $breakpoint-navigation-threshold) {
+      flex-direction: row;
+    }
+
+    // navigation row
+    &__row {
+      @extend %fixed-width-container;
+      @extend %navigation-row;
+
+      &--full-width {
+        @extend %vf-grid-container-padding;
+        @extend %navigation-row;
+        width: 100%;
       }
     }
 
+    @include deprecate('3.0.0', 'Use .p-navigation__row / .p-navigation__row--full-width instead') {
+      &.row {
+        @extend %navigation-row;
+      }
+    }
+
+    // navigation logo
+    &__banner {
+      display: flex;
+      flex: 0 0 auto;
+      justify-content: space-between;
+    }
+
     &__logo {
       display: flex;
       flex: 0 0 auto;
@@ -94,6 +117,13 @@ $navigation-hover-opacity: 0.58;
       }
     }
 
+    &__image {
+      align-self: center;
+      max-height: 2rem;
+      min-height: 1.5rem;
+    }
+
+    // navigation items
     &__nav {
       display: none;
       flex-direction: column;
@@ -106,6 +136,19 @@ $navigation-hover-opacity: 0.58;
       }
     }
 
+    &__link {
+      @extend %navigation-item;
+
+      & > a {
+        @extend %navigation-link;
+      }
+    }
+
+    &__links {
+      @extend %navigation-items;
+    }
+
+    // p-search-box overrides
     .p-search-box {
       flex: 1 0 auto;
       margin: -1px 0 $spv-inner--small 0;
@@ -124,32 +167,7 @@ $navigation-hover-opacity: 0.58;
       }
     }
 
-    %navigation-row {
-      display: flex;
-      flex-direction: column;
-
-      @media (min-width: $breakpoint-navigation-threshold) {
-        flex-direction: row;
-      }
-    }
-
-    &__row {
-      @extend %fixed-width-container;
-      @extend %navigation-row;
-
-      &--full-width {
-        @extend %vf-grid-container-padding;
-        @extend %navigation-row;
-        width: 100%;
-      }
-    }
-
-    @include deprecate('3.0.0', 'Use .p-navigation__row / .p-navigation__row--full-width instead') {
-      &.row {
-        @extend %navigation-row;
-      }
-    }
-
+    // small screen navigation toggles
     &:target {
       &::after {
         display: none;

From 5c79872e888c6f776a2ac163c0830727f81406b8 Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Wed, 26 Feb 2020 14:46:46 +0100
Subject: [PATCH 2/8] Move subnav script to separate file

---
 docs/examples/patterns/navigation/_script.js  | 81 ++++++++++++++++++
 .../patterns/navigation/subnav-dark.html      | 85 +------------------
 docs/examples/patterns/navigation/subnav.html | 85 +------------------
 3 files changed, 83 insertions(+), 168 deletions(-)
 create mode 100644 docs/examples/patterns/navigation/_script.js

diff --git a/docs/examples/patterns/navigation/_script.js b/docs/examples/patterns/navigation/_script.js
new file mode 100644
index 0000000000..9f96d9ba02
--- /dev/null
+++ b/docs/examples/patterns/navigation/_script.js
@@ -0,0 +1,81 @@
+/**
+  Opens a given subnav by applying is-active class to it
+  and setting aria-hidden attribute on dropdown contents.
+  @param {HTMLElement} subnav Root element of subnavigation to open.
+*/
+function openSubnav(subnav) {
+  subnav.classList.add('is-active');
+  var toggle = subnav.querySelector('.p-subnav__toggle');
+  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
+  dropdown.setAttribute('aria-hidden', 'true');
+}
+
+/**
+  Closes a given subnav by removing is-active class to it
+  and setting aria-hidden attribute on dropdown contents.
+  @param {HTMLElement} subnav Root element of subnavigation to open.
+*/
+function closeSubnav(subnav) {
+  subnav.classList.remove('is-active');
+  var toggle = subnav.querySelector('.p-subnav__toggle');
+  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
+  dropdown.setAttribute('aria-hidden', 'false');
+}
+
+/**
+  Closes all subnavs on the page.
+*/
+function closeAllSubnavs() {
+  var subnavs = document.querySelectorAll('.p-subnav');
+  for (var i = 0, l = subnavs.length; i < l; i++) {
+    closeSubnav(subnavs[i]);
+  }
+}
+
+/**
+  Attaches click event listener to subnav toggle.
+  @param {HTMLElement} subnavToggle Toggle element of subnavigation.
+*/
+function setupSubnavToggle(subnavToggle) {
+  subnavToggle.addEventListener('click', function(event) {
+    event.preventDefault();
+    event.stopPropagation();
+
+    var subnav = subnavToggle.parentElement;
+    var isActive = subnav.classList.contains('is-active');
+
+    closeAllSubnavs();
+    if (!isActive) {
+      openSubnav(subnav);
+    }
+  });
+}
+
+// Setup all subnav toggles on the page
+var subnavToggles = document.querySelectorAll('.p-subnav__toggle');
+
+for (var i = 0, l = subnavToggles.length; i < l; i++) {
+  setupSubnavToggle(subnavToggles[i]);
+}
+
+// Close all menus if anything else on the page is clicked
+document.addEventListener('click', function(event) {
+  var target = event.target;
+
+  if (target.closest) {
+    if (!target.closest('.p-subnav__toggle') && !target.closest('.p-subnav__item')) {
+      closeAllSubnavs();
+    }
+  } else if (target.msMatchesSelector) {
+    // IE friendly `Element.closest` equivalent
+    // as in https://developer.mozilla.org/en-US/docs/Web/API/Element/closest
+    do {
+      if (target.msMatchesSelector('.p-subnav__toggle') || target.msMatchesSelector('.p-subnav__item')) {
+        return;
+      }
+      target = target.parentElement || target.parentNode;
+    } while (target !== null && target.nodeType === 1);
+
+    closeAllSubnavs();
+  }
+});
diff --git a/docs/examples/patterns/navigation/subnav-dark.html b/docs/examples/patterns/navigation/subnav-dark.html
index 718182c315..85aec9dd39 100644
--- a/docs/examples/patterns/navigation/subnav-dark.html
+++ b/docs/examples/patterns/navigation/subnav-dark.html
@@ -86,89 +86,6 @@
 </header>
 
 <script>
-/**
-  Opens a given subnav by applying is-active class to it
-  and setting aria-hidden attribute on dropdown contents.
-  @param {HTMLElement} subnav Root element of subnavigation to open.
-*/
-function openSubnav(subnav) {
-  subnav.classList.add('is-active');
-  var toggle = subnav.querySelector(".p-subnav__toggle");
-  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
-  dropdown.setAttribute('aria-hidden', 'true');
-}
-
-/**
-  Closes a given subnav by removing is-active class to it
-  and setting aria-hidden attribute on dropdown contents.
-  @param {HTMLElement} subnav Root element of subnavigation to open.
-*/
-function closeSubnav(subnav) {
-  subnav.classList.remove('is-active');
-  var toggle = subnav.querySelector(".p-subnav__toggle");
-  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
-  dropdown.setAttribute('aria-hidden', 'false');
-}
-
-/**
-  Closes all subnavs on the page.
-*/
-function closeAllSubnavs() {
-  var subnavs = document.querySelectorAll('.p-subnav');
-  for (var i = 0, l = subnavs.length; i < l; i++) {
-    closeSubnav(subnavs[i]);
-  }
-}
-
-/**
-  Attaches click event listener to subnav toggle.
-  @param {HTMLElement} subnavToggle Toggle element of subnavigation.
-*/
-function setupSubnavToggle(subnavToggle) {
-  subnavToggle.addEventListener('click', function(event) {
-    event.preventDefault();
-    event.stopPropagation();
-
-    var subnav = subnavToggle.parentElement;
-    var isActive = subnav.classList.contains('is-active');
-
-    closeAllSubnavs();
-    if (!isActive) {
-      openSubnav(subnav);
-    }
-  });
-}
-
-// Setup all subnav toggles on the page
-var subnavToggles = document.querySelectorAll('.p-subnav__toggle');
-
-for (var i = 0, l = subnavToggles.length; i < l; i++) {
-  setupSubnavToggle(subnavToggles[i]);
-}
-
-// Close all menus if anything else on the page is clicked
-document.addEventListener('click', function(event) {
-  var target = event.target;
-
-  if (target.closest) {
-    if (!target.closest('.p-subnav__toggle') && !target.closest('.p-subnav__item')) {
-      closeAllSubnavs();
-    }
-  } else if (target.msMatchesSelector) {
-    // IE friendly `Element.closest` equivalent
-    // as in https://developer.mozilla.org/en-US/docs/Web/API/Element/closest
-    do {
-      if (
-        target.msMatchesSelector('.p-subnav__toggle') ||
-        target.msMatchesSelector('.p-subnav__item')
-      ) {
-        return;
-      }
-      target = target.parentElement || target.parentNode;
-    } while (target !== null && target.nodeType === 1);
-
-    closeAllSubnavs();
-  }
-});
+  {% include 'examples/patterns/navigation/_script.js' %}
 </script>
 {% endblock %}
diff --git a/docs/examples/patterns/navigation/subnav.html b/docs/examples/patterns/navigation/subnav.html
index e006cce7b3..ba383c02c8 100644
--- a/docs/examples/patterns/navigation/subnav.html
+++ b/docs/examples/patterns/navigation/subnav.html
@@ -86,89 +86,6 @@
 </header>
 
 <script>
-/**
-  Opens a given subnav by applying is-active class to it
-  and setting aria-hidden attribute on dropdown contents.
-  @param {HTMLElement} subnav Root element of subnavigation to open.
-*/
-function openSubnav(subnav) {
-  subnav.classList.add('is-active');
-  var toggle = subnav.querySelector(".p-subnav__toggle");
-  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
-  dropdown.setAttribute('aria-hidden', 'true');
-}
-
-/**
-  Closes a given subnav by removing is-active class to it
-  and setting aria-hidden attribute on dropdown contents.
-  @param {HTMLElement} subnav Root element of subnavigation to open.
-*/
-function closeSubnav(subnav) {
-  subnav.classList.remove('is-active');
-  var toggle = subnav.querySelector(".p-subnav__toggle");
-  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
-  dropdown.setAttribute('aria-hidden', 'false');
-}
-
-/**
-  Closes all subnavs on the page.
-*/
-function closeAllSubnavs() {
-  var subnavs = document.querySelectorAll('.p-subnav');
-  for (var i = 0, l = subnavs.length; i < l; i++) {
-    closeSubnav(subnavs[i]);
-  }
-}
-
-/**
-  Attaches click event listener to subnav toggle.
-  @param {HTMLElement} subnavToggle Toggle element of subnavigation.
-*/
-function setupSubnavToggle(subnavToggle) {
-  subnavToggle.addEventListener('click', function(event) {
-    event.preventDefault();
-    event.stopPropagation();
-
-    var subnav = subnavToggle.parentElement;
-    var isActive = subnav.classList.contains('is-active');
-
-    closeAllSubnavs();
-    if (!isActive) {
-      openSubnav(subnav);
-    }
-  });
-}
-
-// Setup all subnav toggles on the page
-var subnavToggles = document.querySelectorAll('.p-subnav__toggle');
-
-for (var i = 0, l = subnavToggles.length; i < l; i++) {
-  setupSubnavToggle(subnavToggles[i]);
-}
-
-// Close all menus if anything else on the page is clicked
-document.addEventListener('click', function(event) {
-  var target = event.target;
-
-  if (target.closest) {
-    if (!target.closest('.p-subnav__toggle') && !target.closest('.p-subnav__item')) {
-      closeAllSubnavs();
-    }
-  } else if (target.msMatchesSelector) {
-    // IE friendly `Element.closest` equivalent
-    // as in https://developer.mozilla.org/en-US/docs/Web/API/Element/closest
-    do {
-      if (
-        target.msMatchesSelector('.p-subnav__toggle') ||
-        target.msMatchesSelector('.p-subnav__item')
-      ) {
-        return;
-      }
-      target = target.parentElement || target.parentNode;
-    } while (target !== null && target.nodeType === 1);
-
-    closeAllSubnavs();
-  }
-});
+  {% include 'examples/patterns/navigation/_script.js' %}
 </script>
 {% endblock %}

From 6808e1ce1ab06a99405dc6d5e31d60864e72cdf5 Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Wed, 26 Feb 2020 16:27:27 +0100
Subject: [PATCH 3/8] Adds support for new p-navigation__items, __item and
 __link classes

Deprecates p-navigation__links, p-navigation__link and > a selectors.

Updates default example to use new classes, adds new deprecated example
to make sure we keep support.
---
 .../examples/patterns/navigation/default.html |  18 +--
 .../patterns/navigation/deprecated.html       |  55 ++++++++
 scss/_patterns_navigation.scss                | 121 ++++++++++++++----
 scss/_patterns_subnav.scss                    |  16 ++-
 4 files changed, 174 insertions(+), 36 deletions(-)
 create mode 100644 docs/examples/patterns/navigation/deprecated.html

diff --git a/docs/examples/patterns/navigation/default.html b/docs/examples/patterns/navigation/default.html
index fd2829bc9d..35c191ce17 100644
--- a/docs/examples/patterns/navigation/default.html
+++ b/docs/examples/patterns/navigation/default.html
@@ -8,7 +8,7 @@
   <div class="p-navigation__row">
     <div class="p-navigation__banner">
       <div class="p-navigation__logo">
-        <a class="p-navigation__link" href="#">
+        <a class="p-navigation__item" href="#">
           <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/5d6da5c4-logo-canonical-aubergine.svg" alt="" width="95" />
         </a>
       </div>
@@ -19,18 +19,18 @@
       <span class="u-off-screen">
         <a href="#main-content">Jump to main content</a>
       </span>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link is-selected" role="menuitem">
-          <a href="#">Products</a>
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item is-selected" role="menuitem">
+          <a class="p-navigation__link" href="#">Products</a>
         </li>
-        <li class="p-navigation__link" role="menuitem">
-          <a href="#">Services</a>
+        <li class="p-navigation__item" role="menuitem">
+          <a class="p-navigation__link" href="#">Services</a>
         </li>
-        <li class="p-navigation__link" role="menuitem">
-          <a href="#">Partners</a>
+        <li class="p-navigation__item" role="menuitem">
+          <a class="p-navigation__link" href="#">Partners</a>
         </li>
         <li class="p-navigation__link" role="menuitem">
-          <a href="#">About</a>
+          <a class="p-navigation__link" href="#">About</a>
         </li>
       </ul>
     </nav>
diff --git a/docs/examples/patterns/navigation/deprecated.html b/docs/examples/patterns/navigation/deprecated.html
new file mode 100644
index 0000000000..33d758b38c
--- /dev/null
+++ b/docs/examples/patterns/navigation/deprecated.html
@@ -0,0 +1,55 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Navigation / Deprecated{% endblock %}
+
+{% block standalone_css %}patterns_subnav{% endblock %}
+
+{% block content %}
+<header id="navigation" class="p-navigation">
+  <div class="p-navigation__row">
+    <div class="p-navigation__banner">
+      <div class="p-navigation__logo">
+        <a class="p-navigation__link" href="#">
+          <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/5d6da5c4-logo-canonical-aubergine.svg" alt="" width="95" />
+        </a>
+      </div>
+      <a href="#navigation" class="p-navigation__toggle--open" title="menu">Menu</a>
+      <a href="#navigation-closed" class="p-navigation__toggle--close" title="close menu">Close menu</a>
+    </div>
+    <nav class="p-navigation__nav">
+      <span class="u-off-screen">
+        <a href="#main-content">Jump to main content</a>
+      </span>
+      <ul class="p-navigation__links" role="menu">
+        <li class="p-navigation__link is-selected" role="menuitem">
+          <a href="#">Products</a>
+        </li>
+        <li class="p-navigation__link" role="menuitem">
+          <a href="#">Services</a>
+        </li>
+        <li class="p-navigation__link" role="menuitem">
+          <a href="#">Partners</a>
+        </li>
+        <li class="p-navigation__link" role="menuitem">
+          <a href="#">About</a>
+        </li>
+      </ul>
+      <ul class="p-navigation__links" role="menu">
+        <li class="p-navigation__link p-subnav" role="menuitem" id="link-1">
+          <a class="p-subnav__toggle" aria-controls="account-menu">
+            My account
+          </a>
+          <ul class="p-subnav__items--right" id="account-menu" aria-hidden="true">
+            <li>
+              <a href="#" class="p-subnav__item">Sign out</a>
+            </li>
+          </ul>
+        </li>
+      </ul>
+    </nav>
+  </div>
+</header>
+
+<script>
+  {% include 'examples/patterns/navigation/_script.js' %}
+</script>
+{% endblock %}
diff --git a/scss/_patterns_navigation.scss b/scss/_patterns_navigation.scss
index 2fa7ca6b6e..eee3535f9d 100644
--- a/scss/_patterns_navigation.scss
+++ b/scss/_patterns_navigation.scss
@@ -69,6 +69,10 @@ $navigation-hover-opacity: 0.58;
     }
   }
 
+  %navigation-item-in-logo {
+    display: flex;
+  }
+
   // no colours
   .p-navigation {
     display: flex;
@@ -112,8 +116,14 @@ $navigation-hover-opacity: 0.58;
       height: 3rem;
       margin: 0 $sph-inner 0 0;
 
-      .p-navigation__link {
-        display: flex;
+      .p-navigation__item {
+        @extend %navigation-item-in-logo;
+      }
+
+      @include deprecate('3.0.0', 'Use .p-navigation__items, .p-navigation__item, .p-navigation__link instead.') {
+        .p-navigation__link {
+          @extend %navigation-item-in-logo;
+        }
       }
     }
 
@@ -136,16 +146,31 @@ $navigation-hover-opacity: 0.58;
       }
     }
 
-    &__link {
+    &__items {
+      @extend %navigation-items;
+    }
+
+    &__item {
       @extend %navigation-item;
 
-      & > a {
+      // this needs to be nested in __item until in 3.0 we remove deprecated __link styles
+      .p-navigation__link {
         @extend %navigation-link;
       }
     }
 
-    &__links {
-      @extend %navigation-items;
+    @include deprecate('3.0.0', 'Use .p-navigation__items, .p-navigation__item, .p-navigation__link classes instead.') {
+      &__link {
+        @extend %navigation-item;
+
+        & > a {
+          @extend %navigation-link;
+        }
+      }
+
+      &__links {
+        @extend %navigation-items;
+      }
     }
 
     // p-search-box overrides
@@ -266,9 +291,7 @@ $navigation-hover-opacity: 0.58;
 
   background-color: $color-navigation-background;
 
-  .p-navigation__link > a,
-  .p-navigation__toggle--close,
-  .p-navigation__toggle--open {
+  %navigation-link-light {
     &,
     &:visited,
     &:focus {
@@ -280,16 +303,43 @@ $navigation-hover-opacity: 0.58;
     }
   }
 
-  @include deprecate('3.0.0', 'Selectors should use classes.') {
-    .p-navigation__link.is-selected > a {
-      opacity: $navigation-hover-opacity;
-    }
+  %navigation-link-light-selected {
+    opacity: $navigation-hover-opacity;
   }
 
-  .p-navigation__link > a::before {
+  %navigation-link-light-before {
     // separator color on small screens
     background: $colors--light-theme--border-default;
   }
+
+  .p-navigation__item > .p-navigation__link, // remove nesting in 3.0 when deprecated __link styles are removed
+  .p-navigation__toggle--close,
+  .p-navigation__toggle--open {
+    @extend %navigation-link-light;
+  }
+
+  .p-navigation__item.is-selected > .p-navigation__link {
+    @extend %navigation-link-light-selected;
+  }
+
+  .p-navigation__item > .p-navigation__link::before {
+    // remove nesting in 3.0 when deprecated __link styles are removed
+    @extend %navigation-link-light-before;
+  }
+
+  @include deprecate('3.0.0', 'Use .p-navigation__items, .p-navigation__item, .p-navigation__link classes instead.') {
+    .p-navigation__link > a {
+      @extend %navigation-link-light;
+    }
+
+    .p-navigation__link.is-selected > a {
+      @extend %navigation-link-light-selected;
+    }
+
+    .p-navigation__link > a::before {
+      @extend %navigation-link-light-before;
+    }
+  }
 }
 
 @mixin p-navigation--dark-theme($color-navigation-background, $color-navigation-text, $override-default: false) {
@@ -300,9 +350,7 @@ $navigation-hover-opacity: 0.58;
 
   background-color: $color-navigation-background;
 
-  .p-navigation__link > a,
-  .p-navigation__toggle--close,
-  .p-navigation__toggle--open {
+  %navigation-link-dark {
     &,
     &:visited,
     &:focus {
@@ -314,14 +362,41 @@ $navigation-hover-opacity: 0.58;
     }
   }
 
-  @include deprecate('3.0.0', 'Selectors should use classes.') {
-    .p-navigation__link.is-selected > a {
-      opacity: $navigation-hover-opacity;
-    }
+  %navigation-link-dark-selected {
+    opacity: $navigation-hover-opacity;
   }
 
-  // separator color on small screens
-  .p-navigation__link > a::before {
+  %navigation-link-dark-before {
+    // separator color on small screens
     background: $colors--dark-theme--border-default;
   }
+
+  .p-navigation__item > .p-navigation__link, // remove nesting in 3.0 when deprecated __link styles are removed
+  .p-navigation__toggle--close,
+  .p-navigation__toggle--open {
+    @extend %navigation-link-dark;
+  }
+
+  .p-navigation__item.is-selected > .p-navigation__link {
+    @extend %navigation-link-dark-selected;
+  }
+
+  .p-navigation__item > .p-navigation__link::before {
+    // remove nesting in 3.0 when deprecated __link styles are removed
+    @extend %navigation-link-dark-before;
+  }
+
+  @include deprecate('3.0.0', 'Use .p-navigation__items, .p-navigation__item, .p-navigation__link classes instead.') {
+    .p-navigation__link > a {
+      @extend %navigation-link-dark;
+    }
+
+    .p-navigation__link.is-selected > a {
+      @extend %navigation-link-dark-selected;
+    }
+
+    .p-navigation__link > a::before {
+      @extend %navigation-link-dark-before;
+    }
+  }
 }
diff --git a/scss/_patterns_subnav.scss b/scss/_patterns_subnav.scss
index c557d30563..247aee95f3 100644
--- a/scss/_patterns_subnav.scss
+++ b/scss/_patterns_subnav.scss
@@ -33,13 +33,21 @@
     }
   }
 
-  // XXX: Fix required because of greedy rule in p-navigation
-  // Can be updated with resolution of:
-  // https://github.com/canonical-web-and-design/vanilla-framework/issues/2168
-  .p-subnav > a {
+  %subnav-link {
     padding-right: 2 * $sph-inner--small + map-get($icon-sizes, default); // icon padded with the default padding-right of selects, inputs etc.
   }
 
+  .p-subnav > .p-navigation__link {
+    // remove nesting in 3.0 when deprecated __link styles are removed
+    @extend %subnav-link;
+  }
+
+  @include deprecate('3.0.0', 'Use .p-navigation__items, .p-navigation__item, .p-navigation__link classes instead.') {
+    .p-subnav > a {
+      @extend %subnav-link;
+    }
+  }
+
   // Theming
   @if ($theme-default-nav == 'dark') {
     .p-subnav::after {

From e24f334ee8fede8e323d64a97e4121dc08d41baf Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Wed, 26 Feb 2020 16:51:16 +0100
Subject: [PATCH 4/8] Update all examples to use new navigation class names

---
 .../patterns/navigation/default-dark.html     | 18 +++---
 .../patterns/navigation/deprecated-dark.html  | 55 +++++++++++++++++++
 .../patterns/navigation/full-width.html       | 18 +++---
 .../patterns/navigation/subnav-dark.html      | 22 ++++----
 docs/examples/patterns/navigation/subnav.html | 22 ++++----
 .../patterns/search-box/navigation-dark.html  | 14 ++---
 .../patterns/search-box/navigation.html       | 14 ++---
 7 files changed, 109 insertions(+), 54 deletions(-)
 create mode 100644 docs/examples/patterns/navigation/deprecated-dark.html

diff --git a/docs/examples/patterns/navigation/default-dark.html b/docs/examples/patterns/navigation/default-dark.html
index 1effa55d87..9dbfbb4222 100644
--- a/docs/examples/patterns/navigation/default-dark.html
+++ b/docs/examples/patterns/navigation/default-dark.html
@@ -8,7 +8,7 @@
   <div class="p-navigation__row">
     <div class="p-navigation__banner">
       <div class="p-navigation__logo">
-        <a class="p-navigation__link" href="#">
+        <a class="p-navigation__item" href="#">
           <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/3c7954dd-logo-canonical-white.svg" alt="" width="95" />
         </a>
       </div>
@@ -19,18 +19,18 @@
       <span class="u-off-screen">
         <a href="#main-content">Jump to main content</a>
       </span>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link is-selected" role="menuitem">
-          <a href="#">Products</a>
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item is-selected" role="menuitem">
+          <a class="p-navigation__link" href="#">Products</a>
         </li>
-        <li class="p-navigation__link" role="menuitem">
-          <a href="#">Services</a>
+        <li class="p-navigation__item" role="menuitem">
+          <a class="p-navigation__link" href="#">Services</a>
         </li>
-        <li class="p-navigation__link" role="menuitem">
-          <a href="#">Partners</a>
+        <li class="p-navigation__item" role="menuitem">
+          <a class="p-navigation__link" href="#">Partners</a>
         </li>
         <li class="p-navigation__link" role="menuitem">
-          <a href="#">About</a>
+          <a class="p-navigation__link" href="#">About</a>
         </li>
       </ul>
     </nav>
diff --git a/docs/examples/patterns/navigation/deprecated-dark.html b/docs/examples/patterns/navigation/deprecated-dark.html
new file mode 100644
index 0000000000..4d0af70bea
--- /dev/null
+++ b/docs/examples/patterns/navigation/deprecated-dark.html
@@ -0,0 +1,55 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Navigation / Deprecated dark{% endblock %}
+
+{% block standalone_css %}patterns_subnav{% endblock %}
+
+{% block content %}
+<header id="navigation" class="p-navigation is-dark">
+  <div class="p-navigation__row">
+    <div class="p-navigation__banner">
+      <div class="p-navigation__logo">
+        <a class="p-navigation__link" href="#">
+          <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/3c7954dd-logo-canonical-white.svg" alt="" width="95" />
+        </a>
+      </div>
+      <a href="#navigation" class="p-navigation__toggle--open" title="menu">Menu</a>
+      <a href="#navigation-closed" class="p-navigation__toggle--close" title="close menu">Close menu</a>
+    </div>
+    <nav class="p-navigation__nav">
+      <span class="u-off-screen">
+        <a href="#main-content">Jump to main content</a>
+      </span>
+      <ul class="p-navigation__links" role="menu">
+        <li class="p-navigation__link is-selected" role="menuitem">
+          <a href="#">Products</a>
+        </li>
+        <li class="p-navigation__link" role="menuitem">
+          <a href="#">Services</a>
+        </li>
+        <li class="p-navigation__link" role="menuitem">
+          <a href="#">Partners</a>
+        </li>
+        <li class="p-navigation__link" role="menuitem">
+          <a href="#">About</a>
+        </li>
+      </ul>
+      <ul class="p-navigation__links" role="menu">
+        <li class="p-navigation__link p-subnav" role="menuitem" id="link-1">
+          <a class="p-subnav__toggle" aria-controls="account-menu">
+            My account
+          </a>
+          <ul class="p-subnav__items--right" id="account-menu" aria-hidden="true">
+            <li>
+              <a href="#" class="p-subnav__item">Sign out</a>
+            </li>
+          </ul>
+        </li>
+      </ul>
+    </nav>
+  </div>
+</header>
+
+<script>
+  {% include 'examples/patterns/navigation/_script.js' %}
+</script>
+{% endblock %}
diff --git a/docs/examples/patterns/navigation/full-width.html b/docs/examples/patterns/navigation/full-width.html
index a5ed30369a..0237795233 100644
--- a/docs/examples/patterns/navigation/full-width.html
+++ b/docs/examples/patterns/navigation/full-width.html
@@ -8,7 +8,7 @@
   <div class="p-navigation__row--full-width">
     <div class="p-navigation__banner">
       <div class="p-navigation__logo">
-        <a class="p-navigation__link" href="#">
+        <a class="p-navigation__item" href="#">
           <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/5d6da5c4-logo-canonical-aubergine.svg" alt="" width="95" />
         </a>
       </div>
@@ -19,18 +19,18 @@
       <span class="u-off-screen">
         <a href="#main-content">Jump to main content</a>
       </span>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link is-selected" role="menuitem">
-          <a href="#">Products</a>
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item is-selected" role="menuitem">
+          <a class="p-navigation__link" href="#">Products</a>
         </li>
-        <li class="p-navigation__link" role="menuitem">
-          <a href="#">Services</a>
+        <li class="p-navigation__item" role="menuitem">
+          <a class="p-navigation__link" href="#">Services</a>
         </li>
-        <li class="p-navigation__link" role="menuitem">
-          <a href="#">Partners</a>
+        <li class="p-navigation__item" role="menuitem">
+          <a class="p-navigation__link" href="#">Partners</a>
         </li>
         <li class="p-navigation__link" role="menuitem">
-          <a href="#">About</a>
+          <a class="p-navigation__link" href="#">About</a>
         </li>
       </ul>
     </nav>
diff --git a/docs/examples/patterns/navigation/subnav-dark.html b/docs/examples/patterns/navigation/subnav-dark.html
index 85aec9dd39..48dd2da389 100644
--- a/docs/examples/patterns/navigation/subnav-dark.html
+++ b/docs/examples/patterns/navigation/subnav-dark.html
@@ -8,7 +8,7 @@
   <div class="p-navigation__row">
     <div class="p-navigation__banner">
       <div class="p-navigation__logo">
-        <a class="p-navigation__link" href="#">
+        <a class="p-navigation__item" href="#">
           <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/20673d9f-lxd_primary--for-dark-bg.svg" alt="" width="95" />
         </a>
       </div>
@@ -19,9 +19,9 @@
       <span class="u-off-screen">
         <a href="#main-content">Jump to main content</a>
       </span>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-1">
-          <a href="#link-1-menu" aria-controls="link-1-menu" class="p-subnav__toggle">LXC</a>
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-1">
+          <a href="#link-1-menu" aria-controls="link-1-menu" class="p-subnav__toggle p-navigation__link">LXC</a>
           <ul class="p-subnav__items" id="link-1-menu" aria-hidden="true">
             <li>
               <a href="#" class="p-subnav__item">Introduction</a>
@@ -34,8 +34,8 @@
             </li>
           </ul>
         </li>
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-2">
-          <a href="#link-2-menu" aria-controls="link-2-menu" class="p-subnav__toggle">LXD</a>
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-2">
+          <a href="#link-2-menu" aria-controls="link-2-menu" class="p-subnav__toggle p-navigation__link">LXD</a>
           <ul class="p-subnav__items" id="link-2-menu" aria-hidden="true">
             <li>
               <a href="#" class="p-subnav__item">Introduction</a>
@@ -54,8 +54,8 @@
             </li>
           </ul>
         </li>
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-3">
-          <a href="#link-3-menu" aria-controls="link-3-menu" class="p-subnav__toggle">LXCFS</a>
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-3">
+          <a href="#link-3-menu" aria-controls="link-3-menu" class="p-subnav__toggle p-navigation__link">LXCFS</a>
           <ul class="p-subnav__items" id="link-3-menu" aria-hidden="true">
             <li>
               <a href="#" class="p-subnav__item">Introduction</a>
@@ -69,9 +69,9 @@
           </ul>
         </li>
       </ul>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-1">
-          <a class="p-subnav__toggle" aria-controls="account-menu">
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-1">
+          <a class="p-subnav__toggle p-navigation__link" aria-controls="account-menu">
             My account
           </a>
           <ul class="p-subnav__items--right" id="account-menu" aria-hidden="true">
diff --git a/docs/examples/patterns/navigation/subnav.html b/docs/examples/patterns/navigation/subnav.html
index ba383c02c8..e939e24493 100644
--- a/docs/examples/patterns/navigation/subnav.html
+++ b/docs/examples/patterns/navigation/subnav.html
@@ -8,7 +8,7 @@
   <div class="p-navigation__row">
     <div class="p-navigation__banner">
       <div class="p-navigation__logo">
-        <a class="p-navigation__link" href="#">
+        <a class="p-navigation__item" href="#">
           <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/ac9a0e00-lxd_primary.svg" alt="" width="95" />
         </a>
       </div>
@@ -19,9 +19,9 @@
       <span class="u-off-screen">
         <a href="#main-content">Jump to main content</a>
       </span>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-1">
-          <a href="#link-1-menu" aria-controls="link-1-menu" class="p-subnav__toggle">LXC</a>
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-1">
+          <a href="#link-1-menu" aria-controls="link-1-menu" class="p-subnav__toggle p-navigation__link">LXC</a>
           <ul class="p-subnav__items" id="link-1-menu" aria-hidden="true">
             <li>
               <a href="#" class="p-subnav__item">Introduction</a>
@@ -34,8 +34,8 @@
             </li>
           </ul>
         </li>
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-2">
-          <a href="#link-2-menu" aria-controls="link-2-menu" class="p-subnav__toggle">LXD</a>
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-2">
+          <a href="#link-2-menu" aria-controls="link-2-menu" class="p-subnav__toggle p-navigation__link">LXD</a>
           <ul class="p-subnav__items" id="link-2-menu" aria-hidden="true">
             <li>
               <a href="#" class="p-subnav__item">Introduction</a>
@@ -54,8 +54,8 @@
             </li>
           </ul>
         </li>
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-3">
-          <a href="#link-3-menu" aria-controls="link-3-menu" class="p-subnav__toggle">LXCFS</a>
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-3">
+          <a href="#link-3-menu" aria-controls="link-3-menu" class="p-subnav__toggle p-navigation__link">LXCFS</a>
           <ul class="p-subnav__items" id="link-3-menu" aria-hidden="true">
             <li>
               <a href="#" class="p-subnav__item">Introduction</a>
@@ -69,9 +69,9 @@
           </ul>
         </li>
       </ul>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link p-subnav" role="menuitem" id="link-1">
-          <a class="p-subnav__toggle" aria-controls="account-menu">
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item p-subnav" role="menuitem" id="link-1">
+          <a class="p-subnav__toggle p-navigation__link" aria-controls="account-menu">
             My account
           </a>
           <ul class="p-subnav__items--right" id="account-menu" aria-hidden="true">
diff --git a/docs/examples/patterns/search-box/navigation-dark.html b/docs/examples/patterns/search-box/navigation-dark.html
index c232032ef4..961eb61bf3 100644
--- a/docs/examples/patterns/search-box/navigation-dark.html
+++ b/docs/examples/patterns/search-box/navigation-dark.html
@@ -8,7 +8,7 @@
   <div class="p-navigation__row">
     <div class="p-navigation__banner">
       <div class="p-navigation__logo">
-        <a class="p-navigation__link" href="#">
+        <a class="p-navigation__item" href="#">
           <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/3c7954dd-logo-canonical-white.svg" alt="" width="95" />
         </a>
       </div>
@@ -19,12 +19,12 @@
       <span class="u-off-screen">
         <a href="#main-content">Jump to main content</a>
       </span>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link" role="menuitem"><a href="#">Products</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">Services</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">Partners</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">About</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">Partners</a></li>
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Products</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Services</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Partners</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">About</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Partners</a></li>
       </ul>
       <form class="p-search-box is-dark">
         <input type="search" class="p-search-box__input" name="search" placeholder="Search" required>
diff --git a/docs/examples/patterns/search-box/navigation.html b/docs/examples/patterns/search-box/navigation.html
index 68cb00c896..baf2fac844 100644
--- a/docs/examples/patterns/search-box/navigation.html
+++ b/docs/examples/patterns/search-box/navigation.html
@@ -8,7 +8,7 @@
   <div class="p-navigation__row">
     <div class="p-navigation__banner">
       <div class="p-navigation__logo">
-        <a class="p-navigation__link" href="#">
+        <a class="p-navigation__item" href="#">
           <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/5d6da5c4-logo-canonical-aubergine.svg" alt="" width="95" />
         </a>
       </div>
@@ -19,12 +19,12 @@
       <span class="u-off-screen">
         <a href="#main-content">Jump to main content</a>
       </span>
-      <ul class="p-navigation__links" role="menu">
-        <li class="p-navigation__link" role="menuitem"><a href="#">Products</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">Services</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">Partners</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">About</a></li>
-        <li class="p-navigation__link" role="menuitem"><a href="#">Partners</a></li>
+      <ul class="p-navigation__items" role="menu">
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Products</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Services</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Partners</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">About</a></li>
+        <li class="p-navigation__item" role="menuitem"><a class="p-navigation__link" href="#">Partners</a></li>
       </ul>
       <form class="p-search-box">
         <input type="search" class="p-search-box__input" name="search" placeholder="Search" required>

From 84f100bed7b37d6e5837995d8092b764791e9e22 Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Wed, 26 Feb 2020 16:54:10 +0100
Subject: [PATCH 5/8] Update docs layout to use new navigation class names

---
 docs/_layouts/default.html | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index 63999e4404..ca5779cdf5 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -27,7 +27,7 @@
       <div class="p-navigation__row--full-width">
         <div class="p-navigation__banner">
           <div class="p-navigation__logo">
-            <a class="p-navigation__link" href="https://vanillaframework.io">
+            <a class="p-navigation__item" href="https://vanillaframework.io">
               <img class="p-navigation__image" src="https://assets.ubuntu.com/v1/d96d86b5-vanilla_black-orange_hex.svg" alt="Vanilla framework logo">
             </a>
           </div>
@@ -41,12 +41,12 @@
           <span class="u-off-screen">
             <a href="#main-content">Jump to main content</a>
           </span>
-          <ul class="p-navigation__links">
-              <li class="p-navigation__link {% if '/examples' not in path %}is-selected{% endif %}"><a href="/">Docs</a></li>
-              <li class="p-navigation__link {% if '/examples' in path %}is-selected{% endif %}"><a href="/examples">Examples</a></li>
-              <li class="p-navigation__link"><a href="https://vanillaframework.io/accessibility">Accessibility</a></li>
-            <li class="p-navigation__link"><a href="https://vanillaframework.io/browser-support">Browser support</a></li>
-            <li class="p-navigation__link"><a href="https://vanillaframework.io/contribute">Contribute</a></li>
+          <ul class="p-navigation__items">
+            <li class="p-navigation__item {% if '/examples' not in path %}is-selected{% endif %}"><a class="p-navigation__link" href="/">Docs</a></li>
+            <li class="p-navigation__item {% if '/examples' in path %}is-selected{% endif %}"><a class="p-navigation__link" href="/examples">Examples</a></li>
+            <li class="p-navigation__item"><a class="p-navigation__link" href="https://vanillaframework.io/accessibility">Accessibility</a></li>
+            <li class="p-navigation__item"><a class="p-navigation__link" href="https://vanillaframework.io/browser-support">Browser support</a></li>
+            <li class="p-navigation__item"><a class="p-navigation__link" href="https://vanillaframework.io/contribute">Contribute</a></li>
           </ul>
           <form class="p-search-box" action="/search">
             <input type="search" id="search-docs" class="p-search-box__input" name="q" {% if query %}value="{{ query }}"{% endif %} placeholder="Search the docs" title="Search the documentation" required />

From 4aab7ac8189aca34b764f1651a851c4fc27d11c7 Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Thu, 27 Feb 2020 10:51:20 +0100
Subject: [PATCH 6/8] Update documentation with info about new nav classes

---
 docs/_layouts/default.html  |  6 +--
 docs/component-status.md    | 76 ++++++++++++++++++++++---------------
 docs/patterns/navigation.md | 14 +++++++
 3 files changed, 63 insertions(+), 33 deletions(-)

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index ca5779cdf5..451944bf4e 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -80,7 +80,7 @@
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/base/forms' %}is-active{% endif %}" href="/base/forms">Forms</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/base/reset' %}is-active{% endif %}" href="/base/reset">Reset</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/base/tables' %}is-active{% endif %}" href="/base/tables">Tables</a></li>
-                  <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/base/typography' %}is-active{% endif %}" href="/base/typography">Typography</a><div class="p-label--updated u-float-right u-no-margin--bottom">Updated</div></li>
+                  <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/base/typography' %}is-active{% endif %}" href="/base/typography">Typography</a></li>
                 </ul>
               </li>
 
@@ -92,7 +92,7 @@
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/breadcrumbs' %}is-active{% endif %}" href="/patterns/breadcrumbs">Breadcrumbs</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/buttons' %}is-active{% endif %}" href="/patterns/buttons">Buttons</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/card' %}is-active{% endif %}" href="/patterns/card">Cards</a></li>
-                  <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/contextual-menu' %}is-active{% endif %}" href="/patterns/contextual-menu">Contextual menu</a><div class="p-label--updated u-float-right u-no-margin--bottom">Updated</div></li>
+                  <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/contextual-menu' %}is-active{% endif %}" href="/patterns/contextual-menu">Contextual menu</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/grid' %}is-active{% endif %}" href="/patterns/grid">Grid</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/heading-icon' %}is-active{% endif %}" href="/patterns/heading-icon">Heading icon</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/icons' %}is-active{% endif %}" href="/patterns/icons">Icons</a></li>
@@ -106,7 +106,7 @@
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/media-object' %}is-active{% endif %}" href="/patterns/media-object">Media object</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/modal' %}is-active{% endif %}" href="/patterns/modal">Modal</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/muted-heading' %}is-active{% endif %}" href="/patterns/muted-heading">Muted heading</a></li>
-                  <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/navigation' %}is-active{% endif %}" href="/patterns/navigation">Navigation</a></li>
+                  <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/navigation' %}is-active{% endif %}" href="/patterns/navigation">Navigation</a><div class="p-label--updated u-float-right u-no-margin--bottom">Updated</div></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/notification' %}is-active{% endif %}" href="/patterns/notification">Notifications</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/pagination' %}is-active{% endif %}" href="/patterns/pagination">Pagination</a></li>
                   <li class="p-sidebar-nav__item"><a class="p-link--soft {% if path == '/patterns/pull-quote' %}is-active{% endif %}" href="/patterns/pull-quote">Quotes</a></li>
diff --git a/docs/component-status.md b/docs/component-status.md
index f7305080af..f406a82c03 100644
--- a/docs/component-status.md
+++ b/docs/component-status.md
@@ -10,14 +10,42 @@ context:
 
 When we add, make significant updates, or deprecate a component we update their status so that it’s clear what’s available to use. Check back here anytime to see current status information.
 
-### What's new in Vanilla 2.7
+### What's new in Vanilla 2.8
 
 <table>
   <thead>
     <tr>
-      <th style="width: 25%">Component</th>
-      <th style="width: 25%">Status</th>
-      <th style="width: 50%">Notes</th>
+      <th style="width: 20%">Component</th>
+      <th style="width: 10%">Status</th>
+      <th style="width: 10%">Version</th>
+      <th style="width: 60%">Notes</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th><a href="/patterns/navigation">Navigation</a></th>
+      <td><div class="p-label--updated">Updated</div></td>
+      <td>2.8.0</td>
+      <td>New navigation classes (<code>p-navigation__items</code>, <code>p-navigation__item</code>, <code>p-navigation__link</code>) were added to replace existing (<code>p-navigation__links</code>, <code>p-navigation__link</code>, and classless <code>&lt;a&gt;</code>).</td>
+    </tr>
+    <tr>
+      <th><a href="/patterns/navigation">Navigation</a></th>
+      <td><div class="p-label--deprecated">Deprecated</div></td>
+      <td>2.8.0</td>
+      <td>Navigation classes <code>p-navigation__links</code>, <code>p-navigation__link</code>, and classless <code>&lt;a&gt;</code> are deprecated and will be removed in future release v3.0. Please use new class names (<code>p-navigation__items</code>, <code>p-navigation__item</code>, <code>p-navigation__link</code>) instead.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Previously in Vanilla
+
+<table>
+  <thead>
+    <tr>
+      <th style="width: 20%">Component</th>
+      <th style="width: 10%">Status</th>
+      <th style="width: 10%">Version</th>
+      <th style="width: 60%">Notes</th>
     </tr>
   </thead>
   <tbody>
@@ -25,96 +53,84 @@ When we add, make significant updates, or deprecate a component we update their
     <tr>
       <th><a href="/patterns/contextual-menu#theming">Contextual menu</a></th>
       <td><div class="p-label--updated">Updated</div></td>
+      <td>2.7.0</td>
       <td>Added dark theme to contextual menu.</td>
     </tr>
     <tr>
       <th><a href="/base/typography#heading-classes">Heading classes</a></th>
       <td><div class="p-label--updated">Updated</div></td>
+      <td>2.7.0</td>
       <td>New heading classes with numbers (<code>p-heading--1</code>, ...) were added for consistency with other class names we use.</td>
     </tr>
     <tr>
       <th><a href="/base/typography#heading-classes">Heading classes</a></th>
       <td><div class="p-label--deprecated">Deprecated</div></td>
+      <td>2.7.0</td>
       <td>Heading classes with numbers as words (<code>p-heading--one</code>, <code>--two</code>, ...) are deprecated and will be removed in future release v3.0. Please use class names with numbers (<code>p-heading--1</code>, <code>--2</code>, ...) instead.</td>
     </tr>
-  </tbody>
-</table>
 
-#### Previously in Vanilla 2.6
-
-<table>
-  <thead>
-    <tr>
-      <th style="width: 25%">Component</th>
-      <th style="width: 25%">Status</th>
-      <th style="width: 50%">Notes</th>
-    </tr>
-  </thead>
-  <tbody>
     <tr>
       <th><a href="/base/forms/#range">Range input</a></th>
       <td><div class="p-label--new">New</div></td>
+      <td>2.6.0</td>
       <td>Styling of Slider component was added to all <code>&lt;input type="range"&gt;</code> elements by default. This makes <code>p-slider</code> class optional for styling range inputs.</td>
     </tr>
     <tr>
       <th><a href="/base/forms/#checkbox">Checkbox, radio button</a></th>
       <td><div class="p-label--updated">Updated</div></td>
+      <td>2.6.0</td>
       <td>New `is-table-header` added to properly align checkboxes and radio buttons used in table headers.</td>
     </tr>
     <tr>
       <th><a href="/patterns/slider">Slider</a></th>
       <td><div class="p-label--updated">Updated</div></td>
+      <td>2.6.0</td>
       <td>Styling of Slider component was added to all <code>&lt;input type="range"&gt;</code> elements by default. This makes <code>p-slider</code> class optional for styling range inputs.</td>
     </tr>
-  </tbody>
-</table>
 
-#### Previously in Vanilla 2.5
-
-<table>
-  <thead>
-    <tr>
-      <th style="width: 25%">Component</th>
-      <th style="width: 25%">Status</th>
-      <th style="width: 50%">Notes</th>
-    </tr>
-  </thead>
-  <tbody>
     <tr>
       <th><a href="/patterns/contextual-menu/#indicator">Contextual menu</a></th>
       <td><div class="p-label--new">New</div></td>
+      <td>2.5.0</td>
       <td>Optional state indicator was added to contextual menu</td>
     </tr>
     <tr>
       <th><a href="/utilities/font-metrics/">Font metrics</a></th>
       <td><div class="p-label--new">New</div></td>
+      <td>2.5.0</td>
       <td>Added <code>u-visualise-font-metrics</code> utility to visualise font metrics</td>
     </tr>
     <tr>
       <th><a href="/base/typography/#line-length">Line length</a></th>
       <td><div class="p-label--new">New</div></td>
+      <td>2.5.0</td>
       <td>Added <code>$max-width--default</code> variable and <code>u-no-max-width</code> utility to control line length</td>
     </tr>
     <tr>
       <th><a href="/utilities/table-cell-padding-overlap/">Table cell padding overlap</a></th>
       <td><div class="p-label--new">New</div></td>
+      <td>2.5.0</td>
       <td>Added <code>u-table-cell-padding-overlap</code> utility to overlap table cell padding</td>
     </tr>
     <tr>
       <th><a href="/utilities/truncate/">Truncation</a></th>
       <td><div class="p-label--new">New</div></td>
+      <td>2.5.0</td>
       <td>Added <code>u-truncate</code> utility to truncate text with ellipsis</td>
     </tr>
     <tr>
       <th><a href="/patterns/icons/#social">Social icons</a></th>
       <td><div class="p-label--updated">Updated</div></td>
+      <td>2.5.0</td>
       <td>Updated style of social icons. Added new <code>.p-icon--rss</code> and <code>p-icon--email</code> icons.</td>
     </tr>
     <tr>
       <th><a href="/patterns/icons/#social">Social icons</a></th>
       <td><div class="p-label--deprecated">Deprecated</div></td>
+      <td>2.5.0</td>
       <td>We will be removing <code>p-icon--canonical</code> and <code>p-icon--ubuntu</code> from social icon set in future release v3.0</td>
     </tr>
+
   </tbody>
 </table>
 
diff --git a/docs/patterns/navigation.md b/docs/patterns/navigation.md
index 9af2604f1f..df22bfa868 100644
--- a/docs/patterns/navigation.md
+++ b/docs/patterns/navigation.md
@@ -8,6 +8,8 @@ context:
 
 <hr>
 
+<span class="p-label--updated">Updated</span>
+
 Vanilla includes a simple navigation bar that you can add to the top of your
 sites.
 
@@ -34,6 +36,18 @@ by adjusting the `$breakpoint-navigation-threshold` in `_settings_breakpoints.sc
 View example of the navigation pattern
 </a>
 
+<span class="p-label--deprecated">Deprecated</span>
+
+In Vanilla 2.8 we deprecated the use of `p-navigation__links`, `p-navigation__link` and classless `<a>` in the navigation. Support for these classes will be removed in future version 3.0.
+
+You should use `p-navigation__items`, `p-navigation__item` and `<a class="p-navigation__link">` instead.
+
+To update to new class names:
+
+- rename all occurrences of `p-navigation__links` to `p-navigation__items`
+- rename all occurrences of `p-navigation__link` to `p-navigation__item`
+- add `p-navigation__link` class to all `<a>` elements that are direct child of `p-navigation__item`
+
 ### Sub-navigation
 
 Sub-navigation drop-down menus can be added to the navigation by including one

From 4d6b64ec49ef824c116b9cb795321552fe2859ce Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Fri, 28 Feb 2020 09:14:58 +0100
Subject: [PATCH 7/8] Updates to subnav example script.

---
 docs/examples/patterns/navigation/_script.js | 35 ++++++++++----------
 1 file changed, 17 insertions(+), 18 deletions(-)

diff --git a/docs/examples/patterns/navigation/_script.js b/docs/examples/patterns/navigation/_script.js
index 9f96d9ba02..e980e48625 100644
--- a/docs/examples/patterns/navigation/_script.js
+++ b/docs/examples/patterns/navigation/_script.js
@@ -1,25 +1,24 @@
 /**
-  Opens a given subnav by applying is-active class to it
+  Toggles visibility of given subnav by toggling is-active class to it
   and setting aria-hidden attribute on dropdown contents.
   @param {HTMLElement} subnav Root element of subnavigation to open.
 */
-function openSubnav(subnav) {
-  subnav.classList.add('is-active');
-  var toggle = subnav.querySelector('.p-subnav__toggle');
-  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
-  dropdown.setAttribute('aria-hidden', 'true');
-}
+function toggleSubnav(subnav, open) {
+  if (open) {
+    subnav.classList.add('is-active');
+  } else {
+    subnav.classList.remove('is-active');
+  }
 
-/**
-  Closes a given subnav by removing is-active class to it
-  and setting aria-hidden attribute on dropdown contents.
-  @param {HTMLElement} subnav Root element of subnavigation to open.
-*/
-function closeSubnav(subnav) {
-  subnav.classList.remove('is-active');
   var toggle = subnav.querySelector('.p-subnav__toggle');
-  var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
-  dropdown.setAttribute('aria-hidden', 'false');
+
+  if (toggle) {
+    var dropdown = document.getElementById(toggle.getAttribute('aria-controls'));
+
+    if (dropdown) {
+      dropdown.setAttribute('aria-hidden', open ? 'true' : false);
+    }
+  }
 }
 
 /**
@@ -28,7 +27,7 @@ function closeSubnav(subnav) {
 function closeAllSubnavs() {
   var subnavs = document.querySelectorAll('.p-subnav');
   for (var i = 0, l = subnavs.length; i < l; i++) {
-    closeSubnav(subnavs[i]);
+    toggleSubnav(subnavs[i], false);
   }
 }
 
@@ -46,7 +45,7 @@ function setupSubnavToggle(subnavToggle) {
 
     closeAllSubnavs();
     if (!isActive) {
-      openSubnav(subnav);
+      toggleSubnav(subnav, true);
     }
   });
 }

From 02b057ab53301e7ce6299f08f5f82708d3961392 Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Fri, 28 Feb 2020 09:15:46 +0100
Subject: [PATCH 8/8] Bump version to 2.8.0

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 7233af197d..2890983226 100644
--- a/package.json
+++ b/package.json
@@ -37,7 +37,7 @@
     "clean": "rm -rf build docs/static/css node_modules/ yarn-error.log",
     "percy": "percy exec -- node snapshots.js"
   },
-  "version": "2.7.1",
+  "version": "2.8.0",
   "files": [
     "/scss",
     "!/scss/docs"