Needs a CSS makeover

[professorhantzen]

This is one of the most clearly-explained documentation centres I've ever seen. But it's also visually "utilitarian" to the point it actually becomes difficult to read and navigate. The previous developer centre ("build") was better in this regard.

For the benefit of coders who may need to switch regularly between the ripple dev portal, Sublime Text, other IDE's and Shell Terminals, could design work also incorporate an (optional) Dark Theme?

Polls I found on the subject showed a consistent preference for Darkness.

[mDuo13]

This is one of the most clearly-explained documentation centres I've ever seen. But it's also visually "utilitarian" to the point it actually becomes difficult to read and navigate. The previous developer centre ("build") was better in this regard.

Aside from a dark theme, can you elaborate what's making it difficult to read and navigate?

[professorhantzen]

Sure - mainly there's inconsistent (random?) vertical and horizontal whitespace everywhere, and too many font-sizes. There's also unnecessarily large amounts of vertical whitespace between list elements and lines of text.

Eg, on this page there are ~9 different sizes for the main font, and vertical and horizontal whitespace appears to have no method or consistency. Five differently-sized vertical gaps are applied in just the area with the world background.

Similar incongruent design can be found throughout the site.

For reference: https://ripple.com/build/ doesn't have such issues. Whitespace is consistent and methodologically applied, and a limitation of 2 or 3 font-sizes are used throughout. Eg, scroll down the main page to the "TUTORIALS", "REFERENCES" menu lists. All whitespace surrounding characters is consistent, and only a single font size is used for the entire section. Clicking on any of the elements brings up a more complicated scenario, but still consistent rules and methodology has been applied and this all assists in readability.

Web-design is a difficult field - CSS is often applied inconsistently across different browser platforms: fonts can appear differently, kerning can vary, anti-aliased versus aliased, resizable displays (meaning user-applied zoom) and different native resolutions and aspect ratios (smartphone in portrait or landscape, versus a desktop or notebook in widescreen display or a 4:3 monitor) all have an impact. Aside from being harder to read, such wide variability in font sizes may exacerbate these issues and is an indication the designer may not fully understand the impact of their design choices. As for whitespace, inconsistencies here not just difficult to read and interpret (think of how religiously such ethics are applied when writing code), it's also an indication that proper bounds have not been applied to the design elements such that they will scale and map consistently across different platforms. I don't want to be harsh, but it honestly looks like whomever put this together doesn't really know what they're doing.

This may not be the best example in the political sense, but have a look at https://www.stellar.org/developers/guides/get-started/create-account.html for an example of clean design for a similarly-sized project. Whitespace is simple and consistent, you can see that there is a clear methodology to elements and how they are spaced both vertically an horizontally, and this remains consistent. Other than the over-extending of the right edge of the code windows (which is arguably a practical choice as some of the example code may extend a long way), I can't fault it. I also see only two font sizes used throughout. Certainly, these aspects make it faster to navigate and ingest. I can't be sure, but it's also highly likely this site will appear without issue on many different systems.

[mDuo13]

We're well aware of the various complications of web design, and admittedly getting all the spacing to be "just right" was not our first priority. (We figure information architecture and overall content are both more important.) I think it's an overstatement to say that most spacing and font-size variances make it "difficult to read and navigate"—except, I guess, for the unfortunate souls who are especially attuned to noticing those things.

We do plan on improving the styles as we can find time—obviously, it's a priorities game, as this stuff competes with time spent on other work like actually researching and writing new content. One of the hardest parts is actually finding all the specific inonsistencies, because it's hard to predict where various CSS rules interact in unexpected ways. (Especially with all the arcane rules already built into Bootstrap.) So, thanks for pointing those out; that makes it much easier to address.

[professorhantzen]

No problem - I figured as much that it might not be a priority, and noted the "beta" tag in that regard.

It could well be I am oversensitive to this stuff, but I only went as far as creating an issue after noticing on reddit a couple of upvoted comments from others also remarking negatively on the CSS/design.

If I may ask, what is the reason for changing the design from what's currently at ripple.com/build?

[patriksletmo]

I'd like to add some comments to this issue after a conversation I had in an internal chat with some other XRPL developers. Please let me know if you'd like me to open another issue instead.

Even though I think that the new design is visually appealing I can't help to notice how the dark theme has made the documentation more difficult to read for me and a couple of others developers. It was suggested that an optional dark theme would be added, but the update changed the design completely, without the option to opt-out of this dark mode.

I would probably not care as much if there were good browser plugins for automatically re-coloring the website in light (think Dark Reader but the opposite), but now that I don't have that option I'd like to see how this can be updated for us with a preference of light theme instead. Especially given that the poll linked in the original post indicates that the preference for both themes are rather similar to each other.

If you'd like, I'm willing to contribute with a pull request.

[mDuo13]

@patriksletmo The ticket for re-adding a light theme is #950. In short, we'd like to do it, and the main limitation is redoing the images to work in both cases or to have multiple versions of the graphics based on theme.