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

Jonathan Gibbons jonathan.gibbons at oracle.com
Fri Aug 31 00:09:50 UTC 2018 

OK

On 08/29/2018 12:15 AM, Priya Lakshmi Muthuswamy wrote:
> 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/20180830/def5b501/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/png
Size: 6594 bytes
Desc: not available
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180830/def5b501/attachment-0002.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/png
Size: 6830 bytes
Desc: not available
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180830/def5b501/attachment-0003.png>

More information about the javadoc-dev mailing list