RFR : 8209052: Low contrast in docs/api/constant-values.html

Priya Lakshmi Muthuswamy priya.lakshmi.muthuswamy at oracle.com
Wed Aug 29 07:15:53 UTC 2018 

Hi Jon,
> 2. There's an inconsistency in the way that links are handled in some 
> places ... sometimes the same color is used for all pseudo-classes for 
> the element (:link, :visited, :hover, :active) and sometimes different 
> colors are used for (:link, :visited) vs (:hover, :active)
Constants and use summary links have accessibility issues and as 
suggested proposed different colors for (link, visited) and (hover,active)
overviewSummary and memberSummary have tabs and active tab have 
different background and font color.
In other summary captions, don't see any links. So I didn't change that.
That's the reason for difference.
> 3. If the same color is used for all the pseudo-classes (:link, 
> :visited, :hover, :active), you don't need to specify them all 
> separately ... just specify the color for the "a" element ... but I'd 
> prefer to see the stylesheet consistently provide different behavior 
> for (:link, :visited) vs (:hover, :active)
In stylesheet, we have default value for a:link, a:visited , a:hover in 
lines : 32-39 And that's the reason we need to override these values 
rather just specifying "a" element .

32 a:link, a:visited { 33 text-decoration:none; 34 color:#4A6782; 35 } 
36 a[href]:hover, a[href]:focus { 37 text-decoration:none; 38 
color:#bb7a2a; 39 }   


webrev with out reorganizing anything with minimal changes : 
http://cr.openjdk.java.net/~pmuthuswamy/8209052/webrev.03/
doc changes:
http://cr.openjdk.java.net/~pmuthuswamy/8209052/api/java.base/java/io/package-use.html
http://cr.openjdk.java.net/~pmuthuswamy/8209052/api/constant-values.html

Thanks,
Priya

On 8/29/2018 4:57 AM, Jonathan Gibbons wrote:
> Priya,
>
> I still don't completely understand the rationale for your proposal, 
> and I guess the problem is we're trying to solve several problems at 
> once here.
>
> 1. There's an accessibility problem for some styles
>
> 2. There's an inconsistency in the way that links are handled in some 
> places ... sometimes the same color is used for all pseudo-classes for 
> the element (:link, :visited, :hover, :active) and sometimes different 
> colors are used for (:link, :visited) vs (:hover, :active)
>
> 3. If the same color is used for all the pseudo-classes (:link, 
> :visited, :hover, :active), you don't need to specify them all 
> separately ... just specify the color for the "a" element ... but I'd 
> prefer to see the stylesheet consistently provide different behavior 
> for (:link, :visited) vs (:hover, :active)
>
> 4. The layout/organization of this part of the file is horrible. This 
> is partly "it's always been this way", and partly to keep CSS happy.  
> But we should try and improve it, sometime.
>
> So, if we focus on just fixing 1 and avoiding ALL the other problems 
> for now, what is the MINIMAL set of edits you need to fix JUST the 
> accessibility problem.  By "minimal" I mean, don't do any gratuitous 
> changes to any line that doesn't need changing (i.e. reflowing 
> lines).  I "think" that means
> adding in these lines
> 450 .constantsSummary caption a:link, .constantsSummary caption a:visited,
> 451 .useSummary caption a:link, .useSummary caption a:visited {
> 452 color:#1f389c;
> 453 }
> and then simply deleting references to those four styles later on.  I 
> think that means 4 lines are changed, and 4 lines are deleted.  The
> lines won't be filled any more, but I don't think it is helping us to 
> have the lines filled. It's like the effect when you delete a word in 
> the middle
> of the paragraph, and you reflow the text ... all subsequent lines 
> change, hiding the underlying significant change.
>
> We can figure out how to handle the other 3 issues that I described, 
> later. I think some it it will come down to writing that spec for the 
> stylesheet and then doing a series of updates to the stylesheet to 
> clean it up.
>
> Next time, can you post an updated set of docs alongside the webrev, 
> so that we can see the effect of these changes live in a browser.
>
> -- Jon
>
> On 08/21/2018 04:18 AM, Priya Lakshmi Muthuswamy wrote:
>> Hi Jon,
>>
>> Replies inline.
>>> Why have you started a new CSS block in lines 468-470, using #ffffff 
>>> as compared to sharing
>>>
>>> the block starting at 450, using #FFFFFF?
>>>
>> Since hover and active have to be declared after link and visited I 
>> created a new CSS block. I will reordered them to fit all the #ffffff 
>> in one block
>>>
>>> It is very hard to visually see/understand the differences in this 
>>> part of the file.
>>> Would it help to reorganize these lines that that it is one style 
>>> (class) per line,
>>> with its variations, such as:
>>>
>>> .deprecatedSummary caption a:link, .deprecatedSummary caption 
>>> a:hover,.deprecatedSummary caption a:visited, ditto for other 
>>> styles, one group per line {
>>>    color:#FFFFFF;
>>>   }
>> They are organized such that all similar states appear together, can 
>> be changed.
>>>
>>> Why are most of the summary styles grouped together, but 
>>> constant/constants/use/uses handled
>>> separately in 464-467?
>> Only constants and use summary links have accessibility issues and 
>> that's the reason they are handled separately.
>> overviewSummary and memberSummary links have white fonts over blue 
>> background and don't have any accessibility issues.
>> In other summary captions, i don't see any links
>>
>> Changes:
>> Normal:
>>
>>
>> hover(since its just hover and need to have contrast color different 
>> from black/blue)
>>
>>
>>
>> Updated webrev: 
>> http://cr.openjdk.java.net/~pmuthuswamy/8209052/webrev.02/
>> Thanks,
>> Priya
>>
>>
>>> On 8/19/18 8:56 PM, Priya Lakshmi Muthuswamy wrote:
>>>>
>>>> Sure Jon.
>>>>
>>>> For this bug can I push this fix 
>>>> (http://cr.openjdk.java.net/~pmuthuswamy/8209052/webrev.01/)
>>>>
>>>> Regards,
>>>> Priya
>>>>
>>>> On 8/17/2018 10:55 PM, Jonathan Gibbons wrote:
>>>>>
>>>>> In addition to the two tables I described before, I'd like to 
>>>>> suggest 3rd, more fundamental table, that comes before the other two.
>>>>>
>>>>> This third table would define the general palette of colors used 
>>>>> in the documentation. This table would list all the background 
>>>>> colors we use, and for each background color, it would list the 
>>>>> foreground colors used for plain text and for links in the various 
>>>>> states (link, hover, visited, etc)  For links, it should also show 
>>>>> any decorations (e.g. underline) that may be used.
>>>>>
>>>>> So this would mean the design document would have 3 parts:
>>>>>
>>>>> 1. A table showing the general palette, as described above
>>>>>
>>>>> 2. A table of list showing what parts of the palette are used in 
>>>>> each of the different parts of all the pages (e.g. navbar, table 
>>>>> headings, etc)
>>>>>
>>>>> 3. As #2, but pointing at the "current" javadoc stylesheet.css, so 
>>>>> that we can compare actual rendering against intended rendering.
>>>>>
>>>>> -- Jon
>>>>>
>>>>>
>>>>>
>>>>> On 8/16/18 9:08 PM, Priya Lakshmi Muthuswamy wrote:
>>>>>>
>>>>>> Sure Jon we can do that
>>>>>>
>>>>>> -Priya
>>>>>> On 8/16/2018 11:06 PM, Jonathan Gibbons wrote:
>>>>>>> Priya,
>>>>>>>
>>>>>>> I guess white will do.  I'll take a look at the webrev.
>>>>>>>
>>>>>>> This is another area where it would be good to see a summary 
>>>>>>> written description (specification) of the use of color
>>>>>>> in the pages.  I don't mean at the detail level of the specific 
>>>>>>> styles in the stylesheet, but rather, an overview of
>>>>>>> the design and use of what sort of colors we should see in what 
>>>>>>> sort of places, such as the navbar, table headers,
>>>>>>> table rows etc.
>>>>>>>
>>>>>>> One thought is that if we wrote this as an HTML document, and 
>>>>>>> included sample fragments of content (not screenshots)
>>>>>>> then we could "test" the design for accessibility using the 
>>>>>>> standard accessibility tools.  Obviously, this is not a replacement
>>>>>>> for testing the generated docs as well, using the official 
>>>>>>> stylesheet, but it would give us a reference for the intent of
>>>>>>> the design when we do need to change the stylesheet.
>>>>>>>
>>>>>>> The more I think of it, we could have two "sample" docs (or two 
>>>>>>> parts to the doc).
>>>>>>>
>>>>>>> One part would be "standalone" and have embedded styles (i.e. 
>>>>>>> <style> tags in the <head>) and illustrate
>>>>>>> the abstract design concepts.
>>>>>>>
>>>>>>> The other part would/should be visually the same, but the 
>>>>>>> content would use styles from standard stylesheet.
>>>>>>>
>>>>>>> -- Jon
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On 08/15/2018 09:04 PM, Priya Lakshmi Muthuswamy wrote:
>>>>>>>>
>>>>>>>> Hi Jon,
>>>>>>>>
>>>>>>>> For hover, yes I see color variation.
>>>>>>>> My proposal :
>>>>>>>> Since its just for hover and also as we need to provide 
>>>>>>>> contrast color other than black/blue, I am suggesting white
>>>>>>>>
>>>>>>>> Normal:
>>>>>>>>
>>>>>>>>
>>>>>>>> hover:
>>>>>>>>
>>>>>>>>
>>>>>>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8209052/webrev.01/
>>>>>>>>
>>>>>>>> Thanks,
>>>>>>>> Priya
>>>>>>>> On 8/15/2018 3:26 AM, Jonathan Gibbons wrote:
>>>>>>>>> Priya,
>>>>>>>>>
>>>>>>>>> Even superficial playing with the JDK API confirms that 
>>>>>>>>> javadoc uses a different color for hovering over links.
>>>>>>>>> I think the same should apply to these summary caption links 
>>>>>>>>> as well.
>>>>>>>>>
>>>>>>>>> -- Jon
>>>>>>>>>
>>>>>>>>> On 08/13/2018 04:58 PM, Jonathan Gibbons wrote:
>>>>>>>>>>
>>>>>>>>>> I'm surprised that you propose to set all of these styles to 
>>>>>>>>>> the same color:
>>>>>>>>>> +.constantsSummary caption a:link, .constantsSummary caption 
>>>>>>>>>> a:hover, .constantsSummary caption a:active,
>>>>>>>>>> +.constantsSummary caption a:visited,
>>>>>>>>>> Doesn't that mean we won't be able to tell the difference 
>>>>>>>>>> between non-visited and visited links?
>>>>>>>>>> Also, if you specify styles for all "a:link a:hover a:active 
>>>>>>>>>> a:visited", what's the point of specifying
>>>>>>>>>> those cases separately: are there any others? Couldn't you 
>>>>>>>>>> just collapse those 4 to just "a"?
>>>>>>>>>> Not that I'm suggesting that: I think it's better to have 
>>>>>>>>>> some stylistic variation when you hover
>>>>>>>>>> over links or have visited them.
>>>>>>>>>>
>>>>>>>>>> -- Jon
>>>>>>>>>>
>>>>>>>>>> On 8/7/18 6:34 AM, Priya Lakshmi Muthuswamy wrote:
>>>>>>>>>>> Hi,
>>>>>>>>>>>
>>>>>>>>>>> Kindly review fix for 
>>>>>>>>>>> https://bugs.openjdk.java.net/browse/JDK-8209052
>>>>>>>>>>> webrev : 
>>>>>>>>>>> http://cr.openjdk.java.net/~pmuthuswamy/8209052/webrev.00/
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> Thanks,
>>>>>>>>>>> Priya
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180829/a23d1550/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: kpefeocinkofpbkh.png
Type: image/png
Size: 6594 bytes
Desc: not available
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180829/a23d1550/kpefeocinkofpbkh-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ldeocfgkiekngjij.png
Type: image/png
Size: 6830 bytes
Desc: not available
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180829/a23d1550/ldeocfgkiekngjij-0001.png>

More information about the javadoc-dev mailing list