Defining design guidelines based on CSS support

[JayPanoz]

I'm submitting a topic for discussion, which goal is to agree on design guidelines that can help make choices and take resolutions.

Short description of the issue/suggestion:

While we did our best to address EPUB Compatibility through documentation, we didn’t necessarily address what ReadiumCSS should do in regards to web/engine/platform compatibility.

It was acceptable to handle things on their own a few years ago e.g. hyphenation was not available in Chromium/Blink on Linux nor Windows, but that didn’t prevent us from using it in ReadiumCSS, especially as it’s kinda critical for published works. With new specs and updates of existing ones, it’s become a little bit more difficult though. My hope is that design guidelines or rules may help keep ReadiumCSS more consistent.

As usual with CSS, things are not as clear-cut as with other languages, mainly because if the rendering engine doesn’t support something, it doesn’t break or err. I’ll try my best to make it as clear as possible.

1. what should we do with non-standard properties i.e. vendor-prefixed properties that are not on the standardisation track?
2. is progressive enhancement desirable, or should we keep it the most consistent possible by targeting the common denominator/baseline?

Non-standard props

There isn’t a lot of such properties in ReadiumCSS, fortunately, but they may end in self-inflicted pain. Such is the case in #113, with a webkit property in safeguards, to protect against raised capitals (initial letter that is bigger but not dropped) w/o a specified line-height. That is consistent with iBooks.app, but creates an inconsistency in ReadiumCSS-based apps across platforms. In hindsight maybe it would be preferable to remove it, and keep things consistent in the Readium ecosystem.

Worse still, in terms of consistency, it is difficult to explain why this is present in ReadiumCSS, but -webkit-column-axis and
-webkit-column-progression aren’t, while they could help with issues such as #96.

Proposed Resolution: I guess this is something we can create a design rule for e.g. “Don’t use props that are not on track to become standard.”

Progressive enhancement

This is probably going to be more of a range – What is preferable? – than picking between 2 options – Y/N – since we wouldn’t have hyphenation in the first place.

I’ve started sharing an overview of new and updated specs in #137 and it’s kinda obvious there may be useful features we could use, but they are obviously supported from specific versions of each rendering engine, which comes with its own set of issues:

• it creates extra rendering inconsistencies on the same platform, using different versions;
• it may create noise for implementers in the form of additional bug reports;
• it may solve issues but only for the latest versions;
• probably more I can’t tell off the top of my head.

On the other hand, that could also help future-proof ReadiumCSS, which is not an insignificant positive.

Proposed Resolution: that probably can’t be a rule, but rather a process i.e. documenting how it could help, what the impacts would be, discussing/voting, and explaining why it was used or not. However, there is probably a way to narrow things down a little bit, before entering this process phase – which sounds extensive and wouldn’t make things really efficient if we have to discuss everything.

Maybe restricting progressive enhancements to minor bugs, or targeting a max version of engines in addition to the min version (see #131). I’m open to ideas and others’ point of view here.

[mickael-menu]

I agree that there's value in a consistent base Readium CSS distribution. Maybe the progressive enhancement could be some kind of opt-in as separate stylesheets, similar to the EBPAJ fonts patch?

As usual with CSS, things are not as clear-cut as with other languages, mainly because if the rendering engine doesn’t support something, it doesn’t break or err.

I know that you have a test suite in the repo. Is there a way to run them automatically? That could be super helpful to have automated tests with screenshot diffs, running on a device farm like BrowserStack to test many different browser in one go.

https://medium.com/seminal/useful-css-regression-testing-tools-99f09a7b8e4c

[JayPanoz]

Maybe the progressive enhancement could be some kind of opt-in as separate stylesheets, similar to the EBPAJ fonts patch?

Some features could make their way into an “experimental” stylesheets of sorts, in order to give implementers an “opt-in” mechanism. I’m still unsure what it could contain though, as it depends on fixes and new features.

It’s also worth noting that since it’s inconsistent by design, CSS offers a mechanism to test for support and style accordingly, at supports. So basically the logic is something like the following in pseudo-code:

if (supports CSS feature X) {
  use these styles 
} else {
  use these other ones
}

But, it’s been obviously designed for authoring, not rendering/overriding. So while it could be useful in a handful of cases, it would mainly be used for issues and features which don’t impact implementation directly I guess – otherwise it’s a footgun.

This is not a strategy I would use for #138 (comment) for instance, as it would impact pagination in nasty ways, considering how immature implementation is and the requirements it forces upon implementers – changing how they handle overflow in vastly different manners depending on what’s supported.

So I guess time (and fixes and feature requests) will tell what’s best in that regard. It’s an option for sure, and it’s good to have.

I know that you have a test suite in the repo. Is there a way to run them automatically?

I’ll have to take a look.

We’re using Backstop.js, which relies on node, Chrome Headless + Playwright or Puppeteer scripts. So it’s unlikely it can work out of the box with BrowserStack.

That said, the test suite is basically made of webpages loaded w/o any interaction so it’s not like it would be a pain to migrate at least this part.