Merge branch 'elastic:main' into main

src-docs/src/views/breadcrumbs/breadcrumbs_example.js

@@ -57,6 +57,13 @@ export const BreadcrumbsExample = {
         </Link>{' '}
         should be used for application-wide navigation.
       </p>
+      <p>
+        See{' '}
+        <Link to="/navigation/tabs/guidelines">
+          <strong>EuiTabs guidelines</strong>
+        </Link>{' '}
+        if your application requires breadcrumbs and tabs on the same view.
+      </p>
     </EuiText>
   ),
   sections: [

src-docs/src/views/flex/flex_example.js

@@ -362,28 +362,6 @@ export const FlexExample = {
         </FlexItemHighlightWrapper>
       ),
     },
-    {
-      title: 'Allowing flex items to wrap',
-      source: [
-        {
-          type: GuideSectionTypes.JS,
-          code: flexGroupWrapSource,
-        },
-      ],
-      text: (
-        <p>
-          You can set <EuiCode>wrap</EuiCode> on <strong>EuiFlexGroup</strong>{' '}
-          if it contains <strong>EuiFlexItems</strong> with minimum widths,
-          which you want to wrap as the container becomes narrower.
-        </p>
-      ),
-      snippet: flexGroupWrap,
-      demo: (
-        <FlexItemHighlightWrapper>
-          <FlexGroupWrap />
-        </FlexItemHighlightWrapper>
-      ),
-    },
     {
       source: [
         {
@@ -455,6 +433,28 @@ export const FlexExample = {
         </FlexItemHighlightWrapper>
       ),
     },
+    {
+      title: 'Allowing flex items to wrap',
+      source: [
+        {
+          type: GuideSectionTypes.JS,
+          code: flexGroupWrapSource,
+        },
+      ],
+      text: (
+        <p>
+          You can set <EuiCode>wrap</EuiCode> on <strong>EuiFlexGroup</strong>{' '}
+          if it contains <strong>EuiFlexItems</strong> with minimum widths,
+          which you want to wrap as the container becomes narrower.
+        </p>
+      ),
+      snippet: flexGroupWrap,
+      demo: (
+        <FlexItemHighlightWrapper>
+          <FlexGroupWrap />
+        </FlexItemHighlightWrapper>
+      ),
+    },
     {
       title: 'Responsive flex groups',
       source: [

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>Do</h2>
+      <p>
+        Follow best practices. Use tabs to organize in-page content. Each tab
+        should contain a segment of information relevant to the current subject.
+        For more UX tips see{' '}
+        <EuiLink href="https://www.nngroup.com/articles/tabs-used-right/">
+          NNG&apos;s article &quot;Tabs, Used Right&quot;
+        </EuiLink>
+        .
+      </p>
+      <h2>Do</h2>
+      <p>
+        For tabs showing primary page content, use the <EuiCode>href</EuiCode>{' '}
+        prop to change the current URL hash. Ensure the tab selection is
+        persisted in the user's navigation history and works with the browser's
+        back button.
+      </p>
+      <EuiSpacer size="xs" />
+      <h2>Do</h2>
+      <p>
+        Ensure when a page is loaded with a URL hash representing a selected tab
+        (as applied by the <EuiCode>href</EuiCode> prop), that the corresponding
+        tab is shown using the <EuiCode>selectedTab</EuiCode> prop.
+      </p>
+      <EuiSpacer size="xs" />
+      <h2>Don't</h2>
+      <p>
+        Apply the <EuiCode>href</EuiCode> prop to change the current page URL
+        hash on more than one set of tabs per page, or non-primary content.
+      </p>
+      <EuiSpacer size="xs" />
+      <h2>Don't</h2>
+      <p>
+        Keep users on the same page visually, but change the higher-level
+        navigation logically. Tabs should keep users at the same place within an
+        application. Breadcrumbs and main navigation should not change. The URL
+        hash is the only thing that should change.
+      </p>
+    </EuiText>
+  </>
+);