@evidentpoint/readium-css

# Readium CSS Variables API [Implementers’ doc] As a reminder, the priority is, in general: ``` USER > AUTHOR > RS ``` ## How to set and remove user preferences ### Setting a user preference ``` var root = document.documentElement; root.style.setProperty("--USER__var", "value"); ``` You don’t need to remove the variable before setting another value, the new value will simply override the existing one. ### Removing a user preference ``` var root = document.documentElement; root.style.removeProperty("--USER__var"); ``` ## Customizable medias * * * ``` --responsive-columns ``` Default is `60em` The `min-width` at which the auto pagination model must be used – will switch from 1 to 2 columns and vice versa. * * * ``` --min-device-columns ``` Default is `36em` The minimum device width of the mobile device for which the auto pagination model must be used. * * * ``` --max-device-columns ``` Default is `47em` The maximum device width of the mobile device for which the auto pagination model must be used. * * * **Warning:** if you customize those medias, all ReadiumCSS `dist` stylesheets must be rebuilt. ## Customizable flags Those custom selectors can be customized before runtime. Check the [“Quickstart” doc](../docs/CSS02-quickstart.md) for further details. The “dummy CSS variable” is a recommended CSS custom property name you can use to set the default value if you don’t customize those selectors and just keep the default. * * * ``` :--scroll-view ``` Default is `readium-scroll-on` Scope: `html` Dummy CSS variable: `--USER__view` Override class: Chrome (should be applied by any means necessary) * * * ``` :--font-override ``` Default is `readium-font-on` Scope: `html` Dummy CSS variable: `--USER__fontOverride` Override class: None. This flag is required to change the `font-family` user setting. * * * ``` :--advanced-settings ``` Default is `readium-advanced-on` Scope: `html` Dummy CSS variable: `--USER__advancedSettings` Override class: None. This flag is required to apply the `font-family`, the `font-size` and/or advanced user settings. * * * ``` :--sepia-mode ``` Default is `readium-sepia-on` Scope: `html` Dummy CSS variable: `--USER__appearance` Override class: Chrome (should be applied by any means necessary) This flag applies the sepia reading mode. * * * ``` :--night-mode ``` Default is `readium-night-on` Scope: `html` Dummy CSS variable: `--USER__appearance` Override class: Chrome (should be applied by any means necessary) This flag applies the night reading mode. * * * ``` :--darken-filter ``` Default is `readium-darken-on` Scope: `html` Dummy CSS variable: `--USER__darkenImages` Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users) This will only apply in night mode to darken images and impact `img`. * * * ``` :--invert-filter ``` Default is `readium-invert-on` Scope: `html` Dummy CSS variable: `--USER__invertImages` Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users) This will only apply in night mode to invert images and impact `img`. * * * ``` :--a11y-normalize ``` Default is `readium-a11y-on` Scope: `html` Dummy CSS variable: `--USER__a11yNormalize` Required flag: `:--fontOverride` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) It impacts font style, weight and variant, text decoration, super and subscripts. * * * **Warning:** if you customize those flags, all ReadiumCSS `dist` stylesheets must be rebuilt. ## Reading System Styles Custom properties for the Reading System are prefixed with `--RS__`. ### Pagination * * * ``` --RS__colWidth ``` The optimal column’s width. It serves as a floor in our design. * * * ``` --RS__colCount ``` The optimal number of columns (depending on the columns’ width). * * * ``` --RS__colGap ``` The gap between columns. It must be set in pixels so that it won’t resize with font size. You must account for this gap when scrolling. * * * ``` --RS__pageGutter ``` The horizontal page margins. It must be set in pixels so that it won’t resize with font size. * * * ``` --RS__maxLineLength ``` The optimal line-length. It must be set in `rem` in order to take `:root`’s `font-size` as a reference, whichever the `body`’s `font-size` might be. ### Safeguards * * * ``` --RS__maxMediaWidth ``` The `max-width` for media elements i.e. `img`, `svg`, `audio` and `video`. * * * ``` --RS__maxMediaHeight ``` The `max-height` for media elements i.e. `img`, `svg`, `audio` and `video`. * * * ``` --RS__boxSizingMedia ``` The box model (`box-sizing`) you want to use for media elements. * * * ``` --RS__boxSizingTable ``` The box model (`box-sizing`) you want to use for tables. ### Default font-stacks * * * ``` --RS__oldStyleTf ``` An old style serif font-stack relying on pre-installed fonts. Default is `"Iowan Old Style", "Sitka Text", Palatino, "Book Antiqua", serif`. * * * ``` --RS__modernTf ``` A modern serif font-stack relying on pre-installed fonts. Default is `Athelas, Constantia, Georgia, serif`. * * * ``` --RS__sansTf ``` A neutral sans-serif font-stack relying on pre-installed fonts. Default is `-apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif`. * * * ``` --RS__humanistTf ``` A humanist sans-serif font-stack relying on pre-installed fonts. Default is `Seravek, Calibri, Roboto, Arial, sans-serif`. * * * ``` --RS__monospaceTf ``` A monospace font-stack relying on pre-installed fonts. Default is `"Andale Mono", Consolas, monospace`. ### Default font-stacks for Japanese publications * * * ``` --RS__serif-ja ``` A Mincho font-stack whose fonts with proportional latin characters are prioritized for horizontal writing. Default is `"ＭＳＰ明朝", "MS PMincho", "Hiragino Mincho Pro", "ヒラギノ明朝 Pro W3", "游明朝", "YuMincho", "ＭＳ明朝", "MS Mincho", "Hiragino Mincho ProN", serif`. * * * ``` --RS__sans-serif-ja ``` A Gothic font-stack whose fonts with proportional latin characters are prioritized for horizontal writing. Default is `"ＭＳＰゴシック", "MS PGothic", "Hiragino Kaku Gothic Pro W3", "ヒラギノ角ゴ Pro W3", "Hiragino Sans GB", "ヒラギノ角ゴシック W3", "游ゴシック", "YuGothic", "ＭＳゴシック", "MS Gothic", "Hiragino Sans", sans-serif`. * * * ``` --RS__serif-ja-v ``` A Mincho font-stack whose fonts with fixed-width latin characters are prioritized for vertical writing. Default is `"ＭＳ明朝", "MS Mincho", "Hiragino Mincho Pro", "ヒラギノ明朝 Pro W3", "游明朝", "YuMincho", "ＭＳＰ明朝", "MS PMincho", "Hiragino Mincho ProN", serif`. * * * ``` --RS__sans-serif-ja-v ``` A Gothic font-stack whose fonts with fixed-width latin characters are prioritized for vertical writing. Default is `"ＭＳゴシック", "MS Gothic", "Hiragino Kaku Gothic Pro W3", "ヒラギノ角ゴ Pro W3", "Hiragino Sans GB", "ヒラギノ角ゴシック W3", "游ゴシック", "YuGothic", "ＭＳＰゴシック", "MS PGothic", "Hiragino Sans", sans-serif`. ### Base styles for all ebooks * * * ``` --RS__baseFontFamily ``` The default typeface for body copy in case the ebook doesn’t have one declared. Please note some languages have a specific font-stack (japanese, chinese, hindi, etc.) * * * ``` --RS__baseLineHeight ``` The default line-height for body copy in case the ebook doesn’t have one declared. ### Default colors for all ebooks * * * ``` --RS__textColor ``` The default `color` for body copy’s text. * * * ``` --RS__backgroundColor ``` The default `background-color` for pages. * * * ``` --RS__selectionBackgroundColor ``` The `background-color` for selected text. It is worth noting it can be customized for each reading mode. * * * ``` --RS__selectionTextColor ``` The `color` for selected text. It is worth noting it can be customized for each reading mode. ### Default styles for unstyled publications #### Typefaces * * * ``` --RS__compFontFamily ``` The typeface for headings. The value can be another variable e.g. `var(-RS__humanistTf)`. * * * ``` --RS__codeFontFamily ``` The typeface for code snippets. The value can be another variable e.g. `var(-RS__monospaceTf)`. #### Typography * * * ``` --RS__typeScale ``` The scale to be used for computing all elements’ `font-size`. Since those font sizes are computed dynamically, you can set a smaller type scale when the user sets one of the largest font sizes. Possible values: `1` | `1.067` | `1.125` | `1.2` (suggested default) | `1.25` | `1.333` | `1.414` | `1.5` | `1.618` * * * ``` --RS__baseFontSize ``` The default `font-size` for body copy. It will serve as a reference font all related computations. * * * ``` --RS__baseLineHeight ``` The default `line-height` for all elements. #### Vertical rhythm * * * ``` --RS__flowSpacing ``` The default vertical margins for HTML5 flow content e.g. `pre`, `figure`, `blockquote`, etc. * * * ``` --RS__paraSpacing ``` The default vertical margins for paragraphs. * * * ``` --RS__paraIndent ``` The default `text-indent` for paragraphs. #### Hyperlinks * * * ``` --RS__linkColor ``` The default `color` for hyperlinks. * * * ``` --RS__visitedColor ``` The default `color` for visited hyperlinks. #### Accentuation colors * * * ``` --RS__primaryColor ``` An optional primary accentuation `color` you could use for headings or any other element of your choice. * * * ``` --RS__secondaryColor ``` An optional secondary accentuation `color` you could use for any element of your choice. ## Reading Modes Custom properties for reading modes are prefixed with `--RS__`. * * * ``` --RS__backgroundColor ``` The `background-color` which must be applied to the entire screen in the reading mode. * * * ``` --RS__textColor ``` The `color` for text in the reading mode. * * * ``` --RS__linkColor ``` The `color` for the links in the reading mode. * * * ``` --RS__visitedColor ``` The `color` for visited links in the reading mode. * * * ``` --RS__selectionBackgroundColor ``` The `background-color` for selected text in the reading mode. * * * ``` --RS__selectionTextColor ``` The `color` for selected text in the reading mode. ## User Settings Custom properties for user settings are prefixed with `--USER__`. * * * ``` --USER__colCount ``` The number of columns (`column-count`) the user wants displayed (one-page view or two-page spread). Scope: `html` Possible values: `1` | `2` | `auto` (default) Required flag: none Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users) To reset, change the value to `auto`. * * * ``` --USER__pageMargins ``` A factor applied to horizontal margins (`padding-left` and `padding-right`) the user wants to set. Scope: `html` It impacts `body`. Recommended values: a range from `0.5` to `2`. Increments are left to implementers’ judgment. Required flag: none Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users) To reset, change the value to `1`. * * * ``` --USER__backgroundColor ``` The `background-color` for the whole screen. Scope: `html` It impacts all elements in the DOM. Possible values: Color HEX (e.g. `#FFFFFF`), `rgb(a)`, `hsl`. Required flag: none Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users) To reset, remove the CSS variable. * * * ``` --USER__textColor ``` The `color` for textual contents. Scope: `html` It impacts all elements but headings and `pre` in the DOM. Possible values: Color HEX (e.g. `#FFFFFF`), `rgb(a)`, `hsl`. Required flag: none Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users) To reset, remove the CSS variable. * * * ``` --USER__textAlign ``` The alignment (`text-align`) the user prefers. Scope: `html` It impacts `body`, `li`, and `p` which are not children of `blockquote` and `figcaption`. Possible values: `left` (LTR) or `right` (RTL) | `justify` Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) Note: the value `start` can be used to let all rendering engines, excepted Trident (IE11) and EdgeHTML (Edge), automatically deal with `left` and `right` based on the direction (`dir` attribute) set for the document and its nested elements. * * * ``` --USER__bodyHyphens ``` Enabling and disabling hyphenation. Scope: `html` It impacts `body`, `p`, `li`, `div` and `dd`. Possible Values: `auto` | `none` Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) **Warning:** for the time being, automatic hyphenation won’t work if you are using the Blink rendering engine (either via Chrome or a Webview) on ChromeOS, Linux and Windows. It indeed is not implemented yet and we recommend not trying to polyfill it using JavaScript as it will create a11y issues, especially with screen readers. * * * ``` --USER__fontFamily ``` The typeface (`font-family`) the user wants to read with. Scope: `html` It impacts `body`, `p`, `li`, `div`, `dt`, `dd` and phrasing elements which don’t have a `lang` or `xml:lang` attribute. Required flag: `:--fontOverride` Override class: User settings (should be applied by any means necessary) To reset, remove the required flag. * * * ``` --USER__fontSize ``` Increasing and decreasing the root `font-size`. It will serve as a reference for the cascade. Scope: `html` Possible values: `var(--RS__oldStyleTf)` | `var(--RS__modernTf)` | `var(--RS__sansTf)` | `var(--RS__humanistTf)` | `<string>` For Japanese, possible values become: `var(--RS__serif-ja)` (horizontal writing) | `var(--RS__sans-serif-ja)` (horizontal writing) | `var(--RS__serif-ja-v)` (vertical writing) | `var(--RS__sans-serif-ja-v)` (vertical writing) | `<string>` Required flag: `:--fontOverride` Override class: User settings (should be applied by any means necessary) To reset, remove the required flag. * * * ``` --USER__typeScale ``` The type scale the user wants to use for the publication. Scope: `html` It requires the `ReadiumCSS-fs_normalize.css` stylesheet. It impacts headings, `p`, `li`, `div`, `pre`, `dd`, `small`, `sub`, and `sup`. Recommended values: a range from `75%` to `250%`. Increments are left to implementers’ judgment. Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) * * * ``` --USER__lineHeight ``` Increasing and decreasing leading (`line-height`). Scope: `html` It impacts `body`, `p`, `li` and `div` Recommended values: a range from `1` to `2`. Increments are left to implementers’ judgment. Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) * * * ``` --USER__paraSpacing ``` The vertical margins (`margin-top` and `margin-bottom`) for paragraphs. Scope: `p` Recommended values: a range from `0` to `2rem`. Increments are left to implementers’ judgment. Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) * * * ``` --USER__paraIndent ``` The `text-indent` for paragraphs. Scope: `p` Recommended values: a range from `0` to `3rem`. Increments are left to implementers’ judgment. Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) * * * ``` --USER__wordSpacing ``` Increasing space between words (`word-spacing`, related to a11y). Scope: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `li`, `div` Recommended values: a range from `0` to `1rem`. Increments are left to implementers’ judgment. Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) * * * ``` --USER__letterSpacing ``` Increasing space between letters (`letter-spacing`, related to a11y). Scope: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `li`, `div` Recommended values: a range from `0` to `0.5rem`. Increments are left to implementers’ judgment. Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users) * * * ``` --USER__ligatures ``` Enabling and disabling ligatures in Arabic (related to a11y). Scope: `html` It impacts all text. Possible values: `none` | `common-ligatures` Required flag: `:--advancedSettings` Override class: User settings advanced (optional but should be applied by any means necessary if provided to users)