Theme boilerplate

[JayPanoz]

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.

[JayPanoz]

Given our current approach, themes are now a simple combination of user settings, which means customized themes can be created on the fly and saved by the user (and cached by the RS).

This issue’d probably be left pending until developers can get their hands dirty in the implementation.

[JayPanoz]

Update: now that I’ve started working on themes and have like 5 well under way, question is do we stick to a combination of user settings and authors’ styles, or not?

For instance, you might want to center headings or apply a drop cap to get some classical feel, have block quotes in a slightly smaller font-size to make it more modern, etc.

So we would need an extra theming module (stylesheet) + flags to achieve that.

[JayPanoz]

Closing this issue to reopen a new and clearer one as it needs to be revisited.