User settings: managing authors’ and users’ intents

User settings are a complex issue because overrides are hard.

Some user settings are all or nothing, others might be raw around the edges, and so on and so forth.

I like to think of user settings as two conflicting intents: the user’s and the author’s.

Although the user’s intent must often win, we can at least polish some details.

The aim of this comment is to kickstart the discussion. It may be wrong in some places, I possibly owe you clarifications here and there, etc. but the main goal is to help implementers make informed decisions about those user overrides.

Managing conflicts

We’re referring to the W3C’s priority of Constituencies there. In other words:

Users’ styles > Authors’ styles > Implementers’ styles

Which is why conceptualizing this issue as intents may help.

Typography is not just a set of settings though, it’s a complex system in which some settings impact other settings. For instance, font-size impacts line-height and line-length, which impacts the number of columns.

It is up to implementers to pick their preferred approach (minimal set, presets, minimal set/presets with advanced settings, maximal set) since it is primarily an UX issue.

!important

User’s intent

Does not apply.

Author’s intent

In theory, using !important is a clear intent the author is willing to enforce some specific style.

What do do

In practice, !important may be abused, it may be a quick fix to solve a cascading issue—and the author didn’t bother taking Reading Systems into account—, it may be used to enforce some styles in Reading Systems overridding any style, etc.

This case is a complex one. We’re designing Readium CSS with the minimum amount of overrides possible but !important may conflict with some user settings. Please refer to the following cases.

Font family (typeface)

User’s intent

The user intends to at least override the typeface used for body copy.

For a11y-related typefaces (Open Dyslexic, bold style of sans-serif family), the user probably intends to replace headings, scripts and italics as well.

Author’s intent

Declaring a font-family for body or p + p.class is so common that it should not be considered an intent per se. While p.class is debatable, it is so widespread in practice (some authoring tools output font-family for every paragraph style) that it can’t be considered an intent in pure CSS.

A different font-family can be set for headings (h1, h2, h3 etc.), blockquote, i, span, etc.

What to do

A different font-family for specific elements should be considered a proper intent: a font may indeed be used to make the structure clearer, achieve visual effects (e.g. manuscript letter) or make sure different languages are displayed correctly.

For a11y-related settings (e.g. Open Dyslexic), you should override those elements too, as not doing it will impact the reading experience negatively. Please make sure to provide a font-stack that covers a large amount of different languages though.

In any case, math content should not be overridden.

Line height (leading)

User’s intent

The user intends to adjust line height, either because it is too solid or too loose by default.

Author’s intent

The author may be trying to enforce vertical rhythm but you really can’t tell if you don’t analyze the entire stylesheet.

What do do

Common elements for the body copy should be overridden (paragraphs, lists…).

Text align (justification)

User’s intent

The user intends to set a personnal preference. Although it is a bad practice in typography, some may prefer justified text without hyphenation.

Author’s intent

If set for body copy, this is a publisher’s or author’s preference.

If explicitly set to right and center for paragraphs, to which left is added for headings, it is a clear intent.

What do do

Clear intents should not be overridden. This may require JavaScript though.

Elements such as headings, tables, pre, etc. should not be overridden: declaring text-align: justify for those elements would indeed degrade legibility.

Hyphenation

User’s intent

The user intends to enable/disable justification, possibly depending on the default/author’s styles.

Author’s intent

Since hyphenation works in combination with justification in proper typography, this should be considered a preference or the enforcement of a typographic rule.

What to do

Typography-wise, it is OK to hyphenate body copy with text-align: left, it is critical to hyphenate body copy with text-align: justify.

We are taking care of elements which should not be hyphenated in the patch stylesheet so that you don’t have to.

Number of columns

User’s intent

The user intends to set a personnal preference. They may be used to reading newspapers, where the column length is quite small, but that can create extra issues on the implementers’ side.

Author’s intent

Does not apply to authors.

What to do

It depends on the implementers’ approach (presets with typographic rules as references Vs. the user can override on a setting-by-setting basis).

Margins

User’s intent

The user intends to adjust line-length.

Author’s intent

We have to override margins for pagination so the most important style is max-width, if set.

What to do

The author intends to limit line-length, but it is unclear they are doing it because some Reading Systems don’t or because they want to enforce one specific (max) line-length.

Reading modes

User’s intent

The user intends to improve visual comfort.

Author’s intent

Does not apply to authors but it could if we create a public API for authors to express intents related to reading modes.

Since authors have filed very few use cases at the moment, this is highly conditional.

What to do

Implementers should take two main variables into account: contrast and luminosity, which means they might want to invert some images or get rid of backgrounds in night mode.

Inverting images that should be inverted in night mode can’t be done well without an author’s intent though.

Nice write up. You might want to mention math in the font-family section.

Yes, thanks!

