Readium CSS User Agent Properties

ReadiumCSS-UserProps.md

There is a proposal for user agent properties. To sum things up, browsers would expose user settings so that you can use them in your CSS.

For instance:

body {
  font-size: const(user-font-size);
  font-family: const(user-font-family);
  /* And so on and so forth… */
}

As a matter of fact, we have something like this in Readium CSS, it is used for internal purposes but, on the authoring side, there are issues to deal with:

1. doesn’t work in Kindle;
2. crashes Adobe’s RMSDK ePub2 parser;
3. ePubCheck currently reports CSS custom properties as errors (it shouldn’t once support for EPUB 3.1 is added);
4. it requires progressive enhancement, therefore extra work.

What you would have to do:

body {
  text-align: justify;
  hyphens: auto;
}

@supports (--var: a) {
  body {
    text-align: var(--USER__textAlign, justify);
    hyphens: var(--USER__bodyHyphens, auto);
  }
}

To clarify:

1. you write styles for Reading Systems which don’t support CSS custom properties (a.k.a. CSS variables);
2. you write a feature query for Reading Systems which support them;
3. you use those user properties, with a fallback if they’re not set e.g. if the user hasn’t set text-align, then justify is the fallback.

Examples of what you could currently do with those custom properties:

• full-width containers;
• icons and/or text in the margins;
• inverting images in night mode;
• adjusting background-color + border-color in night modes;
• adjusting the font-sizes based on the font-size user setting;
• more generally, authoring your CSS so that it is 100% compatible with user settings.

After thorough testing, I do believe this is the simplest way forward for both authors and developers. But it implies a new paradigm and best practices.

Finally, it could probably make a “Do Not Touch my CSS” switch an easier implem, as user settings would be an integral part of the authors’ CSS. Indeed, this is by far the biggest pain point we have to deal with at the RS’ CSS level—i.e. a lot of !importants + a whole lot more of details to take into account for each user setting. In other words, for such a mechanism to exist, the author’s CSS must be user-centric.

What a user-centric stylesheet would look like (sort of, this is still a proposal in its early days).

:root {
  font-size: const(user-font-size);
  background-color: const(user-background-color);
  color: const(user-color);
}

body {
  font-family: const(user-font-family);
  line-height: const(user-line-height);
  hyphens: const(user-hyphens);
  text-align: const(user-text-align);
}

h1 {
  font-size: 2em;
}

h2 {
  font-size: 1.5em;
}

p {
  font-size: 1em;
  margin: const(user-paragraph-margin) 0;
  text-indent: cont(user-text-indent);
}

figure.bleed {
  position: relative;
  margin: 1.5rem 0;
  left: calc(const(user-margins) * -1);
  width: calc(100% + (const(user-margins) * 2);
}

aside.bordered {
  border: 2px solid currentColor;
  padding: 0.75rem const(user-margins);
}

aside.inverted {
  background-color: const(user-color);
  color: const(user-background-color);
}

/* The following selector, you don’t want user overrides */
.warning {
  background-color: crimson;
  color: white;
  font-weight: bold;
}

/* The following selector, you don’t want the font-family to be overridden */
.greek {
  font-family: "my-embedded-font-for-greek", Times, serif;
}

The author’s styles could be defined as fallbacks there, in case the user setting is not set. Once again, this is a simplistic example and we need to wait and see where the proposal is going.