Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify and unify rustdoc sidebar styles #59860

Closed
4 tasks done
lambda opened this issue Apr 10, 2019 · 1 comment · Fixed by #92692
Closed
4 tasks done

Simplify and unify rustdoc sidebar styles #59860

lambda opened this issue Apr 10, 2019 · 1 comment · Fixed by #92692
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@lambda
Copy link
Contributor

lambda commented Apr 10, 2019

Rustdoc's sidebar uses several visually heavyweight elements, and also has inconsistent styling between different sections.

This has been broken out of #59829 to provide smaller, actionable items that can be independently discussed and worked on. A review of rustdoc for accessibility, especially for dyslexia and attention disorders, finds that there are a number of visually distracting elements in rustdoc which can draw attention away from the main content. This should be considered along with the other issues mentioned in #59829 about the overall effect of a number of distracting elements on the page.

There are several heavyweight UI elements.

  • The headings for the item in question, and the parent item, are enclosed in a black-bordered, white background box, contrasting with the background
  • The crate name is bold in the parent item box
  • There are high contrast horizontal rules on both sides delimiting the headings in the current page
  • There are large, bold headings, with a lot of whitespace and low-contrast horizontal rules below in the parent item section
  • Headings are centered, while items are left justified

In addition, the two sections have quite inconsistent styling.

  • Headings in the top section are same size as individual items, but centered and delimited by heavy horizontal rules
  • Headings in the bottom section are a large, bold font, with a lot of space and very light horizontal rules

Screenshot of current item section of sidebarScreenshot of parent item section of sidebar

We can compare that with the sidebar in mdBook; while they serve different purposes, it is useful to look at them together.

mdBook simply uses an outline view for nesting, without larger or bolder headings. It does have bold chapter/section numbers, which is slightly attention grabbing, but otherwise is both a simpler style and fits more content into the sidebar with less decoration.

Screen Shot 2019-04-10 at 4 42 17 PM

Specific recommendations:

  • Drop the black bordered white boxes in the sidebar
  • Drop the black horizontal rules in the sidebar
  • Use at most two attributes to distinguish levels of headings and individual items. Those could include:
    • Indentation, as in an outline view like mdBook
    • Font size
    • Font boldness
    • Extra whitespace
    • Single light horizontal rule
  • Prefer left-aligned text to centered
@jonas-schievink jonas-schievink added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Apr 10, 2019
@jsha jsha added the A-rustdoc-ui Area: Rustdoc UI (generated HTML) label Oct 20, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants