chore: Issue 2426 - Updated documentation for vf-details

components/vf-details/CHANGELOG.md

@@ -1,3 +1,7 @@
+### 1.2.2
+
+* Changed: Updated documentation  [Tracking issue](https://github.com/visual-framework/vf-core/issues/2127)
+
 ### 1.2.1
 
 * Updated status to live - [Tracking issue](https://github.com/visual-framework/vf-core/issues/2170).

components/vf-details/README.md

@@ -4,16 +4,100 @@
 
 ## About
 
-Use this interactive accordion-link component in places where information is optional.
+Use `vf-details` to let users reveal optional supporting information without leaving the page.
 
 ## Usage
 
-- This component makes use of the [HTML `details` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details#attr-open).
-- To toggle the default state, the `open` attribute: `<details class="vf-details" open>`.
+`vf-details` is the Visual Framework disclosure component. It hides supplementary information behind a short, descriptive summary until the user chooses to reveal it.
+
+Information inside a disclosure must always be optional to read - to be helpful, not essential. Users should be able to understand the page and complete their main task(s) without opening it.
+
+A disclosure component can contribute to page height reduction, but should not reduce the user's mental effort to find, remember, understand and compare information. Hiding content can increase this effort when users must open several sections.
+
+<strong>Top tip: review and simplify the content before introducing a disclosure component.</strong>
+
+### When to use
+
+Use `vf-details` for:
+
+- Short supplementary explanations that some users may need.
+- Additional context that is not required to understand the main content.
+- Optional background information or definitions.
+- Comparing content that is related.
+
+Only use the component after confirming that the information can safely be hidden.
+
+### When not to use
+
+Do not use `vf-details` for:
+
+- Information users need to understand the page.
+- Information required to complete a task.
+- Forms, filters or other task controls.
+- Large amounts of text or complex instructions.
+- Displaying data, tables, charts, figures, images or other assets.
+- Unrelated sections placed together to shorten a page.
+- Disclosures nested inside other disclosures.
+
+When the disclosed content needs primary or secondary actions, consider a dedicated page or a task-focused pattern such as a panel or modal. When users need to compare detailed information, keep it visible or use a structure designed for comparison.
+
+### Single disclosures
+
+`vf-details` is by default a single disclosure element. The component uses the native `<details>` and `<summary>` elements. Omitting the open attribute (<details class="vf-details" open>) produces the native closed state.
+
+You can use the component when displaying a single piece of optional supporting information.
+
+A single disclosure should:
+
+- Be closed by default.
+- Have a short and specific summary.
+- Contain no more than three short paragraphs of text.
+- Contain only one level of information.
+- Use a text link as its only additional interaction, when required.
+- Remain understandable when viewed separately from other disclosures.
+
+Do not place a disclosure around one short sentence simply to reduce page height. If the content is brief and useful to most users, keep it visible.
+
+If a disclosure needs to be open when the page loads, reconsider whether the information should be hidden at all.
+
+#### Using `vf-stack` and `vf-grid`
+
+To create multiple stacked `vf-details` components, you can utilise `vf-stack` or `vf-grid` within the div element.
+
+Use either layout utility to arrange a group vertically. The layout component controls the space between each disclosure; it does not change how the disclosures behave.
+
+### Content guidance
+
+#### Summary labels
+
+The summary is the label users select to reveal the content. It must describe what will appear when the disclosure is opened.
+
+Summary labels should:
+
+- Be short and specific.
+- Use sentence case.
+- Make sense without the expanded content.
+- Be unique within a group.
+- Use familiar language.
+- Describe the information rather than the interaction.
+
+#### Expanded content
+
+Expanded content should:
+
+- Mainly consist of text.
+- An inline link is the only recommended interaction inside expanded content.
+- Be concise and easy to understand at a glance.
+- Contain no more than three short paragraphs.
+- Directly answer or explain the summary.
+- Use the same terminology as the surrounding page.
+- Remain supplementary to the primary experience.
+
+Do not use disclosures to store content removed from the main page without first reviewing whether it is still needed.
 
 ## Install
 
-This repository is distributed with [npm][https://www.npmjs.com/]. After [installing npm][https://www.npmjs.com/get-npm] and [yarn](https://classic.yarnpkg.com/en/docs/install), you can install `vf-details` with this command.
+This repository is distributed with [npm](https://www.npmjs.com/). After [installing npm](https://www.npmjs.com/get-npm) and [yarn](https://classic.yarnpkg.com/en/docs/install), you can install `vf-details` with this command.
 
 ```
 $ yarn add --dev @visual-framework/vf-details