RFR: 8344301: Refine stylesheet for API docs [v4]

[Nizar Benalla]

On Mon, 3 Mar 2025 15:05:35 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
>> 
>> List of changes:
>> 
>>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>>  - Fix font size and line height inconsistencies in many places.
>>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>>  - Add a subtle gray background to code elements in normal text to set them apart.
>>  - Highlight headings of member details when they are used as link targets.
>>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>>  - Improve styling of additional HTML files in `doc-files` directories.
>>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>>  - Various cleanup.
>> 
>> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
>> 
>> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).
>
> Hannes Wallnöfer has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Changes:
>     - Adjust subnav link color to meet WCAG contrast rules
>     - Use subnav color for captions with links to meet WCAG rules
>     - Make table header work with new caption color
>     - Adjust some gaps
>  - Changes:
>     - Bring back breadcrumb highlight for current element
>     - Use default tab color for search page caption

I left a couple of comments, but they are not a blocker for this PR.
Our stylesheet is quite large so we might want to consider running a linter on it in the future.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css line 827:

> 825:     font-size: inherit;
> 826: }
> 827: code {

I noticed there is a duplicate `code` selector (first used in line 162), is this intentional?
I also think it's odd to have `code` after `:is(h1, h2, h3, h4, h5, h6, sup, sub, small, big) code`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css line 1537:

> 1535:     }
> 1536: }
> 1537: pre {

Duplicate selector, It doesn't have the same fields as the one from line 129

-------------

PR Review: https://git.openjdk.org/jdk/pull/23678#pullrequestreview-2664235129
PR Review Comment: https://git.openjdk.org/jdk/pull/23678#discussion_r1983234865
PR Review Comment: https://git.openjdk.org/jdk/pull/23678#discussion_r1983231137