oli.jp style guide


This is a personal style guide for oli.jp. I’m publishing it to share and for feedback, and also because I <strong>ly believe you should build a style guide for every site you make. Hopefully this one will give you a head start.

My CSS stylesheet is here.

Assumptions & Setup

  • add extra styling directly to head <style>, or add per block, targeted by id and in <style scoped> e.g <table> code like #testing-results .col1, #testing-results .col2 {width: 33%;}
  • UTF8 and attributes quoted so only these characters need to be entities: “&” &amp; and “<” &lt; (I do “>” &gt; as well via snippets)
  • main content is inside <article>
  • the center column is 60%, with min-width = 400px (667px total), and max-width = 672px (1120px total)
  • the baseline grid is based on 24px, which = line-height (16px/1.5 default font size)
  • My RadiantCMS weblog uses these custom tags
    • <r:comment>…</r:comment> — comments that won’t be in HTML source
    • <r:code>…</r:code> — for blocks of code so I don’t have to work with entitied code samples (also where formatting comes from). Not for inline code samples.
  • @font-face in effect for headings and code (hopefully won’t be too slow). Deliberately not using for body copy until WebKit fixes bug 25207

Class-based block styles


These are highlighted (block-level) sections of content:

  • class="callout" — white box for long asides or content that’s not suitable for marginalia, but not important enough for callout highlight-block; use for diversions/backstory
  • class="callout highlight-block" — white box with gold border; use for vital content such as a main points summary or disambiguation guide, kind of like a block-level <strong>
  • class="callout note-block" — pinkish box with pink border and italics; use for author notes when drafting (remove before publishing) as a visual todo reminder
  • class="callout warning-block" — white box with red border; use for serious warnings
  • Note <blockquote>, <table> and <img> have similar styles by default (add .clean to container to turn off block <img> styling, and .cleaner to disable border and padding)


In general, use callout highlight-block instead. This style can be used for an aside that’s more important than or too long for marginalia, but not something in need of emphasis.

  1. one
  2. two
  3. three

class="callout highlight-block"

Use this style to emphasise crucial blocks of content (ref: choosing between <article>, <section>, and <div>, Chapter 3)

  • Able
  • Miss Baker
  • Laika

class="callout note-block"

Use this style for author notes — text is italicised by default

class="callout warning-block"

Use this style to warn the reader about serious problems

An example table
Column header Another header
Row header Some data


Use <blockquote> for including long-form content from other sources. Highlight important text using <mark>. In addition to text in <p>, blockquotes can contain lists, tables etc. Add a citation using <footer><cite><a href="link">Citation source</a></cite></footer>


Use a 2 space-per-tab indent. Use <mark> to indicate relevant text (formatted as bold). This is what a standard code block looks like (<pre><code>)

<p>This is what a standard code block looks like (<pre><code>…</code></pre>)</p>

This is the same block with .callout applied

<p>This is what a standard code block with .callout looks like (<pre class="callout"><code>…</code></pre>)</p>

The formatting plugin (<r:code>) makes code look like this (no need to escape anything, but no ability to use <mark> in <code>, which is styled bold outside the code formatting plugin.)

Formatted Code

On oli.jp the following sample will be auto-formatted:

<p>This is what a standard code block using the formatting plugin looks like (<code>r:code</code>)</p>

Aside — sidenote marginalia

An <aside> in the right margin for minor content, notes, definitions, reminders or any other short piece of text that’s an addendum and not main content. For longer runs of text consider <aside class="callout">, which appears in the main column.

<aside class="sidenote"><p>…</p></aside>

I place it in the source before the thing I want to describe so it’s level once floated right

Browser support table (and vendor prefix code)

Basically just a table (aping caniuse.com: check Mozilla Developer Network links for first added dates), but adding the class table.browser-support formats vendor prefixes. Use .warning on <td> to color version number red, then add table note numbers with <sup>1</sup> etc manually. Combine these with <ol class="key"> and make sure your <li> order matches the table notes ;-) These table notes should refer/link to further explanation. I’m using <abbr title="not supported">-</abbr> for the unsupported dash. Finally I’ve made <th> 30% wide (to stop <td> from wrapping for no reason), and <code> in <th> has no-wrap.

There’s also an aside style .vendor-prefix for a copy-paste code block to the right of the table (needed?).

Table 2: Browser support for box-sizing
IE Mozilla Safari Chrome Opera
8.01 -ms- 1.0 -moz-
3.0 -webkit- 5.0 -webkit- 7.0 -o-
  1. IE 8 only supports discombobulation, not full transubstantiation. See Black magicks (relative link) for more info.

Example table for multi-column layout information:

Table 3: this table has the classes .browser-support.wide
Property IE Mozilla Safari Chrome Opera
column-width - 1.5 -moz- 3.0 -webkit- 5.0 -webkit- -
column-count - 1.5 -moz- 3.0 -webkit- 5.0 -webkit- -
columns - - 3.0 -webkit- 5.0 -webkit- -
column-gap - 1.5 -moz- 3.0 -webkit- 5.0 -webkit- -
column-rule - 3.5 -moz- 3.01 -webkit- 5.01 -webkit- -
column-span - - - - -
  1. WebKit browsers (Safari and Chrome) don’t display a column-rule that’s wider than column-gap (ref).


If you’d like to do multicolumn text (I used it for a list of short terms); class="column" = 2 columns, class="columns" = 3 columns. They can also be used with .callout if you want.

  • one
  • two columns
  • three
  • four
  • five
  1. one
  2. two
  3. three columns
  4. four
  5. five
  • one
  • two
  • three columns
  • four
  • five

Basic block positioning

