RFR: JDK-8289334: Use CSS variables to define fonts and colors

[Jonathan Gibbons]

On Thu, 11 Aug 2022 15:29:46 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet.
> 
> [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions:
> 
> [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/
> 
>  - Some colors have been unified to reduce the number of variable definitions:
>       - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border)
>       - Header cells of user defined tables now use the same color as structural tables
>  - Some sub-pixel sizing and spacing changes in random places
> 
> Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette
> 
> The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties.

Mostly excellent.

There is one question about why you have converted some values from hex to `rgba` values, not to CSS custom properties.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java line 333:

> 331:             // The order of the addStylesheet(...) calls is important
> 332:             addStylesheet(head, DocPaths.SCRIPT_DIR.resolve(DocPaths.JQUERY_UI_CSS));
> 333:             addStylesheet(head, DocPaths.JQUERY_OVERRIDES_CSS);

The edit as-is is OK, but the general code here makes me wonder if this class belongs in the `markup` package.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 89:

> 87: }
> 88: h1 {
> 89:     font-size:1.428em;

I appreciate these numbers give per-pixel consistency with before, but 3 decimal places seems a bit extreme!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 959:

> 957: }
> 958: div.page-search-info button#page-search-copy:hover {
> 959:     background-color: rgba(128, 128, 160, 0.2);

why have the old hex values just been converted to `rgba` values, and not CSS custom properties?

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

PR: https://git.openjdk.org/jdk/pull/9839