rustdoc styling improvements for readability · Issue #59845 · rust-lang/rust (original) (raw)

This is being broken out of #59829 to provide smaller, actionable items that can be independently discussed and worked on.

Comparing the overall rustdoc styling with recommendations for accessibility, including for dyslexia and attention disorders, there are a number of improvements that could be made.

In addition, the mdBook default styling, which is already used for the Rust Book and other official Rust documentation, already meets or comes closer to meeting several of these criteria, so one way to achieve several of these goals would be to unify styling with mdBook.

A few of these recommendations may be more appropriate for a separate theme rather than the default theme, but I think many of these changes could improve readability and usability for all users.

• Remove extraneous horizontal rules; horizontal rules should generally be used sparingly, but are used heavily in rustdoc. Appropriate spacing and sizing of headers can replace most uses of horizontal rules.
• Use a sans-serif font for the body text
• Change the font size and column width such that lines are at most 100 characters wide, preferably under 80. This probably means also limiting width of example code to 70 or 80 columns or so, but that's probably OK, example code shouldn't need as much room as the standard convention of 100 columns.
• Consider a lower contrast theme, either as the default or as an option distinct from the dark theme. This can be overdone, some sites go overboard with low-contrast themes, but there's a lot of room for going lower contrast before getting to that point.
• Reduce use of color, as colored text can catch attention and the more colors used the more distracting it can be. Additionally, relying on color to convey information presents problems for those with colorblindness.
  • Consider removing use of different colors for links to different kinds of items (structs, enums, type aliases, macros, etc). This may be worth its own issue as it interacts with the search UI. rustdoc: use smaller number of colors to distinguish items #91480
  • Consider removing colored headings; headings are already distinguished by size, font, spacing, and horizontal rules (though those should probably be also be dropped). In general, only one or two attributes should change to distinguish headings, otherwise they become too prominent and can drown out the text.
  • Consider removing the color from the "Run" link in the example code, or only coloring it upon hover. Also consider unifying styling of example code "Run" link with mdBook, though mdBook could also use lower contrast controls by default. Make Run button visible on hover #92058
• Reduce or eliminate the use of background boxes for inline <code> spans; the Python approach of not having a background box if it is already highlighted as a link seems like a nice idea.
• Increase leading to 1.5 times the font size, and greater inter-paragraph spacing (WCAG recommends 250% of the line height, but that looks quite excessive to me; 2em looks like a readability improvement to me without being excessive) rustdoc: tweak line spacing and paragraph spacing for accessibility #93694
• Provide a theme with a larger font size, or use a 1 rem default font size to pick up the browser default font size (increasing the font size across the board doesn't necessarily improve readability; some users actually find smaller fonts more readable) Set font size proportional to user's font size #92448