@readium/css

# Quickstart Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides styles for reflowable text: - a CSS normalize for EPUB contents; - paged and scrolled views; - default styles; - reading modes (night, sepia, etc.); - themes; - user settings. **Note:** Readium CSS stylesheets were not designed and should not be used for fixed-layout EPUB, nor other file formats like FB2, PRC, Mobi, TEI, etc. ## Important info **TL;DR: use the stylesheets in the `css/dist` folder if you don’t need to customize Readium CSS.** All the flags and variables can then be taken at face value in the docs. - The `src` files, which are modules, can’t be used AS-IS. They indeed have to be processed by PostCSS to create `dist` stylesheets. - By default, those modules are daisy-chained and compiled into 3 `dist` stylesheets: 1. `ReadiumCSS-before.css`; 2. `ReadiumCSS-default.css` (for unstyled ebooks); 3. `ReadiumCSS-after.css`. - We’re currently managing RTL and CJK (including horizontal and vertical writing) scripts using specific `dist` stylesheets: 1. Right to Left stylesheets are distributed in an `rtl` folder; 2. CJK horizontal stylesheets are distributed in an `cjk-horizontal` folder; 3. CJK vertical stylesheets are distributed in an `cjk-vertical` folder. - The build process is currently subpar as it has been designed for our default and must be changed entirely if you want to process and use modules directly – which would make sense with HTTP2 for instance. ## How To Inject ReadiumCSS stylesheets into the `<head>` of (X)HTML documents. 1. `ReadiumCSS-before.css` 2. Authors’ stylesheet(s) or `ReadiumCSS-default.css` for unstyled publications 3. `ReadiumCSS-after.css` Check the [Stylesheets order doc](../docs/CSS06-stylesheets_order.md) for further details. For RTL, you would then have to load the stylesheets in the `rtl` folder. Same for CJK. Check the [“Internationalization” doc](../docs/CSS16-internationalization.md) for guidance. By default, we inject all stylesheets on load and rely on custom properties (a.k.a. CSS variables) set on `html` to apply user settings. ## Customize ReadiumCSS ships with a `ReadiumCSS-config.css` file you can use to customize it a little bit. It allows implementers to choose selectors for the user settings’ flags. In order to provide this customization, we use custom selectors, which will hopefully become [standards implemented at some point](https://drafts.csswg.org/css-extensions/), but require PostCSS at the moment. Consequently, you’ll have to rebuild all `dist` stylesheets if you’re changing this file. ### Flags for user settings By default, we are using flags in the form of CSS variables to manage reading modes and user settings. But you might want to customize those flags in order to use custom attributes (`data-*`) or good old CSS classes. A complete list of flags can be found in the [User preferences doc](../docs/CSS12-user_prefs.md). As an example, if you want to use a CSS class for night mode, it could look like: ``` @custom-selector :--night-mode .night-mode; ``` And if you want to use custom attributes for advanced settings, it could look like: ``` @custom-selector :--advanced-settings [data-settings="advanced"]; ``` Both would then have to be appended to `html` at runtime. Once again, you must rebuild `dist` stylesheets. ### Add and remove modules We have to add and remove modules depending on the language/script of the publication so this need is covered out of the box. In the `css/src` folder, you’ll find all the needed stylesheets you will process to `css/dist`. Those stylesheets contain a list of imports e.g. for `ReadiumCSS-before.css`: ``` @import "../ReadiumCSS-config.css"; @import "modules/ReadiumCSS-base.css"; @import "modules/ReadiumCSS-fonts.css"; @import "modules/ReadiumCSS-html5patch.css"; @import "modules/ReadiumCSS-safeguards.css"; ``` As a consequence, modules you want to use have to be listed in those `-before` and `-after` files. Then rebuild them using PostCSS. Additional user settings MUST be added to the `user-settings-submodules` folder, and make the required flag clear, if applicable. Please remember to take the cascade into account, as issues might arise just because the order has been changed or modules moved from `-before` to `-after` – in which case we won’t be able to reproduce and debug an issue if we don’t know this important detail. See [Stylesheets order doc](../docs/CSS06-stylesheets_order.md) for further details. ### Reading System variables If you want to change the name of `--RS__` prefixed variables, you will have to change it in every module. ### User settings variables If you want to change the name of `--USER__` prefixed variables, you will have to change it in every module. ## Build dist stylesheets First, please make sure you have node.js installed. If you don’t, go [download it on the official page](https://nodejs.org/en/). Then navigate to the `readium-css` folder in your terminal and type: ``` npm install ``` This will install all dependencies needed to build `dist` stylesheets. Once you have customized `src` files, in the terminal type: ``` npm run-script build ``` This will rebuild all `dist` stylesheets in their specific folder. ### Options Other scripts are available: - `build:ltr` for default stylesheets (Left to Right); - `build:rtl` for Right to Left stylesheets; - `build:cjk` for CJK scripts; - `build:vertical` for CJK and the Mongolian scripts in vertical writing. ### Additional info Further details about the build and test processes can be found in [the npm doc](../docs/CSS22-npm.md). ## Manage User Settings Currently, user settings are managed by setting CSS variables at the `:root` level (`html` element). ### Flags At the top of each user settings submodule, you will find the required flag for the preference. This flag is needed for the setting to work. ### User variables All settings can be set using `--USER__` prefixed variables. Set those properties for `html` and the cascade will automatically do its job. To set a variable: ``` var root = document.documentElement || document.getElementById("iframe-wrapper").contentWindow.document.documentElement; root.style.setProperty("--USER__var", "value"); ``` To remove a variable: ``` var root = document.documentElement || document.getElementById("iframe-wrapper").contentWindow.document.documentElement; root.style.removeProperty("--USER__var"); // or root.style.setProperty("--USER__var", ""); ``` Please note you must implement a fallback strategy if you want to support Internet Explorer 11 and early versions of Microsoft Edge. ### Examples #### Changing hyphenation and justification ``` root.style.setProperty("--USER__advancedSettings", "readium-advanced-on"); root.style.setProperty("--USER__textAlign", "justify"); root.style.setProperty("--USER__bodyHyphens", "auto"); ``` Of course this example is simplistic. You could for instance create an helper to set multiple properties at once. #### Apply sepia mode To apply the sepia mode, you can use a flag that will apply preset values. ``` root.style.setProperty("--USER__appearance", "readium-sepia-on"); ``` ## Create Themes In Readium CSS model, themes are a set of user settings you can store and retrieve. Add the properties to `html` and you get a theme. Depending on the prefix you are using, `--RS__` or `--USER__`, your theme will override the publisher’s styles or not. The rule being `USER > PUBLISHER > RS`. Check the [User Preferences doc](../docs/CSS12-user_prefs.md) for a list of available user variables. You can also retrieve ReadiumCSS presets for font-stacks and modes by adding it as a package, then importing its exposed json files. For instance in JS/TS: ``` import sepiaMode from "readium-css/css/vars/sepia.json"; const sepiaBackground = sepiaMode.sepiaMode.RS__backgroundColor; ```