mi6
Structure for laying out larger components and their sub components
Summary
Design and implement a structure for laying out larger components and their sub-components.
💬 Description
At the minute, we are yet to have a structure on how to deal with the larger components and sub-components in the website. Simply listing them all in the same page for a component such as Data Table will be too much information. The issue will design how this should be laid out.
Currently, each component has its own guidance page with three sections: guidance, code and accessibility. For larger components with lots of features, there will be a lot of content to display on a single page making it harder to navigate and consume. Therefore, these components' guidance should be split into multiple sub-pages that focus on a single sub-component or feature.
To do this, we will use the existing grouping functionality available in the left-hand navigation. We use this already in the styles and accessibility section to provide groupings of content. See the 'content style' section for an example.
Complex component therefore should be structured as follows:
- Complex component group -- Overview -- Sub-component or feature A -- Sub-component or feature B -- Sub-component or feature C
Each page in this group would follow the same asset page structure as normal component pages with guidance, code and accessibility tabs.
On the overview page, the default component can be displayed, or a complex variant showcasing many of the features. The code tab would show high level examples and not contain anything related to specific functionality. The accessibility page again contains info at the top component level, but leaves feature specific info to the sub-pages.
On the sub-component pages, specific examples showing the sub-component functionality is displayed and guided upon. Code and accessibility tabs contain info specific to that sub-component.
As an example, consider how a data tables guidance page may be structured.
Data tables (group)
- Overview
- Visualisation
- Navigation
- Sorting
- Filtering
- Virtualisation
- Editing
The overview page would contain information about data tables at the high level, including when to use versus when not to use, general content guidance and basic configuration.
For changing appearance or other ways of visualizing the data, this guidance would be found on the sub-page for visualization. Same for other specific features such as navigation, sorting, filtering etc.
This approach also scales well as we can simply add new guidance pages for new features as we increment the component and add functionality.
💰 Use value
Help customers navigate our components and sub-components and splits big guidance pages into more manageable and searchable chunks.
This change was given priority 4/5, as part of the website restructure.
Consider using this pattern for the following cases:
Complex components with lots of features
Data table could be split into an overview page for core functionality, and pages for key features, e.g. sorting and filtering.
Components with multiple variants that have lots of guidance
Select could be split into single, multi and searchable, with an overview page that has the guidance that is the same for each.
Button could be split into normal, icon and file-upload.
