mi6 / mi6/ic-design-system

Structure for laying out larger components and their sub components

Open
#653 1 comment 0 reactions 0 assignees View on GitHub
guidance
Dominant language
MDX
Stars
79
Forks
52
Avg merge
18h 58m
Merged PRs (30d)
4

Description

## 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.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing grouping functionality in the left-hand navigation, especially the content style section, and the current guidance, code and accessibility asset-page structure. Define how a complex component group, overview page and sub-component pages should be organized, then confirm that the structure supports the Data Table example and remains searchable and navigable.

Written by the indexing model from the issue text.

Assessment

Domain
design, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.