From 738a054f2b8e56d80a7da05d230bc2cee257beb7 Mon Sep 17 00:00:00 2001 From: 1Copenut Date: Wed, 6 Dec 2023 14:38:59 -0600 Subject: [PATCH 1/3] [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 | 13 +++--- src-docs/src/views/tabs/tabs_guidance.js | 53 ++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 8 deletions(-) create mode 100644 src-docs/src/views/tabs/tabs_guidance.js diff --git a/src-docs/src/views/tabs/tabs_example.js b/src-docs/src/views/tabs/tabs_example.js index 91daf00c723..a5d8ed3aac5 100644 --- a/src-docs/src/views/tabs/tabs_example.js +++ b/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: , intro: (

- Use tabs to organize in-page navigation, segmenting - mutually-exclusive content under a single organizational principle. For - more guideline usage see{' '} - - NNG's article "Tabs, Used Right" - - . + Use tabs to organize related but unique content for a single idea or + subject. Tabs show and hide content using in-page{' '} + navigation UI.

), diff --git a/src-docs/src/views/tabs/tabs_guidance.js b/src-docs/src/views/tabs/tabs_guidance.js new file mode 100644 index 00000000000..b4294782b0b --- /dev/null +++ b/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 () => ( + <> + +

Follow best practices for tabbed interfaces

+

+ 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{' '} + + NNG's article "Tabs, Used Right" + + . +

+ +

Use props to tailor the user experience

+

+ 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{' '} + selectedTab prop to show a second or third tab on + page load. You could also use the onTabClick prop to + add custom click behavior. +

+ +

Manage the user experience if you change routes or URLs

+

+ Be sure the correct tab is selected if you use the{' '} + href prop to append a hash to the current route. If + your tab adds a #tabbedHash 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. +

+ +

Tabs must not update higher-level navigation

+

+ Do not update navigation such as{' '} + breadcrumbs or{' '} + navigation menus{' '} + 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. +

+ + +); From 15cb3504187045b111b3370862e366f55b1bdbc1 Mon Sep 17 00:00:00 2001 From: 1Copenut Date: Thu, 7 Dec 2023 10:26:50 -0600 Subject: [PATCH 2/3] Adding EuiTabs guidance cross-link to EuiBreadcrumbs. --- src-docs/src/views/breadcrumbs/breadcrumbs_example.js | 7 +++++++ src-docs/src/views/tabs/tabs_guidance.js | 10 ++++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/src-docs/src/views/breadcrumbs/breadcrumbs_example.js b/src-docs/src/views/breadcrumbs/breadcrumbs_example.js index 1f0c72bfee3..9d3ec472d66 100644 --- a/src-docs/src/views/breadcrumbs/breadcrumbs_example.js +++ b/src-docs/src/views/breadcrumbs/breadcrumbs_example.js @@ -57,6 +57,13 @@ export const BreadcrumbsExample = { {' '} should be used for application-wide navigation.

+

+ See{' '} + + EuiTabs guidelines + {' '} + if your application requires breadcrumbs and tabs on the same view. +

), sections: [ diff --git a/src-docs/src/views/tabs/tabs_guidance.js b/src-docs/src/views/tabs/tabs_guidance.js index b4294782b0b..308fbaf9111 100644 --- a/src-docs/src/views/tabs/tabs_guidance.js +++ b/src-docs/src/views/tabs/tabs_guidance.js @@ -1,4 +1,5 @@ import React from 'react'; +import { Link } from 'react-router-dom'; import { EuiCode, @@ -42,8 +43,13 @@ export default () => (

Tabs must not update higher-level navigation

Do not update navigation such as{' '} - breadcrumbs or{' '} - navigation menus{' '} + + breadcrumbs + {' '} + or{' '} + + navigation menus + {' '} 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. From 28314ad35df5259a51a34b095e6e50c69192da83 Mon Sep 17 00:00:00 2001 From: 1Copenut Date: Fri, 8 Dec 2023 16:42:44 -0600 Subject: [PATCH 3/3] Updated docs based on team feedback. --- src-docs/src/views/tabs/tabs_guidance.js | 52 +++++++++++------------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/src-docs/src/views/tabs/tabs_guidance.js b/src-docs/src/views/tabs/tabs_guidance.js index 308fbaf9111..63ae1397f89 100644 --- a/src-docs/src/views/tabs/tabs_guidance.js +++ b/src-docs/src/views/tabs/tabs_guidance.js @@ -1,5 +1,4 @@ import React from 'react'; -import { Link } from 'react-router-dom'; import { EuiCode, @@ -11,48 +10,43 @@ import { export default () => ( <> -

Follow best practices for tabbed interfaces

+

Do

- 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{' '} + 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{' '} NNG's article "Tabs, Used Right" .

+

Do

+

+ For tabs showing primary page content, use the href{' '} + 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. +

-

Use props to tailor the user experience

+

Do

- 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{' '} - selectedTab prop to show a second or third tab on - page load. You could also use the onTabClick prop to - add custom click behavior. + Ensure when a page is loaded with a URL hash representing a selected tab + (as applied by the href prop), that the corresponding + tab is shown using the selectedTab prop.

-

Manage the user experience if you change routes or URLs

+

Don't

- Be sure the correct tab is selected if you use the{' '} - href prop to append a hash to the current route. If - your tab adds a #tabbedHash 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. + Apply the href prop to change the current page URL + hash on more than one set of tabs per page, or non-primary content.

-

Tabs must not update higher-level navigation

+

Don't

- Do not update navigation such as{' '} - - breadcrumbs - {' '} - or{' '} - - navigation menus - {' '} - 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. + 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.