Enhancing styling with Pico CSS and adding some features

[Ahmedmhmud]

I replaced water.css with Pico CSS for more modern styling and fixing the ToC format and highlighting, also enhancing the code block, That was enhancing of the pull request #1671

This is the current state:

[jdesrosiers]

This isn't quite what I was expecting. There's so little difference between this and what I had, I'm questioning whether pico is necessary. You're customizing pico so much, is there anything left of pico? The point of something like pico (or water) is that it provides all the general styling and we can keep our stylesheet very simple and a cover only a few customizations specific to us. For example, I expect the code block titles and toc to be in our stylesheet, but I don't expect to see things like headings. I expect maybe some pico css variables being set, but this looks like it's replacing most of what I expect pico to give us.

[Ahmedmhmud]

I understand now where is the mistake
I will remove the customizations that are overriding the pico styling and in the worst-case I will try another alternative that give a good styling without extra code and keeps the sheetstyle simple

[Ahmedmhmud]

I'll leave the newest update for you to see whenever you are free @jdesrosiers , @gregsdennis
What's new:

• Removing all the extra unnecessary customizations

That is the final look so far:

[jdesrosiers]

I pushed some changes cleaning up more more stuff that should be handled by pico.

[Ahmedmhmud]

Great improvements!
The last thing now is to fix padding and margins to get the page a nice format
I'll do it and see if there is anything else

[Ahmedmhmud]

Hi, @jdesrosiers
I think it is alright now and I'll leave the code review to you and @gregsdennis whoever is free

[jdesrosiers]

You implemented the padding in a place that only applies when the screen is larger. I updated the solution so that it always applies. I also addressed a problem where wide tables could make the whole page scroll horizontally. Now only the table scrolls.

[jdesrosiers]

I think we have a good baseline now and can do some customization from here. Honestly, I'm not too happy with the way it looks. It doesn't feel like a standards document to me. I especially hate the neon blue primary link color. It looks more like a Las Vegas show than a standards document. Pico has a lot of variables we can use to tweak the look and feel. Let's see what we can do to make it look more serious.

[Ahmedmhmud]

Oh.. my bad, I made it so it was required to have a screen more than 64rem, thanks for the observation
So for colors I will try some variables and see if it gets more standard and inform you with the newest update

[Ahmedmhmud]

I made the links looks better with changing color to make the whole thing looks more standard, any other recommendations?

[jdesrosiers]

It looks better, but I'm not sure about removing the underline on links. That's part of user feedback to know its clickable. I see pico uses a different color for hover, but the colors are so similar now that it's barely noticeable. I think since we don't have the UI experience to do this right, we should stick with the traditional underline.

I wonder if a different font will make it look more like a standard.

Do you think you can do something about the horizontal scroll that shows up in the left column sometimes.

Screencast.From.2026-03-02.10-31-39.mp4

[Ahmedmhmud]

Ok deal
I will change the links to be underlined, try a new font to see if it helps, change the color to make the hover effect appears and finally try to solve the horizontal scroll bug in the ToC

[jdesrosiers]

Ahh, I see the problem with the scrolling is that long words can overflow the side bar. That's the kind of problem I was talking about when I said we might have problems with indentation. I tried something different to give use more space. First, I gave the side bar some more space. Then, I reduced the indentation significantly and added a horizontal line to better show the hierarchy.

I also cleaned up some styling related to both line and block code.

More exciting, however, is that I figured out a color scheme I think I'm happy with. It occurred to me to use the color palette from the code highlighting as a reference and starting point. With a few tweaks, I'm happy with how it came out.

[Ahmedmhmud]

Yes, I think it looks great now.
It is now like a standard documentation as we was hoping

[gregsdennis]

This looks really good, guys.

I did notice that we have some places where keywords link to their respective sections, but these are the exception. Usually they're not linked.

I've added an item to #1612 to cover this, so not critical for this work.

[jdesrosiers]

I'm going to go ahead and merge. I'm sure we're find more things that need tweaking, but I think this is a good solid base at this point.