This is part of the a11y baseline, as defined in issue #18

It seems removing/obscuring images can help with dyslexia. I’ll need confirmation there.

If so, what would be the best option? Removing images entirely? Replacing them with a placeholder? Obscuring them? What about figcaptions?

We started discussing this during the latest engineering call. I’m opening this specific issue so that we can gather outside feedback from the community, especially as @danielweck and @laudrain are dealing with accessibility on a regular basis and can probably point out specific issues and shortfalls. And of course @llemeurfr can forward this issue to a11y experts in contact with EDRLab.

It’s also worth noting that we will probably get more feedback once the Readium Desktop app is available (with an installer), so this should be considered something we’ll have to iterate over. Hence this baseline, which is what we’ll ship in the beta.

So, our current baseline for user settings is:

• night/sepia modes + custom background-color and color
• text-align + hyphens
• font-size + line-height
• typefaces: dys + humanist in bold
• letter and word-spacing
• removing italics (which could be automatic when switching to the two specific typefaces?)

This is a mere draft, really. For instance, Daniel already pointed out that color-blindness will have to be managed (and unfortunately, there is no media query to deal with the OS global user settings, which exist in MacOS/iOS for instance).

And there’s obviously a lot more to deal with, which is the purpose of the OS a11y module. Only Microsoft high-contrast-mode is currently addressed.

We’ll have to make decisions about reading modes there: if the user sets the monochrome option, how are we supposed to deal with sepia and colors? If the user sets an inverted high-contrast mode, what happens with night mode? I know this question might sound kind of dumb at first sight, but there can be multiple users for the same computers, using the same account, etc.

What I can say when it comes to typefaces is that, from research, the more varied typefaces available, the better. There is no silver bullet there, some people don’t like Open Dyslexic for instance, and prefer Verdana or other sans-serif typefaces.

I know Microsoft has commissioned accessible versions of two typefaces (Fluent Sitka and Calibri) but it is a package users have to install, we can’t embed them in apps. Their EULA clearly state that:

b. No Distribution Rights. This agreement does not grant you a license to distribute nor sublicense all or part of the software to any third party.

For the record, there is also an alternative to Open Dyslexic, Accessible-dfa, and it apparently supports more glyphs, but we have to gather feedback to see whether it’s a solid alternative or not

As for OS settings, I can anticipate some Media Queries (see level 5) but others are not clearly defined yet and discussions are still held in the W3C WG repo.

I can see two extra settings at first sight:

• unfloat elements
• remove drop caps

Anything else?

I'm submitting a feature request

Short description of the issue/suggestion:

The build process is currently all or nothing for user settings, you can only bundle, you can’t “compile” each module into a specific stylesheet.

What is the expected behaviour?

With HTTP2, it makes sense to break up CSS into smaller files e.g. user settings submodules. We should anticipate this need.

What is the current behaviour?

We’re currently bundling everything into the ReadiumCSS-after.css stylesheet.

What is the motivation / use case for changing the behaviour?

Implementers might prefer to append/remove styles for user settings on user interaction.

Do you know which CSS modules (stylesheets) are impacted?

This is limited to user settings.

Other information (e.g. related issues, suggestions how to fix, links for us to have context)

• That’s probably for v1, and not the beta.
• I would vastly prefer implementing that using good old gulp/grunt given how tedious Webpack or some others are at working with CSS – creates an awful lots of issues for people not familiar with the latter bunch.

This will be a tougher one.

Unlike horizontal RTL, for which there is an attribute you can target in CSS (dir), vertical-writing is a CSS property: you need to know its value (and there are deprecated values to take into account if you want to support IE 11). Please feel free to confirm/infirm, maybe I’m missing something obvious there.

We definitely need to constrain the height of the document in scroll mode, when vertical-writing is used, so I’ll probably bet on appending a flag inside html so that we can do that in CSS.

Unfortunately, there is another painful issue we must take into account: -epub-writing-mode (in which the prefix is the culprit).

Blink and Webkit have aliased the -epub- prefix, Gecko didn’t (FYI didn’t check Trident/EdgeHTML yet). Consequently, if the author is using -epub-writing-mode: vertical-rl, it will fail in Firefox, Gecko wants the unprefixed property there.

I’m pretty sure those issues were tackled in Readium 1 at some point, so any hint would be greatly appreciated.

