chore: Issue 2426 - Updated documentation for tabs

components/vf-tabs/CHANGELOG.md

@@ -1,3 +1,7 @@
+### 2.1.12
+
+* Changed: Updated documentation  [Tracking issue](https://github.com/visual-framework/vf-core/issues/2426)
+
 ### 2.1.11
 
 * Changed: Test cases added for React  [Tracking issue](https://github.com/visual-framework/vf-core/issues/2174)

components/vf-tabs/README.md

@@ -8,11 +8,113 @@ The ever-useful tabs. This component works best with the included JS, but you ca
 
 ## Usage
 
-These tabs have been made with accessibility in mind, however tabs should be avoided where content structure avoids the need to use tabs.
+Tabs allow users to switch between a small number of related content sections without leaving the current page or task. Only one tab panel is shown at a time.
 
-Nested tabs are also possible, as demonstrated in the example, however this provides further usability challenges and should be strongly avoided.
+Use tabs when the sections are peers, belong to the same context, and users are likely to switch between them. Do not use tabs to hide important content, shorten a long page or replace page navigation.
 
-### Angular
+### When to use
+
+Use `vf-tabs` when all of the following are true:
+
+- The content can be divided into a small number of related peer sections.
+- Users usually need to view one section at a time.
+- Users may need to switch between sections while staying in the same task.
+- The sections do not need to be compared side by side.
+- The first tab can show the most useful or most common content by default.
+- Panel content appears immediately or uses a clear loading state.
+
+Suitable examples include:
+
+- Grouping a small number of related settings within one task.
+- Organising one item into a few related sections, such as Overview, Details, and Activity.
+
+### When not to use
+
+Do not use `vf-tabs` when:
+
+- Users need to read sections in order.
+- Users need to compare information across sections.
+- Most users need to see information from every section.
+- The sections are separate destinations or pages.
+- The content is long enough to require its own page structure.
+- The tab set would contain too much content, reducing scanability.
+- Important warnings, validation errors, or required information would be hidden.
+- Tabs are being used mainly to make a page appear shorter.
+
+If the content does not meet the usage criteria, consider another pattern.
+
+#### Choose the right pattern for your use case
+
+| User need | Recommended pattern | Reason |
+|---|---|---|
+| Switch between a few peer sections in the same context | Tabs | Keeps users in the same task while changing the visible section |
+| Open and close several sections independently | Details | Allows more than one section to remain open |
+| Reveal one short piece of optional information | Details | Provides a lighter interaction than a full tab set |
+| Compare values, attributes, or results | Table or comparison layout | Keeps related information visible at the same time |
+| Move through sections of a long page | In-page navigation or contents list | Preserves reading order and keeps all content available |
+| Move between separate destinations | Page navigation | Gives each destination its own URL, title, and navigation state |
+| Change the presentation of the same data | Filter, segmented control, or view switcher | Shows that the same content set is being changed or filtered |
+| Complete steps in order | Stepper or sequential page structure | Communicates progress and dependency between steps |
+
+### Anatomy
+
+A tab set contains:
+
+- <strong>Tab list</strong>: the group of tab controls.
+- <strong>Tab labels</strong>: short, clear text that describes the content in each tab panel.
+- <strong>Selected tab</strong>: the active control associated with the visible panel.
+- <strong>Inactive tabs</strong>: available controls that show other panels when selected.
+- <strong>Focus state</strong>: the visible keyboard focus indicator.
+- <strong>Tab panel</strong>: the content area associated with the selected tab.
+- <strong>Panel heading</strong>: a heading that identifies the visible content.
+
+The selected state and focus state must be visually distinct. Selected shows which panel is active. Focus shows which control will respond to the next keyboard action.
+
+### Content guidance
+
+#### Tab labels
+
+Write labels that are short, specific, and easy to scan.
+
+Use:
+
+- One or two words where possible.
+- Sentence case.
+- Parallel wording across the tab set.
+- Labels that describe the panel content.
+
+Avoid:
+
+- Generic labels such as "More", "Other", "Tab 1", or "Information".
+- Repeated labels within the same tab set.
+- Icon-only labels.
+- Labels that rely on badges or counts to make sense.
+- Labels that need to wrap or truncate.
+
+#### Number of tabs
+
+Use two to six tabs as the recommended range.
+
+Six tabs should be treated as an exception and should have a clear user need. Longer tab lists can make labels harder to scan and layouts harder to manage on smaller screens.
+
+If there are more than six sections, consider whether the content would work better as an accordion, in-page navigation, separate pages or another structure.
+
+#### Order and default tab
+
+- Put the most useful or most frequently needed tab first.
+- Keep the order stable.
+- Select one tab by default.
+- Do not reorder tabs based on recent use unless the behaviour is clearly communicated.
+
+#### Panel content
+
+Each panel should have a meaningful heading. Where useful, repeat the tab label as the panel heading so the content remains clear when printed, stacked or viewed without JavaScript.
+
+Place shared instructions, warnings and primary actions outside the tab set when they apply to all panels. Do not hide information that users need to understand another panel.
+
+Keep panel content focused and self-contained. Avoid placing long, complex or required tasks inside hidden panels, especially forms. Forms usually work better outside the tab set, where users can understand the full task, review their answers and find errors without switching between panels.
+
+### Angular support
 
 As of version 2.1.5 vf-tabs has experimental Angular support.
 This package was generated with Angular version 15.2.0 and has been tested on application with Angular version 15.2.0.
@@ -126,7 +228,7 @@ This package was generated with Angular version 15.2.0 and has been tested on ap
   <vf-tabs [tabsdata]="tabsdata"></vf-tabs>
   ```
 
-### React
+### React support
 
 As of version 2.1.6 vf-tabs has experimental React support which has been tested on react version 18.2.0