Combine these basic classes to add images or examples into text

  • .left — float: left
  • .right — float: right
  • .half — width: 45%
  • .right.half — automatically add a border on the left to separate
  • .aside.img — float: right and clear: both
  • .group — clearfix

Example — list plus image floated right inside <div class="group"> *

Visual example of the semantic element nesting in the following list
  • Page header (site name, logo, search…)
  • Main navigation
  • Main content (wrapper)
    • Article (main column)
      • Article title
      • Article metadata
      • Article content…
      • Article footer
    • Sidebar
      • Sidebar title
      • Sidebar content…
  • Page Footer

Default element styles


Default sizes are:

  1. <h1> — 2em Museo Slab
  2. <h2> — 1.5em Museo Slab
  3. <h3> — 1.25em Museo Slab
  4. <h4> — 1.125em Helvetica Neue
  5. <h5> — 1em Helvetica Neue bold
  6. <h6> — 1em Helvetica Neue

<h1> level heading title (italic, bold)


<h2> level heading title (italic, bold)


<h3> level heading title (italic, bold)


<h4> level heading title (italic, bold)


<h5> level heading title (italic, bold)


<h6> level heading title (italic, bold)


Note that while I load Museo Sans and Museo Sans italic, I don’t use bold or bold italic fonts (to cut down page weight and because I don’t need them) — don’t use or they may be faked poorly by the browser.

Default table style

Tables are centered and based on the width of the content by default. For forcing full column width, or for larger tables that also use the margins, you can use:

  1. .wide — center column full width
  2. .wider — center column plus right margin
  3. .widest — center column plus both margins

Note that .wider and .widest kill .sidenote, and all three will break .callout boxes. Don’t forget <thead>! Bonus points for using scope="col|row" ;-)

Table with no width class applied
Pattern Meaning Described in section CSS
* any element Universal selector 2
Table with no width class applied, but lots of content
Pattern Meaning Described in section CSS
* any element Universal selector Some extra text to demonstrate how table width works when there’s more than one line of content in a table cell 2
Table with .wide
Pattern Meaning Described in section CSS
* any element Universal selector 2
Table with .wider
Pattern Meaning Described in section CSS
* any element Universal selector 2
Table with .widest
Pattern Meaning Described in section CSS
* any element Universal selector 2

Using document or scoped styles you can also control column widths, eg #testing-results .col1, #testing-results .col2 {width: 33%;}

Default image style

Hanami — cherry blossom viewing

block-level <img>

Hanami — cherry blossom viewing

<img class="clean"> (no box shadow)

Hanami — cherry blossom viewing

<img class="cleaner">.cleaner removes border and padding

Example image that’s wide enough to break the layout

<img class="cleaner wide">.wide removes max-width (to width: auto;) so images larger than the content column won’t be scaled down

Hanami — cherry blossom viewing inline image (inside <p>)

Default figure style

Hanami — cherry blossom viewing

Currently images are left-aligned by default, and images in figures are centered by default.

Definition lists

A Rhesus monkey who, riding on a V2 rocket to over 63 km on June 11, 1948, became the first monkey astronaut
Albert II
Attained the altitude of 134 km on June 14, 1949, becoming USA’s first space monkey
The Kármán line of 100 km is considered the beginning of space

Phrasing styles & sundry items

  • .amp or <abbr title="and">&amp;</abbr>@simplebits ampersand (&) (for headings; I use <abbr> ;-)
  • .semantic-list — this suppresses bullets/numbering (eg if you want a list without them)

Default phrasing styles

First this is a link. Going alphabetically we have an abbreviation, then the <b> element, followed by a line break
next a cite element (browser default), then an inline code example (<code>) containing <mark>. Next some deleted text, followed by a definition (no special styling). Emphasised text is semantically different from italicised text. Images inside <p> are automatically inline (outside they’re block). Some inserted text precedes text the user should enter (“enter the password kronos”) via the keyboard (<kbd>), and marked text (<mark>). We then have programming output using <output>, an inline quote using <q>, some legalese using <small>, and a <span> of text (obviously unstyled). For important content there’s <strong>. Subscript text (<sub>) like H2O and superscript text (<sup>) such as Mme Baker won’t break the measure. Mathematic variables (<var>) like $monkey use the default style. Finally there’s the poorly-supported <wbr> element for indicating acceptable break points in long words. It’s most useful in code samples, for example:

  • Without <wbr>: <a href="http://www.whatwg.org/specs/webapps/currentwork/multipage/contentmodels.html#phrasingcontent0">
  • With <wbr>: <a href="http://www.whatwg.org/specs/webapps/currentwork/multipage/contentmodels.html#phrasingcontent0">

Other bits (just in case)

In-article table of contents

This makes a 1/2 width box floated right, intended to contain in-article links (linking to the ids that I added for the .permalink effect). Use <nav class="in-page">, with <h2> for the title. It only has styles for two levels of nesting.


Similar to .sidenote, the class .meta moves things to the left margin. Currently I only use it for article metadata.

The meta style works differently to .sidenote — it’s absolutely positioned using the containing flow element (add .relative to give the containing element position:relative)

Changed blocks (<ins> & <del>)

This isn’t an issue at the moment, but there are also styles for inline and block-level inserted content, and inline deleted content.

An inserted block (.callout.changed-block) containing some inserted text (<ins>). I don’t use this style for now but I could if I preferred green over gold for the highlighted blocks (<del>).


If you have any feedback, please let me know via Twitter (@boblet).


  1. Added heading permalinks (on hover) and fixed a bad in-page link. Also fixed a typo in discussing img.wide.
  2. Added a link to the stylesheet (d’oh) and an introductory paragraph.