docs: improves UX UI

[alexialechot]

Description

• #0

This PR solves the issue by

• Merging all separate pages into one unified sidebar
• Making the Learn page the default landing page
• (Planning to add FAQ as a second page in the future)
• Improving sidebar styling and adopting official Studio colors
• Added a Resources page containing all our most important links for easy access

Supporting information

Before

Screen.Recording.2025-11-06.at.16.00.59.mov

After

Screen.Recording.2025-11-06.at.16.01.35.mov

Review guidelines

Estimated Time of Review: 40 minutes

Checklist before merging:

• Confirm that the relevant changelog(s) are up-to-date in case of any user-facing changes
• Add search bar
• Redirect / to /learn/Getting-started/intro

[alexialechot]

Hello team,

I’m really looking forward to all your feedback, not only about the code but also about the UX behavior and the UI.

There are two features missing in this PR:
• The search bar
• Redirect from / to /learn/Getting-started/intro (not sure how to implement it)

Regarding the search bar, I think we need an account with DocSearch / Algolia. Could someone with access to our official email set that up?

Thanks in advance!

[domire8]

I'm initially not convinced by the sidebar. There are many examples now, number growing, and expanding those will make the sidebar super long and difficult to navigate between pages. Have you tried it out with all examples expanded?

[alexialechot]

I'm initially not convinced by the sidebar. There are many examples now, number growing, and expanding those will make the sidebar super long and difficult to navigate between pages. Have you tried it out with all examples expanded?

I understand your point, and it’s valid to consider sidebar length. However I believe this isn’t a real issue because this layout actually simplifies the user journey. Users have everything in one place so they don’t need to search across multiple page. At the same time they don’t have to expand everything if they don’t want to.

We can also address your concern with a compromise: we could make sections uncollapsed by default similar to what React does. This way, the most important items are immediately visible, but the sidebar remains manageable as the number of examples grows. https://react.dev/learn

[eeberhard]

Echoing dominic's point, the single side bar has a risk of being very long and difficult to easily navigate as we add more content. In addition, it's incompatible with the versioning approach of #369 which requires separate sidebars for versioned vs unversioned docs, so at minimum we need two top-level sections.

It also makes the Learn item in the navbar both a bit pointless (since there is only one page) and also too generic (should all content including compatibility tables, setup instructions, examples, API reference be considered "learning"?)

I don't know exactly what the names of those sections in the navbar should be but could be Docs for general (unversioned) documentation, concepts, etc and Examples or Learn for the versioned core info and examples.

Edit: I see you wrote "(Planning to add FAQ as a second page in the future)" so then at least Learn would not be the only item in the navbar

[rrosa24]

I agree with Alexia that the single bar helps the user journey, as I felt there was an expectation before that all pages would be visible (whereas some were hidden behind the other tabs/ buttons). I echo the other feedback that a single tab is confusing. I would instead expect the side menu is open as the default/ accessed by clicking on "AICA Documentation"

[eeberhard]

there was an expectation before that all pages would be visible (whereas some were hidden behind the other tabs/ buttons)

I don't quite understand, could you elaborate?

[rrosa24]

@eeberhard just that in the current docs.aica.tech, when I am technically on the "Getting Started" tab, I get the impression that the left hand menu includes the full docs (whereas it is only the "Getting Started" submenu)

[alexialechot]

In addition, it's incompatible with the versioning approach of #369 which requires separate sidebars for versioned vs unversioned docs, so at minimum we need two top-level sections.

Could you list which docs are versioned and which are unversioned? @eeberhard

I echo the other feedback that a single tab is confusing. I would instead expect the side menu is open as the default/ accessed by clicking on "AICA Documentation"

I also agree that having a single tab/page can be confusing. I initially set it up this way because there will be an FAQ page, and I didn’t want to have to reintroduce the Learn page later. @rrosa24

[eeberhard]

Could you list which docs are versioned and which are unversioned?

"core" versioned docs include the tour of AICA Studio and all guides/examples, and everything else is unversioned

[SprGrf]

I expected not to like the unified sidebar for the reason that was mentioned about the extensive length, but strangely I quite enjoyed having the overview of what is there. I think JTC is a good example, where we previously had the two guides in two different pages. With the new layout I can switch between the two and compare the contents easier. I have no opinion on how this could affect and work with current versioning though.

About the Learn and future FAQ pages; I am not sure if it makes sense to have that distinction there, logically. Help is already an item on the Learn page, why would FAQ be separate? How do we decide what goes where?