Editing Soma - JayPanoz/Soma GitHub Wiki

Oh OK. Yeah, look, I didn’t document it very well ... ¯_(ツ)_/¯

But documenting a CSS for ePub is a really tough job—basically, comments everywhere leading to bloat, BLOAT, BLOAT! So let’s say that if something is surprising to you, don’t change it.

However, I may give some pieces of advice for some really important stuff.

  • -webkit-text-fill-color is allowing the override of iBooks’ a default color. Now, iBooks got 4 themes (white, sepia, gray, black) and the value of the default color is modified dynamically based on the theme currently in use—in order to meet WCAG 2.0’s contrast ratio. In other words, don’t override and stick to default if you want to use color for links. As far as I can tell, there is no color meeting this WCAG requirement for all 4 themes.

  • Do not ever declare black or shades of gray using color for text: some apps won’t invert this value when the user enables night mode and, as a result, they’ll get dark text on a dark background, making the text unreadable. If you really need black, use color: inherit.

  • Do not ever declare font-family for p or li and other critical bodycopy elements as it will disable the typeface setting for users in a shitload of apps and devices. Let the cascade do its job, making those elements inherit from body.

  • Do not ever declare font-size in px as it will disable the font size setting in RMSDK. Moreover, Kindle eInk devices don’t map 1em and 100% to 16px but a multiple of 16px depending on display resolution (e.g. 32px, 64px and so on and so forth).

  • Don’t rely on the html selector. Please note RS usually declare text-rendering: optimizeLegibility when it doesn’t have issues (rendering or performance) so do not impose it on users—especially as there are wild bugs out there.

  • Don’t rely on text-transform and font-variant, pseudo-classes and -elements for “critical styling”, e.g. headings, strong emphasis, list style type, thematic break (hr), &c. This is not supported in RMSDK.

  • If you have snippets of code in your eBook, you’d better embed a monospace font in your ePub file. Some devices/apps don’t have a default one and will render code as serif or sans-serif.

  • Be insanely cautious with em values for margins and paddings, especially left and right; if the user increases font-size, margins will increase accordingly. As a result, you get bigger text in a smaller container. This is the reason why I am using values in % (computed based on width of container).

  • Styling of HTML5 elements (e.g. aside, figure, section, &c.) relies on the mini reset. Don’t ever get rid of this reset, please, because ePub2-only RS are still popular worldwide.

  • If you change the modular scale (i.e. font-size), all line-heights and margins have to be recalculated if you want to keep vertical rhythm.

  • Don’t use decimal values in @media amzn-mobi{}, KindleGen converter will round them quite harshly. Please also note Mobi7 supports ± HTML 3.2.

  • Cover img styling in ePub is crap. Design your cover with a 16:9 aspect ratio and you should be safe. 16:10 or 4:3 and you’re screwed–unless you modify img.cover styles, that is.

  • Whatever you do, don't leave the proprietary Amazon media queries (amzn-kf8 + amzn-mobi) empty: it will crash RMSDK. CSS comments won’t fix this issue.