[BUG] Text is invisible for example blocks in dark mode

[Tobski]

Describe the bug
When looking at an an example block in the sparse memory section in dark mode, the text is invisible.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://docs.vulkan.org/spec/latest/chapters/sparsemem.html#sparsememory-accessing-unbound
2. Switch to dark mode
3. Example block shows up as white text on white background - the only visible thing is a hyperlink for VK_FORMAT_R8_UNORM.

Expected behavior
The text should all be visible, with the example block background changing to match dark mode so the lighter text shows up.

Screenshots

Desktop (please complete the following information):

• OS: Windows 10 (64-bit)
• Browser: Firefox
• Version: 147.0.3 (64-bit)

[oddhack]

@gpx1000 I believe this is because src/css/vars.css in the UI is not setting a dark mode suitable scheme for --example-background and --example-border-color - maybe just changing them to --panel-background and --panel-border-color would do?

N.b. this is the only example block in the spec, AFAICT, and in the interim we could just change it to a NOTE block or like that. Or just say "For example, ..." and leave out the block.

[gpx1000]

Makes sense. I'll probably do a dark mode quick change soon to just hit the major annoyances (don't use pure black for background) while we figure out the color scheme we ultimately want.

[gpx1000]

https://gpx1000.github.io/Vulkan-Site/spec/latest/index.html That's the current "new" dark mode with CSS changes.

[gpx1000]

https://gpx1000.github.io/Vulkan-Site/spec/latest/chapters/sparsemem.html#sparsememory-accessing-unbound

[Tobski]

Looks good to me, thanks @gpx1000!

[oddhack]

Makes sense. I'll probably do a dark mode quick change soon to just hit the major annoyances (don't use pure black for background) while we figure out the color scheme we ultimately want.

I disagree about "don't use pure black for background" being a desirable change. This change lowers contrast globally for the document, and for my eyes, that makes it far less easy to read.

[SaschaWillems]

That's interesting. I do have a high contrast screen, and Steve's change makes it a lot easier on my eyes due to the contrast being too high with pure white on pure black.

[oddhack]

That's interesting. I do have a high contrast screen, and Steve's change makes it a lot easier on my eyes due to the contrast being too high with pure white on pure black.

I hestitate to say it (especially because I don't use Windows), but Microsoft may have got this right with a distinction between "light/dark" and "high contrast" themes. Also I think it's time we rebooted the effort to get a professional accessibility assessment done, focusing on Antora. This is something that will eventually affect most of the WGs and I don't think the current ad-hoc approach to tweaking the themes will withstand more and more users of them.

[gpx1000]

I hestitate to say it (especially because I don't use Windows), but Microsoft may have got this right with a distinction between "light/dark" and "high contrast" themes. Also I think it's time we rebooted the effort to get a professional accessibility assessment done, focusing on Antora. This is something that will eventually affect most of the WGs and I don't think the current ad-hoc approach to tweaking the themes will withstand more and more users of them.

Do you recommend a second toggle in the header to turn high contrast on/off or do we want to dedicate dark-mode to high contrast as it currently is. I worry that it'll be hard to get a solution that pleases everyone. This lighter grey look was in response to #143 which edits the same file by necessity as this one. We can continue the contrast discussion there or here.

[oddhack]

Do you recommend a second toggle in the header to turn high contrast on/off or do we want to dedicate dark-mode to high contrast as it currently is. I worry that it'll be hard to get a solution that pleases everyone. This lighter grey look was in response to #143 which edits the same file by necessity as this one. We can continue the contrast discussion there or here.

This is why I think we should get an objective assessment done - what I recommend can be diametrically opposed to what anyone else with a different visual system or display setup (e.g. #143) recommends. And the more options added, the more maintenance work and option paralysis ensues.

[oddhack]

I just pinged Emily & Neil to ask about funding for this. A few years ago we discussed doing an accessibility analysis of the Vulkan spec but never executed, and have shifted over to Antora now so the framing discussion is different.