Short analysis on visual clarity: Attention, Emphasis, Separation, Grouping and Unambiguity

[fabianwohlfart]

Dear Nuxters,

When I look at the documentation, I often feel overwhelmed by the many options, hints, links to different sections, and the overall interconnectivity. As a trained designer, my first thought was: How can I visually enhance the readability?

I would like to share a brief analysis with you. It may open up a discussion or at least provide some stimuli for thought. I am well aware that the following is highly opinionated. I'm also aware that the Nuxt docs are derived from the Nuxt UI Pro docs template. However, since I primarily use Nuxt directly, I believe this is the appropriate place to address the following.

The focus of this analysis is on achieving clarity in design to make the layout, elements, and behaviors more understandable for users. While individual layout parts, elements, and behaviors may be clear on their own, there is room for improvement when they work together. Enhancing these interactions may improve the overall clarity of the documentation.

(1) Attention

The docs use a 10-column grid. However, the main section is slightly off to the right because the child element also uses a 10-column grid instead of 8.

Paired with the narrow max-width, this layout leads to the blurring of boundaries between navigation, main text, and side content. While reading, your eyes often jump to the navigation, making it harder to read and maintain focus.

One solution would be to consistently use a 10-column grid and adjust the spacing accordingly. I also added a max-w-8xl (96rem) to the wrapper and a max-w-5xl to the navigation and aside sections.

(2) Emphasis

(2.1)

Within the documentation, we have various elements that demand attention: current main navigation, current navigation, current breadcrumb, title, description, current table of contents, text links, inline code, and info boxes.

Emphasis can be very useful as it helps readers scan the text quickly or find specific information. However, every emphasis also interrupts the reader's flow. As a side note, Jan Tschichold, one of the most influential typographers for print, once said: "The addiction to highlight almost half of the words [...] makes the reader feel like they're being considered as idiots."

It's generally agreed that when highlighting elements in a text, it's best to use a single type of emphasis—whether it be bold, italic, color, background-color, underline, or border—so that no one element stands out too much or overwhelms the others.

We can easily balance the emphasis by making the following adjustments:

1. Breadcrumbs should not be green.
2. Remove letter-spacing from the introduction.
3. Use a distinguishable font size (font-xl) for the description text, keep it white, and avoid turning down the color.
4. Avoid using bold for inline code.
5. Avoid using bold for links.
6. Soften the background color of the info boxes.
7. Always place the imperative/verb at the beginning (e.g., "try out…", "read more…", "find other…") and make the entire info box a clickable link.
8. Consider giving all linked boxes a dashed border for consistency.
9. Use white and gray colors for the table of contents instead of adding color

So, we come from here (Original)

To here (Modified Emphasis)

To here (With Grid adjustments)

1. Start by reading the navigation.
2. Jump to the introduction block.
3. Then proceed to the main content.
4. Optionally, explore the aside section afterward.

(2.2)

Another issue with the current emphasis strategy is that the colored boxes vie for attention and compete with the most critical part: code examples. For instance, on the Configuration page, there's a excessive amount of information presented one after the other, with each piece of information emphasized differently.

I believe it would be beneficial to tone down these boxes. While adjusting the background of the boxes, we could also align the color of the inline code with the color of the code examples to enhance consistency. It's reasonable to maintain the strong border color, as it serves as the primary emphasis style.

(3) Separation

Connected to the previously mentioned point about the difficulty of differentiating content due to numerous emphasis levels, it's also challenging to follow the content because there are no clear breaks for the reader to understand where one section ends and another begins.

Headlines could be enhanced by adding an underline and increasing the spacing, especially at the top. This results in more completed sections.

(4) Grouping

There's often a lot to cover regarding various aspects of a particular feature, which is why info boxes are frequently used. However, similar to emphasis, the sheer volume of info boxes can be overwhelming, and it's not always clear how to follow up as a reader.

Group similar elements together: In this example, the reader can better understand that a series of "read more" blocks will follow. (Additionally, each "read more" should be a link itself; in this example, there are two inline links, and the middle info box is a link.)

(5) Unambiguity

Inline code and info boxes are sometimes links, and sometimes they're not. The visual difference lies in a dashed versus a solid border, which can be easily overlooked.

Given 3 seconds to scan the site, it's not immediately clear if "nuxt.config.ts" is clickable or if "defineNuxtConfig" is clickable, and if they are not clickable, why not?

One solution would be to make links appear more like buttons rather than tags. Another option would be to use an arrow, similar to what's done with external links.

The end

I've only picked a few examples, but I'm aware that there are likely many more cases that need careful consideration before implementing any changes. However, I'm confident that the principles of attention, emphasis, separation, grouping, and unambiguity can be applied to those other cases as well. If any of the points resonate with you, I'm happy to help

[benjamincanac]

Hello @fabianwohlfart,

Thanks a lot for taking the time to make this analysis which comes at the perfect time as we're currently working on the next major of Nuxt UI and Nuxt UI Pro.

I will take your suggestions into account while making thew new components and share a preview link on this issue once we have the nuxt.com website upgraded to the new @nuxt/ui & @nuxt/ui-pro packages.

[fabianwohlfart]

Sounds good! Looking forward.