Repository: rust
Issue: Reduce visual prominence of controls, source links, and version numbers in rustdoc
Labels: T-rustdoc,C-enhancement,A-rustdoc-ui

This is being 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. These should be considered along with the other issues mentioned in #59829 about the overall effect of a number of distracting elements on the page.

Items in rustdoc can have a number of controls and auxiliary information associated with them, which can be quite prominent and distracting. These should either be eliminated, or made less prominent so that the reader can more easily follow the main content and only notice them when they need to find them.

At the top of a page, we see several controls that are larger and more prominent than the main text. The top of page `[-]` and `[src]` controls are larger and bolder than the body text. The version number is a bit smaller and lower contrast, but unexplained what it means.

Immediately above the main text is a "Show declaration" disclosure which is lower contrast, but larger, than the main text, and the main text itself also has a disclosure control immediately to its left, crowding it.

![Screenshot of Ipv4Addr header showing issues described above](https://user-images.githubusercontent.com/37398/55902587-dac55480-5b99-11e9-9966-6934499bb713.png)

`impl` blocks have disclosure controls indicating a nesting relationship, even though the headings themselves don't, which leads to some distracting spacing. They also can have a number of closely spaced prominent `[src]` links and version numbers. The `[src]` links are a slightly larger font size (17px) than the content (16px).

![Screenshot of Ipv4Addr impl demonstrating nested disclosure boxes and src links](https://user-images.githubusercontent.com/37398/55903214-24fb0580-5b9b-11e9-90e2-b975f4372802.png)

![Screenshot of method in Ipv4Addr impl demonstrating version numbers and src links](https://user-images.githubusercontent.com/37398/55903215-24fb0580-5b9b-11e9-82b9-d621d32898cd.png)

There are also a variety of different sizes of these disclosure controls, which don't match the logical hierarchy.

![Screenshot of blanket impl with "Show undocumented items" disclosure larger than ](https://user-images.githubusercontent.com/37398/55904714-88d2fd80-5b9e-11e9-8744-7b3b38f012d2.png)

There's an additional "important traits" control that appears on some methods which indicates some important traits implemented by the return value of the method. This allows showing traits that are implemented by the return type for thing like iterator adapters, where the user usually cares more about the trait implemented than the concrete type. This adds another UI element which is high contrast, doesn't match in size, and has a different way of disclosing hidden information. Previous discussion of this design is present in the implementation issue, #45039.

![Screen shot demonstrating appearances of "important traits" control to left of disclosure controls for several iterator adapters](https://user-images.githubusercontent.com/37398/55906930-6a233580-5ba3-11e9-945b-e5a391d14846.png)

![Screen shot demonstrating unique modal dialog for "important traits"](https://user-images.githubusercontent.com/37398/55907104-d9008e80-5ba3-11e9-84d1-f6e399b6c045.png)

There is going to need to be a balance between reducing or eliminating the visual impact of these elements, while still making the same information easily discoverable for those who need it.

Here are a few suggestions about how we might be able to achieve this. 

* [x] Avoid having these elements look like syntax. `[+]`, `[-]`, and `[src]` could be mistaken for some kind of source code annotation; the brackets are also very eye-catcing. Using more standard disclosure controls (such as `⊞` and `⊟`, or ▶︎ and ▼), and prose like `source` instead of `[src]`, may help.
* [x] Make source links and version information smaller and lower contrast; could make them become full contrast on hover
* [ ] Move version numbers introduced and source link to less prominent location
  - perhaps inline with the text of the docs
  - perhaps immediately to the right of the first line of the declaration, rather than right-justified
* [ ] Use English for the version number and source link
  - "Introduced in Rust 1.12.0"
  - "Since 1.12.0"
  - "source"
  - Something simple like "_(since 1.12.0 / source)_" might be appropriate.
* [ ] Adjust the sizes of disclosure controls and text to follow logical hierarchy and be smaller and less prominent than content
* [ ] Use standard disclosure control for "important traits", or if possible, just include the relevant information inline so you don't have to click through to it. These options were considered but ultimately not chosen in the implementation issue #45039.