I need to design a boilerplate for the default stylesheet (cf issue #3) and Reading System themes.
What is interesting is that, in theory, authors and users could use it too.

Here is a list of the settings I’ve currently implemented. Consider this a draft which may evolve depending on implementers’ feedback.

Once again, we’re leveraging CSS custom properties (a.k.a. variables) so you can choose to use them dynamically or “compile” them to fixed values beforehand.

Finally, the stylesheet is based on HTML5 Suggested Rendering. We’ll have to see if we need to take care of stuff like <p class="heading1"> or not (it’s probably not worth it considering we’ll always have edge cases we can’t manage properly).

• --THEME__textColor: global color of the text
• --THEME__backgroundColor: global color of the background
• --THEME__baseFontFamily: typeface for body copy (you can use font-stacks listed in #4)
• --THEME__compFontFamily: typeface for headings (and other elements of your choice)
• --THEME__codeFontFamily: typeface for code
• --THEME__baseFontSize: font size for body copy
• --THEME__baseLineHeight: line-height for body copy
• --THEME__flowSpacing: margin-top and -bottom for flow content (block elements)
• --THEME__paraSpacing: margin-top and -bottom for paragraphs (overrides the former var)
• --THEME__paraIndent: text indent for paragraphs
• --THEME__typeScale: Should you use this variable, font-sizes for headings can be computed automatically. Values can be [1.067 | 1.125 | 1.2 | 1.25 | 1.333 | 1.414 | 1.5 | 1.618] to enforce harmony, or any other custom value. What’s interesting there is that you can change the value dynamically, depending on the user’s font-size, the size of the screen, etc.
• --THEME__linkColor: color of links
• --THEME__visitedColor: color of visited links
• --THEME__primaryColor: primary accentuation color (you could use for headings for instance)
• --THEME__secondaryColor: secondary accentuation color

Note to implementers:

CSS Variables are cascading, which means you get a lot of flexibility. If not set, they will simply fall back to the inherited/initial value, or the fallback you have set. In other words, you can have a stylesheet with variables which are not declared, anticipating the user adjusting settings.

You can define a new value for specific elements, you can set them as inline styles, you can manage themes as a simple set of variables (say using JSON) and the styles will update when you append them, you can build an UI so that users can make their own themes, etc.

I’ve written a doc if needed. They’re super powerful, can help ease a lot of issues, and you can always fall back to inline styles if they are not supported.

This will be part of the experimental features we may ship in the beta release.

A pure CSS solution has some drawbacks, as demonstrated in issue 18:

1. it will only work reasonably well in the scrolled view;
2. we have to claim responsibility for at least the line-height (paragraphs);
3. you can end up with the same background color at the end of one paragraph and the beginning of another;
4. I’m unable to tell how much memory and CPU this will consume since linear-gradient is quite heavy, CSS-wise.

Possible alternative is something like lining.js, which might bring support to the paged view – right now, I can’t tell.

Short description of the issue/suggestion:

We have a lot of docs in markdown form that could be published almost AS-IS, similar to what’s being done on https://github.com/readium/architecture.

What is the expected behaviour?

Docs + intro (ReadMe) available as a website i.e. readium.github.io/readium-css

What is the current behaviour?

You have to take a deep dive into the master branch to find the doc.

What is the motivation / use case for changing the behaviour?

It would be a lot more readable and easier to access.

Other information (e.g. related issues, suggestions how to fix, links for us to have context)

Beware navigation across docs and links I guess.

To sum things up those samples were automatically created from Wikipedia pages, and the markup is quite unsatisfactory – to say the least. It can occasionally create issues in vertical writing mode as some divs will overlap.

Although they’re good enough for our current tests, which are quick i18n checks (font, default, metadata, etc.), it could be useful to improve markup in the future so that we can extend tests to more complex stuff (including advanced user settings, etc.).

I won’t be able to manage that for the time being (got the alpha version to release and monitor) so any PR would be greatly appreciated. If you’re willing to help, do not hesitate to contact me if you have questions. Please be aware you must sign and send the Readium ICLA before doing the PR though.

This is the crux of issue #19 about vertical-writing so I decided to open a more specific issue.

To put things simply, a lot of stylesheets won’t ship with all the necessary prefixed and/or unprefixed properties, especially the -epub-props, which can create quite a visible issue with writing-mode, and some others as well.

In the alpha version of ReadiumCSS, we’re enforcing writing-mode when needed, based on a chain of educated guesses (language of the publication, page-progression-direction, etc.) but that’s at the document :root level, and doesn’t take children into account.

And there’s a lot more:

• text-emphasis
• text-orientation
• text-combine-upright
• word-break
• line-break
• hyphens
• text-transform
• etc.

See this mappings table in this PostCSS plugin (which is a proof of concept).

From Laurent:

A radical solution would be to avoid treating such issues "on the fly", but as a "repair" action activated by the user himself. Because after all, the culprit is the missing standard CSS property, and this should be solved once for all in the EPUB file.
To do this, we would have to a/ developer a "repair" (or "cleaning") lib b/ offer it as a command line tool and/or c/ plug it into the Readium test apps in some way.

I really can’t see any other way than preprocessing stylesheets to add the missing properties, to be honest, since unsupported properties can’t be retrieved using getComputedStyle.

This primarily impacts Gecko/Quantum and Trident/EdgeHTML so we’re talking about web apps there, although some developers could decide to use the native Windows WebView – also heard about an Electron-like framework built on top of Quantum but I can’t find any info about that right now.

See edrlab/thorium-reader#20

Not sure this can be the job of CSS though as it is kinda simplistic (a 5-minute implementation) and I’m unable to list all the possible issues it could create… but here we go. Off the top of my head:

• the CSS for the two methods would have to be different so it can’t live as a pure static representation in ReadiumCSS, it would have to be handled depending on the pagebreak markup (empty + title VS. number in a span);
  • either via a flag/class/attribute;
  • or injected dynamically as a link or style in the <head>.
• in the spread view (two columns), as a user, I’d probably expect numbers to be displayed in the outside margin (so left for the left column and right for the right column) but that’s only my preference and can’t tell what others would expect, obviously;
• high page numbers → there is a possibility the margin could not be large enough to accommodate 3+ numbers very well:
  • we have a page margin setting to take into account;
  • should the font-size increase with the content’s?
• that would be part of content, not UI:
  • users will get two different paginations: the pagebreak one in margins and the UI one in the page’s footer – I can remember that iBooks supported pagebreak at some point, and they decided to replace the footer’s pagination with the pagebreak one at the time, then removed support for some reason;
  • cascading issues with screen readers?
  • cascading issues with selection/highlight?
  • cascading issues with CFI/Search?
• kind of an edge case but we should also probably take into account that numbers in margins can also be used to number lines or paragraphs in some publications (plays, STEM, etc.). I’ve seen ebooks numbering lines with a number on the left/right (not in margins because it’s not possible for authors) so in this case, the user would have two different sets of numbers.

This could be a good candidate for the “experimental features” we’ve been discussing two weeks ago though – and would allow us to test in real conditions.

Am also wondering if experimental features should maybe be plugins (and not modules per se)?

This issue mainly impact variables but can impact the global design (and docs) as well.

There are some inconsistencies here and there and I’d really like to correct them so that implementers don’t have to deal with some cognitive overhead: something that is not logic or natural, etc. For studying linguistics, I know how important it is to have a coherent system in which things that achieve the same look the same so do not hesitate to report issues related to this.

As far as I can tell:

• Variables related to background- and color (including ::selection and links) should use the same prefix: it is not the case yet (we have --RS__ and --THEME__; the most natural option would be managing that as a ReadiumCSS-day_theme.css stylesheet and use --THEME__.
• we’re missing default values for letter- and word-spacing in the docs.
• The --USER__advancedSettings flag is actually working backwards since we’re mapping that to “Publisher’s Styles”. Since it’s the only flag working that way, it might be surprising at first sight.
• disabling hyphenation for inline code and var, etc. (i.e. in paragraph) should be in the patch stylesheet and not user settings, as it should probably be disabled in any case.

While I can get hyphens: auto to work in Chrome Desktop, we just can’t get it to work in Chrome Mobile (including Web Views).

Here’s what you can get on Desktop:

On mobile, it just won’t happen…

Even in landscape…

Tried changing the lang attribute from en to en-US to check if their mapping is super strict, to no effect.

Checked other ebook apps, and got the same result: no hyphens.

It kinda drives me crazy as it is supposed to be supported in Chrome only on Android and Mac…

Links:

• Chrome’s intent to ship
• Chromium bugs
• CanIUse

This issue originally appeared in the readium-js issue tracker but ReadiumCSS is impacted as well.

We’re currently aligned with iBooks and treat color overrides pretty much in the same fashion for sepia and night modes (heavy usage of !important in night mode to force the color of links or svg text, something we don’t do for sepia mode since it can be treated as the day mode).

Sepia mode: https://github.com/readium/readium-css/blob/develop/css/src/modules/ReadiumCSS-sepia_mode.css
Night mode: https://github.com/readium/readium-css/blob/develop/css/src/modules/ReadiumCSS-night_mode.css

However, we’ll have themes (and custom user colors) in the beta, and things will become tricky.

In anticipation of themes a few months ago, I fantasized sepia and night modes being redesigned as light and dark modes themes (and custom user colors) can actually reuse, but that’s easier said than done.

Indeed, it is not rare apps offer a light blue or mint background, possibly for a11y reasons (pastel backgrounds may help with dyslexia, color blindness, or vision problems for instance) and that can’t work as in sepia mode:

• blue links on a light blue background;
• red on a pink background;
• green/red headings on a mint background;
• #666 text on a gray background;
• etc.

So a light mode in which we don’t override colors wouldn’t work in those cases, it would probably be more like a “twilight/gloom mode”, in between light and dark.

Just trying to learn the lessons from the Compatibility Living Standard there. This will be part of Readium CSS docs.

That’s quite some dirty work but I do believe it’s worth it and it can help in the longer term (interop + compat).

Please review this document and let me know if we can improve it.

This document describes a collection of non-standard CSS properties, metadata, and attributes that implementers should take into account to support for compatibility with the de facto EPUB ecosystem.

It also lists important standard features that authors are accustomed to.

Introduction

There exists an increasingly large corpus of ebook content that depends on non-standard CSS properties, metadata and attributes. This document aims to describe the minimal set that Reading Systems might be willing to support for optimal ebook compatibility.

CSS At-rules

@page

@page

The @page CSS at-rule is used to modify the page margins in Legacy RMSDK (the one for EPUB 2).

Margins applied in this rule will apply to any “screen” in paged views, unlike the ones set for html or body. It could therefore be used to apply extra margins to the web view or iframe.

The @page at-rule can be accessed via the CSS object model interface CSSPageRule.

MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/@page

@supports

@supports

The @supports CSS at-rule lets authors specify declarations that depend on a browser's support for one or more specific CSS features. This is called a feature query.

It is critical for the advancement of modern CSS that implementers try their best at supporting this rule, especially when pre-processing EPUB files before distribution, since it is one of the very few mechanisms allowing authors to do progressive enhancement (layout, typography, etc.) and to get around bugs in older Reading Systems that don’t support it.

MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/@supports

Non-standard Kindle Media queries

Since 2012, Amazon has been providing authors with non-standard media queries so that they can declare specific styles for the old format (Mobi7) and the latest ones (KF8 and above).

@media amzn-kf8

@media amzn-mobi

Authors expect the styles in those declarations to be ignored by EPUB Reading Systems. Do not try to support them.

Docs: Kindle Publishing Guidelines

Interactive and Fixed-layout EPUB 2

There exists a significant corpus of fixed-layout and/or interactive files which leveraged the display options created by iBooks and Kobo for EPUB 2.

Kobo

To declare an EPUB as a FLEPUB (Fixed-Layout EPUB), a file named com.kobobooks.display-options.xml must be present inside the EPUB’s META-INF folder (where the container.xml resides).

The contents of this display options file seem to always be:

<?xml version="1.0" encoding="UTF-8"?> 
<display_options>
  <platform name="*">
    <option name="fixed-layout">true</option>
  </platform>
</display_options>

As of November 2011, FLEPUB supports embedded fonts, audio, JavaScript (partially), media overlays (smil). It doesn't support video and SVG.

Apple

To declare an EPUB 2 file as fixed-layout or interactive, a file named com.apple.ibooks.display-options.xml must be present inside the EPUB’s META-INF folder (where the container.xml resides).

Display Options

Supported display options are:

• platform: *, iphone, or ipad
• specified-fonts: true or false
• interactive: true or false
• fixed-layout: true or false
• open-to-spread: true or false
• orientation-lock: landscape-only, portrait-only, or none (default).

Example

<?xml version="1.0" encoding="UTF-8"?>
<display_options>
  <platform name="*">
    <option name="specified-fonts">true</option>
    <option name="interactive">true</option>
    <option name="fixed-layout">true</option>
    <option name="open-to-spread">true</option>
  </platform>
  <platform name="iphone">
    <option name="orientation-lock">landscape-only</option>
  </platform>
</display_options>

Metadata

Calibre

Calibre is using specific metadata for series and rating.

This metadata has a calibre: prefix.

Series

<meta content="Title of the Series" name="calibre:series" />

This item indicates the series the publication is part of.

Series index

<meta content="1.0" name="calibre:series_index" />

This item designates the position (index) of the publication in this series.

Rating

<meta content="10.0" name="calibre:rating" />

This item stores the rating the user has explicitely set for the publication. 2.0 is one star, 10.0 is five.

iBooks

iBooks is using specific metadata for embedded fonts, versioning, gaiji, scroll axis, and the EPUB3 files created with iBooks Author.

This metadata has an ibooks: prefix.

Authors must add the following prefix attribute in their <package> first:

prefix="ibooks: http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/

Then, they can use the ibooks-specific metadata.

Book versioning

<meta property="ibooks:version">1.0.0</meta>

When using book versioning, content providers are allowing iBooks customers who have downloaded the old version of the book to be notified that a new version is available for download. If the customer chooses to download it, the new version will replace the prior version on its devices.

Unfortunately, there is no way to retrieve the changelog for each version since this is managed at the iTunes level.

Docs: iBooks Asset Guide

Embedded fonts

<meta property="ibooks:specified-fonts">true</meta>

Authors can use the specified-fonts attribute to indicate the EPUB files contains embedded fonts, or override a user’s justification and hyphenation preferences. In other words, it preserves the font-family, text-align, and hyphens declarations as specified in the CSS stylesheet, as long as the user does not choose a different typeface when reading the book.

Docs: iBooks Asset Guide

Gaiji and image sizing

<meta property="ibooks:respect-image-size-class">className</meta>

Gaiji are small, inline images that represent characters that are not available in a character or font set. Gaiji are typically used for older symbols or characters in Japanese that have fallen out of use. Authors can define a custom class name for which iBooks will respect an image's dimensions. Those inline images will then not be altered like other images, for which iBooks may force sizing.

Some authors may have used this metadata to force sizing for specific images, and not only gaiji. Moreover, some might use it to invert specific images like illustrations in night mode, since iBooks does it automatically in order for gaiji to be the same color as text’s.

Docs: iBooks Asset Guide

Scroll axis

<meta property="ibooks:scroll-axis">vertical | horizontal | default</meta>

iBooks’ scroll theme scrolls vertically for books with horizontal text, and scrolls horizontally for books with vertical text. By default, Japanese and Chinese books will thus scroll horizontally, while all other languages scroll vertically. This meta allows authors to redefine the scroll direction.

Docs: iBooks Asset Guide

iBooks Author EPUB3 output

<meta property="ibooks:format">RMT</meta>

This meta is automatically added to EPUB3 files generated with iBooks Author. It is probably used to trigger another rendering engine which supports very specific -ibooks- prefixed CSS properties (i.e. -ibooks-layout-hint, -ibooks-list-text-indent, -ibooks-strikethru-type, -ibooks-strikethru-width, -ibooks-underline-type, -ibooks-underline-width, -ibooks-stroke, -ibooks-popover-background, and -ibooks-popover-shadow) and the Tab Stops for CSS.

Moreover, this format is using interactive widgets which are managed at the Reading System level (the EPUB file contains <object> with a type of application/x-ibooks+widget and custom data-attributes for styling).

It could be used as a flag to indicate that the EPUB file was meant for iBooks and there will be rendering issues, especially interactive widgets since they won’t work as intended by the author.

Attributes

The iBooks Reading System is using a set of custom attributes to manage styling and features.

iBooks writing mode

__ibooks_writing_mode

Values can be the ones for the CSS property writing-mode i.e. horizontal-tb, vertical-rl, or vertical-lr.

This attribute is used to style pagination and scroll, the “page” dimensions, and vertical-alignment of some elements.

iBooks theme

__ibooks_internal_theme

Values can be BKWhiteStyleTheme, BKSepiaStyleTheme, BKGrayStyleTheme, or BKNightStyleTheme.

This attribute is used to apply reading modes (background-color, color and filter).

A handful of authors have been using them as a replacement to alternate stylesheets in iBooks.

iBooks font-family override

__ibooks_font_override

Value can be true.

This attribute is used to indicate DOM elements for which the font-family must be changed when the user applies a typeface.

iBooks text-align override

__ibooks_align_override

Value can be true.

This attribute is used to indicate DOM elements for which text-align must be changed when the user sets justification preferences.

iBooks respect image size (gaiji)

__ibooks_respect_image_size

Value can be true.

This attribute is used to style images which class have been explicitly set in the ibooks:respect-image-size-class meta.

Non-standard CSS properties

EPUB authors may have used the following non-standard properties to achieve specific styling or get around Reading Systems’ overrides.

Adobe text layout

adobe-text-layout

Values can be optimizeSpeed and (probably) optimizeLegibility, or auto.

Although this property and (especially) its values look like something close to text-rendering – so close that authors might have been using text-rendering instead –, it isn’t exactly the same.

At the time RMSDK 9.2 was released, this CSS property allowed authors to disable the typography enhancements, including hyphenation, by forcing the older text engine. It was thus primarily used to disable hyphenation, as some devices didn’t support adobe-hyphenate – and you could not disable hyphens for headings for instance.

Source: MobileRead Forums

Overflow scrolling

-webkit-overflow-scrolling

Values can be auto or touch.

The -webkit-overflow-scrolling CSS property controls whether or not touch devices use momentum-based scrolling for a given element.

Some authors may have been using this CSS property to improve the scrolling of overflowing elements, especially in fixed-layout.

Docs: Safari Docs

Non-breaking space mode

-webkit-nbsp-mode

Values can be normal or space.

The -webkit-nbsp-mode CSS property specifies the behavior of non-breaking spaces within an element.

This CSS property might pop up in files generated with the built-in MacOS’ (Cocoa) HTML generator.

Please note that although it might fix an issue in some languages like English, it might also create other issues in some languages, where non-breaking space shouldn’t be treated as a normal space (e.g. punctuation in French).

Docs: Safari Docs

Text fill

-webkit-text-fill-color

The -webkit-text-fill-color property defines the foreground fill color of an element’s text content.

Authors may have used this property to force a color for text in night mode, especially when targeting iBooks.

Text stroking

-webkit-text-stroke
-webkit-text-stroke-color
-webkit-text-stroke-width

The -webkit-text-stroke-color property specifies a stroke color for an element’s text, the -webkit-text-stroke-width property specifies the width of the stroke drawn at the edge of each glyph of an element’s text.

This can (rarely) be used to achieve text with a stroked effect, or faux bolding.

Background color and gradients

-webkit-linear-gradient()

The -webkit-linear-gradient() function must be treated as an alias of linear-gradient().

Some authors might have been using this to force a background-color in night mode, so it would be used in combination with -webkit-text-fill-color so that the text color is forced as well.

Mobile Text Size Adjustment

-webkit-text-size-adjust

The -webkit-text-size-adjust property allows control over the text inflation algorithm used on some mobile devices, many mobile browsers indeed apply a text inflation algorithm to make the text larger and more readable. By using this property, authors can simply opt out or modify this behavior.

Some web authors and/or authoring software might be using this property out of habit, but it actually breaks iBooks’ font-size user setting for instance. This should not be an issue in Readium CSS.

Docs: CSS Mobile Text Size Adjustment Module Level 1

Text decoration styling

-webkit-text-decoration-line
-webkit-text-decoration-color
-webkit-text-decoration-style

The -webkit-text-decoration-line CSS property sets the kind of decoration that is used on text in an element, the -webkit-text-decoration-color CSS property sets the color of the decorative additions to text and the -webkit-text-decoration-style CSS property sets the style of the lines.

There are standard unprefixed properties for these but some authors may have been using the -webkit- ones only.

MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Text_Decoration

Hyphenation

adobe-hyphenate

Values can be none, explicit, or auto.

This must be treated as an alias of hyphens.

A very large part of authors have been using this CSS property to control hyphenation. It should not be an issue as they probably at least used -webkit-hyphens and -epub-hyphens in addition to this adobe-hyphenate CSS property.

Source: MobileRead Forums

Hyphenate limit

-webkit-hyphenate-limit-before
-webkit-hyphenate-limit-after
-webkit-hyphenate-limit-lines

The -webkit-hyphenate-limit-before CSS property indicates the minimum number of characters in a hyphenated word before the hyphenation character, the -webkit-hyphenate-limit-after CSS property indicates the minimum number of characters in a hyphenated word after the hyphenation character, and the -webkit-hyphenate-limit-lines CSS property indicates the maximum number of successive hyphenated lines in an element.

Those properties are standardized in CSS Text Module Level 4, but -webkit-hyphenate-limit-before and -webkit-hyphenate-limit-after have been replaced with the hyphenate-limit-chars CSS property.

Docs: CSS Text Module Level 4

EPUB properties

Some authors might have used -epub- prefixed properties only, thinking they were enough since those CSS properties were standardized. Authors are now strongly encourage to use unprefixed properties.

In the meantime, implementers may want to polyfill at least some of those properties, especially those related to vertical writing, as practical issues may arise due to the lack of file updates on the authoring side. A mapping is available in the EPUB 3.1 spec if needed.

One important part of the Readium CSS project is collecting feedback and queries from the e-production community (CSS authors).

I think it is important to make a recap so that this information is available to implementers and authors can weigh in—I know there’s an issue #1 for this but it has gone way out of focus and quite difficult to parse.

CSS Authors’ typical profile

The typical CSS author has been doing e-production for 3 years or more (76%), is primarily concerned about interoperability (80%) and feels like he/she gets at least CSS fundamentals (88%). Also, most of his/her queries are related to layouts you can do in print that you can’t in ebooks yet.

So, I know there is no average, there are extremes (and the middle will take care of itself), but from experience, I can tell that is a pretty common profile in the eprdctn community. Same for queries, as publishing is still a print-first industry (and print layouts are “the gold standard”).

A few personal notes:

• interoperability implies Kindle, back to Mobi7 (which was ± HTML 3.2);
• from the samples we could collect, there were (a few) specific versions of EPUB files for iBooks, which is an issue partly related to distribution (authors don’t know the app the reader will use and don’t want risking rendering issues);
• sometimes, specific versions mean authors (and/or software) will fall back to EPUB 2 files, in order to get around support uncertainty;
• one key is probably progressive enhancement techniques, but that’s more of an education/evangelization issue—we quickly discussed this with @HadrienGardeur and the lack of pragmatic docs, best practices, etc. indeed can be a practical issue.

Workflow and authoring

Workflow is still print-centric

DTP software is still prevalent (more than 2/3 of answers), but automation is a thing (XML and even Node.js).

This means that should we provide new design options, change won’t happen overnight. Authors would have to add them to their workflow first (manual editing or automation upgrade), then authoring software would have to support them.

What’s interesting is that most authors would appreciate having such design options (more than 75%, on two polls), but if there isn’t any side-effects in other apps (cf. interoperability). Of course that would require production moving to EPUB 3 (EPUB 2 still makes up roughly 70% of all incoming content @ Kobo).

So once again, we have an education/evangelization issue there.

Authoring practices

CSS authoring varies greatly—and this shows in our samples, we’ve even found a file in which InDesign generated styles were inlined.

Almost 2/3 of authors use a custom stylesheet that they adjust for every book, very few actually rely on the styles output by their DTP tools. As a consequence, there’s no consensus when it comes to the CSS selectors authors use. It can be:

• p
• .class
• p.class
• div.class p.class
• [epub|type=""] p
• super-specified selectors with or without combinators (from samples).

Reasons include:

• ease of use;
• complexity and variety of the publication contents;
• semantics (especially with epub:type);
• “that’s how the conversion vendor does it.”

To me, it means that if we want to solve the user settings issue well, we’ll have to find clever and inventive ways, selectors specificity being a dead-end in practice.

There’s a proposal for user agent properties, a draft for customization, etc. and I feel like they have some potential—for upcoming files, what’s already distributed is probably lost—, should EPUB have a “do not touch my CSS” mechanism at some point. E.g, with user agent properties, authors could design user-centric stylesheets (in theory, RS could not override styles at all and just set values for those properties).

In the meantime, we have to “emulate” the cascade (see issue #5) and resolve to !important. So that’s trying to make a not-so-perfect mechanism into something more elegant, which requires a lot of fine-tuning.

Worries and issues

Worries

What bothers authors the most:

1. the app overriding styles without asking/user’s explicit demand (a.k.a. user setting)
2. the complete lack of control over page layout (margins, background, etc.)
3. user overrides which are all or nothing

Interestingly, reading modes’ adjustments and user settings feedback are not priorities—which doesn’t mean they aren’t concerns. There’s two assumptions I could make there:

• providing readers with images filters in night mode (cf. issue #7) is probably the best first step we can make as a significant part of authors might not use extra markup to deal with it on an image-per-image basis (especially if no other RS supports it);
• user settings feedback is probably one of the best practical ways to deal with non-binary user settings and overrides (cf. user agent properties proposal) so, once again, education/evangelization kicks in.

Issues

Top issues in order of priority:

1. images’ sizing e.g. author’s sizing is not respected, image is cut-off (we have a safeguard for that);
2. broken media queries (which makes responsive design impossible);
3. lack of support for modern CSS;
4. Math.

I guess this won’t surprise anyone, those are long-standing issues in need of solutions (media queries don’t work in columned-content) and fixes (flexbox, grid, and modern layout specs have a lot of bugs in columns’ implementations). Our best bet there is collaborating with the CSS-multicol spec editors since we’re probably one of the major use cases for this spec.

Popular requests

Unsurprisingly, a lot of requests are about layouts possible in print that you can’t do in e-.

• full bleed (container, image, background-color)
• support for paged-media (running header/footer, float figures top/bottom, etc.)
• vertical centering and alignment
• floated shapes (wrapping the image and not its bounding box)
• possibility to use margins for icons
• baseline grid
• force chapter title as running header
• proper support of page-breaks
• media queries for reading modes (sepia, night, etc.)
• stylable popup footnotes

Interoperability issues reported

We care deeply about interoperability. Although Readium CSS has been designed from scratch, a lot of research has been put into other Reading Systems in order to improve interop (and not introduce breaking changes/side-effects). To my knowledge, we’re even the first project openly tackling EPUB implementations’ interoperability.

Let’s say that one of our major goal is to provide authors with a solid bedrock, so that Readium CSS does not become an issue for them.

A few interop issues have been reported, and I guess it’s worth listing them:

• page margins: some apps/devices have huge page margins, others don’t have any, it’s really hard for authors to know what they should be doing here (margin: 0 or margin: value);
• support the stuff that already exists, don’t create custom namespaces/metadata (the issue being that some existing specs are really really hard to implement well in practice);
• image optimization (I guess this can be related to picture and srcset);
• font obfuscation isn’t implemented everywhere.

This is a draft for a future implementers’ doc. Please feel free to review the recommendations.

While we recommend using system fonts to get the best performance whenever possible, implementers might want to use Open Source Fonts in order to provide users with more choice. On the Android platform, for instance, system fonts are limited to one typeface per family, which means you don’t get a lot of options out of the box.

Consequently, amongst the thousands of fonts available online, a pre-selection of 26 have been reviewed in details. Those typefaces were selected based on multiple factors:

1. they have enough styles (4: regular, italic, bold, bold italic) and don’t break authors’ expectations;
2. they can be used in body copy;
3. they are of good quality and were designed with screen rendering in mind;
4. they can be free alternatives to system fonts available on other platforms;
5. they offer good-enough support for at least latin languages.

Here’s the complete list of those 27 fonts:

• IBM Plex Sans
• IBM Plex Serif
• Crimson Text
• Spectral
• Vollkorn
• Lora
• Gandhi Sans
• Gandhi Serif
• Gentium Book Basic
• PT Sans
• PT Serif
• Merriweather Sans
• Merriweather Serif
• Alegreya
• Heuristica
• Bitter
• Charis SIL
• Faustina
• Volkhov
• Libre Franklin
• DejaVu Sans
• Rubik
• Source Sans Pro
• Fira Sans
• Proza Libre
• Rosario
• Clear Sans

How were those fonts reviewed

Each of the 27 fonts has been undergoing tests in real rendering situations.

They were rendered on the Android, iOS, MacOS, and Windows platforms, using SD and HD displays when possible, in multiple browsers (IE11, Edge, Safari, Chrome, Firefox).

Then each font was:

1. compared to its closest reference (system font);
2. tested against the latin, cyrillic and greek languages;
3. tested against the small capitals and numeric OpenType features.

Note: For some reason, a lot of Google Fonts don’t have the “™” character so you’d better fine-tune your font-stacks.

Results

It is important to state that you can’t really go wrong with those fonts. We simply decided to go with fonts providing the best rendering in the worst situation possible (Windows ClearType on a mediocre screen), and the best language support as well. If you don’t have to support Windows, for instance, then you can try fonts we don’t recommend.

We sometimes forget that users can’t necessarily afford bleeding-edge technology, which is why it was important to review those fonts in various conditions.

For your information, here are the results for Windows ClearType rendering at 1em (or 100%).

Buggy

• IBM Plex Sans (will become excellent once hinting issues are fixed)

Mediocre

• Alegreya
• Crimson Text (supports latin + cyrillic + greek though)
• Lora
• Spectral (maybe try using medium instead of regular on Windows)

Average

• Gentium Book Basic
• Heuristica
• Volkhov
• DejaVu Sans
• Faustina (Average+)

Good

• Vollkorn
• PT Serif
• Bitter (the Google Fonts version was reviewed but the FontSquirrel version is more complete)
• Charis SIL
• Rubik
• Source Sans Pro
• PT Sans
• Gandhi Serif

Excellent

• IMB Plex Serif
• Merriweather Sans
• Merriweather
• Gandhi Sans
• Fira Sans
• Proza Libre
• Rosario
• Clear Sans

Recommended Typefaces

Twelve typefaces are recommended so that implementers can pick a few among this extended selection.

Note: Supported Languages focus on diacritics. Support for latin languages like English, which are not using diacritics, is implied.

Serif fonts

Charis SIL

• Source: https://software.sil.org/charis/
• Google Fonts: NO
• Design: SIL International
• License: SIL-OFL

• Reference: Charter
• Classification: Slab
• Styles: 4
• Metrics:
  • Contrast: TBD
  • x-height: TBD
  • weight: TBD
  • width: TBD

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish, Cyrillic.

OpenType Features: none

Faustina

• Source: https://github.com/Omnibus-Type/Faustina
• Google Fonts: YES
• Design: Omnibus Type
• License: SIL-OFL

• Reference: Charter, Bookerly
• Classification: Slab
• Styles: 8
• Metrics:
  • Contrast: 0.39
  • x-height: 0.76
  • weight: 0.06
  • width: 0.45

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish.

OpenType Features: none

IBM Plex Serif

• Source: https://github.com/IBM/type
• Google Fonts: NO
• Design: IBM
• License: SIL-OFL

• Reference: Georgia, Droid Serif
• Classification: Modern
• Styles: 6
• Metrics:
  • Contrast: TBD
  • x-height: TBD
  • weight: TBD
  • width: TBD

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish.

OpenType Features: none

Merriweather

• Source: https://fonts.google.com/specimen/Merriweather
• Google Fonts: YES
• Design: Sorkin Type Co
• License: SIL-OFL

• Reference: Iowan Old Style
• Classification: Modern
• Styles: 8
• Metrics:
  • Contrast: 0.51
  • x-height: 0.75
  • weight: 0.08
  • width: 0.52

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish, Cyrillic.

OpenType Features: none

PT Serif

• Source: https://fonts.google.com/specimen/PT+Serif
• Google Fonts: YES
• Design: ParaType
• License: Paratype PT Serif Free Font License

• Reference: Charter
• Classification: Slab
• Styles: 4 (+ 2 for captions)
• Metrics:
  • Contrast: 0.55
  • x-height: 0.71
  • weight: 0.06
  • width: 0.47

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish, Cyrillic.

OpenType Features: none

Vollkorn

• Source: http://vollkorn-typeface.com
• Google Fonts: YES
• Design: Friedrich Althausen
• License: SIL-OFL

• Reference: Athelas, Bembo
• Classification: Modern
• Styles: 8
• Metrics:
  • Contrast: 0.53
  • x-height: 0.68
  • weight: 0.06
  • width: 0.45

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish, Cyrillic

OpenType Features: small caps, numeric figure values, numeric spacing values (and more)

Sans-serif fonts

Clear Sans

• Source: https://01.org/clear-SANS
• Google Fonts: NO
• Design: Intel
• License: Apache 2.0

• Reference: Trebuchet MS
• Classification: Sans
• Styles: 8
• Metrics:
  • Contrast: TBD
  • x-height: TBD
  • weight: TBD
  • width: TBD

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish, Cyrillic, Greek.

OpenType Features: none

Fira Sans

• Source: https://github.com/mozilla/Fira
• Google Fonts: YES
• Design: Carrois Apostrophe for Mozilla
• License: SIL-OFL

• Reference: Seravek
• Classification: Humanist
• Styles: 18
• Metrics:
  • Contrast: 0.25
  • x-height: 0.76
  • weight: 0.07
  • width: 0.42

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish, Cyrillic, Greek.

OpenType Features: none

Libre Franklin

• Source: https://github.com/impallari/Libre-Franklin
• Google Fonts: YES
• Design: Impallari Type
• License: SIL-OFL

• Reference: Arial, Helvetica, San Fransisco, Franklin Gothic
• Classification: Sans
• Styles: 18
• Metrics:
  • Contrast: 0.28
  • x-height: 0.71
  • weight: 0.07
  • width: 0.44

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish.

OpenType Features: none

Merriweather Sans

• Source: https://fonts.google.com/specimen/Merriweather+Sans
• Google Fonts: YES
• Design: Sorkin Type Co
• License: SIL-OFL

• Reference: Arial, Helvetica, San Fransisco
• Classification: Sans
• Styles: 8
• Metrics:
  • Contrast: 0.30
  • x-height: 0.75
  • weight: 0.08
  • width: 0.45

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish.

OpenType Features: none

PT Sans

• Source: https://fonts.google.com/specimen/PT+Sans
• Google Fonts: YES
• Design: ParaType
• License: Paratype PT Sans Free Font License

• Reference: Seravek
• Classification: Humanist
• Styles: 4 (+ 2 for captions + 2 for narrow)
• Metrics:
  • Contrast: 0.16
  • x-height: 0.71
  • weight: 0.06
  • width: 0.39

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish, Cyrillic.

OpenType Features: none

Source Sans Pro

• Source: https://github.com/adobe-fonts/source-sans-pro
• Google Fonts: YES
• Design: Adobe
• License: SIL-OFL

• Reference: Seravek
• Classification: Humanist
• Styles: 12
• Metrics:
  • Contrast: 0.20
  • x-height: 0.74
  • weight: 0.06
  • width: 0.39

Supported Languages: Albanian, Bosnian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Turkish.

OpenType Features: numeric figure values

Windows

We recommend picking system fonts if you don’t find any in this list of recommendations. Indeed, Microsoft has been investing a lot of resources to design fonts that render perfectly on this platform, especially with ClearType. Typefaces like Cambria, Constantia, Arial Nova, Georgia Pro, Sitka, Verdana Pro, and more, offer a large amount of styles, excellent language support and perfect rendering, even on mediocre screens.

There’s really no need to use an alternative if you can use those typefaces.

I'm trying to find a way to fit cover image onto single page. CSS has max-height: 95%; and max-width: auto; as well as a container p with object-fit: contain; and overflow: hidden;. But Readium is ignoring this. Any suggestions?

There is quite a lot of information we could document thanks to contributors’ insights, feedbacks and reports. So thanking those contributors in an acknowledgments section is I guess the least we can do.

Currently, we’re relying on CSS for horizontal margins (left/right). Vertical margins (top/bottom) are managed at the web view (or iframe) level so that we don’t mess with the viewport height unit.

Source is available on the phase1-pagination branch.

This issue discusses the pros and cons of using this CSS implementation.

How it works

Line-length

Because columns have a floor but no ceiling in this configuration i.e. they can grow to 100% of their container’s width, we have to limit line-length using max-width on body.

body {
  max-width: 35rem;
}

Which means we must have margin set to auto so that the page is centered.

body {
  max-width: 35rem;
  margin: 0 auto !important;
}

In pink, the column width, and in yellow, the elements nested in body. The margin: auto centers the page.

It is still unclear how we should manage max-width though, since some EPUB files may have one set by the CSS author i.e. do we !important it or not.

This max-width is set using a CSS variable.

:root {
  --RS__maxLineLength: 35rem;
}

Which means you could use px, ch, etc. as units. By using rem in combination with margin: auto, we simply leverage HTML’s default responsiveness: the bigger the root font-size, the smaller the left and right margins, which is something you would expect in terms of typography.

Page margins

Since margin: auto can be 0, we must set a minimal page margin by using padding i.e. internal margin, which impacts the box sizing. Consequently, we have:

body {
  max-width: 35rem;
  margin: 0 auto !important;
  box-sizing: border-box; /* We need it because padding is part of the box */
  padding: 0 20px !important;
}

Once again, this can be set with a variable.

:root {
  --RS__pageGutter: 20px;
}

It is set in pixels so that it doesn’t increase with font-size.

As you can see, there is no column-gap, everything is currently managed with padding.

Since body is laid out in columns, this padding will be applied to each column i.e. 2 × 20px in two-page spread. It will also add up to column-gap i.e. 2 × 20px + column-gap (this value is currently 0 as it wasn’t yet implemented in the scroll function).

Pros

Closer to the metal

We rely on the browser/web view to compute and lay out everything, avoiding possible rounding errors which might create extra bugs (due to JS’ inaccuracies you must take care of).

You don’t have to tweak values in real-time so it’s faster in theory. We’re trying to take advantage of columns’ logic there. Although they’re using a pseudo-algorithm and are missing some pieces (minmax() for columns’ width, like in CSS grid), they can do great things once they are tamed. But we must also make sure this approach won’t have side effects on CFI.

It is responsive by default i.e. “one font-size to rule the whole.” For instance, if font-size is too big for 2 columns then it will automatically switch to 1, max-width taking over to manage the line-length.

Customizable

Although it’s responsive by default, you can still use CSS variables to force specific values if needed.

Easy fine-tuning

You can fine-tune padding with media queries, either by targeting devices or relative widths.

User settings

Switching from 1 to 2 columns is one line of CSS but you would have to enable/disable the setting in some conditions e.g. make it available only in landscape mode on mobile.

A custom margin user setting could be applied changing the value for padding. Thanks to box-sizing: border-box, it would also apply to the page in portrait mode.

You would get some flexibility with the font-size setting i.e. either keeping the same page size in all configs or making it responsive to the current font-size.

Extra design options for CSS authors

Should an implementer decide to use CSS variables in production, and since they are interpolated by the rendering engine itself, it could open up new design options for CSS authors. For instance, you could in theory do “full-width” images by using the RS__pageGutter variable.

/* Please note you’ll obviously need a fallback so the following should be put inside a feature query */

figure.full-width {
  position: relative;
  left: 0;
  left: calc(var(--RS__pageGutter) * -1);
  width: 100%;
  width: calc(100% + var(--RS__pageGutter) * 2);
}

It works in two-page spread too.

You could also expose that as a data-attribute (e.g. data-RS-figure="full-width") in order to manage it as you wish or set the --RS__pageGutter variable as the value of another variable so that you can manage it in different configurations, especially as you may have set a column-gap, which would have to be taken into account for left and width, and reset overflow to visible for the figure.

:root {
  --authorPrefix__figureGutter: var(--RS__pageGutter);
}

/* Two columns */
@media screen and (min-width: 60em) {
  :root {
    --authorPrefix__figureGutter: 0px !important;
  }
}

We could also have full-width headers, blockquotes, preformated text, etc (padding would simply be --RS__pageGutter to align contents).

I guess it would be more reasonable to tag anything CSS Variables as progressive enhancement in such cases, so that implementers don’t have to polyfill for browsers which don’t support them—should they use CSS variables, obviously. But that is implementers’ call.

Authors willing to do such effects will do it anyway. Only will they have a margin/padding on every element but figures. This might irritate some readers because this margin could be set in em and reflow with font-size, or px and be too large on small screens, or doesn’t adapt to the margin user setting, etc.

If we could at least explore and discuss design solutions (and their issues), it would improve the current situation a little bit (authors so frustrated they don’t even want to explain their current problems).

Cons

Logic

The whole logic might not be easy to grasp at first, since columns’ logic might be weird when you’re not used to it. I must still document how columns work to make it clearer to people who are not familiar with it.

You must deal with large screens

On large screens, you either have to control the font-size (bigger default if desktop + large viewport) or the viewport itself (web view || iframe’s size).

Users might no be used to responsive margins

Users might not be used to responsiveness and could see the margin: auto as a bug and not a feature if you decide to use em for max-width (would be computed based on the body’s font-size) or change the font-size at the :root level.

The cascade

CSS authors could mess things up e.g. page margins, line-length, media queries, etc. (either by using super specific selectors to force their own values or by accident), which would defeat this CSS approach since you’ll have to add inline styles in the DOM to make sure your values apply.

By providing design options to authors, we could prevent nasty hacks. Since a lot of hacks are the result of current design limitations, managing some on our side—with much better control—could probably much their life easier, especially if they just have to add attributes in their markup (cf. pop-up footnotes). See issue #1.

Harmony

You can not have equal left, center (gap) and right “margins”. Center (gap) will be at least double the outside margins since you can’t target even and odd columns to apply padding on the left or the right (:nth-column() doesn’t exist).

You could add the missing width for left and right margins to the web view or iframe though.

Two-page spread implies some complexity

You have to reset max-width when you have two columns (or else the gap might be huge), and manage it for larger font-sizes (user-setting).

It requires normalization

You must normalize font-size for :root, at any cost necessary but we can keep the authors’ value for body. In other words, we would have to make it clear authors should consider 1rem = 16px.

How do RS tend do do this?

No margin, no padding, column-width and column-gap are dynamically set in pixels depending on the viewport, and the RS sometimes switches to one column when font-size is too big for 2.

Consequently, a user setting for page margins would bring some complexity and some Reading Systems prefer not to implement it.

Please note we should at least have a minimal margin (5–8px) for body. Indeed, should some glyphs appear at the start or end of the line, their descendants/ascendants might be clipped in italic/script (e.g. “f”, “g”, “j”). See this SO issue + I can report iBooks has had this issue since they removed their 5-pixel margin-left and -right on body and some users have complained about it publicly.

What we need

• Implementers’ and authors’ feedback to check whether this approach can be sustainable.
• Samples from publishers/CSS authors because we’re walking on eggshells there.

Since some user settings heavily depends on this decision, it’d better be taken as soon as possible. “Default CSS” and “reading modes” phases shouldn’t be impacted at first sight but the sooner, the better.

Right now, responsive columns (i.e. page → spread) are in the pagination module, which may raise implementation issues for various reasons e.g. dev wants to manage it programmatically, colNumber user setting doesn’t work in some contexts, etc.

It will be a lot better to create a specific module that implementers can opt-in – or opt-out, to be discussed.

Impact:

1. pagination: https://github.com/readium/readium-css/blob/develop/prototype/src/ReadiumCSS-pagination.css#L116
2. user pref: https://github.com/readium/readium-css/blob/develop/prototype/src/user-settings-submodules/ReadiumCSS-colNumber_pref.css#L13

Implementers might want to manage the availability of the user setting in the UI anyway (for instance, only allowing it on smartphones in landscape mode) so managing this via CSS can be a complication in some situations.

When using RLT css, this book cover is cut off and has strange flow.
Please check this link for testing files. readium/swift-toolkit#185
As shown in the picture below, It could be reproduced with Safari on Mac. It has the same effect in our app using WKWebView. It should looks good in WKWebView.
This is a SVG node inside h1 node. If I move everything from h1 to body, it will be fixed.
So, there might be some problem with h1 styles.

Following a discussion related to the iOS implementation, we defined 4 types of overrides:

1. chrome (UI);
2. chrome advanced;
3. user overrides;
4. user overrides UI.

It would be great if we could reach a consensus so that this classification can become some sort of recommendation.

Chrome

• reading modes
• paged/scrolled view

Chrome advanced

• number of columns
• margins
• custom reading modes (background and text color)
• filters (darken and invert for night mode)

User overrides

• font-family
• font-size

User overrides advanced

• line-height
• text-align and hyphens (those two should work together)
• paragraph spacing
• paragraph indent
• letter-spacing
• word-spacing
• type scale
• all bold (that should probably be a typeface in the humanist stack though)
• no italics

Opinions?

[edit] We’ll also probably have extra a11y-related settings e.g. “all bold”, “strip italics”, etc. That could be automatic flags we add when the user picks a theme or even a typeface, or advanced user overrides.

AccessibleDFA should be AccessibleDfa:

(the file itself is AccessibleDfA, but that's alright ;)

Hello @JayPanoz what do you think about CSS text-size-adjust?
https://developer.mozilla.org/en-US/docs/Web/CSS/text-size-adjust

I am asking following the discussion in this issue:
readium/readium-js-viewer#686

Thanks!

As @JayPanoz stated in #4 about Installing extra fonts, this is actually a thing.
Users want to have control to meet their disability, preferences, taste…
Providing a Google fonts install in the reading app is a good thing but what will be better is to provide the list of fonts already aiviable in the system as most of the users would have already installed there their needed fonts.
It needs a work specific for each platform and implementation but will be the best way to provide users an install extra font features.

Most operating systems have a way to install custom fonts at a OS level so why do each app will reinvent the wheel and provide their on way to install font for their own use instead of just letting the user pick in the system installed fonts.
As an example, even iOS which was really close have add a way to install fonts through Apple configurator app and the process is even simpler through http://sub.pentacom.jp/custom-ios-fonts/ or an app like Anyfont. Even font vendors like Myfonts eased the process with an install function directly on the order page.
Before this, each app which want to give this option have done an install in app with the major drawback that the font was only aiviable in the app. Now with system install, all app could browse and pick a font from the system as other OS.
This is an example but most platform have this possibility. Its works to done for each one but this seems the way to go as users willing to install a custom fonts in their reading apps must probably have ever installed it on the system for use in other apps.

This is part of the accessibility baseline, as defined by issue #18

We currently normalize everything but drop caps when the a11y flag is set, removing italics, superscripts, etc.

Drop caps are quite popular in ebooks (for some unknown reason 😛) and their implementation can vary greatly so we need to find some reliable way to normalize them e.g. if using p:first-letter, it won’t override span.dropcap so we need to go the extra mile, it’s impossible to override svg and img, etc.

This normalization is bound to fail with at least some implementations.

Issue originally discussed at:
readium/r2-navigator-js#18

This is an issue I prefer to open early, as discussions will undoubtedly happen when web app implementations will start.

To sum things up, we leverage CSS custom properties (a.k.a. variables), and that makes Readium CSS customizable, JS-friendly, flexible and fast (so far, since we don’t have to traverse the DOM all the time).

Unfortunately, there are a few browsers which won’t, or currently don’t, support CSS Variables. In particular IE11 and Edge 14. While I’ve been designing with this lack of support in mind (for instance, user settings can inherit from inline styles added to html whenever possible), other parts will need a fallback strategy.

It’s worth noting I could actually manage a fallback strategy in pure CSS. Indeed, we could write a static representation as the default, then switch to CSS Variables using feature queries (@supports).

It’s hard to say which strategy will be the best option though, as we need feedback from practical implementations. Some developers will probably resolve to classes or attributes (html) to manage that, others to JavaScript, others might simplify user settings in that case, etc. And there’s of course a consistency concern there.

Needless to say stylesheets can be edited if needed. Implementers could obviously use classes/attributes in the reading modes and user settings stylesheets, they’ve been designed to be strategy-agnostic (the cascade and inheritance being a key there, as this is what will allow implementers to avoid traversing the DOM in JS, wherever possible).

So let’s keep that in mind and see how we can work it out once this issue arises.

This issue is meant for tracking progress.

The roadmap can be found in the Wiki.

August 21, 2017

We’ll publish the Readium CSS prototype on the master branch this week, with basic documentation so that implementers can take a look, review, test and report issues if needed.

A lot of testing has happened this last week, with few minor issues to report, and quite good results in any browser tested (Chrome, Safari, Firefox, Edge).

Proto features

• Support for Latin (LTR, horizontal-writing)
• Basic paged + scroll rendering
• Basic page margins
• Default stylesheets (base, unstyled EPUBs, highlights)
• Basic user settings:
  • night and sepia modes;
  • font family;
  • font size.

Font size being the more complex issue to manage, check issue #8 as it is UX-related.

Ahead of schedule

The good news is that we’re way ahead of schedule for the following:

• Advanced user settings:
  • line-height;
  • hyphenation;
  • text align;
  • paragraphs’ margin;
  • text indent.
• Customizable themes
• A11y-related user settings:
  • letter and word spacing.

Extras

We can reliably offer extra user settings for images in night mode:

• darken;
• invert.

Known issues

• We might need to (partly) implement the outline algo (for font-size) in the normalize stylesheet. Problem is EPUB3 files make heavy use of section and the type scale issues are generally related to aside. If authors use div we can’t do anything.
• max-width in scroll and one-column view (user setting) doesn’t apply because of the media query in pagination at the moment. This will be fix in alpha (advanced paged + scroll rendering).
• User’s line-height may not apply in a few publications.
• Sometimes headings’ margin-left are aligned on text-indent, should we override that if the user sets text-indent: 0?
• Some or all pictures may not be rendered in sepia mode because of mix-blend-mode. It happens in Blink/Webkit in particular, the former being the worst. This has consequently been disabled in the proto.
• Should we set a base line-height? Some authors don’t and the default is something like 1.2?

Note: I’ll use “i18n” instead of “internationalization”.

So let’s be honest, this issue will quite probably stand as “The Readium CSS issue” since it is roadmap-blocking, is impacting other parts of Readium 2 (streamer, navigator, API, apps developed by EDRLab), and will need a lot of documentation. In other words, it’s a project on its own, nested in the Readium CSS project.

I’ve spent the last 3 weeks documenting this issue, and you can think of it as a summary of the research that has been done. I won’t list everything there but only what is critical to provide implementers and readers with a solid baseline. I’m willing to make this baseline the best we can get (say, bulletproof although rough around the edges) but it’s worth noting we’ll need help from experts in those various and diverse languages and their typography to turn it into an excellent user experience.

Roadmap

First and foremost, I’d be in favor of updating our current roadmap. Vertical writing is indeed blocking and I’d like to move it to the beta version.

What it means is that we could ship support for horizontal-tb CJK, Right to Left and Indic languages in the alpha version relatively quickly, and then focus on vertical-writing, since our work on a11y baseline has been ahead of time since the beginning of this project.

I believe we would all probably agree that the prototype has proved a solid-enough bedrock – of course we have edge cases to deal with but it’s fine for the vast majority of contents – and pushing the small and easy wins for RTL/horizontal-tb CJK/Indic on the develop branch would allow us to release an alpha on the master branch early 2018. This would probably send a good signal too since the proto has been released 3 months ago already.

On a related note, we’ll start documenting columns handling (e.g. page progression) in January 2018 so it would make sense to prioritize LTR/RTL (horizontal-tb), especially as we’ll be able to document vertical-writing immediately after – quite frankly, this will be critical since they are conceptual changes to take into account.

Global needs outscoping Readium CSS

Obviously, Readium CSS won’t be able to fly in autopilot mode there. It needs either flags it can target or smart handling of its resources depending on the publication.

Minimal set of features

What we’ll need:

• checking the page-progression-direction for the spine (streamer);
• checking the language, and they can be multiple <meta> (streamer);
• loading specific stylesheets based on those previous indications (API);
• appending xml:lang and/or lang attribute if it’s missing in XHTML documents (API);
• appending dir="rtl" attribute if it’s missing in XHTML documents (API);
• loading specific fonts’ lists for user settings, based on language (Apps);
• adding/removing specific user settings, based on language (Apps);
• having the toc and at least some pieces of user settings (e.g. text-align) with a rtl direction for RTL languages (Apps);
• page-progression from right to left (navigator).

A longer-term issue will be localization, should you want to get this need covered in the apps, as implementers might want an easy way to translate strings, etc. But it’s up to EDRLab, obviously.

Writing-mode and RTL mapping

For writing mode, those are the writing-mode we should apply based on the language and page-progression-direction:

I propose we simplify this model for Chinese and rely on page-progression-direction with an extra check for language (zh), and not bother with all those variants.

It’s worth noting we should not add dir="rtl" there, for the CJK languages.

In Right to left, we can simply rely on page-progression-direction, if the language is not CJK (and Mongolian) but here is a mapping of languages you might encounter, just for your information:

Right to Left

This shouldn’t be a huge issue in Readium CSS, as we only need a few adjustments, specific base and default styles, and typefaces.

Hopefully, this doesn’t impact our views (paged and scrolled) since columns will behave as expected.

Our pagination model is the following:

 _________________    _________________
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|      Col 1      |  |      Col 2      |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
 —————————————————    ————————————————— 

CSS Multicol in horizontal-tb (x-axis)

When the dir attribute is set on html, it becomes:

 _________________    _________________
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|      Col 2      |  |      Col 1      |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
 —————————————————    ————————————————— 

CSS Multicol in horizontal-tb + dir="rtl" (x-axis)

Our main CSS-related concern there should be typefaces, as we’ll need outstanding fonts to deal with typography requirements (ligatures, multi-baseline levels, joining rules, etc.).

CJK (horizontal-tb)

Similar to RTL: we only need a few adjustments, specific base and default styles, and typefaces.

This should already provide support for the vast majority of contents in Chinese (vertical-writing is not used in mainland China, but only in Taiwan, Hong Kong and Macao), and Korean.

Chinese, Japanese and Hangul share a lot in terms of typography but having a few adjustments for each language would be a plus since differences are quite minor.

Other languages

For the time being, we’re only focusing on Devanagari, which should not have a huge impact. Once again, we’ll need a few adjustments, with the main focus being typefaces.

Vertical Writing

This is by very far our biggest issue in Readium CSS since we can’t necessarily manage that well, cross-platform-wise.

We don’t have anything to force the column-axis in CSS, which means that our spread model (two columns next to each other)

 _________________    _________________
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|      Col 1      |  |      Col 2      |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
|                 |  |                 |
 —————————————————    ————————————————— 

CSS Multicol in horizontal-tb (x-axis)

Will automatically become the following in vertical-rl:

 _____________________________________
|                                     |
|                                     |
|                Col 1                |
|                                     |
|                                     |
 —————————————————————————————————————
 _____________________________________
|                                     |
|                                     |
|                Col 2                |
|                                     |
|                                     |
 ————————————————————————————————————— 

CSS Multicol in vertical-* (y-axis)

So the best we can do right now is a fragmented scrolled-view:

  _____________________________________
 |                                     |
 |                                     |
 |                                     |
 |                                     |
 |                                     |
 |                Col 1                |
 |                                     |
 |                                     |
 |                                     |
 |                                     |
 |                                     |
 |                                     |
  ————————————————————————————————————— 
- - - - - - - - - - - - - - - - - - - - - (Overflow begins here)
  _____________________________________
 |                                     |
 |                                     |
 |                                     |
 |                                     |
 |                                     |
 |              Overflowed             |
 |                 Col                 |
 |                                     |
 |                                     |
 |                                     |
 |                                     |
 |                                     |
  ————————————————————————————————————— 

New fragmented scrolled-view for vertical-* (y-axis)

In other words, one column with overflowed columns on the y-axis, which 1) will force implementers to map left/right (swipe/buttons) on bottom/top and 2) won’t allow them to have page-transition animations.

Note: The only alternative to solve those issues at the moment would be writing a renderer in JavaScript. It’s worth noting that if you’re only targeting iOS, there is a solution in pure CSS though.

What’s even worse is that the same typefaces can’t necessarily be used (proportional/fixed-width depending on writing-mode), and I’ll have to make adjustments for quotes and other details in the base and default stylesheets based on writing-mode…

Note: We won’t try to manage horizontal-tb documents in vertical-rl publications in a smart way for the time being. This use case is indeed not defined in the EPUB spec. Besides, we’ve got nothing at the OPF level to deal with it, and checking the writing-mode during runtime will blow performance in extreme ways i.e. 15 seconds to render some XHTML files… which would be worse than supporting this use case in terms of UX.

Longer terms issues include:

• polyfilling -epub-properties for web apps;
• support for alternate stylesheets (which is critical if the implementer wants to offer a horizontal/vertical-writing user setting);
• support for rendition: align-x-center;
• support for ibooks:respect-image-size-class (gaiji) and ibooks:scroll-axis metas (see EPUB Compat doc);
• user settings (some like letter- and word-spacing might have to be removed, and not only for CJK);
• rendition: flow of scrolled-doc.

Out of scope

There are some typography and layout issues which are not our responsibility but rendering engines’. Those issues include:

• line-adjustment and justification (RTL and CJK);
• run-in headings (display: run-in), which is popular in CJK;
• ruby and its styling;
• bidi;
• Kashida Elongation (Arabic);
• joining forms (Arabic);
• single-letter styling (Arabic).

Documentation

In theory, I would only have to document the new fragmented scrolled-view model for vertical-writing, and adjustments for user settings.

In practice, I’m willing to go the extra mile and will document typographic and layout concepts, and make glossaries, so that Western implementers have everything at hand to deal with requirements and issues in CJK and languages they might not be familiar with.

This will obviously take time but will fix a huge pain point.

Overarching Issues

• We don’t have any text layout requirement for hebrew, we’ll need help
• Hangul, Chinese, Arabic and Indic Text Layout requirements are incomplete, we’ll have to keep track of updates and changes
• We have not defined a precise baseline for i18n, it may be wise to do it
• It would be useful to have data about writing-mode, RTL, typefaces used/expected, etc.

Resources

• W3C Internationalization Working Group Home Page
• Creating HTML Pages in Arabic, Hebrew and Other Right-to-left Scripts (tutorial)
• Styling vertical Chinese, Japanese, Korean and Mongolian text
• International text layout and typography index
• Requirements for Japanese Text Layout
• Requirements for Chinese Text Layout
• Requirements for Hangul Text Layout
• Requirements for the Arabic Script
• Requirements for Hebrew Text Layout
• Requirements for Indic Text Layout
• EBPAJ File creation guide

We’ll need this for a11y, see issue #18.

The most reasonable implementation to me at first sight:

• create a --USER__a11yFocus flag (custom prop), since we already have a --USER__a11yNormalize;
• outline’s customization can be handled in day, sepia and night mode modules, like ::selection.

But then it’s about UX i.e. is this an explicit = user can turn it on/off, or implicit = automatically enabled depending on some conditions?

Also, we’re (finally) entering FXL territory for this one. So maybe it would be a better idea to make focus its own module and then re-customize it in the sepia and night modes only.

Feedback from Daniel:

Yes, as a matter of fact I was running tests this week, as part of a DAISY activity where we are in the process of defining good practice recommendations for content creators (aka production guidelines), specifically in the context of extended descriptions (typically, for images ... but this can apply to complex information structures like tables too).

Semantically we can leverage existing / upcoming techniques (including fallback mechanisms for non-supporting user agents / reading systems) such as aria:details and aria:describedby, alongside HTML5 <details><summary>, or <aside epub:type="footnote">, etc.

Stylistically, we can use :active and :hover for link interactions, :active to "highlight" link destinations (i.e. to emphasize the point of regard of navigation targets), typically with CSS outline styles rather than border (as the latter usually messes-up the border-box model of arbitrary EPUB HTML documents).

Problem: several EPUB reading systems (including Readium(1), iBooks iOS/OSX, Edge) seem to interfere with URL anchor / fragment identifier, thereby breaking CSS :target pseudo-class. This is something I have been keen to get right in Readium2, where the navigation logic (link activation) is also "hijacked" by some kind of reading system logic, especially in Electron as we listen to <a> DOM click event, as well as higher-level / platform-specific navigation events via a WebView API (which allows us to capture the annoying window.location programmatic redirects that InDesign uses, among other things).

So, going back to the question at hand: should ReadiumCSS allow apps to opt into aggressive style overrides (!important) for common user interactions such as :focus, :target, :active, :hover, etc.?

Well, given that ReadiumCSS can already force (over authored styling) "colour themes" and various other visual formatting rules, it seems logical to allow reading systems to ensure consistent styling for the aforementioned interactions too, some possibly customizable via user preferences, for example the thickness of the :focus outline, or whether or not to enable :target emphasis at all (for people who have difficulty to find the point of regard when following hyperlinks).

Must still think about the best option to implement that. At first sight, it looks like a good candidate for a dedicated module, a little bit like the OS_a11y one, especially as implementers may want to use it in fixed-layout as well.

We’ve started working on the fixed-layout implementation.

While we won’t inject styles in there, authors and beta-testers might still report CSS-related issues I’ll then try to investigate.

Authors are also encouraged to report rendering issues they have encountered in Readium or any other Reading System so that we can check if it’s browser-related, markup-related, scaling-related, type-related, etc.

Warning: this is a debatable issue for which we MUST get feedback from both implementers and authors.

[This original message was edited with the following TLDR for clarification. It will also be easier to keep track of issues this way]

TLDR

Scope

The aim of this issue is to list common issues CSS authors have had to deal with. It is not strictly scoped to Readium CSS since I will document those issues so that could also serve as a reference for the upcoming specs.

At the moment, we’re very far away from discussing “how it should be done.” The idea is to explore whether “it can be done.” This will probably require prototyping and beta-testing in ways which are not 100% standards-compliant but beta-testing will also be documented so that the maximum amount of information can be made available.

Also, it’s worth repeating that two important changes were made in the EPUB 3.1 revision:

1. undated references to HTML in EPUB 3.1
2. replacement of EPUB Style Sheets with CSS References

We have to take that into account, which is why I’ll be referring to the HTML design principles for the sake of anticipation.

Most use cases will probably be about styling since I’m dealing with CSS there (there could be interactive use cases as well, but that’s out of this project’s scope). This has a lot of implications, the major one being it should not be markup territory.

What is critical is a list of use cases. So let’s focus on that at first. There may well be use cases interesting to the web platform, so “how it should be done” is extremely conditional (e.g. use cases fit for ARIA or specific media queries because they are a11y-related).

Use cases

• invert images in night mode (and possibly other styling depending on reading modes)
• bleeds, cf. EPUB-CG — Rendering

Original Message

While documenting the wiki, I came across nasty hacks which I’d personally like to prevent if possible.

• iBooks’ theme detect in CSS
• Device-specific styles via JS
• Some authors have also been using the iBooks’ meta for gaiji since it inverts images in night mode

And so on and so forth.

Worst-case scenario: it becomes a technical debt on the RS side.

Best-case scenario: it stops working at some point and authors will update their files.

Real-case scenario: it becomes a technical debt on the RS side if hacks’ usage is significant, authors don’t update their files, a minor update introduces regressions, nobody’s happy.

I guess we could acknowledge there are issues for which we definitely need authors’ help. It could be seen as some kind of “help us help you” mechanism. After all, the more hacks authors will create, the more issues we’ll have when it comes to reading modes and user settings.

For instance, we could imagine something like:

<img alt="Desc" src="img/my-image.png" data-reading-mode="adapt" />

In which data-readind-mode="adapt" ("adapt" is there because XHTML but we can make it boolean) automatically inverts or “sepiaes” the image with a CSS filter, depending on the current reading mode selected by the user.

If epub:type="noteref|footnote + popup is any clue, authors are likely to use such a mechanism if they can benefit from it.

In that case, we must reserve styling and make it clear it’s the RS’ responsibility to deal with it, not the authors’. And use super-specific selectors so that it has no effect on other elements.

Considering the image example, implementers might choose darker or lighter shades for some modes and will have to fine-tune filters accordingly, so that the background colors are exactly the same.

Of course there are probably other cases, and managing it entirely through CSS will make it more maintainable, updatable and portable (for other SDKs).

Custom attributes will be EPUB3-only though. But this is already the case for epub:type so, as far as I’m concerned, it’s not an issue. It’s whether we consider it presentation (classes) or behavior (custom attributes).

Sure, there are alternate stylesheets but support has been so rare that very few people have used it. And they are not likely to use it if other major RSs don’t support it, so I’m trying to be pragmatic here.

If we decide to provide such an “API”, question is do we design it as some kind of standard in disguise other SDKs can use, especially as authoring tools’ implementation is another issue to consider. It’s high time we tackle those issues, especially as implems might drive standards, w3c-style.

I’d like implementers and authors to discuss this, because I feel it’s a critical issue for which we have to find compromises sooner than later. It could also be of interest to browser vendors for reading modes (Safari, Pocket & al.) since authors might require such mechanism at some point.

Also, if you’re an author, please feel free to list problematic issues related to such a public API.

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.

Font size

User’s intent

The user intends to adjust the font-size, either because it is too small or too large by default.

Author’s intent

This may be considered an intent if a font-family is set for body copy.

What do do

The author could be trying to compensate for a smaller or larger x-height.

You might want to normalize font-size (à la iBooks) if the user changes the typeface.

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.

This issue originated in Architecture.

I was reminded of this by discovering the article “Your interactive makes me sick”, which will make the issue way more articulated that I could ever articulate it myself.

Summary

There’s an a11y “issue” which is quite unknown, but may impact a lot of people, either temporarily or permanently: vestibular disorders.

In other words, some interactions can make the user dizzy, uneasy, and in some cases ruin her/his entire day, because it feels like you can’t keep balance when walking or even staying up, or feel vertigo.

The biggest issue

Because of difficulties posed by accurately diagnosing and reporting vestibular disorders, statistics estimating how common they are, how often they occur, and what social impacts they have range widely.

So, disclaimer, I can confirm that since I suffered from such disorders a few years ago, it suddenly appeared and then 6 months later, it was over. No doctor could explain it nor why. All I know is that one morning I woke up not super well, an animation on a web site ruined my day, and it keep up going like that for months. Some apps had simply become unusable while the web had become a landmine… and then it vanished and that was over. But some people have to live with it for their whole life.

This is not uncommon BTW, this even tends to be the norm when you’re starting to do some research, as there are lots of people who suffer from vestibular disorders but don’t know why and nobody can tell them, despite meeting a lot of doctors and specialists. Besides, effects range so widely that it makes it even more complicated to diagnose.

Impacts

So this obviously impacts anything related to motion (animations, transitions, etc.). For instance, starting iOS7, some users had to set the “Reduce Motion” pref in a11y settings.

So that’s up to apps, but I can think of page-transition animations which should probably be disableable for instance, so it may impact r2-glue-js as well.

There’s also the accessibility hazards at the OPF level. I’m not particularly optimistic a lot of content providers use that, but I know I’ve been using it since I had to cope with vestibular disorders myself and, yeah, as an author I’d like that to be taken into account if the meta is present in the EPUB file (e.g. a popup telling the user there is motion simulation in the publication and bla bla bla).

Options

At the very minimum, allow the user to disable animations which may create effects (e.g. page-transition animation). But everything else will vary from implementation to implementation.

On iOS/Mac, there’s a system setting which has been implemented and Safari/Webview supports the prefers-reduced-motion media query to design accordingly.

There’s little we can do about content, but we can at least promote what Mozilla got wonderfully right from the start i.e. an overlay asking users to set their preference.

I’m taking the liberty to ping @rdeltour to see if he can add to this issue and/or raise another one and/or ping others directly – or not – impacted. The more we can do to grab implementers’ attention, the better.

Since the default stylesheet is the next phase, I’d like to anticipate a little bit. It would be useful to collect feedbacks while I’m testing pagination and page margins.

Contrary to what one may think at first sight, this is something for which I’ll have to take authors expectations into account. Indeed, there is a bunch of people relying entirely on default styles (think about hr for instance) and, consequently, they won’t bother embedding a custom stylesheet. Others might rely on default styles and only customize some elements (e.g. :link color or small-capitals, etc.).

The good news is that we already have a default stylesheet, the UA’s. I validated UA stylesheets against HTML5 suggested rendering and can report there are some differences, but it doesn’t impact default styles (flow and phrasing content, quotes, headings, lists, tables, embedded content, images, etc.).

The bad news is we don’t necessarily want to use it AS-IS. HTML5 suggested rendering doesn’t have to deal with user settings (font size, line height, margins, etc.), fragmentation (i.e. page breaks, widows and orphans), hyphenation and reading modes (especially night modes).

Please note I still have to check HTML4 Suggested Rendering for ePub 2.

I can probably save us a lot of issues by adapting and modernizing HTML5 suggested rendering a little bit:

1. use a smaller type scale so that headings don’t become an issue when the user sets a bigger font-size;
2. redefine colors so that borders become white in night modes;
3. tweak sup and sub so that they don’t break the line height;
4. redefine horizontal margins and paddings for block quotes, figures, lists, etc. to accommodate smartphones (40px is really really huge, especially when you start nesting lists since it can grow to 120px or 160px);
5. redefine tab-size so that one tab is not 8 spaces in pre (I understand why this default value but find it quite stupid considering smartphones exist);
6. as far as I can tell, although it’s not managed via UA stylesheets, some browsers default font-variant-* quite well but I can normalize it to make sure all UAs have the same values (that’s like 5 or 6 lines of CSS);
7. take care of basic fragmentation + hyphenation.

Then the question will be “do we make it more bookish?”

Bookish implies stuff as:

• picking a font-stack and defining a font-family for body (some UAs default to Times New Roman, which has been heavily criticized by Matthew Carter because it’s way too thin for HD displays, and it doesn’t ship with Open Type Features which could improve legibility, while more modern fonts do)
• replacing paragraphs’ margins with a text indent (we would be quite possibly be breaking authors’ expectations there);
• in that case, you could also reset the text-indent for paragraphs following a heading (more elegant, visual harmony, etc.);
• Forcing pre to pre-wrap so that we don’t have overflow-x (probably more readable though not perfect);
• centering figures;
• taking care of vertical rhythm so that page baselines are aligned, at least for text (images are another issue CSS Rhythmic Sizing is trying to solve);
• etc.

My opinion at the moment is that we should probably improve HTML5 Suggested Rendering (think about it as EPUB Suggested Rendering if this can help conceptualize it) and use themes for the bookish changes. In other words, power to the user. On the other hand, there is bookish stuff which could be part of defaults, especially declaring a font-stack since the default font-family may not support all languages (anticipating CJK/RTL there).

I know the idea is to provide default styles for unstyled publications but we could use this stylesheet to improve/help authors a little bit (thinking about Open Type, hr + night modes, etc.).

I’ll also have to deal with CJK and RTL. I’ve done some Japanese in the past, am familiar with some best practices, but it was in western publications. In other words, I’ll have to do extended research to make sure we can manage CJK and RTL well. In addition, we could probably write “best practices” for this so that it can help both implementers and authors.

On a related note, there is the W3C Typography repo which could be useful. It points to typographic information relevant to the web platform.

The “help wanted” label is precisely for CJK and RTL. I can find ressources, best practices, examples, etc. but I’d like to make sure we have bulletproof styles there. Typography experts dealing with CJK and RTL are warmly welcome to weigh in this issue, and do “styles review” once the default stylesheet is created.

For instance, my assumption is that we could manage that by targeting lang but that approach may be completely wrong for various reasons. So I’d like to know how experts manage that in practice.

Since we agreed we need an book-oriented stylesheet, I’ll try to provide implementers with reliable font stacks making the most of pre-installed fonts.

For some languages, we may have to fill the gaps, and use libre/open source fonts like Noto Serif for instance. How to manage that is still unclear but I’d like to find a solution which is optimized i.e. not loading the whole 20mb font if there is a possibility to load only a subset (unicode range).

Fundamentals

UA defaults if no font-family is set usually are:

• Times New Roman
• Droid Sans/Roboto on Android

You could force Android using a serif font by declaring

font-family: “Times New Roman”;

But it will be resolved to Droid Serif.

For generic families (sans-serif, serif, monospace), you’ll usually get:

• Arial/Helvetica/Roboto for sans-serif;
• Times/Times New Roman/Droid Serif for serif;
• Courier/Courier New/Droid Mono for monospace.

Historically, anything monospace has had a font-size of 13.33px so you’d better be cautious about that. A margin of 1em will indeed be 13.33px for pre.

Finally, rendering engines fall back on a glyph basis. If a glyph is not available in the preferred font, it will check if it is in the second one, and so on and so forth, for each glyph.

UI

If you want a system font stack, it already exists.

font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantrell, "Helvetica Neue", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

This is a modernized version taking popular Linux distros and emoji into account.

Default

For latin, I’ll privilege fonts with good Open Type support. I’ll test them using one of my own “web apps.” What I can already say is that fonts OSs have been adding since 4–5 years tend to ship with OT features so we can leverage that.

For CJK/RTL, I’ll pick fonts with the widest set of glyphs available. Once again, we may have to fill the gaps so this is a more complex issue.

I'm submitting a feature request: to add some CSS3-break reference stylesheets.

Short description of the issue/suggestion:

CSS3-break standard will be slowly incorporated to web browsers... But is a crucial element to differenciate usual web page from "good paged media", is a key feature for the professional use of EPUB — as competitor for PDF, Kindle, etc. in publishing and digital preservation perspectives.

• Use cases at print-css.rocks are suitable for "paged media" in general, and to compare with PDF as expected layout.

• CSS WG harness/test/css-break-3_dev have the main snippets. (8 pass 6 fail with Chromium).

• Support: is growing, see e.g. https://bugs.chromium.org/p/chromium/issues/detail?id=368053

Although I do think this repo might not be the best place to discuss User Experience—it’s more implementation-centric—, it is worth having a general issue imho. Indeed, we can’t have a clear separation of concerns there, the CSS design impacting UX and vice versa.

While discussing Readium CSS during the Readium 2 conference call yesterday, UX has been one of our major concerns. And I do believe @danielweck and @HadrienGardeur are right about that: defaults, themes, user settings are not just styles we add and remove, they are tools we offer to users. Now, one of our top priorities is building a good experience so that users can focus on, and enjoy reading electronic publications.

UX in general, and user research in particular, are by no means easy. They also require quite a budget—please note there has been some DIY tips and tricks lately though. Minimal (DIY) usability testing is I guess critical because very little user research on Reading Systems and ebooks has actually been published so far.

Anyways, Readium CSS design is pretty modular, with a lot of user settings. It doesn’t mean developers have to implement all those settings, obviously. What we want to offer is flexibility, so that implementers can do as they wish:

• providing themes and a basic font-size setting;
• providing common settings + reading modes;
• providing themes, with a custom one created by the user via advanced settings;
• etc.

There are small details we must take into account. For instance, what we discussed yesterday:

• we’ll try to manage font-size in pure CSS, but it requires normalizing the publisher’s styles (because some authors use keywords, px or pt and the user setting won’t work). Do we normalize as soon as the user sets a different font-size or do we ask them to opt-in via a checkbox?
• for some larger font-sizes, we’ll have to adjust line-height. Some users with bad vision will indeed set a 36px or 48px default and we don’t want the leading to be too loose (huge gaps between lines).

Of course, there are a lot of other UX issues we’ll have to deal with as we go along. So please feel free to use this issue to report and discuss them. We will then be able to make recommandations related to UX in docs.

I thought it would be a good idea to list all the specs and proposals which are likely to impact Readium CSS at some point in the future. Some of them are still in their early days but we’ll probably have to review the project once they are clearly defined.

The W3C CSSWG-Drafts repo is a good way to keep up.

To be honest, I’ve already been reviewing our approach to check whether it is future-proof or not. So far so good but we’ll have to keep the following in mind.

Media Queries Level 5

• Source
• Impact: Global (a11y)
• CSSWG Issues

Logical Properties and Values

• Source
• Impact: Global (esp. vertical writing and RTL)
• CSSWG Issues

CSS Extensions

• Source
• Impact: Global (CSS architecture)
• CSSWG issues
• Note: this specification defines methods for extending several CSS features (custom selectors, custom properties, custom functions, custom combinators, custom @ rules).

Calc notation: min() and max()

• Source
• Impact: Global
• Note: this could help us define floor and ceiling values for a lot of configurations (e.g. have a ceiling for headings font-size when a large user font-size is set)

User Agent Properties

• Source
• Impact: Default, Themes, User Settings

CSS Rhythmic Sizing

• Source
• Impact: Pagination, User settings
• CSSWG Issues

CSS Fonts Module Level 4

• Source
• Impact: Default (Variable fonts), User settings (font-min|max-size)
• CSSWG Issues

COGA Semantics to Enable Personalization

• Source
• Impact: Implementations, User settings (related draft)
• Related TF: PWG Personalization Task Force

Multicol editing

• Source
• Impact: Pagination
• CSSWG Issues

W3C i18n

• Source
• Impact: CJK & RTL

CSSOM (a.k.a. Houdini)

• Source
• Impact: Implementations
• CSSWG Issues

First and foremost, thanks for helping us improve Readium CSS, you’re awesome!

At the moment, we have one test app on iOS (dedicated github repo), it’s still an alpha but we feel confident it can give an accurate preview of how Readium CSS will eventually be used.

This list may be updated at some point, to reflect the changes and fixes we’ve done.

Currently, this is the list of issues you should probably focus on when testing your EPUB files:

• Rendering issues with publisher’s styles enabled;
• Unexpected styling and/or overrides with publisher’s styles enabled;
• Any specific issue related to font-size (this has been a pain point during dev so we’d better make sure it is OK);
• Issues specific to reading modes (sepia/night);
• Unexpected behaviors on user overrides e.g. something that doesn’t change while it should and vice versa;
• Fragmentation issues when changing user settings;
• A11y issues (the sooner we discover them, the better; fixing them could indeed require major refactoring if we don’t discover soon enough).

We have put a Google Form in place in case you want to test and give feedback for every point: https://goo.gl/forms/h1Bl34Xy5xzA3xej2.

There’s also a couple of extra questions to get feedback from the authoring perspective (will you be able to cope with all the settings, does the fonts selection feel good to you, etc.).

Google docs mirror for this issue

We’re very likely to ship with a “standard” theme for night mode. There are a couple of issues we must deal with, especially as it is a11y-related. In other words, we can probably make a few compromises but authors will have to make the most.

In the spirit of issue #5, I’d like to kickstart the conversation way ahead of time.

The current situation

The sad truth is that nobody knows how to deal with that.

• Invert/High contrast modes at the Operating System Level use a global filter (Windows | Mac).
• MacOS/iOS are not a global setting but a list of independent settings e.g. you can invert colors and use monochrome, and then add high contrast.
• Google has had a hard time implementing high contrast mode in Chrome.
• Reader Modes usually get rid of authors’ CSS so they don’t even have to deal with the related issues.
• Reading Systems sometimes use a global filter as well, sometimes try to do it via CSS.
• Kindle is normalizing colors and enforcing sufficient contrast ratio when converting EPUB files to KFX (+ font-family and font-size by the way)

Major issues

• Night mode ≠ white on black: it can be white on dark grey, it can be #FCFCFC on #121212, etc.
• Images: when there are a lot and they have a white background, night modes becomes useless. And we don’t know which images to invert, we can’t even rely on the format. There is some stuff I can manage with, say, 95% confidence (epub:type title page + image) though.
• SVG: even more complex than images.
• Backgrounds: figures, asides, etc. are complex to manage, especially as there are CSS hacks out there (using a linear-gradient + -webkit-text-fill-color for text). There’s also text on background images which we’d better not override if we don’t override background-image (JS territory).
• Borders: what do do of black borders, borders for which the color doesn’t provide sufficient contrast, etc? And we can’t check the color for the border’s element in pure CSS, that’s JS territory.
• Colors: contrast is an issue, especially when night mode is used as an a11y tool. Once again, the -webkit-text-fill-color hack might be used to enforce links’ or headings’ color.
• Gaiji i.e. a character that is valid in a given writing system, but that is not included in the present font and/or the present character encoding, and which therefore is displayed using an image, which we must invert at any cost necessary (and we can’t do p > img). iBooks had to create a metadata for that.
• Performance: if we have to check every element in the DOM, it will kill performance. Once again, this is something for which I wish we had Houdini (at 97% support).

Design

At first sight:

• Will override background-color and border-color but not background-image;
• Will override color but not -webkit-text-fill-color;
• Won’t invert images, and this is why I’m pushing for a mechanism so that authors can signal some images must be inverted. It could be ARIA territory (cc @rdeltour) since it also impacts high-contrast mode in nasty ways (cf. google issues in Chrome implem);
• SVG is a tough one, especially if the background is transparent and the author is not using currentColor for fill (can check some SVG attributes and the colors but it will result in insane CSS selectors);
• We must find something for gaiji; the fact iBooks and Kindle bothered implementing specific mechanisms to deal with it kind of show this is critical;
• Performance is @danielweck’s territory. I can find clever ways to deal with some overrides but for the complex ones, we can’t do without computed styles.

Possible issues this will create

• RSs stand in the first line so they will take the heat if users complain, especially if other RSs manage night mode the way the user wishes;
• Since there is no real “standard” in managing night mode, I can’t even tell what the users’ expectations are;
• Some authors will probably complain about color and stuff (but it’s an accessibility issue);
• Some others will point out alternate stylesheets exist (but it doesn’t solve the issues for the millions of files out there).

OpenType issue?
Chromium-specific? (reproducible with r2-testapp-js and readium-desktop, I haven't tried elsewhere)
Book/CSS-specific? (Screenshots below with "Accessible EPUB3")

...to be determined.

We’re already using PostCSS to ease the setup (concat files, stylelint, etc.) so I was wondering if implementers would be OK using CSS Next to “Use tomorrow’s CSS syntax, today.”

Benefits:

• Readium CSS would be “future-proof” i.e. at some point in the future, CSS next processing won’t be needed anymore (current features are sync’d with upcoming specs);
• Takes care of CSS variables → static representation;
• Would make Readium CSS a lot more readable (thinking about :not(), matches, custom media queries, media query ranges, etc.);
• fallbacks would be easier to manage;
• nesting and mixins (like pre-processors).

Caveats:

• major caveat is we’ll have a “dependency” (but dist, as opposed to src, could be used to get around this issue);
• implementers might not be used to the upcoming specs (and their syntax);
• same for contributors.

So, worst case scenario, that could become a barrier to entry. However, we’re likely to use it to make styles more readable. To sum things up, we could use it sporadically, to improve authoring a little bit, and skip the more complex features.

So we already have this issue in practice, cf. vertical-writing (issue #19), for which authors’ stylesheets are missing the necessary prefixed properties for some styles (-ms-, -moz-, etc.) and contents won’t render as expected.

Have just received this piece of information from @SeldomScene:

Hi Jiminy,

Just for your info, be careful with prefixed properties, as Google asked us to remove every prefixed properties except those used by them (i.e. -webkit-), because their programs didn't ingest correctly our files (it's new).

So we have to remove any -ms- and -moz- existing in our files...

Vincent

EUB3 ISIcrunch platform for education

I’ll repeat what I said in issue #26.

If that’s Google Play Books, they’re consequently creating an interoperability issue – and we already have an awful lot because vendors decide to do such stuff unilaterally. It also breaks yet another fundamental rule of CSS, and change the way it is working so this is bad. This should be raised at a higher level, because it impacts the whole ecosystem and, more importantly, competitors.

How are they parsing CSS in the first place? You can’t encounter this issue unless you create it and are extremely lazy – in the worst case scenario, stripping those declarations is a 2-line script…

There is a bunch of styles for which you absolutely need the prefix, and not having all whenever needed will have consequences and create rendering issues.

So if we have Reading System vendors telling authors to not use them because they have a bug, it hurts the whole ecosystem.

More generally, what do we want to do about this? Put the burden on authors or make up for the missing properties, when applicable?

That will impact Trident (IE11), EdgeHTML (MS Edge), and Gecko/Quantum (Firefox). It doesn’t impact the apps, which are using Blink/Webkit.

Note: I’ll use the acronym FOUV for “Flickering of Undefined Variables” since CSS people have been using FOIT (Flash of Invisible Text) and FOUT (Flash of Unstyled Text) for such issues already.

This isn’t necessarily an issue related to CSS variables, it would also arise for classes or custom attributes. So it’s about injecting them in the critical rendering path to optimise the perceived experience.

Right now, in the iOS app, users might encounter some flickering when user settings are set. This is (probably) because the CSS variables are set using JavaScript when the DOM is loaded.

A few performance details we have to take into account:

1. the CSS variables are set on html, so they’re in theory the earliest possible in the DOM (when the stylesheets are retrieved, and styles computed, they’re defined if they’re already set);
2. we know that at least Blink (Chrome) has a special cache for them when they’re set on html, it’s an optimization trick they’re using to make them super fast since they’re global (and not scoped to an element);
3. ReadiumCSS is leveraging the inherit value whenever possible for user settings, which means the variable is strictly kept at the html level, and other elements inherit the value.

This is an issue which can’t obviously be scoped to ReadiumCSS only, it depends on a large amount of other factors e.g. computing pagination, loading assets like fonts, etc.

@HadrienGardeur has been willing to discuss an optimization for three weeks now so I’m taking the liberty of opening this issue on this repo so that everyone can weigh in and we can document all the factors we must take into account, and what our options are.

We’ll probably have to deal with FOIT or FOUT anyway (i.e. large embedded fonts) so FOUV could potentially be treated the same.

We have the issue of mixed writing-modes (with different page-progression-direction), which we solve pretty crudely at the moment i.e. the primary writing-mode is applied to every HTML document.

Considering CJK can also be written horizontal-tb, maybe we can add in docs that if the publication contains a significant portion of Latin-only documents, authors should consider using this writing mode as the primary one.

This is part of the a11y baseline, as defined in issue #18

It seems floating elements can parasitize reading. But I’ll need some confirmation there.

ReadiumCSS_docs.epub:
https://github.com/readium/readium-css/blob/develop/docs/ReadiumCSS_docs.epub

@JayPanoz would it be possible please to store in the GitHub repository the extracted files of ReadiumCSS_docs.epub, for example inside a folder called ReadiumCSS_docs?
https://github.com/readium/readium-css/tree/develop/docs/ReadiumCSS_docs

This way, the Readium "cloud / web reader" won't have to load the entire 1.5+MB EPUB in memory:
https://readium.firebaseapp.com/?epub=https%3A%2F%2Frawgit.com%2Freadium%2Freadium-css%2Fdevelop%2Fdocs%2FReadiumCSS_docs.epub

Thanks! :)

I found an EPUB that has a stylesheet using the selector html

example_author_styles.css =

html {
    background-color: #fffeee;
}

With the regular stacking of ReadiumCSS this author style doesn't seem to be respected because of this line

The !important is what's stopping it

@JayPanoz Is this intentional?