Default colors need improvement

[craigscott-crascit]

Using asciidoctor-epub3 1.5.0.alpha.17

Contrary to the claims in the readme, the colors of the default theme don't always give good results across the different viewing modes. In some cases, text can be completely unreadable. Here's a few observations with the current stylesheet on some apps/devices:

• For best readability, when viewing with white background the main text should ideally be black (0x000000). This is what you will typically see with commercially produced ebooks (as far as I've been able to tell). The current default for asciidoctor-epub3 appears to be 0x333332 instead, which is dark but not as dark as it should be. This was one of the first things a reader noticed on Kindle (text not as dark and clear as other ebooks). I see the same in calibre and iBooks on a mac desktop, so I presume it would be the same everywhere. Since this is likely to be the default/most commonly used viewing mode, it's an important one to give the optimal readability.

• For black background (Night mode), the text in calibre is still quite dark and hard to read. On iBooks, it's a good contrast and doesn't have the same issue, so the problem seems to be reader-specific.

• For sepia dark, on calibre the text color is the same as the background color, so it disappears completely! Again, iBooks is okay for sepia dark.

[craigscott-crascit]

FWIW, the default theme for asciidoctor-pdf has a similar issue for the white background case, but asciidoctor-pdf supports being able to import the default theme and override only the bits you want. There is no equivalent functionality for asciidoctor-epub3 releases, so the only alternative is to copy the entire stylesheet (all three files). That means you'd also miss any changes to these stylesheets that are made from one release of asciidoctor-epub3 to another, so it is not an ideal workaround.

[mojavelinux]

As I've mentioned in other issues, I've admitted defeat over trying to create a nice looking theme. Pure black on white is generally discouraged for screen devices as the contrast is too strong and creates discomfort for many readers. However, ebook device manufactures have jumped in and modified how shades of gray are displayed (for this reason) so what's defined as 333332 ends up being much, much lighter in day mode and nearly invisible in other modes. So we're working against the system. (It's not our fault the devices get it wrong, but that's just the way it is).

Let's just use pure black in the default theme and leave it up to a custom stylesheet to use other colors.

(For the record, you never see pure black on a Kindle because the device simply doesn't or cannot display it).

[slonopotamus]

I believe that Calibre is not a good tool for testing dark/night modes (or the issue is more complex than it looks). If I change text color from #333332 to #000000 and enable "Black" theme in Calibre, text remains black, so it is invisible on black background. Calibre has "Override all book colors = In dark mode" that fixes text color in both "Black" and "Dark sepia" modes, however all text coloring is lost for obvious reasons.

So, while general thesis that asciidoctor-epub3 text isn't black enough still might be true, changing it to completely black does not fix readability across all Calibre modes and only changes "text is unreadable in dark sepia mode" into "text is unreadable in black mode".

[mojavelinux]

I think the solution is to not set the font color. The reason we had set it before is because we did not want black.

Once again, the readers are supposed to be changing the colors uniformly, but we've learned that we cannot trust that contract.

[slonopotamus]

@mojavelinux Hmm. Avoiding font colors at all is a rather hard restriction. We have syntax highlighting, colored icons, shades of grey for various things... I don't quite understand where is the boundary between coloring and not-coloring.

[mojavelinux]

I meant for the main text. The other stuff is out of our control since you're right, we need to use colors.

[slonopotamus]

This is how our README looks in Calibre after I removed all #333332 from CSS and turned on dark sepia theme.

It is simply awful. I'm still not convinced whether this mode should influence our decisions at all, maybe it's just broken. I'll take a look at how other readers handle night/dark modes.

At least these screenshots say "no, removing main text color is not enough for dark sepia mode in Calibre". I think there is a reason why they offer "Override all book colors = In dark mode" option.

[slonopotamus]

And black theme is not going to work too. I dunno what they're thinking about. It is impossible to pick colors that would look OK on both white and black background.

[mojavelinux]

My spouse uses Calibre to read books. In her experience, the dark mode is totally broken. So I don't think this should be driving decisions. I think iBooks or Kindle should be our main reference.

[slonopotamus]

@mojavelinux So. Do we want to only change main text color or to rescale all our palette into darker shades? Theoretically thinking, the latter should make more sense.

[mojavelinux]

I think it's both. All colors that are used likely need to be darker, but the main text shouldn't have a color defined (which will default to black). But its never going to be perfect because EPUB 3 readers are imperfect.

[slonopotamus]

Related: #337, #67.

[slonopotamus]

For best readability, when viewing with white background the main text should ideally be black (0x000000).

Funnily, GitHub uses #24292e for main text.

[slonopotamus]

So. I've created #347 that changes asciidoctor-epub3 to a darker palette.