(And address CJK+RTL where needed.)

Overrides are hard because CSS itself was not created to expect them, and ereaders therefore can only but try to go around its nature of abiding only to a strict view of the author. In other words, it's because ereaders can only cheat, and cheating is always fragile.

How are the issues listed here specific to ebooks only and not webpages too, therefore justifying adding rendering quirks to ereaders that deviate from how browsers render content, instead of tackling how it is that CSS user overrides should work, what elements and CSS properties they would override and with what values, and how to write CSS properties that take values (even deltas) from user preferences (or forcibly ignore them), in the CSS spec itself?

These are IMHO aspects that shouldn't (won't) be resolved by having each ereader (or browser) have their own quirks that sidestep CSS. Heck, considering Readium aims at becoming an SDK, it cannot even be considered a single ereader itself.

Shouldn't this be tackled from within CSS, by officially extending it (thus, from within the CSS WG, not any ereader developer group or any other parallel organization) in a manner that brings a way of writing styles that honor (or not honor) user preferences, and make user overrides, and their behavior, part of the standard, to which all ereaders (and browsers) could uniformly adhere. As a matter of fact, some browsers have sort of faced these issues too and tried to tackle them, just as well, in their own way each, with "reader" modes that not infrequently are unsuccessful at identifying what to keep and what to throw away.

The more ereaders deviate from how browsers render content (why are they still two different things?) the longer chaos and stagnation will permeate the ebook space.

BTW, didn't IDPF and W3C just merge?

Overrides are hard because CSS itself was not created to expect them.

Actually, this was addressed from the start: https://www.w3.org/People/howcome/p/cascade.html. You could actually think of the OP as trying to map the concept of “weighted influence.” I just did and it takes replacing “probably”, “might”, etc. with percentages.

But since the concept of “weighted influence” didn’t make it and Houdini is not a thing yet, we have to do it on our own for ePub2/EPUB3, for which both authors and users have expectations (short term).

instead of tackling how it is that CSS user overrides should work, what elements and CSS properties they would override and with what values, and how to write CSS properties that take values (even deltas) from user preferences (or forcibly ignore them), in the CSS spec itself?

Flexbox took 7 years (and multiple iterations) to become a recommended spec, and grid 5 years— Bloomberg spent money sponsoring Igalia to help with the implementation BTW. It is important to remark there were practical implementations to see which parts could work in practice and which couldn’t, which hasn’t necessarily been the case for EPUB specs in the past.

The work being done there is entirely documented, so that it can serve as a reference for future specifications (long term). And it requires tremendous efforts to do that, especially when most of the feedback you can get is “I don’t care/I don’t know/We must spec it and this is how it should be done.”

You’re free do design a spec and create a ponyfill for it, then discuss it with browsers. You can also make a feature request/proposal on the WICG’s discourse. But you’ll to explain how is has been done, the issues it created (including users’), significant use cases it will deal with, take implementations’ complexity into account, etc. It’ll take years.

And then maybe they’ll tell you to use the Houdini API to do that, because they believe they don’t need it. This is probably how pagination will be treated anyway.

Heck, considering Readium aims at becoming an SDK, it cannot even be considered a single ereader itself.

Please be assured we have intensive discussions about that and this impacts the CSS design in extensive ways.

We can make recommandations, we can document best practices, but once again, if authors don’t offer another feedback than “spec it!”, progress won’t likely be made. if there is no public recommandations, then it will be ten times worse, and you’ll get even more fragmentation. Please excuse me if “intents” is a baby step because it is unrealistic we can spec something complex by the end of the year.

At the moment, some Reading Systems are choosing the nuclear option because readers may complain otherwise and it’s a business for them. Believe me, making the situation a little better for everyone in this one implementation is already a Herculean effort.

As a matter of fact, some browsers have sort of faced these issues too and tried to tackle them, just as well, in their own way each, with "reader" modes that not infrequently are unsuccessful at identifying what to keep and what to throw away.

I’m doing everything I can to find common issues and discuss them with browser vendors. Inverting images in night/reader modes was the first issue I opened for this repo.

But it turns out it is super difficult to find someone at Apple, Firefox, Google, etc., and not having solid use cases illustrating authors’ requests and feedbacks doesn’t help, especially when there is no public reference to point at.

And should I find someone to discuss this, I must also be prepared to face one significant challenge: what if some are completely uninterested in doing this because their users are completely fine with Reader mode getting rid of all authors’ styles? This really is a possibility.

The more ereaders deviate from how browsers render content (why are they still two different things?) the longer chaos and stagnation will permeate the ebook space.

We’re making lots of efforts sticking to the web. Checking UA stylesheets was the first thing I did.

