@bmartinezcalvo We originally had the design tokens above components for the reason you outlined in the task description, but decided to move them under components since there are a lot of them and the long list obscures the component documentation, which we exact will be used more often than the design tokens visualizations. We could certainly revisit this decision, or come up with alternate solutions (e.g. collapse the sidebar sections so, for example, the list of design tokens pages doesn't display in the sidebar until you land on the design tokens intro page). In general, the length of the sidebar content is problematic.

Also, with Vitepress, you can have different sidebars depending on the path you're on. We could consider doing something like the GitHub primer site, where they have links in the header for "design" and "build", and each of those sections of the site has its own sidebar.

In T305353#7829154, @AnneT wrote:

@bmartinezcalvo We originally had the design tokens above components for the reason you outlined in the task description, but decided to move them under components since there are a lot of them and the long list obscures the component documentation, which we exact will be used more often than the design tokens visualizations. We could certainly revisit this decision, or come up with alternate solutions (e.g. collapse the sidebar sections so, for example, the list of design tokens pages doesn't display in the sidebar until you land on the design tokens intro page). In general, the length of the sidebar content is problematic.

@AnneT I know the length of the sidebar content is too long and problematic, it's the reason why I proposed also in this task to add accordions in each main section to hide/show all subsections. Something like this:

With this solution we could view all main sidebar sections in the first glance. Also we could decide if we want to have open by default the Components section since it's the most important section as you comment.

In my opinion we don't have to reflect the internal logic of implementation in the navigation. Tokens are important and we talk about the necessity for them to be built and used in several places in the documentation.
Nonetheless I'm convinced the average user of Codex demo page is more interested in the components list than in the tokens. An accordion could maybe help, but would mean an extra click. Something that gets nerve-wrecking fast, if one section is the by far most used (to be evaluated).

In T305353#7875292, @Volker_E wrote:

In my opinion we don't have to reflect the internal logic of implementation in the navigation. Tokens are important and we talk about the necessity for them to be built and used in several places in the documentation.
Nonetheless I'm convinced the average user of Codex demo page is more interested in the components list than in the tokens. An accordion could maybe help, but would mean an extra click. Something that gets nerve-wrecking fast, if one section is the by far most used (to be evaluated).

@Volker_E I don't think that one more click for accordion would make the user gets stressed, I think an accordion here would order our sections and would give the user more peace of mind, although doing one more click. Also, we could add an accordion in each section and leave the components section opened by default since it's the most important section to view.

Just to let you know, some small improvement on the sidebar and its grouping have being achieved as part of: https://phabricator.wikimedia.org/T309109

Further conversation needed here to define what is the team agrees to be the way forward

I'm still convinced that most folks are going for Components first, then icons, then tokens. We should orient on our users and not on our architecture.

In T305353#8015528, @Volker_E wrote:

I'm still convinced that most folks are going for Components first, then icons, then tokens. We should orient on our users and not on our architecture.

I agree with @Volker_E we could orient on our users instead on our architecture.

In T305353#7832588, @bmartinezcalvo wrote:

In T305353#7829154, @AnneT wrote:

@bmartinezcalvo We originally had the design tokens above components for the reason you outlined in the task description, but decided to move them under components since there are a lot of them and the long list obscures the component documentation, which we exact will be used more often than the design tokens visualizations. We could certainly revisit this decision, or come up with alternate solutions (e.g. collapse the sidebar sections so, for example, the list of design tokens pages doesn't display in the sidebar until you land on the design tokens intro page). In general, the length of the sidebar content is problematic.

@AnneT I know the length of the sidebar content is too long and problematic, it's the reason why I proposed also in this task to add accordions in each main section to hide/show all subsections. Something like this:

With this solution we could view all main sidebar sections in the first glance. Also we could decide if we want to have open by default the Components section since it's the most important section as you comment.

About the organization, as I commented here some time ago the organization that seems more logical to me is:

1. Design Tokens
2. Icons
3. Components
4. Patterns (if we add them in the future)

It' the most logical to me since without tokens and without icons we couldn't create components, for this reason they are organized from small to large.

But, the most important thing we should update in our left menu (apart from organize our sections) is to add an accordion on each section to be able to show/hide the info inside. I think this is one of the most important improvements in our left menu since now the user needs to do scroll to read all the left menu sections and subsections.