[DOCS] Adding guidance to EuiTabs for improved UX

* Adding a Guidance tab to EuiTabs docs
* Providing UX guidance for hash routes and higher-level navigation

src-docs/src/views/tabs/tabs_example.js

@@ -9,9 +9,9 @@ import {
   EuiTab,
   EuiTabbedContent,
   EuiText,
-  EuiLink,
 } from '../../../../src/components';
 
+import TabsGuidance from './tabs_guidance';
 import { tabsConfig } from './playground';
 
 import Tabs from './tabs';
@@ -31,16 +31,13 @@ const controlledSource = require('!!raw-loader!./controlled');
 
 export const TabsExample = {
   title: 'Tabs',
+  guidelines: <TabsGuidance />,
   intro: (
     <EuiText>
       <p>
-        Use tabs to organize <strong>in-page</strong> navigation, segmenting
-        mutually-exclusive content under a single organizational principle. For
-        more guideline usage see{' '}
-        <EuiLink href="https://www.nngroup.com/articles/tabs-used-right/">
-          NNG&apos;s article &quot;Tabs, Used Right&quot;
-        </EuiLink>
-        .
+        Use tabs to organize related but unique content for a single idea or
+        subject. Tabs show and hide content using <strong>in-page</strong>{' '}
+        navigation UI.
       </p>
     </EuiText>
   ),

src-docs/src/views/tabs/tabs_guidance.js

@@ -0,0 +1,53 @@
+import React from 'react';
+
+import {
+  EuiCode,
+  EuiText,
+  EuiLink,
+  EuiSpacer,
+} from '../../../../src/components';
+
+export default () => (
+  <>
+    <EuiText grow={false}>
+      <h2>Follow best practices for tabbed interfaces</h2>
+      <p>
+        Use tabs to organize in-page content. Each tab should contain a segment
+        of information relevant to the current subject. For more best practices
+        see{' '}
+        <EuiLink href="https://www.nngroup.com/articles/tabs-used-right/">
+          NNG&apos;s article &quot;Tabs, Used Right&quot;
+        </EuiLink>
+        .
+      </p>
+      <EuiSpacer size="xs" />
+      <h3>Use props to tailor the user experience</h3>
+      <p>
+        Tab props allow consumers to set the selected tab on first render, and
+        add custom behavior on tab click. For instance, you could use the{' '}
+        <EuiCode>selectedTab</EuiCode> prop to show a second or third tab on
+        page load. You could also use the <EuiCode>onTabClick</EuiCode> prop to
+        add custom click behavior.
+      </p>
+      <EuiSpacer size="xs" />
+      <h3>Manage the user experience if you change routes or URLs</h3>
+      <p>
+        Be sure the correct tab is selected if you use the{' '}
+        <EuiCode>href</EuiCode> prop to append a hash to the current route. If
+        your tab adds a <EuiCode>#tabbedHash</EuiCode> to the URL, the matching
+        tab should be selected when users refresh the page. It can be confusing
+        to users when hash routes do not match a selected tab.
+      </p>
+      <EuiSpacer size="xs" />
+      <h3>Tabs must not update higher-level navigation</h3>
+      <p>
+        Do not update navigation such as{' '}
+        <EuiLink href="/#/navigation/breadcrumbs">breadcrumbs</EuiLink> or{' '}
+        <EuiLink href="/#/navigation/collapsible-nav">navigation menus</EuiLink>{' '}
+        when users click on tabs. Tabs show localized information and it is not
+        always clear what changed if tabs are below the fold or navigation does
+        not match the route.
+      </p>
+    </EuiText>
+  </>
+);