But there are millions of EPUB files out there. We’re willing to help authors, I’m dedicating a lot of time to collecting feedback and requests, I’m even proposing opt-in mechanisms but if authors don’t list use cases, we don’t know what we should do it for. It’s a simple as that, I’ve already spent an entire weekend clarifying this on another issue.

Given the timespan, you should really forget the idea of spec’ing things. It’s been three weeks already and the only use cases I listed are mine. Now, I get feedback from implementers, and they’re all about use cases, not specs or stuff. Should you wait apps ship to provide feedback and make requests, it will get exponentially harder to implement them, because implementations might differ and the CSS design could be biased due to the lack of authors’ feedbacks.

If you’re talking about (P)WP, it is another thing entirely, and this is not the repo to discuss it, https://github.com/w3c/wpub is.

List of user settings we currently have designed:

color
background-color
font-size
font-family
text-lign
line-height
page margins
paragraph spacing
paragraph indent
bodycopy hyphens
number of columns

Those won’t necessarily be the settings you’ll get in the UI. Implementers may indeed use presets, or themes, and provide users with advanced settings, or just use all those settings by default.

I’ll probably add:

word-spacing
letter-spacing

As it is know part of WCAG 2.1.

Which also raises two extra issues:

the user should be able to set custom background-color and color (color pickers)
the user might want to use one specific typeface and override any author’s font-family

For 1, it means the RS behaving as in night-mode (cf. issue #7), i.e. overriding any color prop as we can’t tell the combination they will pick. Extra technical issue for @camill-a, Safari/webkit doesn’t ship with the dedicated HTML5 input for color so it would have to be polyfilled.

For 2, it may be an extra advanced setting but making it an extra step hurts my UX sensibility a little bit.

I’ve started documenting this for implementers and authors. It is super important to note that, per spec, we must emulate this cascading priority

In other words, here is the order of priority:

transition declarations;
important user agent declarations;
important user declarations;
important override declarations (DOM Level 2 Style)
important author declarations;
animation declarations;
normal override declarations; (DOM Level 2 Style)
normal author declarations;
normal user declarations;
normal user agent declarations.

Obviously “2. important user agent declarations” is by no means a wildcard. However, we must all (users, authors, RS) notice that the order of precedence is turned upside down when !important is used. So authors’ !important should not override UA’s and users’. If some authors aren’t happy with that, they should turn to the spec’s editors.

Last time I checked DOM Level 2 Style, there were serious differences in implems which made its use non-trivial (especially when you start manipulating the index, different rules being returned depending on the browser) so don’t hold your breath too much about that.

Finally, we don’t have any universal and reliable mechanism to set a stylesheet as an UA’s or a User’s. This is the crux of the issue, since having such a possibility would solve user settings more easily.

Of course this also implies I’ll have to sort our styles:

user agent;
user;
override.

Since we must de facto deal with those three (user settings being an interface for writing the user stylesheet).

Interesting link @dauwhe provided on Twitter: User Agent properties and variables, especially the IRC Log.

We’re kind of heading in this direction—mainly for internal purposes, we’re not publicly exposing them to authors at the moment—, only we’re using var() since constant() is not a thing yet.

Question is, should we expose all our variables (RS and user) to authors? In practice, Readium CSS will ship with a micro framework for implementers to typeset/layout unstyled ebooks so authors could basically use it too if we provide --RS__variables…

Feedback from authors would be greatly appreciated since it’s up to them. Indeed, var() breaks the RMSDK CSS parser and are not compatible with Kindle, so they would have to use it with feature queries, e.g.

.box {
  background-color: crimson;
  color: white;
}

@supports (--a: 0) {
  .box {
    background-color: var(--USER__backgroundColor, crimson);
    color: var(--USER__textColor, white);
    border: var(--USER__textColor, crimson)
  }
}

Where crimson and white are their default values when the user hasn’t set colors/reading modes yet.

It is my understanding that they will have to do that anyway, should they want to leverage user-properties once they are available.

Timing is clearly unfortunate there, as we have to take WIP specs related to user settings into account. IMHO we’d better deal with it sooner than later, especially as we may have to come back to Readium CSS later to “implement” those specs, the CSS reference for EPUB 3.1 being the W3C Snapshot. Our “pseudo ponyfills” could serve as placeholders there—or maybe even a RS implem of the spec since we probably won’t be able to manage user-properties like UAs and would consequently have to pass our user settings to authors using var().

As an update, a first quick round of testing with our samples went quite well. There are a few minor issues here and there but nothing to worry about, and the “rec” (OP) + cascade level 3 spec are pretty well respected at the moment.

I will obviously do more testing but we’ll be able to push the prototype next week (cf. roadmap) then iterate quickly as most user settings are currently working as expected.

I’m temporarily closing this issue since this is now documented.

Can reopen it so do not hesitate to weigh in if needed.

readium / readium-css